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

Why

LLMs using the KB MCP server can create notes in collections and search by collection, but cannot assign existing documents to a collection or delete documents. This forces users to drop out to the HTTP API for routine document management. Both operations are fully supported at the database and HTTP API layers but aren't wired through to MCP tools.

What Changes

• Add kb_set_collection MCP tool — assigns, changes, or removes the collection on an existing document by manipulating collection: prefixed tags via the existing engine.update_tags() method.
• Add kb_delete MCP tool — deletes a document by ID, calling the existing DELETE /api/v1/documents/{doc_id} endpoint via a new engine.delete_document() method.

Capabilities

New Capabilities

• mcp-document-management: MCP tools for modifying and deleting existing documents (kb_set_collection, kb_delete).

Modified Capabilities

(none — the engine API endpoints already exist; this change only adds MCP tool wrappers)

Impact

• MCP server (mcp/server.py): Two new tool registrations.
• MCP engine client (mcp/engine.py): One new method (delete_document). The update_tags method already exists and will be reused.
• Engine API: No changes — DELETE /api/v1/documents/{doc_id} and PUT /api/v1/documents/{doc_id}/tags already exist.
• Breaking changes: None. Additive only.