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 分