metacontract mcp

mc-mcp

metacontract（mc） フレームワーク向けの Model Context Protocol（MCP）サーバーです。Foundry との連携とセマンティックなドキュメント検索により、スマートコントラクトの開発を支援します。

---

概要

mc-mcp は、metacontract（mc）フレームワーク向けに設計された拡張可能な MCP サーバーです。 以下のようなツールを提供することで、AI を活用したスマートコントラクト開発のワークフローを実現します。

• mc_search_docs_semantic：mc のドキュメントとユーザーが設定したソースを対象にセマンティック検索を実行し、構造化された JSON の結果を返します。
• mc_setup：metacontract/template を使用して、新しい Foundry プロジェクトを初期化します。（ディレクトリが空でない場合は、設定で setup.force=true を設定してください。）
• mc_test：ワークスペースで Foundry のテスト（forge test）を実行します。
• mc_deploy：mcp_config.toml で指定されたスクリプトを使用してコントラクトをデプロイします。ドライラン（デフォルト）とブロードキャストモード（broadcast: true 引数）に対応しています。
• mc_upgrade：mcp_config.toml で指定されたスクリプトを使用してコントラクトをアップグレードします。ドライランとブロードキャストモードに対応しています。
• mc_lint：（近日公開） ベストプラクティスやエラーについて、プロジェクトファイルをリントします。
• mc_erc7201_slot：ERC-7201 を使用して、名前空間付きストレージスロットを計算します。

---

設定とプロジェクトルート

プロジェクトルートは、常に MC_PROJECT_ROOT 環境変数で指定します。

• パスの解決は MCP クライアントの実装に委ねられるため、MC_PROJECT_ROOT 環境変数が必要です。これにより、異なる環境間で一貫性と信頼性のある動作が実現します。
• mc-mcp のコマンドまたはツールを実行する前に、MC_PROJECT_ROOT をプロジェクトルートディレクトリに設定してください。
• mcp_config.toml を含むすべての設定ファイルは、このディレクトリに置く必要があります。
• MC_PROJECT_ROOT が設定されていないか、指定先が存在しない場合、mc-mcp はエラーを返して起動しません。
• mcp_config.toml が見つからない場合、mc-mcp は組み込みのデフォルト値を使用し、警告を記録します。

例：プロジェクト構成

/path/to/your/project/
├── mcp_config.toml   # (optional) Project configuration
├── contracts/
├── scripts/
└── ...

設定ファイル（mcp_config.toml）

• このファイルは MC_PROJECT_ROOT ディレクトリ直下に配置してください。
• 省略した場合、mc-mcp はすべての設定値にデフォルト設定を使用します。
• 設定例とフィールドの説明を以下で確認できます。

---

はじめに

1. mc-mcp をインストールする（CLI ツールとして）

# recommended for most users
cargo install mc-mcp

# Or, to use the latest development version from GitHub:
cargo install --git https://github.com/metacontract/mc-mcp.git

# Alternatively, you can clone and build manually:
git clone https://github.com/metacontract/mc-mcp.git
cd mc-mcp
cargo build --release

2. MCP クライアントに追加する

mc-mcp は、以下のような MCP 対応クライアントで使用できます。

• Cursor
• Cline
• RooCode

例：Cursor

設定（./cursor/mcp.json またはグローバル設定）に MCP サーバーを追加します。

{
  "mcpServers": {
    "mc-mcp": {
      "command": "mc-mcp", // or "/path/to/mc-mcp/target/release/mc-mcp",
      "env": {
        "MC_PROJECT_ROOT": "/absolute-path/to/your/project"
      }
    }
  }
}

例：Cline

Cline はワークスペース内の MCP サーバーを自動検出します。 詳細な設定については、Cline のドキュメントを参照してください。

例：RooCode

RooCode は標準で MCP 連携に対応しています。 詳細については、RooCode のドキュメントを参照してください。

{
  "mcpServers": {
    "mc-mcp": {
      "disabled": false,
      "timeout": 60,
      "command": "mc-mcp",
      "transportType": "stdio",
      "alwaysAllow": ["mc_setup", "mc_search_docs_semantic", "mc_test", "mc_deploy", "mc_upgrade"], // if needed
      "env": {
        "MC_PROJECT_ROOT": "/absolute-path/to/your/project"
      }
    }
  }
}

その後、MCP クライアントが mc-mcp サーバーを自動的に起動します。

• 初回起動時に、事前構築済みのドキュメントインデックス（prebuilt_index.jsonl.gz）が存在しない場合、最新の GitHub リリースからダウンロードされます。

3. 新しい mc プロジェクトを初期化する

エージェントに「setup mc project」と指示するだけで初期化できます。

または、手動でセットアップします。

forge init <your-project-name> -t metacontract/template
cd <your-project-name>

4. スマートコントラクトを開発する

• MCP 対応のエージェント／IDE を使用して mc-mcp と連携します。
• 設計、ドキュメントの検索、TDD サイクルの実行（mc_test、mc_search_docs_semantic など）を行います。

設定例

プロジェクトのルートに mcp_config.toml という名前のファイルを作成します。

# Reference sources for semantic search
[reference]
# The prebuilt index is downloaded to the system cache directory by default.
# You can override the path here if needed:
# prebuilt_index_path = "/custom/path/to/prebuilt_index.jsonl.gz"

[[reference.sources]]
name = "mc-docs"
source_type = "local"
path = "metacontract/mc/site/docs"

[[reference.sources]]
name = "solidity-docs"
source_type = "local"
path = "docs/solidity"

[[reference.sources]]
name = "user-docs"
source_type = "local"
path = "docs/user"

# Default scripts used by tools
[scripts]
deploy = "scripts/Deploy.s.sol"  # Used by mc_deploy
upgrade = "scripts/Upgrade.s.sol" # Used by mc_upgrade

# Optional: Settings for broadcasting transactions (used when broadcast=true)
rpc_url = "http://localhost:8545" # RPC endpoint URL
private_key_env_var = "PRIVATE_KEY" # Name of the env var holding the deployer's private key

• prebuilt_index_path …（任意）事前構築済みインデックス（jsonl または gzip 圧縮された jsonl）へのパスです。設定すると、デフォルトのキャッシュ場所より優先されます。起動時にインデックスが読み込まれ、Qdrant にアップサートされます。
• 各 [[reference.sources]] には、name、source_type（通常は local）、および path（実行ディレクトリからの相対パス）が必要です。
• [scripts].deploy と [scripts].upgrade では、それぞれ mc_deploy ツールと mc_upgrade ツールが使用するデフォルトの Foundry スクリプトパスを指定します。
• broadcast: true 引数を指定して mc_deploy または mc_upgrade を使用する場合は、[scripts].rpc_url と [scripts].private_key_env_var が必要です。forge はこれらを使ってトランザクションを送信します。
• すべてのパスが存在するディレクトリでなければ、インデックス作成に失敗します。

完全な設定構造については、config.rs も参照してください。

---

特長

• 保守性とテスト容易性を高める レイヤード（オニオン）アーキテクチャ
• パフォーマンスと安全性を実現する Rust による実装
• #[tool] アノテーションベースのツール定義を備えた MCP SDK（modelcontextprotocol-rust-sdk）
• 高速なセマンティック検索を実現する Qdrant（組み込みベクターデータベース）
• fastembed-rs を使用した ローカル埋め込み生成
• comrak による Markdown 解析
• figment による 柔軟な設定
• tracing による 構造化ログ
• CI/CD：事前構築済みのドキュメントインデックスを生成、圧縮し、GitHub Release アセットとして公開します

---

アーキテクチャ

• ライブラリ＋バイナリクレート構成
• ドメイン／アプリケーション／インフラストラクチャのレイヤー構造
• 手動の依存性注入
• 厳格な内向き依存ルール（エントリーポイント → アプリケーション → ドメイン ← インフラストラクチャ）
• 事前構築済みインデックス：初回実行時に GitHub Releases から自動でダウンロードされます（クレートには含まれません）

---

プロジェクト構成

• src/domain/ — コアビジネスロジック、トレイト、エンティティ
• src/application/ — ユースケース、DTO
• src/infrastructure/ — 統合機能（Qdrant、埋め込み、ファイルシステムなど）
• src/main.rs — エントリーポイント、MCP ツールの登録、DI

---

開発

• TDD：テスト駆動開発を必須としています（ユニットテスト／統合テスト）。
• 統合テスト：Qdrant には testcontainers を使用し、分離された安定したテスト環境を確保します。
• CI/CD：GitHub Actions によるビルド、テスト、事前構築済みインデックスアーティファクトの管理

テストとトラブルシューティング

一部のテスト（特に統合テストと埋め込み関連のテスト）は、OS のファイルディスクリプター上限やキャッシュロックの問題により失敗することがあります。

よく使うコマンド（Makefile 経由）

• すべてのテスト（無視されたテストを含む）：

  make test-all
  

• ユニットテスト（lib のみ、キャッシュロックをクリーンアップし、シングルスレッドで実行）：

  make test-lib
  

• 統合テスト（シングルスレッドで実行）：

  make test-integration
  

• 埋め込みモデルのキャッシュをクリーンアップ：

  make clean-cache
  

トラブルシューティング

• Too many open files エラーが表示される場合：
  • テストの実行前に、シェルでファイルディスクリプターの上限を引き上げます：ulimit -n 4096
  • テストを順次実行します：cargo test -- --test-threads=1（または make test-lib／make test-integration を使用します）
• 埋め込みモデルのキャッシュに関連する .lock エラーが表示される場合：
  • キャッシュをクリーンアップします：make clean-cache
• forge コマンドを含むテストが予期せず失敗する場合：
  • 該当するテストファイル（src/main.rs のテスト）内のモックスクリプト設定が正しいことを確認します。
• 注：
  • Makefile には一般的なタスク用の便利なショートカットが用意されていますが、OS や CI 環境によっては、ファイルディスクリプターの上限を手動で調整する必要があります（ulimit）。
  • 詳細については、各 Makefile ターゲットを参照してください。

---

タスク管理と進捗

最新のマイルストーン、進捗状況、詳細なタスク追跡については、こちらを参照してください： ➡️ mc-mcp タスクリスト

---

ライセンス

MIT