tctc-mcp

tctc-mcp

AI エージェントに ERC-7303 （Token-Controlled Token Circulation）のロールを提供する MCP サーバーです。エージェントは自身のオンチェーン権限を確認でき、人間のプリンシパルは制御トークンをミント／バーンして権限を付与／取り消しできます。権限サーバーは不要です。

ステータス：v0.3.4 — v0.2 の IERC7303 自動検出に加え、ガス不要の自動失効に対応した期限付きロールを追加しました。npm で公開済み （tctc-mcp）で、単体テスト済みです。また、Sepolia のデモデプロイに対して、実際の MCP クライアントを通じて一連の動作（付与 → 確認 → 取り消し → 確認、および75秒間の付与 → 自動失効）をエンドツーエンドで検証済みです。

デモ（60秒）

人間がAIエージェントにミント権限を付与すると、エージェントはオンチェーンでそれを検証してNFTをミントします。人間がロールトークンをバーンすると、エージェントは即座にその機能を失います。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 アプリケーションのスターター

実際の API ルートを tctc-mcp で保護する方法を確認してみませんか？

tctc-openai-starter は、Sign-In with Ethereum でウォレットの所有権を検証し、設定されたロールを tctc-mcp で確認して、オンチェーンのゲートによってアクセスが許可された場合にのみ OpenAI を呼び出す、独立した Next.js スターターです。

GitHub テンプレートとして使用できます。

任意の MCP サーバーをトークンゲートする：tctc-gate

逆方向の機能もこのリポジトリにあります。 tctc-gate (npm) は、ERC-7303 のロール確認を**既存の任意の MCP サーバー（変更なし）**の前段に配置する透過的な stdio プロキシです。アクセスが拒否されると、ダッシュボードに必要な情報をあらかじめ入力した状態で開く付与用 URL が返されます。tctc-mcp ではエージェントがロールについて問い合わせ、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 → owner / 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 はこれを 2 通りの方法で使用します。

• target ロール — ロール設定で指定するのはターゲットコントラクトのみです。 サーバーは、そのロールを制御する制御トークンをコントラクト自身から読み取り、判定結果にはターゲット自身の hasRole() の回答を使います。

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

• discover_roles — ロール設定がまったくなくても、実行時に任意のアドレスをイントロスペクションします。準拠していないコントラクトは supportsIERC7303: false を返します。静的な controlTokens 設定は、IERC7303 導入前のデプロイメント向けの代替手段として引き続き利用できます。

動作する例：examples/config.sepolia.discovery.json （シークレット不要、公開 RPC）。scripts/e2e-discovery.mjs でライブ検証済みです。

時限ロール：ガスレスな自動失効（v0.3）

エージェントへの権限委譲は、通常短期間です。「1 時間だけ mint する」「このタスクの間だけ操作する」といった具合です。有効期限付き制御トークン （ExpiringControlTokens）を使うと、保有者の有効期限が過ぎた時点で balanceOf() は 0 を返します。そのため、トランザクションなしでロールが自動的に失効します。権限付与者が失念したり、オフラインになったり、鍵を失ったりしても失効します。ERC-7303 のターゲットコントラクトには一切変更が不要です（Sepolia の有効期限デモ用ターゲットは TCTCDemoToken とバイト単位で同一のコピーです）。

• **付与：**付与テンプレートに $expiresAt を含むロールには、有効期限の指定が必要です。 expiresInSeconds: 3600 を指定した grant_role は、「MINTER_ROLE を 1 時間付与する」という意味です。

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

• **確認：**制御トークンが有効期限を公開している場合、check_role の証拠に expiresAt（Unix 秒）が含まれます。これにより、エージェントは「この権限は 5 分後に失効します」と自己申告できます。

• **キルスイッチは変更なし：**有効期限はフェイルセーフであり、置き換えではありません。 revoke_role（発行者によるバーン）を使えば、有効期間内に引き続き即時失効できます。

動作する例：examples/config.sepolia.json の TIMED_MINTER_ROLE。scripts/e2e-expiry.mjs でライブ検証済みです（75 秒間付与 → 追加のトランザクションなしで失効する様子を確認できます）。

人間向けダッシュボード

公開中：https://tctc-mcp.vercel.app/ — tctc-mcp が AI エージェントに ERC-7303 ロールを提供する一方、TCTC Dashboard はそれらを管理する人間に同じオンチェーン状態を提供します。任意の IERC7303 ターゲットを調査し、hasRole の判定結果と各制御トークンの balanceOf の証拠をリアルタイムで確認できます。また、発行者としてロールを付与・取り消し（有効期限付き制御トークンには時限付与とカウントダウン表示も対応）したり、ブラウザーウォレットから新しい制御トークンコレクションを直接デプロイしたりできます。1 つの信頼できる情報源であるチェーンを、2 種類のクライアントで利用できます。詳細とお試し用リンクについては、dashboard/README.md をご覧ください。

AI エージェントへの権限委譲だけが用途ではありません。ERC-7303 コントラクトならどれでも使えるため、このダッシュボードは汎用的なオンチェーン権限管理ツールとしても機能します。証明書コレクションの発行、ロールの付与と取り消し、誰が何を保有しているかの監査を、すべてブラウザーウォレットから行えます。

ドキュメント

• docs/CONCEPT.md — 背景と根拠：AI エージェントの認可レイヤーとしての TCTC、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 件のユニットテストと、実際の MCP クライアントを通じてオンチェーンのキルスイッチサイクルを実行した Sepolia E2E テスト。
• examples/config.sepolia.json — Sepolia デモデプロイ用の具体的な設定（主要ロール、静的バインディング）と、TCTC リポジトリの MyComplexToken サンプル（IERC7303 の target 検出によって解決される COMPLEX_* ロール）。
• examples/config.sepolia.agent.json — 同じデモデプロイ用の、シークレットを含まないエージェント側設定（公開 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 を実装しており、hasRole、制御トークンのゲッターを備え、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 スターター。
• エージェントスキル（エージェントに TCTC の安全な使用方法を教えます。npx skills add kofujimura/tctc-skills でインストール）： https://github.com/kofujimura/tctc-skills
• TCTC リファレンス実装：https://github.com/kofujimura/TCTC