CosmWasm MCP Server Template

CosmWasm MCP サーバーテンプレート

署名者がブロードキャストするクエリおよび実行エントリポイントメッセージをラップする、Rust 製の MCP サーバーです。このプロジェクトテンプレートは、あらゆる CosmWasm コントラクトで動作するはずです。

このプロジェクトのビルド

このプロジェクトのビルドには、Rust の nightly ビルドが必要です。これにより、rustc の edition 2024 を使用できます。

# Switch rustc to `nightly` channel
rustup default nightly

# Build for development
cargo build

# Build for deployment
cargo build --release

使用方法

このプロジェクトは、あらゆる CosmWasm コントラクトで使用できる MCP サーバーテンプレートですが、独自のコントラクトでこのテンプレートを使用するには、いくつか簡単な変更が必要です。

このテンプレートを独自のコントラクトで使用するには、次の_必須_変更を実施してください。

ステップ 1 - Cargo.toml を更新する

• Cargo.toml のコントラクト依存関係を変更します

Cargo.toml から次の行を削除し、コントラクトの依存関係に置き換えてください。

cw20-wrap = { git = "https://github.com/archway-network/cw20-wrap.git", version = "1.0.0", features = ["library"] }

ステップ 2 - コントラクトをライブラリとしてビルドできることを確認する

• 追加した依存関係が cosmwasm_std::entry_point、query、execute をエクスポートしないように_してください_。

たとえば、コントラクトで次のように entry_point、query、execute（および、プロジェクトに応じて instantiate、reply、migrate など）をインポート_しないでください_。

use cosmwasm_std::{
    entry_point, to_json_binary, Binary, Deps, DepsMut, Env, MessageInfo, Response, StdResult,
    Uint128,
};
// ...
pub fn execute(deps: DepsMut, env: Env, info: MessageInfo, msg: ExecuteMsg) -> Result<Response, ContractError> {
    // ...
}
pub fn query(deps: Deps, _env: Env, msg: QueryMsg) -> StdResult<Binary> {
    // ...
}

代わりに、次のように機能ゲートを使用してコントラクトのエントリポイントを制御してください。

#[cfg(not(feature = "library"))]
use cosmwasm_std::entry_point;
use cosmwasm_std::{
    to_json_binary, Binary, Deps, DepsMut, Env, MessageInfo, Response, StdResult,
    Uint128,
};
#[cfg_attr(not(feature = "library"), entry_point)]
pub fn execute(deps: DepsMut, env: Env, info: MessageInfo, msg: ExecuteMsg) -> Result<Response, ContractError> {
    // ...
}
#[cfg_attr(not(feature = "library"), entry_point)]
pub fn query(deps: Deps, _env: Env, msg: QueryMsg) -> StdResult<Binary> {
    // ...
}

ステップ 3 - server.rs を更新する

• src/server.rs のコントラクト依存関係を変更します

src/server.rs ファイルの先頭（コードを参照）で、デフォルトの cw20-wrap 依存関係を削除し、コントラクトに対応する依存関係に置き換えてください。MCP サーバーが AI エージェントに理解できる JSON スキーマを作成できるよう、コントラクトでは msg::QueryMsg と msg::Execute を公開エクスポートする必要があります。

/// Replace the below import with the contract you want the MCP server to support
use cw20_wrap::msg::{ExecuteMsg, QueryMsg};

ステップ 4 - contract.rs のデプロイ済みコントラクトアドレスを更新する

src/contract.rs の末尾（コードを参照）で、コントラクトのメインネットおよびテストネットへのデプロイに使用するアドレスを更新してください。また、エントリを削除してテストネットまたはメインネットの一方のみを残す場合は、CwMcp::new() 関数内の contracts 配列から該当するエントリを削除する必要があります（コードを参照）。

/// Replace with your deployed contract addresses.
/// This helps the query msg and tx msg builders wrap
/// your query and tx messages to the contract into
/// CosmWasm's `QueryRequest` and `CosmosMessage` types
/// that can be broadcast by a rpc enabled wallet tool
pub static CONTRACT_MAINNET: &str =
    "archway1gaf9nw7n8v5lpjz9caxjpps006kxfcrzcuc8y5qp4clslhven2ns2g0ule";
pub static CONTRACT_TESTNET: &str =
    "archway1r8kepegwhldwqanuurc769l2g0qxlsm2sm6t5rhqjzcerxsgshls267f7a";

ステップ 5（任意） - カスタム型の MCP ツールを有効にする

• コントラクトでカスタム型やレスポンスを使用していて、AI エージェントが利用できると有益だと思われる場合は、その方法を示す例（コメントアウト済み）が server.rs にあります（src/server.rs の以下のスニペットを参照）。

/// (Optionally) if your contract provides any custom query response types
/// configure this tool so the MCP agent can access them. Allowing the MCP
/// agent to access the custom query responses enables it to provide smarter
/// advice, and summaries, about exacly what data can be fetched when making
/// a query to the contract.
/// @see: src/query.rs
#[tool(description = LIST_QUERY_RESPONSE_DESCR)]
async fn list_query_responses(&self) -> Result<CallToolResult, Error> {
    let schema = schema_for!(AllQueryResponse);
    let serialized: String = serde_json::to_string(&schema).unwrap_or("".to_string());
    Ok(CallToolResult::success(vec![Content::text(serialized)]))
}

ステップ 6（任意） - LLM 向けの指示をカスタマイズする

• システムプロンプトのコンテキストに関するすべてのサーバー指示とツールの説明は、src/instruction.rs にあります。
• src/instruction.rs の内容は、基本的な動作例です。複雑なコントラクトや複数のコントラクトからなるシステムを扱う場合は、LLM により詳しいコンテキストを提供できるよう、ツールとサーバーの説明を改善するとよいでしょう。
• LLM 向けの指示を改善し、コントラクトに合わせてカスタマイズする方法については、Ambur MCP server の instruction.rs を参照してください。

ステップ 7（任意） - MCP サーバーのトランスポートモードを設定する

• このテンプレートでは、stdio、sse、http-streamable の 3 つのトランスポートモードをサポートしています
• このテンプレートのデフォルトのトランスポートモードは stdio です
• トランスポートモードについて：
  • stdio - サーバーはシステム標準入力／出力を使用して応答します
  • sse - サーバー送信イベントサーバー（MDN のドキュメント）
  • http-streamable - JSON API サーバー機能を提供する、リモート MCP サーバー向けの新しい標準です（Claudemcp のドキュメント）

AI の精度を最適化する

スキーマ生成では、コードにドキュメントコメントを追加することが重要です

サーバーの指示、ツールの説明、ツールパラメーターの説明を充実させても、AI が不正確または誤解を招くデータを提供し続けたり、コントラクトのエントリーポイントについて十分な詳細を示さなかったりすることがあります。通常、これはコントラクトのソースコードにある msg::QueryMsg と msg::ExecuteMsg にドキュメントコメント（例：スラッシュ 3 つのコメント「///」）が不足しているために起こります。

これは、schemars がドキュメントコメントを説明メタデータフィールドとしてスキーマに直接埋め込むためです。

以下は、LLM エージェントのガイドとして役立つ、適切にコメントが付けられた msg::QueryMsg の例です。

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    /// Get all swaps (enumerable)
    /// Return type: ListResponse
    List {
        start_after: Option<String>,
        limit: Option<u32>,
    },
    /// Get all Collection Offers (enumerable)
    /// Return type: ListResponse
    ListCollectionOffers {
        start_after: Option<String>,
        limit: Option<u32>,
    },
    // ...
}

上記の QueryMsg の 2 つのバリアントは、生成されたスキーマに次の説明を埋め込みます。クエリーのエントリーポイントを解釈する必要がある LLM にとって、非常に役立ちます。

[
    {
      "description": "Get all swaps (enumerable) Return type: ListResponse",
      "type": "object",
      "required": [
        "list"
      ],
      // ... 
    },
    {
      "description": "Get all Collection Offers (enumerable) Return type: ListResponse",
      "type": "object",
      "required": [
        "list_collection_offers"
      ],
      // ...
    },
]

複数コントラクトのシステム

• 複数のコントラクトをサポートする MCP サーバーを構築するのが適切な場合もあります。これを実現する方法はシンプルです。

1. コントラクトに名前空間を付けます（例：シンボルのインポートの重複を避けるため）
2. パターンマッチングとツールパラメーターを実装し、異なるコントラクトを切り替えられるようにします
3. 複数コントラクトの完全な例については、Ambur MCP サーバーを参照してください

この MCP サーバーテンプレートが提供するツール

この MCP サーバーは、デフォルトで次の 6 つのツールと機能を提供します。

1. list_contract_deployments - Ambur のコアコントラクトアドレス（メインネットとテストネット）を一覧表示します
2. list_nft_collections - Ambur NFT（メインネットとテストネットのコントラクトアドレス、コレクション名、コレクションの説明）を一覧表示します
3. list_query_entry_points - Ambur のコアマーケットプレイスコントラクトに対して実行できるクエリーを一覧表示します
4. build_query_msg - RPC に接続されたウォレットがブロードキャストできる、Ambur のコアマーケットプレイスコントラクトへのクエリーを構築します
5. list_tx_entry_points - Ambur のコアマーケットプレイスコントラクトに対して実行できるトランザクションを一覧表示します
6. build_execute_msg - RPC に接続されたウォレットが署名してブロードキャストできる、Ambur のコアマーケットプレイスコントラクトへのトランザクションを構築します

MCP を Claude Desktop に接続する

以下の手順では、MCP サーバーが stdio モードでビルドされていることを前提としています（Claude Desktop で最も簡単に設定できるモードです）。

リリースバイナリをビルドし、MCP サーバーの command にそのパスを指定します。実行引数（args）は必要ありません。

// claude_desktop_config.json
{
  "mcpServers": {
    "ambur": {
      "command": "/your-computer-path/cosmwasm-mcp-template/target/release/cosmwasm-mcp-template",
      "args": []
    }
  }
}

仮想マシン環境や WSL ユーザーの場合は、仮想マシンを command として実行し、実行引数（args）でバイナリを実行する場所を仮想マシンに指定します。

// claude_desktop_config.json
{
  "mcpServers": {
    "ambur": {
      "command": "wsl.exe",
      "args": [
        "bash",
        "-ic",
        "/your-vm-path/cosmwasm-mcp-template/target/release/cosmwasm-mcp-template",
      ]
    }
  }
}

MCP を LangGraph に接続する

グラフプロジェクトに @langchain/mcp-adapters をインストールする必要があります。このパッケージは MCP エンドポイントをグラフのツールに変換します。

@langchain/mcp-adapters を使用する

// graph.ts
import { MultiServerMCPClient } from "@langchain/mcp-adapters";
// ...
// Create client and connect to server
const client = new MultiServerMCPClient({
  throwOnLoadError: true,
  prefixToolNameWithServerName: true,
  additionalToolNamePrefix: "mcp",
  mcpServers: {
    cosmwasm_contract: {
      transport: "sse",
      url: "http://localhost:8000", // Or, URL + IP of a remote host
      useNodeEventSource: true,
      reconnect: {
        enabled: true,
        maxAttempts: 5,
        delayMs: 2000,
      },
      // Or, uncomment to use transport mode `http-streamable`:
      // url: "http://localhost:8000",
      // headers: {},
      // automaticSSEFallback: false
    },
  },
});

const tools = await client.getTools();
// ...