Ahma MCP

🚀 Ahma MCP

Ahma MCP 能让你仅用一个 JSON 文件，就能将命令行工具转化为智能代理。借助真正的多线程工具使用代理式 AI 工作流，它能让你的工作完成得更高效。

ahma_mcp 能快速适配命令行工具，供 AI 调用。AI 调用工具后，能迅速确认后台进程已启动，从而继续进行规划和分析，并在每个操作完成时自动接收工具执行结果。多个并发的工具调用可并行执行。若有需要，个别工具和子命令可标记为 synchronous: true，以实现传统的阻塞式 MCP 工具调用。通常情况下，AI 无需 await 异步工具完成，因为工具完成时它会自动获取结果，但在必要时也可以这么做。

Ahma（芬兰语中意为狼獾）是一款坚韧且敏捷的工具，与常见的同步工具相比，它能加速你的工作流，让你更快地完成复杂任务。

🚀 快速开始

使用支持 MCP 的 VS Code 是体验 ahma_mcp 的最快方式。

# 1) 克隆仓库并构建发布版本的二进制文件
git clone https://github.com/paulirotta/ahma_mcp.git
cd ahma_mcp
cargo build --release

# 2) 将 `tools/`、`.vscode/` 和 `.gihub/chatmodes/` 复制到你的 VS Code 项目中，并根据需要编辑路径、工具和 AI 工具使用指南。

然后将内容复制到你的 VS Code MCP 配置文件中（各操作系统的文件位置如下），重启 VS Code，即可开始使用。

✨ 主要特性

通用特性

• 通用 CLI 适配：通过 MTDF JSON 配置，可与任何命令行工具配合使用。
• 异步优先架构：操作默认异步执行，结果会自动推送给 AI，减少 AI 阻塞时间，支持并发工作流。
• 多工具支持：单个服务器可同时处理多个 CLI 工具，每个工具对应一个 MTDF JSON 文件。
• 测试驱动开发：使用 cargo nextest 进行全面测试，超过 70 个测试用例确保可靠性。
• 代码覆盖率集成：内置 cargo llvm-cov 支持，用于详细的测试覆盖率分析和报告（同步操作）。
• 简洁工具命名：“默认”子命令模式提供直观的工具名称，无冗余后缀。
• 模块化工具架构：可选工具存于单独的 JSON 文件中，提高可维护性和组织性。
• 集中式指导系统：tool_guidance.json 中的可重用指导块通过 guidance_key 引用，确保跨工具的 AI 指令一致。
• MtdfValidator：内置模式验证确保 MTDF 配置正确，防止常见错误。
• AI 优化指导：工具描述包含明确建议，鼓励高效的并发工作。

关键特性

• 异步优先执行：操作默认异步执行，完成时自动发送 MCP 进度通知，消除 AI 阻塞，支持并发工作流。
• 动态工具适配：使用 MTDF（MCP 工具定义格式）从 JSON 配置自动创建 MCP 工具模式，无需编译即可集成工具。
• 高性能 shell 池：预热的 shell 进程使命令启动速度提高 10 倍（5 - 20ms 对比 50 - 200ms），优化同步和异步操作。
• AI 生产力优化：集中式指导系统中的可重用块指导 AI 客户端继续高效工作，而非等待结果。
• 选择性同步覆盖：快速操作（状态、版本、检查）可在 JSON 配置中标记为 "synchronous": true，以立即获取结果，无需通知。
• 统一工具接口：为每个 CLI 应用子命令暴露 MCP 工具，通过一致的命名模式简化 AI 交互模型。
• 自动结果推送：无需轮询或等待，操作完成时，结果通过 MCP 通知自动推送给 AI 客户端。
• 可定制工具提示：为 AI 客户端提供智能建议，告知其在操作执行期间可进行的高效并行工作。

高级特性

操作管理与监控

• 实时操作监控：使用 status 工具跟踪所有运行操作的状态。
• 智能等待功能：使用 await 工具监控操作，可配置超时时间（1 - 1800 秒，默认 240 秒）。
• 渐进式超时警告：在超时时间的 50%、75% 和 90% 时接收警告，跟踪长时间运行的操作。
• 自动错误修复：操作超时时获取具体建议，包括：
  • 检测陈旧的锁文件（Cargo.lock、package-lock.json、yarn.lock、composer.lock 等）。
  • 网络连接检查和离线模式建议。
  • 磁盘空间和资源使用监控建议。
  • 进程冲突检测和解决步骤。
• 部分结果恢复：超时时，已完成的操作返回结果，失败的操作提供详细错误信息。

优雅开发工作流

• 信号感知关闭：在文件更改和 cargo watch 重启期间优雅处理 SIGTERM/SIGINT 信号。
• 操作完成宽限期：关闭前提供 10 秒窗口，让正在进行的操作自然完成。
• 开发友好重启：开发期间文件更改不会突然终止操作，操作会先完成并交付结果。
• 进度反馈：关闭序列期间，视觉进度指示器（🔄⏳⚠️）显示操作状态。

📦 安装指南

前提条件

• Rust 1.70+：从 rustup.rs 安装。
• VS Code：支持 MCP（推荐安装 GitHub Copilot 扩展）。
• Git：用于克隆仓库。

安装步骤

1. 克隆并构建仓库：

   git clone https://github.com/paulirotta/ahma_mcp.git
   cd ahma_mcp
   cargo build --release
   

2. 验证安装：

   ./target/release/ahma_mcp --help
   

工具配置

Ahma MCP 使用 tools/ 目录中的 MTDF（MCP 工具定义格式）JSON 文件来定义 CLI 工具集成：

内部工具（在 ahma_mcp 中实现）：

• await.json - 操作协调，等待一个或多个工具完成。
• status.json - 正在进行和最近完成的操作信息。

外部工具定义 用于命令行工具，存于 .ahma/tools/ 中。复制并编辑你需要的工具，或添加自己的工具：

Rust 生态系统：

• cargo.json - Rust 包管理器，支持递归子命令（13 个子命令）。
• cargo_audit.json - 审计 Cargo.lock 的安全漏洞（2 个子命令）。
• cargo_bench.json - 为 Rust 项目运行基准测试（1 个子命令）。
• cargo_clippy.json - 增强的 Rust 代码 linting 和质量检查（1 个子命令）。
• cargo_edit.json - 编辑 Cargo.toml 文件的工具（4 个子命令）。
• cargo_fmt.json - 根据风格指南格式化 Rust 代码（1 个子命令）。
• cargo_llvm_cov.json - Rust 项目的 LLVM 源代码覆盖率（8 个子命令，同步）。
• cargo_nextest.json - Rust 的下一代测试运行器（1 个子命令）。

版本控制与 CI/CD：

• git.json - Git 版本控制系统（10 个子命令）。
• gh.json - GitHub CLI，支持嵌套操作，如 cache delete 和 run cancel（10 个子命令）。

通用开发：

• python3.json - Python 解释器和模块执行（7 个子命令）。
• gradlew.json - Android/Java 项目的 Gradle 包装器（47 个子命令）。
• shell_async.json - 异步执行 shell 命令（1 个子命令）。
• long_running_async.json - 用于测试异步行为的睡眠实用工具（1 个子命令）。

文件操作：

• cat.json - 查看文件内容（单个命令）。

每个 MTDF 文件可使用 guidance_key 字段引用 .ahma/tool_guidance.json 中的指导块，避免指导重复，确保一致性。有关详细的模式信息和验证，请参阅 。

测试安装

运行全面的测试套件以验证一切正常：

# 使用 nextest 运行所有测试（更快的测试运行器）
cargo nextest run

# 运行带覆盖率分析的测试
cargo llvm-cov nextest --html --open

# 替代方案：标准 cargo 测试
cargo test

你应该会看到类似以下的输出：

✓ Finished running 76 tests across 45 binaries (2.34s)

💻 使用示例

基础用法

以下是使用 Ahma MCP 与 VS Code 集成的基本步骤：

# 克隆并构建仓库
git clone https://github.com/paulirotta/ahma_mcp.git
cd ahma_mcp
cargo build --release

# 复制配置文件到 VS Code 项目
# 编辑配置文件中的路径、工具和 AI 工具使用指南

# 复制内容到 VS Code MCP 配置文件
# 不同操作系统的配置文件位置不同
# 重启 VS Code

高级用法

VS Code MCP 集成

步骤 1：在 VS Code 中启用 MCP

在你的 VS Code 设置中（Ctrl/Cmd+, → 搜索 "settings.json"）添加以下内容：

{
  "chat.mcp.enabled": true
}

步骤 2：配置 MCP 服务器

创建或编辑你的全局 MCP 配置文件：

位置：

• macOS：~/Library/Application Support/Code/User/mcp.json
• Linux：~/.config/Code/User/mcp.json
• Windows：%APPDATA%\Code\User\mcp.json

{
    "servers": {
        "ahma_mcp": {
            "type": "stdio",
            "cwd": "${workspaceFolder}",
            "command": "target/release/ahma_mcp",
            "args": [
                "--server",
                "--tools-dir",
                "tools"
            ]
        }
    },
    "inputs": []
}

步骤 3：重启 VS Code

保存 mcp.json 文件后，重启 VS Code 以激活 MCP 服务器。

步骤 4：验证连接

1. 打开 VS Code 并与 GitHub Copilot 开始聊天。
2. 你应该会在可用的 MCP 服务器列表中看到 "ahma_mcp"。
3. 让你的 AI 使用 ahma_mcp 工具，例如："使用 ahma_mcp 显示 git 状态"。

可用工具

连接成功后，你将可以使用约 44 个动态生成的 MCP 工具：

Git 操作：

• mcp_ahma_mcp_git_status - 检查工作树状态
• mcp_ahma_mcp_git_add - 暂存更改
• mcp_ahma_mcp_git_commit - 创建提交
• mcp_ahma_mcp_git_push - 上传更改
• mcp_ahma_mcp_git_pull - 下载更改
• 还有 17 个以上的 git 子命令

Cargo 操作：

• mcp_ahma_mcp_cargo_build - 构建项目
• mcp_ahma_mcp_cargo_test - 运行测试
• mcp_ahma_mcp_cargo_run - 运行二进制文件
• mcp_ahma_mcp_cargo_check - 检查代码而不构建
• mcp_ahma_mcp_cargo_doc - 构建文档
• mcp_ahma_mcp_cargo_add - 添加依赖项
• mcp_ahma_mcp_cargo_remove - 移除依赖项
• mcp_ahma_mcp_cargo_update - 更新依赖项
• mcp_ahma_mcp_cargo_fetch - 获取依赖项
• mcp_ahma_mcp_cargo_install - 安装二进制文件
• mcp_ahma_mcp_cargo_search - 搜索 crate
• mcp_ahma_mcp_cargo_tree - 依赖树
• mcp_ahma_mcp_cargo_version - Cargo 版本
• mcp_ahma_mcp_cargo_rustc - 自定义 rustc
• mcp_ahma_mcp_cargo_metadata - 包元数据
• mcp_ahma_mcp_cargo_audit_audit - 审计依赖项的漏洞
• mcp_ahma_mcp_cargo_bench_bench - 运行基准测试
• mcp_ahma_mcp_cargo_clippy_clippy - 使用 clippy 进行代码 linting
• mcp_ahma_mcp_cargo_edit_add - 使用 cargo-edit 添加依赖项
• mcp_ahma_mcp_cargo_edit_remove - 使用 cargo-edit 移除依赖项
• mcp_ahma_mcp_cargo_edit_upgrade - 使用 cargo-edit 升级依赖项
• mcp_ahma_mcp_cargo_edit_bump_version - 使用 cargo-edit 提升包版本
• mcp_ahma_mcp_cargo_fmt_fmt - 使用 rustfmt 格式化代码
• mcp_ahma_mcp_cargo_nextest_run - 使用 nextest 运行测试
• mcp_ahma_mcp_cargo_llvm_cov_test - 使用 LLVM 覆盖率运行测试（同步）
• mcp_ahma_mcp_cargo_llvm_cov_run - 使用 LLVM 覆盖率运行二进制文件（同步）
• mcp_ahma_mcp_cargo_llvm_cov_report - 生成覆盖率报告（同步）
• mcp_ahma_mcp_cargo_llvm_cov_show_env - 显示覆盖率环境（同步）
• mcp_ahma_mcp_cargo_llvm_cov_clean - 清理覆盖率数据（同步）
• mcp_ahma_mcp_cargo_llvm_cov_nextest - 使用 LLVM 覆盖率运行 nextest（同步）
• 可选（如果已安装）：clippy、nextest、fmt、audit、upgrade、bump_version、bench

文件操作（核心集）：

• mcp_ahma_mcp_cat_run - 查看文件内容
• mcp_ahma_mcp_grep_run - 搜索文本模式
• mcp_ahma_mcp_sed_run - 编辑文本流
• mcp_ahma_mcp_echo_run - 输出文本

可选（按需添加）：可以重新引入列表工具（ls.json）；测试不再假设其存在。

操作管理：

• mcp_ahma_mcp_status - 检查所有操作的状态（活跃、完成、失败）
• mcp_ahma_mcp_wait - 等待操作完成，可配置超时时间（1 - 1800 秒，默认 240 秒）

故障排除

MCP 工具无法使用

1. 验证二进制文件路径是否存在：ls -la /path/to/your/ahma_mcp/target/release/ahma_mcp
2. 检查工具目录路径：ls -la /path/to/your/ahma_mcp/.ahma/tools/
3. 完全重启 VS Code
4. 检查 VS Code 开发者工具（帮助 → 切换开发者工具）中的 MCP 错误

“execution_failed” 错误

• 确保 mcp.json 中的所有路径都是绝对路径（无 ~ 或环境变量）
• 使用直接的二进制文件路径，而非 cargo run
• 验证文件权限：chmod +x /path/to/your/ahma_mcp/target/release/ahma_mcp
• 若更新了仓库，重新构建发布版本的二进制文件：cargo build --release

性能问题

• 始终使用预构建的二进制文件路径（而非 cargo run）
• 使用绝对路径以避免查找延迟
• 确保已运行 cargo build --release

操作超时

• 默认超时时间为 240 秒（4 分钟），大多数操作足够。
• 使用 status 工具检查哪些操作仍在运行。
• 使用 await 工具设置自定义超时时间：超时范围为 1 - 1800 秒（最大 30 分钟）。
• 常见的超时原因包括网络问题、锁定文件或资源争用。
• 检查陈旧的锁定文件（Cargo.lock、package-lock.json、yarn.lock 等）。
• 验证下载操作的网络连接。
• 在长时间构建期间，使用 top 或活动监视器监控系统资源。

开发工作流中断

• Ahma MCP 包含对 cargo watch 和文件更改重启的优雅关闭处理。
• 开发期间文件更改时，正在进行的操作有 10 秒时间自然完成。
• 信号处理（SIGTERM/SIGINT）允许干净关闭，而非突然终止。
• 即使在关闭序列期间，操作也会收到完成通知。

性能：预热 shell 池

Ahma MCP 使用预热的 shell 池来最小化命令启动延迟。详情请参阅 shell_pool.rs

📚 详细文档

创建自定义工具配置

如果你想添加自己的 CLI 工具，可在 tools/ 目录中创建一个 MTDF（MCP 工具定义格式）JSON 文件：

快速开始模板

{
    "name": "your_tool",
    "description": "Brief description of the tool",
    "command": "your_command",
    "enabled": true,
    "subcommand": [
        {
            "name": "subcommand_name",
            "guidance_key": "sync_behavior",
            "synchronous": true,
            "description": "What this subcommand does",
            "options": [
                {
                    "name": "option_name",
                    "type": "string",
                    "description": "Option description"
                }
            ]
        }
    ]
}

指导系统

使用集中式指导系统维护一致的 AI 指令：

• 引用指导块：对于长时间运行的操作，使用 "guidance_key": "async_behavior"。
• 引用指导块：对于快速操作，使用 "guidance_key": "sync_behavior"。
• 引用指导块：对于 await/status 工具，使用 "guidance_key": "coordination_tool"。
• 自定义指导：在 tool_guidance.json 中定义可重用块。

文档和示例

• 完整 MTDF 规范：
• 实际示例：查看 中的实时工具配置（例如，cargo.json、python3.json、gh.json）。
• 模式验证：内置的 MtdfValidator 提供有用的错误消息和建议。
• IDE 支持：JSON 模式支持开发环境中的自动完成功能。

🔧 技术细节

MTDF: MCP 工具定义格式

MTDF 是 ahma_mcp 基于 JSON 的工具配置格式，支持动态工具加载，无需更改代码：

• 动态工具注册：通过在 tools/ 目录中创建 JSON 文件添加新工具。
• 零编译集成：添加 CLI 工具无需更改 Rust 代码。
• 递归子命令支持：使用嵌套子命令对复杂的 CLI 工具进行建模（例如，cargo nextest run、gh cache delete）。
• 简洁工具命名：“默认”子命令模式提供简洁的工具名称（例如，cargo_fmt 而非 cargo_fmt_default）。
• 模块化架构：可选工具存于单独的 JSON 文件中，提高可维护性。
• 集中式指导系统：通过 tool_guidance.json 实现可重用的 AI 指导块。
• 模式验证：内置的 MtdfValidator 确保配置正确。
• 同步/异步控制：每个子命令可进行细粒度的执行模式控制。
• JSON 模式导出：自动生成的模式位于 ，用于验证和 IDE 支持。

兼容性

除 Grok Code Fast 1（它更喜欢终端而非 MCP 工具调用）外，测试过的工具调用 AI 均可正常工作。

支持 STDIO MCP 的 IDE 应该可以正常使用，但大多数测试是在 VS Code 中进行的。

基于 HTTP 的 MCP 客户端目前尚不支持。

欢迎提交问题报告和拉取请求。

📄 许可证

本项目根据 Apache License 2.0 或 MIT License 许可。