## Context The MCP server (`mcp/server.py`) exposes KB operations as tools for LLM clients. Collections are an abstraction over tags — internally stored with a `collection:` prefix. The server already has helpers for managing collection tags (`_collection_tag`, `_ensure_exclusive_collection`, `_strip_collection_tags`) and the engine client (`mcp/engine.py`) already has an `update_tags()` method. Document deletion is supported by the engine API at `DELETE /api/v1/documents/{doc_id}` but has no corresponding engine client method or MCP tool. ## Goals / Non-Goals **Goals:** - Expose collection assignment for existing documents via MCP (`kb_set_collection`) - Expose document deletion via MCP (`kb_delete`) - Follow existing patterns in `server.py` and `engine.py` **Non-Goals:** - Bulk operations (multi-document collection assignment or deletion) - Tag management beyond collections (direct tag add/remove via MCP) - Undo/recycle bin for deleted documents - Changes to the engine API layer — all endpoints already exist ## Decisions ### 1. Reuse `_ensure_exclusive_collection` for kb_set_collection The server already has `_ensure_exclusive_collection(doc_id, collection)` which removes any existing `collection:*` tags and applies the new one. The `kb_set_collection` tool will use this directly when a collection is provided, and manually remove collection tags when clearing. **Alternative considered**: Exposing raw tag add/remove to the LLM. Rejected because it leaks the `collection:` prefix implementation detail and the LLM could create inconsistent state (multiple collections on one document). ### 2. New `engine.delete_document()` method for kb_delete Add a simple `delete_document(doc_id)` to `mcp/engine.py` that calls `DELETE /api/v1/documents/{doc_id}`. This follows the same pattern as all other engine client methods. ### 3. Return confirmation with document metadata on delete `kb_delete` will return the response from the engine API which includes `{"status": "deleted", "document_id": ..., "title": ...}`. This gives the LLM confirmation of what was deleted without needing a separate get call. ## Risks / Trade-offs - **[Accidental deletion]** → The LLM could delete the wrong document. Mitigation: the tool requires an explicit `document_id`, and the response includes the title so the LLM can verify. No bulk delete is exposed. - **[Collection cleared unexpectedly]** → Passing `collection=None` to `kb_set_collection` removes collection assignment. Mitigation: the parameter description will make this behavior explicit.