From d078af9ad39e4664e46ff38d48cebf207e79a5dd Mon Sep 17 00:00:00 2001 From: Steve Cliff Date: Thu, 2 Apr 2026 22:03:41 +0100 Subject: [PATCH] Split MCP docs into MCP.md with AI tool setup examples Move MCP server documentation from README into dedicated MCP.md. Add configuration examples for Claude Code, VS Code, Cursor, Windsurf, and JetBrains IDEs. Co-Authored-By: Claude Opus 4.6 (1M context) --- MCP.md | 174 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 60 ++----------------- 2 files changed, 178 insertions(+), 56 deletions(-) create mode 100644 MCP.md diff --git a/MCP.md b/MCP.md new file mode 100644 index 0000000..8940dae --- /dev/null +++ b/MCP.md @@ -0,0 +1,174 @@ +# MCP Server (Agent Integration) + +The MCP server exposes kb operations as native MCP tools, so agents can search, add notes, upload files, and manage documents without shelling out to the CLI. + +## Start the MCP server + +The compose files include a `kb-mcp` service alongside the engine. Set `KB_MCP_API_KEY` to require Bearer token auth from connecting agents: + +```bash +KB_API_KEY=your-engine-key KB_MCP_API_KEY=your-agent-key \ + docker compose -f engine/compose.nvidia.yaml up -d +``` + +Or run the MCP server standalone: + +```bash +docker run -d --name kb-mcp \ + -p 3000:3000 \ + -e KB_ENGINE_URL=http://your-engine-host:8000 \ + -e KB_API_KEY=your-engine-key \ + -e KB_MCP_API_KEY=your-agent-key \ + --restart unless-stopped \ + docker.dcglab.co.uk/dcg/kb/mcp:latest +``` + +## MCP tools + +| Tool | Description | +|---|---| +| `kb_search` | Hybrid search with optional collection/tag/type filters | +| `kb_addnote` | Add a text note (queued for async ingestion) | +| `kb_update_note` | Update an existing note in place | +| `kb_get` | Get document details by ID or source path | +| `kb_status` | Engine health and statistics | +| `kb_jobs` | Ingestion queue status | +| `kb_upload_start` | Start a chunked file upload | +| `kb_upload_chunk` | Upload a base64-encoded file chunk | +| `kb_upload_finish` | Finish upload and submit for ingestion | + +## Collections + +The MCP server supports **collections** — scoped document namespaces implemented via tag conventions. Use these to separate agent memory from user documents: + +- `documents` (default) — user-facing documents +- `memory` — agent memory and preferences +- `workspace` — working context + +Tools accept a `collection` parameter. The MCP server translates this to `collection:` tags on the engine, and strips them from responses so agents see a clean `"collection": "memory"` field. + +## MCP server configuration + +| Variable | Default | Description | +|---|---|---| +| `KB_ENGINE_URL` | `http://localhost:8000` | Engine API URL | +| `KB_API_KEY` | (none) | Engine API key | +| `KB_MCP_API_KEY` | (none) | Bearer token required from agents (disabled if unset) | +| `KB_MCP_PORT` | `3000` | Port to listen on | + +## Connecting AI coding tools + +The kb MCP server uses **Streamable HTTP** transport at `http://your-host:3000/mcp`. Below are configuration examples for popular AI coding tools. + +### Claude Code (CLI / Desktop / Web) + +Add the server to your project or user settings: + +```bash +claude mcp add kb-server --transport http http://localhost:3000/mcp +``` + +Or add it manually to `.claude/settings.json` (project) or `~/.claude/settings.json` (global): + +```json +{ + "mcpServers": { + "kb-server": { + "type": "http", + "url": "http://localhost:3000/mcp", + "headers": { + "Authorization": "Bearer your-agent-key" + } + } + } +} +``` + +### VS Code (GitHub Copilot) + +Add to your `.vscode/settings.json` (workspace) or user settings: + +```json +{ + "mcp": { + "servers": { + "kb-server": { + "type": "http", + "url": "http://localhost:3000/mcp", + "headers": { + "Authorization": "Bearer your-agent-key" + } + } + } + } +} +``` + +Or add to `.vscode/mcp.json` in your workspace: + +```json +{ + "servers": { + "kb-server": { + "type": "http", + "url": "http://localhost:3000/mcp", + "headers": { + "Authorization": "Bearer your-agent-key" + } + } + } +} +``` + +### Cursor + +Add to `.cursor/mcp.json` in your project root: + +```json +{ + "mcpServers": { + "kb-server": { + "type": "streamable-http", + "url": "http://localhost:3000/mcp", + "headers": { + "Authorization": "Bearer your-agent-key" + } + } + } +} +``` + +### Windsurf + +Add to `~/.codeium/windsurf/mcp_config.json`: + +```json +{ + "mcpServers": { + "kb-server": { + "serverUrl": "http://localhost:3000/mcp", + "headers": { + "Authorization": "Bearer your-agent-key" + } + } + } +} +``` + +### JetBrains IDEs (IntelliJ, WebStorm, PyCharm, etc.) + +Add to `.junie/mcp.json` in your project root, or configure via **Settings > Tools > AI Assistant > MCP Servers**: + +```json +{ + "servers": { + "kb-server": { + "type": "http", + "url": "http://localhost:3000/mcp", + "headers": { + "Authorization": "Bearer your-agent-key" + } + } + } +} +``` diff --git a/README.md b/README.md index dc2307f..057dbf3 100644 --- a/README.md +++ b/README.md @@ -190,62 +190,10 @@ Data is device-agnostic — you can ingest on NVIDIA and serve from AMD or CPU ( ## MCP server (agent integration) -The MCP server exposes kb operations as native MCP tools, so agents can search, add notes, upload files, and manage documents without shelling out to the CLI. +The MCP server exposes kb operations as native MCP tools over Streamable HTTP, so agents can search, add notes, upload files, and manage documents without shelling out to the CLI. Includes setup guides for Claude Code, VS Code, Cursor, Windsurf, and JetBrains IDEs. -### Start the MCP server +See **[MCP.md](MCP.md)** for full details — server setup, available tools, collections, configuration, and client examples. -The compose files include a `kb-mcp` service alongside the engine. Set `KB_MCP_API_KEY` to require Bearer token auth from connecting agents: +## Agent skill -```bash -KB_API_KEY=your-engine-key KB_MCP_API_KEY=your-agent-key \ - docker compose -f engine/compose.nvidia.yaml up -d -``` - -Or run the MCP server standalone: - -```bash -docker run -d --name kb-mcp \ - -p 3000:3000 \ - -e KB_ENGINE_URL=http://your-engine-host:8000 \ - -e KB_API_KEY=your-engine-key \ - -e KB_MCP_API_KEY=your-agent-key \ - --restart unless-stopped \ - docker.dcglab.co.uk/dcg/kb/mcp:latest -``` - -### MCP tools - -| Tool | Description | -|---|---| -| `kb_search` | Hybrid search with optional collection/tag/type filters | -| `kb_addnote` | Add a text note (queued for async ingestion) | -| `kb_update_note` | Update an existing note in place | -| `kb_get` | Get document details by ID or source path | -| `kb_status` | Engine health and statistics | -| `kb_jobs` | Ingestion queue status | -| `kb_upload_start` | Start a chunked file upload | -| `kb_upload_chunk` | Upload a base64-encoded file chunk | -| `kb_upload_finish` | Finish upload and submit for ingestion | - -### Collections - -The MCP server supports **collections** — scoped document namespaces implemented via tag conventions. Use these to separate agent memory from user documents: - -- `documents` (default) — user-facing documents -- `memory` — agent memory and preferences -- `workspace` — working context - -Tools accept a `collection` parameter. The MCP server translates this to `collection:` tags on the engine, and strips them from responses so agents see a clean `"collection": "memory"` field. - -### MCP server configuration - -| Variable | Default | Description | -|---|---|---| -| `KB_ENGINE_URL` | `http://localhost:8000` | Engine API URL | -| `KB_API_KEY` | (none) | Engine API key | -| `KB_MCP_API_KEY` | (none) | Bearer token required from agents (disabled if unset) | -| `KB_MCP_PORT` | `3000` | Port to listen on | - -## Claude Code skill - -This tool is designed to be wrapped as a Claude Code skill. See `SKILL.md` for the skill definition. +If you are restricted from using MCP server, or you just prefer to utilise Agent SKILLS, please also see `SKILL.md` for the skill definition.