bolyra

@bolyra/mcp

为 MCP 工具调用设置访问门控，确保只有获授权的 Agent 才能调用敏感工具。

快速开始（60 秒）

npm install @bolyra/mcp @bolyra/sdk @modelcontextprotocol/sdk

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { withBolyraAuthStdio } from '@bolyra/mcp';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

server.tool('read_file', { path: { type: 'string' } }, async (args) => ({
  content: [{ type: 'text', text: `Reading ${args.path}` }],
}));

withBolyraAuthStdio(server.server, {
  devMode: true,
  toolPolicy: {
    // 1n = READ_DATA, 2n = WRITE_DATA (BigInt — add 'n' suffix)
    read_file: 1n,
  },
});

就这么简单。现在，每个 tools/call 都需要有效的 Bolyra 证明包。

开发模式（完整示例）

开发模式使用模拟证明——无需电路制品、无需可信设置，即可立即启动。可用它在接入真实 ZKP 验证前构建和测试服务。

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { withBolyraAuthStdio } from '@bolyra/mcp';

// Server
const server = new McpServer({ name: 'my-server', version: '1.0.0' });

server.tool('read_file', { path: { type: 'string' } }, async (args) => ({
  content: [{ type: 'text', text: 'file contents...' }],
}));

withBolyraAuthStdio(server.server, {
  devMode: true,
  toolPolicy: {
    // 1n = READ_DATA, 2n = WRITE_DATA (BigInt — add 'n' suffix)
    read_file: 1n,
    write_file: 2n,
  },
});

await server.connect(new StdioServerTransport());

客户端：

import { createDevIdentities, attachBolyraProof } from '@bolyra/sdk';

const { human, agent } = await createDevIdentities();
const auth = await attachBolyraProof(human, agent, { devMode: true });

// stdio
await client.callTool({ name: 'read_file', arguments: { path: '/tmp/x' }, _meta: auth.meta });
// HTTP
await fetch('/mcp', { headers: { ...auth.headers }, ... });

工作原理

每个 tools/call 请求都必须携带一个证明包：一对 Groth16 证明（一个来自人类的电路，一个来自 Agent 的电路），并绑定到共享的会话随机数。

服务端：

1. 从 params._meta.bolyra（stdio）或 Authorization: Bolyra <base64> 标头（HTTP）中提取证明包。
2. 验证握手——包括两项证明、随机数时效性和分数下限。
3. 根据 Agent 的有效位掩码检查工具的权限策略。
4. 将 BolyraAuthContext 附加到请求，供下游处理程序使用。
5. 如果任何步骤失败，则返回 MCP 错误。

发现请求（initialize、tools/list）无需身份验证即可通过。

委托链（v=2 证明包）可跨多个跳转，将权限范围从根凭证逐级收窄至叶子 Agent。工具策略看到的有效位掩码始终属于叶子 Agent，即权限范围最受限的一方。

API 参考

服务端 — stdio

withBolyraAuthStdio(server: McpServer, config: BolyraMcpConfig): void

包装一个 McpServer 实例。必须在 server.connect(transport) 之前调用。

服务端 — HTTP

bolyraAuthMiddleware(config: BolyraMcpHttpConfig): express.RequestHandler

Express 中间件。应挂载在 MCP HTTP 处理程序之前。未通过身份验证的 tools/call 请求将被拒绝，并返回 HTTP 401。

客户端辅助函数

attachBolyraProof(
  human: HumanIdentity,
  agent: AgentCredential,
  options?: AttachProofOptions,
): Promise<BolyraClientAuth>

执行握手并返回 { headers, meta, bundle }。设置 options.devMode = true 可跳过真实证明流程，改为生成模拟证明包。

attachDelegatedBolyraProof(
  human: HumanIdentity,
  rootCred: AgentCredential,
  hops: DelegationHopSpec[],
  options?: AttachProofOptions,
): Promise<BolyraClientAuth>

与 attachBolyraProof 类似，但会遍历委托链并返回 v=2 证明包。

验证

verifyBundle(bundle: BolyraProofBundle, config: BolyraMcpConfig): Promise<BolyraAuthContext>

直接验证证明包——适用于自定义传输或离线验证。

checkToolPolicy(
  toolName: string,
  ctx: BolyraAuthContext,
  policy: ToolPermissionPolicy,
): { allowed: boolean; reason?: string }

检查 BolyraAuthContext 是否满足工具所需的位掩码。

开发身份（从 SDK 重新导出）

createDevIdentities(options?: DevIdentityOptions): Promise<DevIdentities>

返回固定种子的 { human, agent, operatorKey }——结果确定，无需电路制品。首次调用时会记录警告。切勿在生产环境中使用。

生产环境配置

将 devMode: true 替换为真实的 resolveCredential 解析器，并让 SDK 指向你的电路制品：

withBolyraAuthStdio(server, {
  resolveCredential: async (commitment) => myRegistry.get(commitment),
  toolPolicy: {
    // 1n = READ_DATA, 2n = WRITE_DATA (BigInt — add 'n' suffix)
    read_file: 1n,
    write_file: 2n,
  },
  sdkConfig: {
    circuitDir: '/path/to/circuits/build',
    rpcUrl: 'https://sepolia.base.org',
    registryAddress: '0x2781dF8b6381462d881C833Fb703d68c661c9577',
  },
});

完整配置接口：

interface BolyraMcpConfig {
  network?: string;          // DID network label (default: 'base-sepolia')
  minScore?: number;         // Minimum score floor 0–100 (default: 70)
  maxProofAge?: number;      // Nonce freshness window in seconds (default: 300)
  toolPolicy?: ToolPermissionPolicy;
  devMode?: boolean;         // Mock verification — dev/test only
  resolveCredential?: (commitment: string) => Promise<AgentCredential | null>;
  sdkConfig?: BolyraConfig;
}

HTTP 变体还会添加 authScheme?: string（默认值为 "Bolyra"）。

传输指南

传输方式	证明包位置	备注
stdio（Claude Desktop、Cursor、Cline）	params._meta.bolyra	MCP 规范未定义 stdio 身份验证接口；_meta 是协议层唯一可用的字段
HTTP / SSE / Streamable-HTTP	Authorization: Bolyra <base64-bundle>	根据 RFC 7235 定义的自定义身份验证方案；符合 OAuth 2.1 资源服务器模式

两种方式在服务端都会生成相同的 BolyraAuthContext。工具处理程序无需知道使用的是哪种传输方式。

示例

参见 examples/protected-file-server/，其中包含一个使用开发模式的完整 stdio 服务端和客户端。运行命令：

cd integrations/mcp
npm run example:protected-file-server