kb/openspec/changes/kb-v3-mcp-server/tasks.md

1. Engine: Schema Migration & updated_at

• 1.1 Add updated_at TEXT column migration to init_schema() in kb/database.py (same pattern as existing ALTER TABLE migrations)
• 1.2 Update insert_document() to include updated_at in returned/stored fields
• 1.3 Update document list endpoint (GET /api/v1/documents) to include updated_at in response and use COALESCE(updated_at, created_at) for date sorting
• 1.4 Update document detail endpoint (GET /api/v1/documents/{id}) to include updated_at in response
• 1.5 Update tag management endpoint (PUT /api/v1/documents/{id}/tags) to set updated_at = current_timestamp on tag changes

2. Engine: Note Mutation Endpoint

• 2.1 Create kb/routes/notes.py with PATCH /api/v1/notes/{id} endpoint
• 2.2 Implement validation: document must exist and have doc_type = 'note' (404 / 422 on failure)
• 2.3 Implement note update logic: delete old chunks/embeddings, run note chunking pipeline, re-embed, insert new chunks, update content_hash and updated_at — all in a single transaction
• 2.4 Register the notes router in engine/main.py
• 2.5 Test: update a note and verify chunks, embeddings, FTS index, and updated_at are all correctly updated
• 2.6 Test: verify rollback on embedding failure preserves original note

3. Engine: Version Bump

• 3.1 Update engine/VERSION to 3.0.0

4. Go Client: Update Note Command

• 4.1 Add PATCH /api/v1/notes/{id} method to internal/api/client.go
• 4.2 Create cmd/updatenote.go — takes document ID and text as positional args, calls PATCH endpoint, formats output (human/json)
• 4.3 Handle error cases: 404 (not found), 422 (not a note), missing arguments
• 4.4 Update cmd/examples.go to include updatenote usage

5. Go Client: Version Bump

• 5.1 Update client/VERSION to 3.0.0
• 5.2 Update client/MIN_ENGINE_VERSION to 3.0.0

6. MCP Server: Project Setup

• 6.1 Create mcp/ directory at repo root with Python package structure
• 6.2 Add mcp SDK and httpx as dependencies (requirements.txt or pyproject.toml)
• 6.3 Implement config: read KB_ENGINE_URL, KB_API_KEY, KB_MCP_API_KEY from environment
• 6.4 Implement Streamable HTTP transport setup using mcp SDK
• 6.5 Implement Bearer token authentication for incoming agent connections (KB_MCP_API_KEY)

7. MCP Server: Core Tools

• 7.1 Implement kb_search tool — proxy to engine search API, translate collection param to collection:* tag filter, strip collection:* tags from results and add collection field
• 7.2 Implement kb_addnote tool — proxy to engine jobs API, apply collection:<name> tag (default collection:documents)
• 7.3 Implement kb_update_note tool — proxy to engine PATCH /api/v1/notes/{id}
• 7.4 Implement kb_get tool — proxy to engine documents API, support lookup by ID or source_path, strip collection tags from response
• 7.5 Implement kb_status tool — proxy to engine status API
• 7.6 Implement kb_jobs tool — proxy to engine jobs API with optional status filter

8. MCP Server: Chunked File Upload

• 8.1 Implement kb_upload_start tool — generate UUID, create temp staging directory, store upload metadata (filename, tags, collection) in memory
• 8.2 Implement kb_upload_chunk tool — validate upload_id exists, decode base64, write chunk to staging directory by chunk_index
• 8.3 Implement kb_upload_finish tool — reassemble chunks in order, forward as multipart upload to engine POST /api/v1/jobs with tags (including collection:*), return job ID, clean up staging
• 8.4 Implement abandoned upload cleanup — background task that removes uploads older than 10 minutes
• 8.5 Test: upload a multi-chunk file and verify it arrives at the engine correctly

9. MCP Server: Collection Management

• 9.1 Implement exclusive collection enforcement — on addnote/addfile, query document tags, remove any existing collection:* tags via engine tag API before applying new one
• 9.2 Implement collection tag stripping in all tool responses (search results, document details)

10. MCP Server: Tool Descriptions

• 10.1 Write kb_search tool description including query expansion and reranking guidance
• 10.2 Write descriptions for all other tools with parameter documentation and usage examples
• 10.3 Include chunked upload usage example in kb_upload_start description

11. MCP Server: Docker & Compose

• 11.1 Create mcp/Dockerfile — Python base image, install dependencies, run MCP server
• 11.2 Add MCP server service to Docker Compose file(s) — connect to engine via Docker network, expose Streamable HTTP port
• 11.3 Document environment variables (KB_ENGINE_URL, KB_API_KEY, KB_MCP_API_KEY) in compose file

12. Integration Testing

• 12.1 Test: MCP search with collection filter returns only matching documents
• 12.2 Test: MCP addnote with collection applies correct tag and enforces exclusivity
• 12.3 Test: MCP update note preserves document ID and tags, updates content and updated_at
• 12.4 Test: chunked file upload end-to-end (start → chunk × N → finish → verify job created)
• 12.5 Test: MCP server rejects unauthenticated connections when KB_MCP_API_KEY is set

13. Release

• 13.1 Build and tag engine Docker images (engine-v3.0.0-*)
• 13.2 Build and tag MCP server Docker image
• 13.3 Build Go client binaries for all platforms
• 13.4 Create git tags: engine-v3.0.0, client-v3.0.0
• 13.5 Update SKILL.md to reference MCP server as primary agent integration path