cedulon
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 demonpm 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 通信。这五个工具只是对现有包的薄封装;它们不会重新实现策略、收据或审计。
工具 | 参数 | 结果 |
|
| 允许 → 返回已签名的收据 JSON。拒绝 → |
| 可选 |
|
|
|
|
| 无 | 以 |
| 无 |
|
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 toolscedulon_auditARead-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_ledgerARead-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_statusARead-only
Server version, policy summary, receipt count, and chain head hash.
Inputs: no named parameters.
cedulon_verify_receiptARead-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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
Governed agent execution: x402 payments, budgets, receipts, verification, and audit.
Agent-native MCP for governed commerce, x402 payments, paid capabilities, and verifiable receipts.
Scoped agent execution. Server-side credentials, policy, budgets and verifiable receipts.
Pre-execution policy gate for consequential agent actions with durable trust receipts.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceDeterministic, auditable payment policy enforcement for AI agents. It provides pre-action authorization with scopes, budgets, allowlists, and signed mandates via an MCP server.MIT
- FlicenseNot gradedqualityDmaintenanceEnables 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.-
- AlicenseAqualityBmaintenanceEnables MCP-speaking agents to execute tool calls through an authorization gate, producing signed decision records and reconciled effect rows for accountability.6Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables 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