touchstone-mcp

@touchstone/mcp-server

四工具 MCP 服务 — build1-spec.md §9。get_index 免费；get_quote、convert 和 verify_receipt 通过 Circle 的 Gateway nanopayments（@circle-fin/x402-batching）设置付费墙， 以 USDC 结算。

工具	返回内容	价格
get_index(version?, date?)	已签名的印本	免费
get_quote(task_class, model)	SIU 价格、汇率、指数引用	$0.001
convert(model, input_tokens, output_tokens)	SIU + USD 等值金额	$0.001
verify_receipt(chain, tx_hash)	已签名的证明：报价金额、已付金额与匹配结果	$0.01

传输方式为 Streamable HTTP（POST /mcp），而非 stdio — x402 是一种 HTTP 状态码协议，因此 付费工具需要 HTTP 层来返回 402。verify_receipt 的链上读取为实时读取 （src/settlement/on-chain.ts），读取真实部署的 TouchstoneEscrow （data/deployments/base-sepolia.json）—— StubSettlementReader（src/settlement/reader.ts） 仍用于测试，以及在未配置区块链时运行服务；这与 @touchstone/print 使用 StubAttestationClient 的模式相同。

在本地运行（Node/Express）

export TOUCHSTONE_ATTESTATION_KEY=0x...  # signs receipts — a dedicated key, never
                                          # TOUCHSTONE_PUBLISHER_KEY, which signs prints and
                                          # anchors on-chain and has no business on this
                                          # public-facing service
export TOUCHSTONE_SELLER_ADDRESS=0x...   # receives USDC payments through Gateway
pnpm run start                       # builds, then listens on $PORT (default 3000)

两个环境变量都是必需的，且没有默认值 — 未完成配置时，服务会拒绝启动，而不会继续运行。 data/prints/ 至少需要一个已发布的印本（pnpm --filter @touchstone/print run publish-print），这样 get_index/get_quote/convert 才有实际数据可提供。

已部署：Cloudflare Workers（mcp.touchstoneassay.com）

线上公开部署位于 src/workers/ — 使用不同的传输方式（Hono + Cloudflare 的 McpAgent，由 Durable Object 支持）和不同的数据加载层（通过 KV 缓存从本仓库公开的 GitHub 内容中获取数据， 因为 Workers 没有文件系统），但提供完全相同的四种工具和完全相同的付费墙逻辑 （../paywall.ts，通过精简的 req/res shim — src/workers/node-shim.ts — 运行， 而非重新实现）。各部分的设计理由见该目录中的文件；wrangler.jsonc 是绑定和路由的权威配置源。

安全边界： 此 Worker 上绝不会出现 TOUCHSTONE_PUBLISHER_KEY — 无论是作为密钥、 变量，还是通过传递依赖引入。唯一的密钥是 TOUCHSTONE_ATTESTATION_KEY，仅用于签署 收据，不做其他任何用途（不锚定、不发起交易、不处理资金）。所有其他绑定均为非敏感信息： 链名称、公开合约地址、公开 RPC URL，以及 TOUCHSTONE_SELLER_ADDRESS（现有托管资金地址，复用为收款地址 — 此 Worker 上根本不存在该地址对应的私钥）。

一次性设置：

npx wrangler login
npx wrangler kv namespace create PRINTS_CACHE   # then paste the id into wrangler.jsonc
npx wrangler secret put TOUCHSTONE_ATTESTATION_KEY

为账户启用一次 Analytics Engine（只能通过仪表盘操作，没有 API/CLI 路径）： https://dash.cloudflare.com/<account-id>/workers/analytics-engine — 如果未完成此操作， 使用情况日志记录（src/workers/analytics.ts）会降级为捕获错误并记录日志后不执行操作，因此绝不会 阻塞服务的其他部分；但要实现其用途（证明采用情况 — 调用次数、不同的付款方地址），就需要启用它。

部署：

pnpm run deploy   # wrangler deploy

更改 wrangler.jsonc 中的任何绑定后，都要重新运行 npx wrangler types — 已提交的 worker-configuration.d.ts 是根据该文件生成的，也是 Env 能满足 agents 的 McpAgent<Env, ...> 泛型约束的关键；如果副本过时，TouchstoneMcpAgent 中的 this.env 会悄然失效。

将此服务列入目录

官方 MCP 注册表（registry.modelcontextprotocol.io）

src/manifest/server.json 是一个符合架构的清单（已根据 static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json 验证），其中包含 remotes: [{ type: "streamable-http", url }] —— 其中的 URL 是占位符（https://mcp.touchstone-assay.example/mcp， 使用了 RFC 2606 保留的 .example 域名），发布前必须替换为实际部署 URL。

curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
mcp-publisher login github
mcp-publisher publish

清单中的 name（io.github.petrkrulis2022/touchstone-mcp）归属于 GitHub-OAuth 命名空间所有权——mcp-publisher login github 必须通过与该命名空间匹配的账户进行身份验证，否则发布会被拒绝。

Smithery、Glama、PulseMCP、mcp.so

每个平台都有自己的提交流程（通常是通过其控制面板关联 GitHub 仓库，或使用特定于注册表的清单文件），且本软件包构建期间并未根据实时文档验证这些流程——提交前请直接查阅各注册表的最新文档，不要轻信这里的摘要，因为你阅读时它可能已经过时。