Skip to main content
Glama

Cedulon

面向代理间花费的审计层:已签名的交易清单、fail-closed(失败即拒绝)策略、已签名的花费收据(可锚定到 SCITT)。

Cedulon 不是支付通道。它位于 x402 和 AP2 之上。

这些包发布在 npm 上,MCP 服务器收录在 MCP Registry 中,但这里没有任何涉及真实资金的部分:没有真实钱包,也没有网络支付通道,只有模拟夹具。cedulon_spend 在模拟通道上结算,并在其自身描述中对此作了说明。

核心包零运行时依赖;MCP 服务器包只依赖官方 MCP SDK。

环境要求

  • Node.js 22 或更高版本(库需要 20+;脚本使用 Node 的类型剥离功能)

  • npm 10 或更高版本

Related MCP server: wwall

安装与运行(全新克隆)

npm install
npx tsc --noEmit
npm run test:all
npm run demo

npm run tamper 预期以非零状态退出(被篡改的字节无法通过校验)。

npm run demo:unguarded 展示未受保护的漏洞:100/100 全部放行。

npm run audit 必须以 0 退出(audit: balanced)。

npm run demo:bypass 必须以非零状态退出:audit: 1 settlement without receipt → FAIL。

npm run demo:bypasses 打印四行 FAIL(缺少收据、金额错误、空引用、垃圾链头),并且只有当每个绕过都被捕获时才以 0 退出;漏掉任何一个绕过都会使其以非零状态退出。

npm run demo:live 对真实的 Base Sepolia USDC 时间窗口进行对账,而不是使用模拟夹具。只读:它只需要在 CEDULON_RPC_URL 中提供一个 RPC URL,不需要钱包、密钥或交易。如果针对一个你不持有其收据的账户运行,链上报告的每一笔结算都会以缺口(gap)的形式返回。

第三方无需信任我们即可复现这一点:docs/RUN_AS_VERIFIER.md。

五分钟上手路径,包括 MCP 主机配置:docs/QUICKSTART.md。

MCP 服务器

Cedulon 可以作为本地 stdio MCP 服务器运行。主机通过 stdin/stdout 进行 JSON-RPC 通信。这五个工具只是对现有包的薄封装;它们不会重新实现策略、收据或审计。

工具

参数

结果

cedulon_spend

amount(字符串)、currency、payee、nonce,可选 tool

允许 → 返回已签名的收据 JSON。拒绝 → { ok: false, reason }(例如 limit-amount)。

cedulon_audit

可选 extraSettlements[](ref、amount、currency、timestampMs)

{ ok, summary, findings }。账目平衡时打印 audit: balanced。

cedulon_verify_receipt

receipt 对象,或 coseHex + publicKeyPem,可选的 countersignature 字段

{ ok, receipt, countersignature }

cedulon_export_ledger

无

以 demo:export JSON 形状返回收据 + 检查点 + 提取数据

cedulon_status

无

{ version, policy, receiptCount, chainHead }

Claude Desktop / Claude Code / Cursor。无需克隆,也无需构建:

{
  "mcpServers": {
    "cedulon": {
      "command": "npx",
      "args": ["-y", "@cedulon/mcp-server"]
    }
  }
}

在 Claude Code 中,该配置只需一条命令:

claude mcp add cedulon -- npx -y @cedulon/mcp-server

策略上限来自环境变量:CEDULON_MAX_AMOUNT、 CEDULON_MAX_CUMULATIVE、CEDULON_MAX_PAYMENTS、CEDULON_WINDOW_MS、 CEDULON_ALLOWED_PAYEES、CEDULON_ALLOWED_CURRENCIES、 CEDULON_ALLOWED_TOOLS、CEDULON_PAYER。设置 CEDULON_STATE_PATH 可在重启后保留收据链;不设置时,账本只保存在内存中。

如果改为在本仓库内基于源码工作:

npm run mcp

该服务器在 MCP Registry 中以 io.github.dogrucanemek-alt/cedulon 的名称收录;server.json 是它发布时使用的入口。

npm run mcpb 构建一个 .mcpb 捆绑包——一个包含服务器及其依赖的 zip 文件,桌面主机可一键安装,策略上限以设置项的形式暴露。它安装的是已发布的 npm 包,而不是打包工作树,因此捆绑包中的内容与 npm 交付给您的完全一致,并且该版本必须已经发布。结果输出到 build/,它是发布产物,不是源码。

smithery.yaml 是较旧的生态格式,不会被提交;Smithery 当前的接入说明接受 HTTPS 端点或 .mcpb 捆绑包。

目录结构

packages/core           policy engine + Decision Token (workspace dep on @cedulon/cose)
packages/cose           deterministic CBOR + COSE_Sign1 (Ed25519)
packages/manifest       signed trade manifest
packages/receipts       spend receipt (COSE default, JSON legacy)
packages/checkpoint     epoch checkpoints + in-process transparency log
packages/audit          rail-extract completeness checker
packages/mcp-guard      MCP tools/call wrapper (mock)
packages/mcp-server     stdio MCP server (official SDK)
packages/x402-adapter   HTTP 402 adapter + mock rail extract
packages/base-extract   read-only Base Sepolia USDC → RailExtract
examples/demo           runaway, dispute, bypass, audit CLI
spec/                   draft-dogru-cedulon-01 (current), -00, plus the
                        reattestation and streaming drafts
THREAT_MODEL.md
docs/RUN_AS_VERIFIER.md

品牌名称仅来自 packages/core/src/brand.ts。

如何引用

引用元数据位于 CITATION.cff。已存档的 -00 版本发布在 https://doi.org/10.5281/zenodo.22099792

许可证

Apache-2.0

Available Tools

5 tools
cedulon_auditA
Read-only

Reconcile the in-process receipt chain and checkpoint against the rail extract: this server's own ledger, or a signed extract you present. Returns audit: balanced or findings, names the account, rail and window it was computed over (scope) when an extract declared one, and counts the class every receipt and row landed in (counts).

Inputs: trust, extract, manifest, payeeTrust, +4 more.

cedulon_export_ledgerA
Read-only

Export receipts, checkpoint, and rail extract in the same JSON shape as npm run demo:export, with the findings, guarantee and counts of the audit over this server's own ledger. A stored checkpoint whose encoding is not strict hex reports hash: null.

Inputs: no named parameters.

cedulon_spendA

Policy-gated spend on the mock rail. Allow returns a signed COSE receipt JSON. Deny returns the fail-closed reason.

Inputs: nonce (required), payee (required), amount (required), currency (required), +1 more.

cedulon_statusA
Read-only

Server version, policy summary, receipt count, and chain head hash.

Inputs: no named parameters.

cedulon_verify_receiptA
Read-only

Verify a spend receipt COSE_Sign1 (and payee countersignature when present). Supply expectIssuerKeyPem to check it against a key you already hold; without one the receipt is only checked against the key it carries, which any key satisfies.

Inputs: coseHex, receipt, publicKeyPem, counterCoseHex, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 5 tools

    Disambiguation4/5

    Each tool targets a distinct verb-object pair: audit reconciles, export_ledger serializes, spend executes, status reports, verify_receipt validates. The only mild overlap is between cedulon_audit and cedulon_export_ledger, since export includes audit findings, but descriptions make the distinction (export is a data dump, audit is a reconciliation verdict) reasonably clear.

    Naming Consistency5/5

    All five tools share the cedulon_ prefix followed by a lowercase verb or verb_noun (audit, export_ledger, spend, status, verify_receipt). The single deviation is status, a noun rather than a verb, but it reads naturally as a state query and does not break the pattern.

    Tool Count4/5

    Five tools is on the thin side but each corresponds to a real lifecycle step of the receipt/policy/rail domain: spend, reconcile, verify, inspect state, export. Nothing appears redundant, though a server this specialized could arguably use a policy-configuration tool.

    Completeness3/5

    The core loop (policy-gated spend, receipt verification, chain audit, status, export) is covered, but there are notable gaps: no tool to manage or update the spend policy, no receipt lookup or paginated receipt listing, and no checkpoint reset or repair operation. An agent hitting a stale or non-strict-hex checkpoint can only observe the failure, not remediate it.

    Maintenance

    ActivityActive
    ResponsivenessMixed handling

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to propose wallet payments while a local, human-authored policy decides whether each transaction is approved, requires human confirmation, or is refused, and records every decision in a signed, append-only ledger.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP-speaking agents to execute tool calls through an authorization gate, producing signed decision records and reconciled effect rows for accountability.
      6
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to inspect, check, and audit signed offline spending authorizations, and to issue hash-chained receipts for each action taken against them. Enforces per-transaction, total, expiry, merchant, and human-approval constraints, returning allow, needs_human, or deny with the specific failing constraint.
      Apache 2.0