kb/openspec/changes/archive/2026-04-04-mcp-collection-and-delete-tools/specs/mcp-document-management/spec.md

ADDED Requirements

Requirement: Set collection on existing document via MCP

The MCP server SHALL expose a kb_set_collection tool that assigns or changes the collection of an existing document. The tool SHALL accept a document_id (required) and collection (optional string). When collection is provided, the tool SHALL ensure the document belongs to exactly that collection by removing any existing collection:* tags and adding the new one. When collection is omitted or null, the tool SHALL remove all collection:* tags from the document, leaving it unassigned.

The tool SHALL return the updated document with the collection field and cleaned tags (collection tags stripped), consistent with other MCP tool responses.

Scenario: Assign untagged document to a collection

• WHEN kb_set_collection is called with document_id=42 and collection="workspace"
• THEN the document SHALL have the tag collection:workspace added
• AND the response SHALL include "collection": "workspace"

Scenario: Change document from one collection to another

• WHEN kb_set_collection is called with document_id=42 and collection="memory" on a document currently in collection "documents"
• THEN the tag collection:documents SHALL be removed and collection:memory SHALL be added
• AND the response SHALL include "collection": "memory"

Scenario: Remove document from all collections

• WHEN kb_set_collection is called with document_id=42 and no collection parameter
• THEN all collection:* tags SHALL be removed from the document
• AND the response SHALL include "collection": null

Scenario: Document not found

• WHEN kb_set_collection is called with a document_id that does not exist
• THEN the tool SHALL return an error response indicating the document was not found

Requirement: Delete document via MCP

The MCP server SHALL expose a kb_delete tool that permanently deletes a document from the knowledge base. The tool SHALL accept a document_id (required integer). Deletion SHALL remove the document, its chunks, embeddings, tags, and any stored file on disk.

The tool SHALL return a confirmation response including the deleted document's ID and title.

Scenario: Successful deletion

• WHEN kb_delete is called with document_id=42
• THEN the document, its chunks, embeddings, tag associations, and stored file SHALL be deleted
• AND the response SHALL include "status": "deleted", the document_id, and the document title

Scenario: Document not found

• WHEN kb_delete is called with a document_id that does not exist
• THEN the tool SHALL return an error response indicating the document was not found

Requirement: Engine client delete method

The MCP engine client (mcp/engine.py) SHALL provide a delete_document(doc_id) method that sends a DELETE request to /api/v1/documents/{doc_id} and returns the JSON response. The method SHALL raise on non-2xx status codes, consistent with other engine client methods.

Scenario: Successful engine client delete call

• WHEN delete_document(42) is called and the engine API returns 200
• THEN the method SHALL return the parsed JSON response

Scenario: Engine client delete for missing document

• WHEN delete_document(999) is called and the engine API returns 404
• THEN the method SHALL raise an httpx.HTTPStatusError