tctc-mcp

tctc-mcp

一个 MCP 服务，向 AI Agent 提供 ERC-7303（代币控制的代币流通）角色：Agent 检查自己在链上的权限，人类主体通过铸造／销毁控制代币来授予／撤销权限——无需权限服务端。

状态：v0.3.4 — 在 v0.2 的 IERC7303 自动发现基础上，新增支持定时角色及无 gas 自动过期（见下文）；已发布至 npm（tctc-mcp），已通过单元测试，并针对 Sepolia 演示部署完成端到端验证（授予 → 检查 → 撤销 → 检查，以及授予 75 秒 → 自动过期，均通过真实 MCP 客户端）。

演示（60 秒）

人类授予 AI Agent 铸造权限；Agent 在链上验证权限并铸造 NFT。人类销毁角色代币后，Agent 立即失去该能力。演示在 Sepolia 实时运行，无需权限服务端。

快速开始

此软件包已发布至 npm，因此无需克隆或构建——npx 会直接获取并运行：

# 1. Get a config. The secret-free Sepolia demo config needs no API keys:
curl -fsSLO https://raw.githubusercontent.com/kofujimura/tctc-mcp/main/examples/config.sepolia.agent.json

# 2. Register with your MCP client, e.g. Claude Code
#    (read-only mode: only query tools are registered)
claude mcp add tctc -- npx -y tctc-mcp --config "$PWD/config.sepolia.agent.json"

# Admin mode (principal side): grant_role / revoke_role also registered.
# Provide the issuer key ONLY via the environment:
claude mcp add tctc-admin --env TCTC_ADMIN_PRIVATE_KEY=0x... \
  -- npx -y tctc-mcp --config "$PWD/config.sepolia.json"

或者在项目级 .mcp.json 中配置：

{ "mcpServers": { "tctc": { "command": "npx",
    "args": ["-y", "tctc-mcp", "--config", "examples/config.sepolia.agent.json"] } } }

更完整的注册示例见 examples/claude.mcp.json。管理员私钥只会从 TCTC_ADMIN_PRIVATE_KEY 环境变量中读取；启动时会拒绝包含任何疑似私钥内容的配置。

在自己的应用中使用 tctc-mcp

唯一受支持的入口是 tctc-mcp bin——通过 npx --no-install tctc-mcp（或 node_modules/.bin/tctc-mcp）启动。切勿直接引用软件包的 dist/ 文件：它们属于内部实现，目录结构不保证版本稳定，而且软件包的 exports 字段会拒绝深层导入。一个最简 MCP-SDK 客户端示例（适用于 Web 后端的模式）见 examples/client-stdio.mjs；发布流水线会对打包后的 bin 进行端到端验证 (scripts/verify-pack.mjs)。

Web 应用入门模板

想看看 tctc-mcp 如何保护真实的 API 路由吗？

tctc-openai-starter 是一个独立的 Next.js 入门模板，通过 Sign-In with Ethereum 验证钱包所有权，使用 tctc-mcp 检查已配置的角色，并且只在链上准入检查通过时才调用 OpenAI。

将其用作 GitHub 模板。

为任意 MCP 服务添加代币门控：tctc-gate

此仓库也包含反向功能： tctc-gate (npm) 是一个透明的 stdio 代理，可在任意现有 MCP 服务前添加 ERC-7303 角色检查，且无需修改服务——拒绝访问时会返回一个授予 URL，打开后会预先填好控制面板。tctc-mcp 让 Agent 可以查询角色；tctc-gate 则在边界处强制执行角色检查：

npx -y tctc-gate --config gate.json -- npx -y some-mcp-server …

工具

工具	模式	用途
list_roles	两者	已配置的角色及其控制代币
check_role	两者	某个账户是否持有某个角色？（实时 balanceOf，并提供证据）
check_all_roles	两者	会话开始时对所有角色进行自我评估
discover_roles	两者	通过 IERC7303 检查任意合约——无需角色配置
resolve_agent	两者*	ERC-8004 agentId → 所有者 / agentURI / agentWallet / ERC-6551 TBA
grant_role	管理员	向主体铸造控制代币
revoke_role	管理员	销毁主体的控制代币——紧急停止开关

* 仅当配置中包含 identity 部分时才会注册。

主体可以是原始 address、ERC-8004 agentId（解析为其 ERC-6551 Token Bound Account，这是推荐的绑定目标），也可以省略以使用配置中的 self。

IERC7303 自动发现（v0.2）

ERC-7303 现在定义了一个内省接口 （ethereum/ERCs#1872，于 2026-07-11 合并）：符合标准的合约会公开 hasRole、控制代币 getter、 配置事件和 ERC-165 检测（interfaceId 0x4ee69337）。 tctc-mcp 通过两种方式使用它：

• target 角色 — 角色配置只需指定目标合约； 服务会从合约自身读取哪些控制代币可以授予该角色， 判定结果则采用目标合约自己的 hasRole() 答案：

  "roles": { "MINTER_ROLE": {
      "target": { "address": "0x4C0a78803D47154B9C6F42EC4AEbab2D1C94c97D" } } }
  

• discover_roles — 在运行时内省任意地址，无需 任何角色配置。不符合标准的合约会报告 supportsIERC7303: false；对于部署在 IERC7303 之前的版本， 静态 controlTokens 配置仍可作为备用方案。

可运行示例：examples/config.sepolia.discovery.json （不含密钥，使用公共 RPC），并已由 scripts/e2e-discovery.mjs 在线验证。

定时角色：无 Gas 自动过期（v0.3）

委托给 Agent 通常是短期的——“铸造一小时”， “在此任务期间代为操作”。使用可过期控制代币 （ExpiringControlTokens）后， 持有者的到期时间一过，balanceOf() 就会返回 0，因此角色会 自动撤销，无需发起交易——即使委托人忘记处理、离线 或丢失密钥也一样。ERC-7303 目标合约完全无需更改（Sepolia 过期演示目标与 TCTCDemoToken 逐字节完全相同）。

• 授予： 授予模板中含有 $expiresAt 的角色 必须设置过期时间——使用 expiresInSeconds: 3600 调用 grant_role，即表示“授予 MINTER_ROLE 一小时”：

  "admin": { "grant": { "function": "mint(address,uint256,uint64)",
                        "args": ["$subject", "$typeId", "$expiresAt"] } }
  

• 检查： 如果控制代币公开了过期时间，check_role 的证据会报告 expiresAt（Unix 秒），以便 Agent 可以自行报告“此权限将在 5 分钟后过期”。

• 紧急开关保持不变： 过期机制是安全保障，而非替代方案—— revoke_role（发行方销毁）仍可在有效期内立即撤销权限。

可运行示例：examples/config.sepolia.json 中的 TIMED_MINTER_ROLE，并已由 scripts/e2e-expiry.mjs 在线验证 （授予 75 秒 → 无需后续交易，观察其过期）。

人类仪表板

在线访问：https://tctc-mcp.vercel.app/ — tctc-mcp 向 AI Agent 提供 ERC-7303 角色的同时，TCTC 仪表板也向管理这些角色的人员展示相同的链上状态：检查任意 IERC7303 目标， 实时查看 hasRole 判定和各控制代币的 balanceOf 证据， 以发行方身份授予或撤销角色（支持定时授予，并为可过期控制代币显示倒计时）， 还可直接通过浏览器钱包部署新的控制代币集合。两个客户端，共享一个事实来源：区块链。详情和试用链接请参阅 dashboard/README.md。

它不只用于 AI Agent 委托：任何 ERC-7303 合约都适用，因此 该仪表板也可用作通用的链上权限管理器——从浏览器钱包 发行证书集合、授予和撤销角色，并审计各项权限的持有者。

文档

• docs/CONCEPT.md — 背景与原理：TCTC 作为 AI Agent 的授权层、它与 ERC-8004（Trustless Agents）和 ERC-6551（Token Bound Accounts）的关系、建议的 ERC-7303 规范更新，以及采用策略。
• docs/MCP_SERVER_SPEC.md — v1 设计规范（架构、配置、工具、安全性、路线图）。
• docs/ERC_DRAFT_EXPIRABLE_1155.md — 计划中的 ERC“Expirable ERC-1155 Tokens”的工作草案：上述限时角色所依据的标准（每个持有者的过期时间、感知时间的 balanceOf、expiresAt/ExpiryUpdated、接口 ID 0x300e616b）。 尚未提交至 ethereum/ERCs；欢迎反馈。
• docs/TEST_REPORT.md — v1 测试报告：24 项单元测试，以及 Sepolia 上的实时 E2E 测试（通过真实 MCP 客户端完成链上紧急停用开关周期）。
• examples/config.sepolia.json — Sepolia 演示部署的具体配置（主要角色、静态绑定），以及 TCTC 仓库的 MyComplexToken 示例（COMPLEX_* 角色，通过 IERC7303 target 发现解析）。
• examples/config.sepolia.agent.json — 同一演示部署的 Agent 端无密钥配置（公开 RPC，无 API 密钥）；即上文快速入门中使用的配置。
• examples/config.sepolia.discovery.json — IERC7303 自动发现变体：未配置控制代币，由目标合约自行说明其角色结构。
• examples/contracts/ — 部署在 Sepolia 上的演示合约源码（AgentControlTokens、TCTCDemoToken、ERC7303、IERC7303）。

演示部署（Sepolia，已通过 Etherscan 验证）

• AgentControlTokens（灵魂绑定、发行方可销毁的 ERC-1155）： 0x12342A7F0190B3AF3F4b47546D34006EDA54eE0B
• TCTCDemoToken（ERC-721 + ERC-7303 目标，实现了 IERC7303 introspection 接口 — hasRole、控制代币 getter；可通过 interfaceId 0x4ee69337 使用 ERC-165 检测）： 0x4C0a78803D47154B9C6F42EC4AEbab2D1C94c97D
• ExpiringControlTokens（灵魂绑定、发行方可销毁的 ERC-1155，支持每个持有者的过期时间；balanceOf 感知时间 — 限时角色的基础）： 0xb5abB6c060ed287e8B25aD121c8B46eE404fF09b
• 过期演示目标（未修改的 TCTCDemoToken 字节码，绑定至过期控制代币）： 0x3eAb11DE9655817A2e2977A486d9D33eBD10c9Ce

开发

git clone https://github.com/kofujimura/tctc-mcp.git && cd tctc-mcp
npm install && npm run build
node dist/index.js --config examples/config.sepolia.agent.json

npm test                  # unit tests (vitest)
node scripts/e2e-live.mjs # live E2E: spawns the server via MCP stdio client
                          # (needs ALCHEMY_API_KEY; admin phase additionally
                          #  TCTC_ADMIN_PRIVATE_KEY and E2E_SUBJECT)

相关项目

• 人工操作仪表板（本仓库，dashboard/）： https://tctc-mcp.vercel.app/
• npm 软件包：https://www.npmjs.com/package/tctc-mcp
• tctc-gate — 为任意现有 MCP 服务添加代币门控，无需修改： https://www.npmjs.com/package/tctc-gate
• tctc-openai-starter — 用于代币门控 OpenAI 访问的 Next.js 起始模板。
• Agent 技能（教 Agent 安全地使用 TCTC；使用 npx skills add kofujimura/tctc-skills 安装）： https://github.com/kofujimura/tctc-skills
• TCTC 参考实现：https://github.com/kofujimura/TCTC