Angreal MCP Server

Angreal MCP 服务

一个 MCP（模型上下文协议）服务，为 AI 助手提供 angreal 项目的发现能力。

概述

此服务向兼容 MCP 的客户端公开 angreal 的命令树结构，使 AI 助手能够：

• 发现 angreal 项目中可用的命令和任务
• 了解项目结构和功能
• 根据上下文建议合适的命令

前提条件

• 必须安装 angreal，并确保它位于 PATH 中
• Rust 工具链（用于从源代码构建）

安装

# Install from crates.io
cargo install angreal_mcp

# Or install from git (latest development version)
cargo install --git https://github.com/colliery-io/angreal-mcp

使用

使用 Claude Code

在 ~/.config/claude-code/mcp_servers.json 中创建或更新 Claude Code MCP 配置文件：

{
  "mcpServers": {
    "angreal": {
      "command": "angreal_mcp",
      "args": [],
      "env": {}
    }
  }
}

使用 Claude Desktop

将以下内容添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "angreal": {
      "command": "angreal_mcp",
      "args": [],
      "cwd": "/path/to/your/angreal/project"
    }
  }
}

使用 Cline（VS Code）

将以下内容添加到 Cline 配置中：

{
  "mcp": {
    "servers": [
      {
        "name": "angreal",
        "command": ["angreal_mcp"],
        "cwd": "${workspaceFolder}"
      }
    ]
  }
}

命令行测试

你可以直接通过命令行测试 MCP 服务：

# List available tools
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | angreal_mcp

# Get angreal command tree
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "angreal_tree", "arguments": {"format": "json"}}}' | angreal_mcp

可用工具

angreal_check

检查当前目录是否为 angreal 项目，并获取项目状态，包括可用命令。

angreal_tree

获取项目中所有可用 angreal 命令和任务的结构化视图。

参数：

• format（可选）：输出格式——"json"（默认）或 "human"

angreal_run

执行 angreal 命令或任务，并可选择传入参数。

参数：

• command（必填）：要执行的 angreal 命令/任务
• args（可选）：其他参数和标志

Agent 使用指南

在 angreal 项目中工作时，使用这些工具来智能地发现和执行命令：

工具使用工作流

1. 从发现开始：使用 angreal_check 验证项目状态和功能
2. 探索命令：使用 angreal_tree 查看带有丰富元数据的可用命令
3. 智能执行：使用 angreal_run，并根据上下文选择参数

最佳实践

• 始终查看 angreal_tree 中的 when_to_use 和 when_not_to_use 指引
• 使用参数建议（recommended_when）以获得更好的结果
• 执行命令前确认前置条件
• 根据命令输出和退出代码判断是否执行成功

常见模式

• 设置工作流：在构建/测试命令之前运行设置/安装命令
• 开发周期：代码更改后使用测试命令，部署前使用构建命令
• 参数选择：调试时使用详细标志，发布时使用生产环境标志

故障排除

• 如果 MCP 服务不可用，重启 Claude Code 以重新初始化
• 检查 angreal 二进制文件是否已安装并可通过 PATH 访问
• 确认你位于 angreal 项目目录中（其中包含 .angreal/ 文件夹）

angreal MCP 服务提供增强的命令元数据，包括使用场景、参数指引和智能分类，从而支持更好的自动化决策。

开发

运行测试

本项目使用 angreal 作为测试运行器：

# Run tests using angreal
angreal test

项目结构

angreal_mcp/
├── src/
│   ├── main.rs      # Main server loop
│   ├── mcp.rs       # MCP protocol implementation
│   └── angreal.rs   # Angreal integration
├── examples/        # Configuration examples
└── tests/          # Integration tests

构建

# Debug build
cargo build

# Release build
cargo build --release

许可证

本项目采用双重许可，遵循 MIT OR Apache-2.0 许可。