Bolyra

io.github.bolyra由 GitHub 账号 bolyra 发布v0.6.4更新于 Oct 24, 2026

MCP auth middleware: gate tool calls so only authorized agents can act.

已验证STDIO仅桌面开发者工具安全与监控

概览

AI 生成的概览

为 MCP 服务器加入 Bolyra 零知识证明鉴权的库，使只有获授权的代理才能调用敏感工具。

可以做什么
  • 包装 MCP 服务器，使每次工具调用都必须携带 Bolyra 证明包（stdio 走请求元数据，HTTP 走 Authorization 头）。
  • 校验人类与代理双方的证明、nonce 新鲜度和最低分数后才放行调用。
  • 按工具权限策略比对代理的有效位掩码，并支持多跳委托链。
  • 提供客户端附加证明、离线校验证明包和检查工具策略的辅助函数。
  • 支持开发模式，用模拟证明和固定种子身份在本地测试。
适用场景
适用于你自己开发或运维的 MCP 服务器，且其工具涉及敏感数据或操作，需要密码学证明人类已授权调用方代理。它是开发库而非现成工具服务器，只有在你编写自己的 MCP 服务器或客户端时才值得引入。
运行要求
以 npm 包形式与 MCP SDK、Bolyra SDK 一同安装，作为本地进程运行在用户机器上。生产环境需要凭据解析器、电路产物文件、RPC 地址和注册合约地址；开发模式不需要电路产物。
安装前请注意
开发模式使用模拟证明和固定种子身份，文档明确说明不可用于生产；若保持开启则鉴权形同虚设。生产配置涉及区块链 RPC 端点和注册合约地址；该库管控的工具调用可能读写数据，策略配置错误会误放行或误拦截工具。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Bolyra，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

@bolyra/mcp

Gate MCP tool calls so only authorized agents can call sensitive tools.

Quick Start (60 seconds)

bash
npm install @bolyra/mcp @bolyra/sdk @modelcontextprotocol/sdk
typescript
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,  },});

That's it. Every tools/call now requires a valid Bolyra proof bundle.

Dev mode (full example)

Dev mode uses mock proofs — no circuit artifacts, no trusted setup, instant startup. Use it to build and test your server before wiring real ZKP verification.

ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';import { withBolyraAuthStdio } from '@bolyra/mcp';
// Serverconst 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());

Client side:

ts
import { createDevIdentities, attachBolyraProof } from '@bolyra/sdk';
const { human, agent } = await createDevIdentities();const auth = await attachBolyraProof(human, agent, { devMode: true });
// stdioawait client.callTool({ name: 'read_file', arguments: { path: '/tmp/x' }, _meta: auth.meta });// HTTPawait fetch('/mcp', { headers: { ...auth.headers }, ... });

How it works

Every tools/call request must carry a proof bundle: a pair of Groth16 proofs (one from the human's circuit, one from the agent's) bound to a shared session nonce.

The server side:

  1. Extracts the bundle from params._meta.bolyra (stdio) or the Authorization: Bolyra <base64> header (HTTP).
  2. Verifies the handshake — both proofs, nonce freshness, score floor.
  3. Checks the tool's permission policy against the agent's effective bitmask.
  4. Attaches a BolyraAuthContext to the request for downstream handlers.
  5. Rejects with an MCP error if any step fails.

Discovery calls (initialize, tools/list) pass through unauthenticated.

Delegation chains (v=2 bundles) narrow scope from root credential to leaf agent across multiple hops. The effective bitmask seen by tool policies is always the leaf's — the most-restricted scope.

API reference

Server — stdio

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

Wraps an McpServer instance. Must be called before server.connect(transport).

Server — HTTP

ts
bolyraAuthMiddleware(config: BolyraMcpHttpConfig): express.RequestHandler

Express middleware. Mount before your MCP HTTP handler. Rejects unauthenticated tools/call requests with HTTP 401.

Client helpers

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

Runs a handshake and returns { headers, meta, bundle }. Pass options.devMode = true to skip real proving and emit a mock bundle.

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

Like attachBolyraProof but walks a delegation chain and returns a v=2 bundle.

Verification

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

Verify a bundle directly — useful for custom transports or offline verification.

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

Check a BolyraAuthContext against a tool's required bitmask.

Dev identities (re-exported from SDK)

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

Returns fixed-seed { human, agent, operatorKey } — deterministic, no circuit artifacts required. Logs a warning on first call. Never use in production.

Production configuration

Swap devMode: true for a real resolveCredential resolver and point the SDK at your circuit artifacts:

ts
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',  },});

Full config interface:

ts
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;}

The HTTP variant adds authScheme?: string (default "Bolyra").

Transport guide

TransportBundle locationNotes
stdio (Claude Desktop, Cursor, Cline)params._meta.bolyraMCP spec defines no stdio auth surface; _meta is the only protocol-level field
HTTP / SSE / Streamable-HTTPAuthorization: Bolyra <base64-bundle>Custom auth scheme per RFC 7235; aligns with OAuth 2.1 resource-server pattern

Both produce the same BolyraAuthContext on the server side. Tool handlers don't need to know which transport was used.

Example

See examples/protected-file-server/ for a complete stdio server + client pair using dev mode. Run it with:

bash
cd integrations/mcpnpm run example:protected-file-server

来源：integrations/mcp/README.md，提交 5e9de85

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v0.6.4最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分