项目简介

Ahma MCP（芬兰语意为“狼獾”）是一个强大而敏捷的工具，旨在将任何命令行工具快速适配为Model Context Protocol (MCP) 感知的AI代理。它支持通过简单的JSON文件定义工具，实现零编译集成。AI可以通过异步调用工具并在后台运行命令时继续思考和规划，从而显著减少任务完成时间，加速AI驱动的工作流。

主要功能点

命令行工具Agent化: 通过JSON文件（MTDF格式）将现有命令行工具（如Git, Cargo, Python, Gradlew, Echo, Cat, Grep, Sed等）转换为AI可调用的Agent，无需代码更改。
异步并行执行: 默认支持异步工具调用，AI在等待命令结果的同时可以继续进行规划和推理，并自动接收工具结果，实现真正的多线程并发，大幅减少任务总时长。
细粒度控制: 可将快速执行的工具标记为同步模式，允许AI立即获得结果。同时，通过文件路径安全限制，确保工具使用范围不超出指定工作目录。
集中式指导系统: 提供可重用的AI指导块（通过 'tool_guidance.json' 配置），帮助AI理解如何有效使用工具，包括异步操作的最佳实践和并发策略。
JSON Schema支持: 自动为每个工具及其子命令生成详细的JSON Schema，用于参数验证和提供丰富的IDE支持（如自动补全和错误提示）。
会话管理与通知: 通过JSON-RPC协议与客户端通信，支持会话管理、能力声明，并提供异步通知机制实时跟踪长时间运行的操作状态，避免AI轮询。
预热Shell池: 使用预热的Shell进程池，最大程度减少命令启动延迟，进一步提升执行效率。

安装步骤

克隆并构建仓库:

git clone https://github.com/paulirotta/ahma_mcp.git
cd ahma_mcp
cargo build --release
# 您可以通过运行以下命令验证安装：
./target/release/ahma_mcp --help

复制默认工具配置文件:
```
cp -r .ahma/ ~/.ahma/
```
（此步骤将仓库中预定义的工具配置（如Git, Cargo等）复制到您的用户配置目录。您可以根据需要删除 '~/.ahma/tools/' 目录下不需要的工具JSON文件。）

服务器配置（MCP客户端用）

此MCP服务器通过Stdio（标准输入输出）协议与MCP客户端（如VS Code的GitHub Copilot Chat）通信。以下是典型的MCP客户端配置示例，用于连接Ahma MCP服务器：

{
    "servers": {
        "ahma_mcp": {
            "type": "stdio", // 通信协议类型，这里是标准输入输出
            "cwd": "${workspaceFolder}", // 服务器的工作目录，通常是AI助手所作用的项目根目录
            "command": "target/release/ahma_mcp", // 启动Ahma MCP服务器可执行文件的命令
            "args": [
                "--server", // 告诉Ahma MCP以服务器模式运行
                "--tools-dir", ".ahma/tools" // 指定工具配置文件所在的目录
            ]
        }
    },
    "inputs": []
}

配置说明:

将上述JSON片段添加到您的MCP客户端全局配置文件中。例如：
- macOS: '~/Library/Application Support/Code/User/mcp.json'
- Linux: '~/.config/Code/User/mcp.json'
- Windows: '%APPDATA%\Code\User\mcp.json'
确保 'command' 字段指向您编译出的 'ahma_mcp' 可执行文件的正确路径。

基本使用方法

重启MCP客户端: 在保存 'mcp.json' 文件后，完全重启您的MCP客户端（如VS Code）以激活新的服务器配置。
启动AI助手对话: 打开VS Code并启动与GitHub Copilot等AI助手的对话。
验证连接: AI助手现在应该能够识别并访问由Ahma MCP提供的工具。
调用工具: 您可以要求AI执行命令，例如：
- “使用 'ahma_mcp' 显示git状态”
- “使用 'ahma_mcp' 运行cargo测试”
- AI将调用相应的命令行工具并返回结果。
异步操作: 对于长时间运行的任务，AI会收到一个操作ID，并可以在后台继续工作。当任务完成时，AI会收到通知，可以根据结果继续下一步规划。
查看状态: 使用 'status' 工具可以随时查询当前活动或已完成操作的状态。
等待操作: 当需要等待特定操作完成才能继续时，使用 'await' 工具（该工具已优化，会智能计算等待时长，而非无限期阻塞）。

关键词

项目简介

主要功能点

安装步骤

服务器配置（MCP客户端用）

基本使用方法

信息