@agentskit/doc-bridge 1.2.4 → 1.2.6

package/docs/mcp.md

@@ -43,6 +43,19 @@ Or with a global/local bin:
 
 Run from the repo root (or pass config discovery that resolves to it). Always `ak-docs index` after doc changes (or gate in CI).
 
+## Claude Desktop MCP Bundle
+
+Maintainers can build the local desktop extension from a clean checkout:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm mcpb:pack
+```
+
+The bundle asks the user to select the repository's `doc-bridge.config.json` and uses that file's directory as the project boundary. It contains a self-contained MCP runtime rather than the optional RAG, chat, or model-provider packages. The build validates the manifest, checks the archive inventory, and exercises all eight tools from the staged runtime.
+
+The stdio server accepts the newline-delimited JSON transport used by current MCP clients and the legacy `Content-Length` framing used by older integrations. Responses use the same framing as each request.
+
 ## Tools
 
 | Tool | Purpose |
@@ -53,6 +66,9 @@ Run from the repo root (or pass config discovery that resolves to it). Always `a
 | `gate.status` | Freshness / configured gates |
 | `retriever.query` | Local retriever chunks |
 | `memory.classify` / `memory.promoteDraft` | Memory pipeline |
+| `registry.topology` | Static curator and delegate topology |
+
+Every tool is annotated read-only. None of these MCP calls writes project files or publishes a memory promotion.
 
 ## Agent guidance (paste into AGENTS.md)
 

package/mcpb/.mcpbignore

@@ -0,0 +1,8 @@
+.env*
+*.log
+*.map
+*.mcpb
+coverage/
+test/
+tests/
+src/

package/mcpb/manifest.json

@@ -0,0 +1,96 @@
+{
+  "manifest_version": "0.3",
+  "name": "doc-bridge",
+  "display_name": "Doc Bridge",
+  "version": "1.2.6",
+  "description": "Deterministic repository handoffs for coding agents, running locally without an LLM or API key.",
+  "long_description": "Doc Bridge turns a repository's own documentation and ownership metadata into deterministic handoffs: where an agent should start, which paths it may edit, which checks it must run, and when a human must take over. The local connector exposes the same read-only contract available through Doc Bridge CLI and CI.",
+  "author": {
+    "name": "AgentsKit",
+    "url": "https://agentskit.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AgentsKit-io/doc-bridge.git"
+  },
+  "homepage": "https://doc-bridge.agentskit.io/",
+  "documentation": "https://doc-bridge.agentskit.io/docs/mcp",
+  "support": "https://github.com/AgentsKit-io/doc-bridge/issues",
+  "icon": "icon.png",
+  "server": {
+    "type": "node",
+    "entry_point": "server/ak-docs.js",
+    "mcp_config": {
+      "command": "node",
+      "args": [
+        "${__dirname}/server/ak-docs.js",
+        "mcp",
+        "--config",
+        "${user_config.project_config}"
+      ],
+      "env": {}
+    }
+  },
+  "tools": [
+    {
+      "name": "handoff.resolve",
+      "description": "Resolve a package or ownership id to its deterministic AgentHandoff."
+    },
+    {
+      "name": "doc.search",
+      "description": "Search the deterministic Doc Bridge index for repository documentation."
+    },
+    {
+      "name": "doc.get",
+      "description": "Read one indexed agent documentation file by id or indexed path."
+    },
+    {
+      "name": "gate.status",
+      "description": "Evaluate documentation gates without writing files."
+    },
+    {
+      "name": "retriever.query",
+      "description": "Return relevant local Doc Bridge index chunks for a query."
+    },
+    {
+      "name": "memory.classify",
+      "description": "Classify local memory candidates into agent, human, playbook, or discard routes."
+    },
+    {
+      "name": "memory.promoteDraft",
+      "description": "Build a reviewable draft promotion body from local memory candidates without publishing it."
+    },
+    {
+      "name": "registry.topology",
+      "description": "Return the static Doc Bridge curator and delegate topology."
+    }
+  ],
+  "tools_generated": false,
+  "keywords": [
+    "coding-agents",
+    "documentation",
+    "handoff",
+    "repository",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "privacy_policies": [
+    "https://github.com/AgentsKit-io/doc-bridge/blob/master/PRIVACY.md"
+  ],
+  "compatibility": {
+    "platforms": [
+      "darwin"
+    ],
+    "runtimes": {
+      "node": ">=22"
+    }
+  },
+  "user_config": {
+    "project_config": {
+      "type": "file",
+      "title": "Doc Bridge configuration",
+      "description": "Select the doc-bridge.config.json file at the root of the repository Doc Bridge may read.",
+      "required": true
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/doc-bridge",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "mcpName": "io.github.AgentsKit-io/doc-bridge",
   "description": "Human↔agent documentation bridge — deterministic handoffs, doc-site links, memory→docs, optional AgentsKit RAG/chat.",
   "type": "module",
@@ -31,11 +31,13 @@
     "docs",
     "examples",
     "README.md",
+    "PRIVACY.md",
     "CONTRIBUTING.md",
     "SECURITY.md",
     "CODE_OF_CONDUCT.md",
     "CHANGELOG.md",
     "LICENSE",
+    "mcpb",
     "tsup.config.ts",
     "tsconfig.json",
     "src"
@@ -53,6 +55,11 @@
     "smoke:docsites": "node scripts/smoke-docsites.mjs",
     "smoke:real-docsites": "node scripts/smoke-real-docsites.mjs",
     "smoke:ollama": "node scripts/smoke-ollama.mjs",
+    "mcpb:stage": "npm run build && node scripts/build-mcpb.mjs stage",
+    "mcpb:validate": "node scripts/build-mcpb.mjs validate",
+    "mcpb:smoke": "node scripts/smoke-mcpb.mjs",
+    "mcpb:pack": "npm run mcpb:stage && npm run mcpb:smoke && node scripts/build-mcpb.mjs pack",
+    "test:mcpb": "node --test scripts/mcpb-contract.test.mjs",
     "coverage:badge": "node scripts/update-coverage-badge.mjs",
     "changeset": "changeset",
     "version-packages": "changeset version && node scripts/sync-version.mjs",
@@ -132,6 +139,7 @@
     "@agentskit/core": "1.12.3",
     "@agentskit/ink": "0.10.4",
     "@agentskit/react": "0.7.4",
+    "@anthropic-ai/mcpb": "2.1.2",
     "@changesets/cli": "^2.31.0",
     "@lhci/cli": "^0.15.1",
     "@playwright/test": "1.61.1",
@@ -140,11 +148,12 @@
     "@types/react": "19.2.17",
     "@types/react-dom": "19.2.3",
     "@vitest/coverage-v8": "4.1.10",
+    "esbuild": "^0.28.1",
     "fumadocs-core": "15.6.5",
     "fumadocs-mdx": "11.6.4",
     "fumadocs-ui": "15.6.5",
     "lucide-react": "0.460.0",
-    "next": "15.5.19",
+    "next": "15.5.21",
     "react": "19.2.0",
     "react-dom": "19.2.0",
     "tailwindcss": "4.3.2",
@@ -152,14 +161,6 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
   },
-  "pnpm": {
-    "overrides": {
-      "esbuild": "^0.28.1",
-      "postcss": "8.5.19",
-      "tmp": "0.2.7",
-      "uuid": "11.1.1"
-    }
-  },
   "directories": {
     "doc": "docs",
     "example": "examples",

package/src/mcp/server.ts

@@ -30,7 +30,9 @@ type McpContext = {
 export const MCP_TOOLS = [
   {
     name: 'handoff.resolve',
-    description: 'Resolve a package or ownership id to an AgentHandoff.',
+    title: 'Resolve repository handoff',
+    description: 'Resolve a package or ownership id to its deterministic AgentHandoff.',
+    annotations: { readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string' }, kind: { type: 'string', enum: ['package', 'ownership'] } },
@@ -39,7 +41,9 @@ export const MCP_TOOLS = [
   },
   {
     name: 'doc.search',
-    description: 'Search the deterministic doc-bridge index.',
+    title: 'Search repository documentation',
+    description: 'Search the deterministic Doc Bridge index for repository documentation.',
+    annotations: { readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: { term: { type: 'string' }, limit: { type: 'number' } },
@@ -48,7 +52,9 @@ export const MCP_TOOLS = [
   },
   {
     name: 'doc.get',
-    description: 'Read an indexed agent documentation file by id or path.',
+    title: 'Read indexed documentation',
+    description: 'Read one indexed agent documentation file by id or indexed path.',
+    annotations: { readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string' }, path: { type: 'string' } },
@@ -56,12 +62,16 @@ export const MCP_TOOLS = [
   },
   {
     name: 'gate.status',
-    description: 'Run the index-freshness gate.',
+    title: 'Check documentation gates',
+    description: 'Evaluate documentation gates without writing files.',
+    annotations: { readOnlyHint: true },
     inputSchema: { type: 'object', properties: {} },
   },
   {
     name: 'retriever.query',
-    description: 'Return local doc-bridge retriever chunks for a query.',
+    title: 'Retrieve documentation context',
+    description: 'Return relevant local Doc Bridge index chunks for a query.',
+    annotations: { readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: { query: { type: 'string' }, limit: { type: 'number' } },
@@ -70,17 +80,23 @@ export const MCP_TOOLS = [
   },
   {
     name: 'memory.classify',
-    description: 'Classify local memory candidates into agent/human/playbook/discard routes.',
+    title: 'Classify memory candidates',
+    description: 'Classify local memory candidates into agent, human, playbook, or discard routes.',
+    annotations: { readOnlyHint: true },
     inputSchema: { type: 'object', properties: {} },
   },
   {
     name: 'memory.promoteDraft',
-    description: 'Build a safe draft promotion body for local memory candidates.',
+    title: 'Draft memory promotion',
+    description: 'Build a reviewable draft promotion body from local memory candidates without publishing it.',
+    annotations: { readOnlyHint: true },
     inputSchema: { type: 'object', properties: {} },
   },
   {
     name: 'registry.topology',
-    description: 'Return the doc-curator registry topology.',
+    title: 'Inspect registry topology',
+    description: 'Return the static Doc Bridge curator and delegate topology.',
+    annotations: { readOnlyHint: true },
     inputSchema: { type: 'object', properties: {} },
   },
 ] as const
@@ -223,12 +239,14 @@ export const handleMcpRequest = (ctx: McpContext, request: JsonRpcRequest): unkn
   throw new Error(`Unsupported MCP method "${request.method ?? ''}"`)
 }
 
-const writeFrame = (payload: unknown): void => {
+type StdioFraming = 'content-length' | 'json-line'
+
+const writeFrame = (payload: unknown, framing: StdioFraming): void => {
   const body = JSON.stringify(payload)
-  process.stdout.write(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`)
+  process.stdout.write(framing === 'json-line' ? `${body}\n` : `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`)
 }
 
-const respond = (ctx: McpContext, request: JsonRpcRequest): void => {
+const respond = (ctx: McpContext, request: JsonRpcRequest, framing: StdioFraming): void => {
   if (request.id === undefined) {
     try {
       handleMcpRequest(ctx, request)
@@ -240,13 +258,13 @@ const respond = (ctx: McpContext, request: JsonRpcRequest): void => {
 
   try {
     const result = handleMcpRequest(ctx, request)
-    writeFrame({ jsonrpc: '2.0', id: request.id, result: result ?? {} })
+    writeFrame({ jsonrpc: '2.0', id: request.id, result: result ?? {} }, framing)
   } catch (error) {
     writeFrame({
       jsonrpc: '2.0',
       id: request.id,
       error: { code: -32000, message: error instanceof Error ? error.message : String(error) },
-    })
+    }, framing)
   }
 }
 
@@ -255,21 +273,35 @@ export const startMcpStdioServer = (ctx: McpContext): void => {
   process.stdin.on('data', (chunk: Buffer) => {
     buffer = Buffer.concat([buffer, chunk])
     while (true) {
-      const headerEnd = buffer.indexOf('\r\n\r\n')
-      if (headerEnd === -1) return
-      const header = buffer.subarray(0, headerEnd).toString('utf8')
-      const match = /content-length:\s*(\d+)/i.exec(header)
-      if (!match?.[1]) {
-        buffer = buffer.subarray(headerEnd + 4)
+      if (/^content-length:/i.test(buffer.subarray(0, Math.min(buffer.length, 32)).toString('utf8'))) {
+        const headerEnd = buffer.indexOf('\r\n\r\n')
+        if (headerEnd === -1) return
+        const header = buffer.subarray(0, headerEnd).toString('utf8')
+        const match = /content-length:\s*(\d+)/i.exec(header)
+        if (!match?.[1]) {
+          buffer = buffer.subarray(headerEnd + 4)
+          continue
+        }
+        const length = Number(match[1])
+        const bodyStart = headerEnd + 4
+        const bodyEnd = bodyStart + length
+        if (buffer.length < bodyEnd) return
+        const raw = buffer.subarray(bodyStart, bodyEnd).toString('utf8')
+        buffer = buffer.subarray(bodyEnd)
+        respond(ctx, JSON.parse(raw) as JsonRpcRequest, 'content-length')
         continue
       }
-      const length = Number(match[1])
-      const bodyStart = headerEnd + 4
-      const bodyEnd = bodyStart + length
-      if (buffer.length < bodyEnd) return
-      const raw = buffer.subarray(bodyStart, bodyEnd).toString('utf8')
-      buffer = buffer.subarray(bodyEnd)
-      respond(ctx, JSON.parse(raw) as JsonRpcRequest)
+
+      const lineEnd = buffer.indexOf('\n')
+      if (lineEnd === -1) return
+      const raw = buffer.subarray(0, lineEnd).toString('utf8').trim()
+      buffer = buffer.subarray(lineEnd + 1)
+      if (!raw) continue
+      try {
+        respond(ctx, JSON.parse(raw) as JsonRpcRequest, 'json-line')
+      } catch {
+        writeFrame({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }, 'json-line')
+      }
     }
   })
   process.stdin.resume()

package/src/version.ts

@@ -1 +1 @@
-export const PACKAGE_VERSION = '1.2.4'
+export const PACKAGE_VERSION = '1.2.6'