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 許可。