Shodai Agreements

@shodai-network/agreements-mcp-server

Agreements API 用の Model Context Protocol サーバーです。Shodai をリモート Streamable HTTP MCP サーバーとして設定すると、契約のライフサイクル全体（作成、検証、事前チェック、デプロイ、入力の送信）を MCP ツールとして呼び出せるようになります。

このサーバーは、@shodai-network/agreements-api-client を介して公開 /v0 API を利用するだけのクライアントです。ビジネスロジックは持たず、認証情報も保存しません。すべてのツール呼び出しで呼び出し元の API キーまたは OAuth アクセストークンを Agreements API ゲートウェイに転送し、ゲートウェイが認証、利用権限、利用量の計測を管理します。

ホステッドエンドポイント

ステートレス Streamable HTTP：POST のみ、JSON レスポンス、サーバー側セッションなし。次のホステッド構成の仕様を使用してください。

Configure Shodai as a remote Streamable HTTP MCP server.

URL:
https://shodai.network/mcp

Auth:
Start the connection and complete Shodai browser sign-in and consent.

Tool environment:
testnet

Use this value as the environment argument on API-calling tools.

標準のホステッドエンドポイントは、Shodai のテストネット認可サーバーを通知します。OAuth 対応の MCP クライアントは、RFC 9728 の保護リソース検出に従ってブラウザー認証を開始し、取得したアクセストークンを使って再接続します。この OAuth 接続には environment: "testnet" を使用してください。

OAUTH_AUTHORIZATION_SERVERS が設定されている場合、サーバーは次の処理を行います。

• /.well-known/oauth-protected-resource（および .../mcp）で RFC 9728 の保護リソースメタデータを提供します
• 認証されていない POST /mcp に対し、WWW-Authenticate（resource_metadata=...）を使って認証を要求します
• API キーに加えて、OAuth アクセストークン（Authorization: Bearer <jwt>）を受け付けます

API キーも引き続きフォールバックおよび本番環境の認証情報として使用できます。Authorization: Bearer cns_pk_... を送信し、キーとツールの environment を一致させてください。テストネットのキーには testnet、本番環境のキーには production を使用します。

初回接続の設定、ツールへのアクセス、型付きデータの準備については、MCP を使ったクイックスタートをご覧ください。

ローカルで実行（stdio）

{
  "mcpServers": {
    "shodai-agreements": {
      "command": "npx",
      "args": ["-y", "@shodai-network/agreements-mcp-server"],
      "env": {
        "AGREEMENTS_API_KEY": "YOUR_API_KEY",
        "AGREEMENTS_API_ENVIRONMENT": "testnet"
      }
    }
  }
}

stdio 環境変数：

Variable	Use
AGREEMENTS_API_KEY (or API_KEY)	ツール呼び出しに使用する API キーです。OAuth クライアント認証情報が設定されていない場合は必須です。
OAUTH_CLIENT_ID / OAUTH_CLIENT_PRIVATE_JWK	エージェント ID 用の OAuth クライアント認証情報認証です。サーバーがベアラートークンを自動で発行・更新します。AGREEMENTS_API_KEY の代替です（両方が設定されている場合は AGREEMENTS_API_KEY が優先されます）。
OAUTH_ISSUER_URL (or OAUTH_TOKEN_URL)	トークンエンドポイントの検出に使用する認可サーバーの発行者、または明示的なトークンエンドポイントです。OAuth クライアント認証情報を使用する場合は必須です。
OAUTH_SCOPE	発行するトークンで要求する、任意のスペース区切りスコープです。
AGREEMENTS_API_ENVIRONMENT	testnet（デフォルト）または production です。
AGREEMENTS_API_BASE_URL	ゲートウェイのオリジンを明示的に上書きします。環境設定より優先されます。
AGREEMENTS_SIGNER_PRIVATE_KEY	書き込みツール用の任意のローカル許可署名者です（開発／テストネットのみ）。
INFURA_PROJECT_ID	組み込みの Linea、Sepolia、Base の契約チェーン用 RPC URL の導出に使用する Infura プロジェクト ID です。
AGREEMENTS_RPC_URL, AGREEMENTS_RPC_URL_<chainId>	許可の準備または署名時に使用する、任意の RPC 上書き設定です。

ツール

ほとんどのツールは、TypeScript クライアントを通じて公開 /v0 API を呼び出し、MCP の動作アノテーション（readOnlyHint、destructiveHint）を付与します。署名とデプロイを安全に行うため、複数の操作を実行するツールもあります。

ホステッドエンドポイントでは、以下の API 呼び出しツールすべてで environment: "testnet" | "production" が必要です。ローカルの stdio モードでは、代わりに AGREEMENTS_API_ENVIRONMENT で指定された環境が固定で使用されます。

ツール	ラップする API	スコープ
list_agreements	GET /v0/agreements	agreements.read
get_agreement	GET /v0/agreements/{id}	agreements.read
get_agreement_document	GET /v0/agreements/documents/{documentId}	agreements.read
get_agreement_state	GET /v0/agreements/{id}/state	agreements.read
get_input_history	GET /v0/agreements/{id}/inputs	agreements.read
validate_agreement	POST /v0/agreements/validate-template	agreements.write
preflight_deployment	POST /v0/agreements/validate	agreements.write
deploy_agreement	POST /v0/agreements/validate、続いて POST /v0/agreements/deploy-with-permit	agreements.write
submit_input	POST /v0/agreements/{id}/input	agreements.write
prepare_deployment_typed_data	POST /v0/agreements/validate、続いてチェーン nonce を読み取ってローカルで EIP-712 ペイロードを構築	agreements.write
prepare_input_typed_data	GET /v0/agreements/{id}、続いてチェーン nonce を読み取ってローカルで EIP-712 ペイロードを構築	agreements.write

リソースは resources/list で検出できます。

リソース	URI
simple-example-agreement	agreements://examples/simple-agreement.json
complex-example-agreement	agreements://examples/complex-agreement.json
authoring-guide	agreements://docs/author-agreement-json.md
docs-index	agreements://docs/index.md

プロンプト：author_agreement（ビジネス上の説明 → agreement JSON）。

署名のカストディモード

デプロイと入力の送信には EIP-712 許可証が必要です。サポートされているモードは 3 つあります。

1. 事前署名済み許可証 — エージェントまたはホストアプリがウォレットを保持し、外部で署名してから、signer／deadline／signature を deploy_agreement または submit_input に渡します。
2. Typed Data を準備して外部で署名 — prepare_deployment_typed_data／prepare_input_typed_data を呼び出して正確な EIP-712 ペイロードを取得し、EIP-712 に対応した任意の署名者で署名してから、書き込みツールを呼び出します。デプロイの場合は、返された normalizedInitValues、normalizedParticipants、normalizedObservers を署名とともに deploy_agreement に渡します。
3. ローカル環境の署名者（stdio のみ） — AGREEMENTS_SIGNER_PRIVATE_KEY を設定すると、書き込みツールがローカルで署名します。開発／testnet 向けの方式です。ホステッドエンドポイントがサーバー側のキーで署名することはありません。

ホステッド環境での最小限のフロー：simple-example-agreement を読み込み、validate_agreement、preflight_deployment、prepare_deployment_typed_data を environment／agreement／chainId／signerAddress および予定しているデプロイコンテキストとともに呼び出し、外部で署名してから、同じ environment、displayName、一致する docUri、正規化済みのデプロイフィールド、許可証フィールドを指定して deploy_agreement を呼び出します。入力の場合は、prepare_input_typed_data を environment／agreementId／inputId／values／signerAddress とともに呼び出し、外部で署名してから、同じ environment を指定して submit_input を呼び出し、その後、状態と入力履歴を再度読み込みます。

ホステッド MCP が受け取るのは署名済みの許可証フィールドのみで、秘密鍵は受け取りません。秘密鍵を使った環境変数による署名は、ローカルの stdio 開発と testnet の自動化でのみ使用します。

セルフホスト

npm install @shodai-network/agreements-mcp-server
agreements-mcp-server-http   # Streamable HTTP on PORT (default 3905), endpoint /mcp

HTTP 環境変数：PORT、HOST、MCP_PATH、PUBLIC_MCP_URL、AGREEMENTS_API_TESTNET_BASE_URL、AGREEMENTS_API_PRODUCTION_BASE_URL、および単一オリジンでのテスト用の任意のローカル環境変数 AGREEMENTS_API_BASE_URL。リクエストのホストとは異なる正規の公開エンドポイントをディスカバリーメタデータに掲載する場合は、PUBLIC_MCP_URL を設定してください。

コンテナでのデプロイ用に Dockerfile が含まれています。GET /healthz はヘルスエンドポイントとして機能します。

開発

pnpm install
pnpm --filter @shodai-network/agreements-mcp-server build
pnpm --filter @shodai-network/agreements-mcp-server test

MCP Inspector を使って対話形式で確認します：

npx -y @modelcontextprotocol/inspector@latest --cli http://localhost:3905/mcp \
  --transport http --method tools/list --header "Authorization: Bearer $SHODAI_API_KEY"

URL ターゲットでの --transport／--header に対応していない古いバージョンの Inspector があるため、@latest を固定してください。

ライセンス

MIT — LICENSE を参照してください。このパッケージは個別に MIT ライセンスが適用されていますが、このリポジトリ内のほかのパッケージには Apache-2.0 ライセンスが適用されています。