40 lines
2.5 KiB
Markdown
40 lines
2.5 KiB
Markdown
## 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.
|