kb/openspec/changes/archive/2026-04-04-mcp-collection-and-delete-tools/design.md

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.