@agentskit/doc-bridge 1.2.4 → 1.2.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.2.6
+
+### Patch Changes
+
+- Restore the stable release security gate with patched Next.js and Sharp versions and pnpm 11-compatible dependency overrides.
+
+## 1.2.5
+
+### Patch Changes
+
+- d2429f4: Add read-only MCP tool annotations, a public privacy policy, and deterministic MCPB packaging for local Claude Desktop installation.
+
 ## 1.2.4
 
 ### Patch Changes
@@ -34,6 +46,7 @@
 
 ### Features
 
+- Add read-only MCP tool annotations, a public privacy policy, and validated MCPB packaging for local Claude Desktop installation.
 - Migrate the documentation portal dogfood from AgentsKit Chat 0.2 packages (`@agentskit/chat-protocol`, `@agentskit/chat-react`) to the consolidated 0.3.x surface (`@agentskit/chat/protocol`, `@agentskit/chat/react`) while keeping `@agentskit/chat` as the root package.
 - Replace the legacy Pages landing with a statically exported Fumadocs portal backed directly by the canonical `docs/**` corpus.
 - Generate `llms.txt`, `llms-full.txt`, raw Markdown, and a hash-verified deterministic AgentsKit Chat artifact from the repository's own Doc Bridge index.

package/CONTRIBUTING.md

@@ -19,6 +19,7 @@ pnpm build
 - Add or update the smallest test that would fail if the behavior regresses.
 - Public contract changes must update the relevant docs under `docs/spec/` or `docs/schemas/`.
 - Dogfood AgentsKit Chat 0.4.x only: `@agentskit/chat`, `@agentskit/chat/protocol`, and `@agentskit/chat/react`. Never reintroduce `@agentskit/chat-protocol` or `@agentskit/chat-react` (`pnpm check:no-legacy-chat-imports`).
+- Never commit API keys, tokens, secrets, or private repository content.
 
 ## Pull request checklist
 
@@ -38,3 +39,8 @@ pnpm release
 ```
 
 Do not publish from a dirty worktree.
+
+Project decisions and maintainer responsibilities are documented in
+[GOVERNANCE.md](GOVERNANCE.md). By participating, you agree to follow the
+[Code of Conduct](CODE_OF_CONDUCT.md). Report vulnerabilities through the
+private process in [SECURITY.md](SECURITY.md).

package/PRIVACY.md

@@ -0,0 +1,38 @@
+# Privacy Policy
+
+Effective date: July 31, 2026
+
+This policy covers the local Doc Bridge MCP server distributed by AgentsKit, including its MCP Bundle for Claude Desktop.
+
+## Data the connector accesses
+
+Doc Bridge accesses only the local project selected by the user through its `doc-bridge.config.json` file. Within that project, its MCP tools may read:
+
+- the Doc Bridge configuration and deterministic index;
+- documentation files explicitly included in that index;
+- ownership and package metadata described by the configuration;
+- `.agent-memory/**` and `.cursor/rules/*.mdc` when the user calls a memory-classification or draft-promotion tool.
+
+Doc Bridge does not read Claude conversation history, Claude memory, browser data, credentials, or files outside the selected project boundary. Indexed-document reads reject paths and symbolic links that resolve outside that boundary.
+
+## Collection, use, and storage
+
+The local MCP server uses project data only to return the handoff, search, documentation, gate, retrieval, memory-classification, draft, or topology result requested by the user. The eight MCP tools are read-only and do not modify project files or publish data.
+
+AgentsKit does not collect or store MCP requests, tool results, project files, or usage telemetry. Source files and any existing Doc Bridge index remain on the user's device and under the user's control.
+
+## Sharing and external services
+
+The local MCP server does not send project data to AgentsKit or another model provider and requires no API key. Claude Desktop receives tool results as the MCP client selected by the user; Anthropic's handling of data in Claude Desktop is governed by Anthropic's own terms and privacy policy.
+
+Optional Doc Bridge RAG and chat integrations are not enabled or bundled by this local connector. If a user separately configures an external adapter or model provider, that provider's privacy terms apply to the data the user chooses to send through that separate integration.
+
+## Retention and deletion
+
+AgentsKit retains no data from the local MCP server. Users control retention by managing their project files, Doc Bridge index, MCP client history, and installed MCP Bundle. Uninstalling the bundle removes the connector; deleting local project data remains the user's responsibility.
+
+## Contact
+
+Questions about this policy can be filed at https://github.com/AgentsKit-io/doc-bridge/issues. Security concerns should follow the private reporting process at https://github.com/AgentsKit-io/doc-bridge/security/policy.
+
+Material changes to this policy will be published in this repository with an updated effective date.

package/README.md

@@ -3,6 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@agentskit/doc-bridge?style=flat-square)](https://www.npmjs.com/package/@agentskit/doc-bridge)
 [![CI](https://img.shields.io/github/actions/workflow/status/AgentsKit-io/doc-bridge/ci.yml?branch=master&style=flat-square)](https://github.com/AgentsKit-io/doc-bridge/actions/workflows/ci.yml)
 [![Pages](https://img.shields.io/github/actions/workflow/status/AgentsKit-io/doc-bridge/pages.yml?branch=master&label=pages&style=flat-square)](https://doc-bridge.agentskit.io/)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13872/baseline)](https://www.bestpractices.dev/projects/13872)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D22-339933?style=flat-square)](package.json)
 [![TypeScript](https://img.shields.io/badge/types-TypeScript-3178c6?style=flat-square)](dist/index.d.ts)
@@ -122,6 +123,21 @@ ak-docs mcp install --cursor   # wires MCP into .cursor/mcp.json
 
 See [docs/getting-started.md](docs/getting-started.md), [docs/mcp.md](docs/mcp.md), and [docs/examples.md](docs/examples.md).
 
+## Claude Desktop MCP Bundle
+
+Doc Bridge can be packaged as a local MCP Bundle for Claude Desktop. The bundle keeps the eight MCP tools read-only and asks the user to select the repository's `doc-bridge.config.json`; that file defines the project boundary Doc Bridge may read.
+
+From a clean checkout:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm mcpb:pack
+```
+
+The command builds Doc Bridge, creates a production-only staging directory, validates the MCPB manifest, packs the extension, checks its file inventory, and writes the local artifact under `.mcpb-output/`. Generated bundles and staging directories are intentionally excluded from Git.
+
+Current packaged compatibility is macOS. Other operating systems will be declared only after the exact bundle passes an independent installation test there.
+
 ## Why this exists
 
 | Pattern | Gap |
@@ -299,6 +315,10 @@ pnpm smoke:ollama    # optional — skips if Ollama/peers unavailable
 
 **Landing:** https://doc-bridge.agentskit.io/
 
+## Privacy Policy
+
+The local MCP server reads only the project selected through `doc-bridge.config.json`. It does not require an API key, send project data to AgentsKit, collect telemetry, or write project files through its eight MCP tools. See the complete [Privacy Policy](PRIVACY.md) for accessed paths, use, storage, sharing, retention, optional integrations, and contact information.
+
 ## Contributing
 
 Issues and PRs are welcome. Start here:
@@ -306,6 +326,7 @@ Issues and PRs are welcome. Start here:
 | Need | Doc |
 |------|-----|
 | Local setup, tests, release flow | [CONTRIBUTING.md](CONTRIBUTING.md) |
+| Governance and maintainer responsibilities | [GOVERNANCE.md](GOVERNANCE.md) |
 | Vulnerability reports | [SECURITY.md](SECURITY.md) |
 | Community standards | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) |
 | Release history | [CHANGELOG.md](CHANGELOG.md) |

package/SECURITY.md

@@ -8,14 +8,19 @@ Security fixes target the latest stable `@agentskit/doc-bridge` release on npm.
 
 Please do not open a public issue for security reports.
 
-Email security reports to `security@agentskit.io` with:
+Use [GitHub private vulnerability reporting](https://github.com/AgentsKit-io/doc-bridge/security/advisories/new) when possible. If that channel is unavailable, email `security@agentskit.io`.
+
+Include:
 
 - affected version or commit
 - reproduction steps
 - impact
 - any suggested fix
 
-We will acknowledge reports as soon as practical and coordinate disclosure before publishing details.
+Please do not include secrets or private repository content beyond what is
+necessary to reproduce the issue. We aim to acknowledge a complete report
+within 14 days, investigate it, and coordinate disclosure and remediation with
+the reporter before publishing details.
 
 ## Security expectations
 

package/action.yml

@@ -20,7 +20,7 @@ inputs:
   package-version:
     description: Exact @agentskit/doc-bridge npm version (kept in sync with this Action release)
     required: false
-    default: '1.2.4'
+    default: '1.2.6'
 
 runs:
   using: composite

package/dist/cli/program.js

@@ -1347,7 +1347,7 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "1.2.4";
+var PACKAGE_VERSION = "1.2.6";
 
 // src/index-builder/capabilities.ts
 var renderCapabilitiesJson = (config, index, paths) => {
@@ -4080,7 +4080,9 @@ import { z as z6, ZodError } from "zod";
 var 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"] } },
@@ -4089,7 +4091,9 @@ var 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" } },
@@ -4098,7 +4102,9 @@ var 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" } }
@@ -4106,12 +4112,16 @@ var 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" } },
@@ -4120,17 +4130,23 @@ var 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: {} }
   }
 ];
@@ -4247,13 +4263,14 @@ var handleMcpRequest = (ctx, request) => {
   if (request.method?.startsWith("notifications/")) return void 0;
   throw new Error(`Unsupported MCP method "${request.method ?? ""}"`);
 };
-var writeFrame = (payload) => {
+var writeFrame = (payload, framing) => {
   const body = JSON.stringify(payload);
-  process.stdout.write(`Content-Length: ${Buffer.byteLength(body)}\r
+  process.stdout.write(framing === "json-line" ? `${body}
+` : `Content-Length: ${Buffer.byteLength(body)}\r
 \r
 ${body}`);
 };
-var respond = (ctx, request) => {
+var respond = (ctx, request, framing) => {
   if (request.id === void 0) {
     try {
       handleMcpRequest(ctx, request);
@@ -4263,13 +4280,13 @@ var respond = (ctx, request) => {
   }
   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: -32e3, message: error instanceof Error ? error.message : String(error) }
-    });
+    }, framing);
   }
 };
 var startMcpStdioServer = (ctx) => {
@@ -4277,21 +4294,34 @@ var startMcpStdioServer = (ctx) => {
   process.stdin.on("data", (chunk) => {
     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 raw2 = buffer.subarray(bodyStart, bodyEnd).toString("utf8");
+        buffer = buffer.subarray(bodyEnd);
+        respond(ctx, JSON.parse(raw2), "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));
+      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), "json-line");
+      } catch {
+        writeFrame({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } }, "json-line");
+      }
     }
   });
   process.stdin.resume();