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 环境变量指定。

• 必须设置 MC_PROJECT_ROOT 环境变量，因为路径解析由 MCP 客户端实现负责。这样可以确保在不同环境中行为一致且可靠。
• 运行任何 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

在设置中添加 MCP 服务（./cursor/mcp.json 或全局设置）：

{
  "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 Release 下载。

3. 初始化新的 mc 项目

你可以直接让 Agent 执行“setup mc project”。

或者，手动设置：

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

4. 开发智能合约

• 使用兼容 MCP 的 Agent/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 实现，兼顾性能与安全性
• MCP SDK（modelcontextprotocol-rust-sdk），通过基于 #[tool] 注解的方式定义工具
• 使用 Qdrant（嵌入式向量数据库）进行快速语义搜索
• 使用 fastembed-rs 在本地生成嵌入向量
• 使用 comrak 解析 Markdown
• 通过 figment 灵活配置
• 使用 tracing 进行结构化日志记录
• CI/CD：生成预构建文档索引，对其压缩，并作为 GitHub Release 资源发布

---

架构

• 库 + 二进制 crate 结构
• 领域 / 应用 / 基础设施 分层
• 手动依赖注入
• 严格的依赖向内规则（入口点 → 应用 → 领域 ← 基础设施）
• 预构建索引：首次运行时从 GitHub Releases 自动下载（不包含在 crate 中）

---

项目结构

• src/domain/ — 核心业务逻辑、trait、实体
• src/application/ — 用例、DTO
• src/infrastructure/ — 集成（Qdrant、嵌入向量、文件系统等）
• src/main.rs — 入口点、MCP 工具注册、依赖注入

---

开发

• TDD：强制采用测试驱动开发（单元测试 / 集成测试）
• 集成测试：使用 testcontainers 测试 Qdrant，确保测试环境隔离且稳定。
• CI/CD：使用 GitHub Actions 进行构建、测试和预构建索引资源管理

测试与故障排除

某些测试（尤其是集成测试和嵌入向量相关测试）可能会因操作系统文件描述符限制或缓存锁问题而失败。

常用命令（通过 Makefile）

• 所有测试（包括被忽略的测试）：

  make test-all
  

• 单元测试（仅 lib，清理缓存锁，单线程运行）：

  make test-lib
  

• 集成测试（单线程运行）：

  make test-integration
  

• 清理嵌入模型缓存：

  make clean-cache
  

故障排除

• 如果看到 Too many open files 错误：
  • 在运行测试之前，先在 shell 中提高文件描述符限制：ulimit -n 4096
  • 按顺序运行测试：cargo test -- --test-threads=1（或使用 make test-lib / make test-integration）
• 如果看到 .lock 错误（与嵌入模型缓存有关）：
  • 清理缓存：make clean-cache
• 如果涉及 forge 命令的测试意外失败：
  • 确认特定测试文件（src/main.rs 测试）中的模拟脚本设置正确。
• 注意：
  • Makefile 为常见任务提供了便捷快捷方式，但某些操作系统或 CI 环境可能需要手动调整文件描述符限制（ulimit）。
  • 更多详情请参阅各个 Makefile 目标。

---

任务管理与进度

如需了解最新里程碑、进度和详细任务跟踪，请参阅： ➡️ mc-mcp 任务列表

---

许可证

MIT