Arcade-MCP

# Arcade-MCP **Arcade-MCP** 是一个连接 **llama.cpp 服务器模型** 与 **MCP 工具** 的轻量级桥梁，实现了结构化的工具执行、进度跟踪和可扩展的本地 AI 工作流。 --- ## 🚀 概述 Arcade-MCP 使本地运行的 `llama.cpp` 模型能够通过简单且模块化的服务器接口与 MCP 兼容的工具进行交互。 本项目适用于： * 本地 LLM 工具编排 * 由 MCP 驱动的代理工作流 * 高性能轻量级推理设置 * 工具增强推理实验 --- ## 🏗️ 架构 ### Claude MCP 工作流（官方图表）  * 官方 Claude MCP 架构，展示了完整的消息流程：用户 → 我们的服务器 → MCP 客户端 → MCP 服务器 → Claude → GitHub。这演示了工具发现（ListToolsRequest/Result）、查询处理（Query + Tools）、工具执行（CallToolRequest/Result）和响应合成如何协同工作。* ### Llama.cpp 服务器运行  * Llama.cpp 服务器在本地运行在 8080 端口，加载 GGUF 模型，显示上下文窗口（8192 个令牌）、批处理、连续批处理启用和多线程推理。服务器提供 `/v1/chat/completions` 端点用于 MCP 集成。* ### CLI 聊天界面  * 命令行界面，展示与 MCP 驱动的代理实时交互。用户可以通过自然语言查询 GitHub 仓库、文件系统和其他工具。界面显示工具执行进度、结果和格式化响应。* ### 网络搜索工具  ### MCP 网络代理 — ARIA > **ARIA** 是一个网络代理，封装了所有 CLI 工具在一个干净的 GUI 中，因此您可以完全跳过终端。 > 它支持 `/` 斜杠命令用于手动工具选择，或根据您的查询自动选择合适的工具。 > > ⚠️ ARIA 仍在积极开发中 — 在低端模型上，自动工具选择可能会表现出不一致的行为。建议使用高端模型以获得最佳结果。 --- ### 基础知识 <img src="./docs/images/basicknowledge.png" width="550"/> ### 网络搜索 <img src="./docs/images/internet.png" width="550"/> ### 斜杠命令 <img src="./docs/images/slashCommand.png" width="550"/> --- ### 技能 #### 代码审查 <img src="./docs/images/CodeExplainSkill.png" width="550"/> #### 文档 <img src="./docs/images/doc_Skill.png" width="550"/> #### 摘要 <img src="./docs/images/summarization_skills.png" width="550"/> ### 系统架构概述 ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ ARCADE-MCP 系统 │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────┐ ┌──────────────┐ ┌─────────────┐ │ │ │ 用户 │────▶│ 我们的服务器 │────▶│ MCP 客户端 │ │ │ │ （CLI） │ │ （Arcade） │ │ │ │ │ └──────────┘ └──────────────┘ └─────────────┘ │ │ │ │ │ │ │ ▼ │ │ │ ┌─────────────┐ │ │ │ │ MCP 服务器 │ │ │ │ │ （工具） │ │ │ │ └─────────────┘ │ │ │ │ │ │ ▼ │ │ │ ┌──────────────┐ │ │ │ │ Claude │◀────────────┘ │ │ │ （llama.cpp） │ │ │ │ 端口 8080 │ │ │ └──────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────┐ │ │ │ 外部服务 │ │ │ │ （天气、 │ │ │ │ 时间、 │ │ │ │ 网络（FS） │ │ │ └──────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘ ``` --- ## 📊 设置架构图表 要显示架构图表，您需要将三个图像上传到您的仓库： 1. **创建 `docs/images/` 目录** 在您的仓库中： ```bash mkdir -p docs/images ``` 2. **添加以下截图/图像**： - `claude-mcp-diagram.png` - 官方 Claude MCP 工作流图表（使用您提供的截图） - `llama-server.png` - Llama.cpp 服务器在终端中运行的截图 - `chat-cmd.png` - CLI 聊天界面运行中的截图 3. **捕获截图**： **对于 `llama-server.png`：** - 使用您的模型运行 Llama.cpp 服务器 - 截取显示服务器启动输出、端口绑定和模型加载的截图 **对于 `chat-cmd.png`：** - 运行您的 Arcade-MCP CLI 聊天界面 - 与其交互（例如，询问 “我有哪些仓库？”） - 截取显示对话和工具执行的截图 4. **上传到 GitHub**： ```bash git add docs/images/*.png git commit -m "添加架构图表" git push ``` 图像将自动显示在 README 中： ``` https://raw.githubusercontent.com/ProjectArcade/Arcade-MCP/main/docs/images/ ``` --- ## 🚀 快速开始 ### 安装步骤 1. **克隆并设置 llama.cpp**： ```bash git clone https://github.com/ggerganov/llama.cpp cd llama.cpp make -j ``` 2. **克隆 Arcade-MCP**： ```bash git clone https://github.com/ProjectArcade/Arcade-MCP.git cd Arcade-MCP ``` 3. **安装依赖项**： ```bash pip install -r requirements.txt # 或 uv pip install -r requirements.txt ``` 4. **下载模型** 并将其放在 `models/` 中： ```bash # 示例：下载一个小模型 wget https://huggingface.co/... -O models/1.5b-instruct.gguf ``` 5. **启动 Llama.cpp 服务器**： ```bash ./build/bin/llama-server -m ./models/1.5b-instruct.gguf --port 8080 ``` 6. **启动 Arcade-MCP** （在新终端中）： ```bash python server.py ``` 7. **开始聊天！** CLI 将提示您输入。 --- ## 📦 需求 * Linux 或 macOS（支持 WSL） * 编译的 `llama.cpp` 服务器二进制文件 * GGUF 模型文件 * Python 运行时（用于 Arcade-MCP 服务器） * 配置的 MCP 工具 --- ## 🧠 模型设置 将您的 GGUF 模型放在 `models/` 目录中。 示例： ``` models/1.5b-instruct.gguf ``` --- ## ⚙️ 启动 Llama.cpp 服务器 运行以下命令启动本地推理服务器： ```bash THREADS=$(($(nproc)-2)) if [ "$THREADS" -lt 2 ]; then THREADS=2; fi ./build/bin/llama-server \ -m ./models/1.5b-instruct.gguf \ --reasoning-format none \ --reasoning-budget 0 \ --host 127.0.0.1 \ --port 8080 \ -c 8192 \ -np 2 \ -b 1024 \ -t $THREADS \ --mlock \ --cont-batching & ``` ### 参数说明 * `-m` — GGUF 模型的路径 * `--host`, `--port` — 服务器绑定配置 * `-c` — 上下文长度（8192 个令牌） * `-np` — 并行序列数 * `-b` — 批大小 * `-t` — CPU 线程数（自动计算） * `--mlock` — 防止模型内存被交换 * `--cont-batching` — 启用连续批处理以提高吞吐量 --- ## 🔌 启动 Arcade-MCP 服务器 运行 MCP 桥接服务器： ```bash python server.py ``` 或： ```bash uv run server.py ``` 服务器将： * 连接到本地 `llama.cpp` API 端点 (`http://127.0.0.1:8080`) * 加载配置的 MCP 工具 * 启用结构化的工具执行工作流 * 初始化会话管理 * 设置请求/响应管道 --- ## 🌐 访问 * LLM 服务器 API → `http://127.0.0.1:8080` * Arcade-MCP 接口 → CLI（计划中的 UI 支持） --- ## 🔄 工作流示例 ### GitHub 仓库查询 1. **用户输入**： "我有哪些仓库？" 2. **服务器处理**：接收查询，初始化 MCP 客户端 3. **工具发现**：MCP 客户端请求 MCP 服务器的可用工具 4. **Claude 分析**：查询 + 工具发送到 Llama.cpp 模型 5. **工具选择**：Claude 用 `ToolUse` 响应 `github_list_repos` 6. **工具执行**：MCP 客户端调用 MCP 服务器 → GitHub API 7. **结果处理**：GitHub 数据通过链返回 8. **响应合成**：Claude 格式化最终人类可读响应 9. **用户输出**： "您的仓库是：arcade-mcp, studybuddy, ..." --- ## ✨ 功能 * **完全本地推理** （无云依赖） * **MCP 工具执行管道** 具有结构化通信 * **流式进度支持** 实现实时反馈 * **模块化和可扩展的架构** 方便工具添加 * **兼容小、大 GGUF 模型** （测试 1.5B-70B+） * **连续批处理** 提高性能 * **多线程推理** 利用可用 CPU 核心 * **会话管理** 实现对话连续性 * **错误处理和恢复** 在每个层级 * **工具感知提示** 实现准确的功能调用 --- ## 🔄 MCP 工作流示例 以下是当您询问 “我有哪些仓库？”时会发生的情况： ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 消息流程时间线 │ └─────────────────────────────────────────────────────────────────────────┘ 1. 用户输入 您： “我有哪些仓库？” ↓ 2. 服务器处理 Arcade 服务器接收查询 → 初始化 MCP 客户端 ↓ 3. 工具发现 MCP 客户端 ──[ListToolsRequest]──▶ MCP 服务器 MCP 服务器 ──[ListToolsResult]───▶ MCP 客户端 可用工具： ✓ github_list_repos ✓ github_get_file ✓ filesystem_read ↓ 4. 查询到 Claude 服务器 ──[查询 + 可用工具]──▶ Llama.cpp ↓ 5. 工具选择 Llama.cpp 分析查询 → 确定：需要调用 github_list_repos Llama.cpp ──[ToolUse: github_list_repos]──▶ 服务器 ↓ 6. 工具执行 服务器 ──[CallToolRequest]──▶ MCP 服务器 MCP 服务器 ──[GitHub API 调用]──▶ GitHub GitHub ──[仓库数据]──▶ MCP 服务器 MCP 服务器 ──[CallToolResult]──▶ 服务器 ↓ 7. 响应合成 服务器 ──[工具结果数据]──▶ Llama.cpp Llama.cpp 格式化人类可读响应 ↓ 8. 用户输出 代理： “您的仓库是： • arcade-mcp - 用于 Llama.cpp 的 MCP 集成 • studybuddy - AI 驱动的学习平台 • lykon - 自定义网络浏览器” ``` ## 🛠 开发 ### 构建 Llama.cpp ```bash git clone https://github.com/ggerganov/llama.cpp cd llama.cpp make -j ``` ### 安装 Python 依赖项 ```bash pip install -r requirements.txt ``` 或使用 `uv`： ```bash uv pip install -r requirements.txt ``` ### 核心模块 **`core/chat.py`** - 聊天会话管理和对话处理 - 管理对话历史 - 处理用户输入/输出格式化 - 会话状态管理 **`core/claude.py`** - 与 Llama.cpp LLM 集成 - 与 Llama.cpp 服务器的 API 通信 - 请求/响应处理 - 上下文窗口管理 **`core/mcp_chat.py`** - MCP 特定聊天界面 - 桥接聊天与 MCP 协议 - 工具调用编排 - 响应合成 **`core/cli.py`** - 命令行界面 - 用户交互循环 - 漂亮的打印和格式化 - 进度指示器 **`core/tools.py`** - 工具定义 - 工具注册 - 输入模式验证 - 执行处理程序 ### 主要文件 **`server.py`** - 应用程序入口点 - 初始化所有组件 - 启动 CLI 界面 - 处理正常关闭 **`mcp_client.py`** - MCP 客户端 - 连接到 MCP 服务器 - 工具发现（ListToolsRequest/Result） - 工具执行（CallToolRequest/Result） **`mcp_server.py`** - MCP 服务器 - 注册可用工具 - 处理工具执行请求 - 返回结果给客户端 --- ## 📄 许可证 GNU 通用公共许可证 ## 🤝 贡献 欢迎贡献！ 请在提交拉取请求前打开问题讨论重大更改。 ### 开发指南 1. 遵循 MCP 规范进行工具实现 2. 添加全面的错误处理 3. 包括文档字符串和类型提示 4. 使用多个模型大小进行测试 5. 为新功能更新文档 --- ## ⭐ 愿景 Arcade-MCP 旨在为构建 **具有工具访问权限的本地 AI 代理** 提供坚实的基础，支持实验、研究和消费级硬件上的生产级工作流。 通过将 `Llama.cpp` 的效率与 MCP 的可扩展性相结合，我们实现了： * **隐私优先的 AI** - 所有处理都发生在本地 * **经济高效的部署** - 无 API 费用 * **可定制的 工作流** - 为您的特定需求构建工具 * **研究友好** - 实验代理架构 * **生产就绪** - 可扩展且可靠的实际应用 --- ## ❓ 故障排除和 FAQ ### 常见问题 **问：Llama.cpp 服务器无法启动** ```bash # 检查端口 8080 是否已被占用 lsof -i :8080 # 杀死现有进程 kill -9 <PID> # 或使用其他端口 ./llama-server -m model.gguf --port 8081 ``` **问：启动 Arcade-MCP 时出现“连接被拒绝”** - 确保 Llama.cpp 服务器先运行 - 检查端口 8080 是否可访问：`curl http://127.0.0.1:8080` - 验证防火墙设置是否不阻止本地连接 **问：模型太慢 / 高 CPU 使用率** ```bash # 减少线程数 -t 4 # 仅使用 4 个线程而不是自动检测 # 减少上下文长度 -c 4096 # 而不是 8192 # 如果内存不足，请禁用 mlock # 删除 --mlock 标志 ``` **问：MCP 工具未被发现** - 检查 `tools/` 目录是否存在并包含 Python 文件 - 验证每个工具是否遵循 MCP 规范 - 检查服务器日志中的工具注册错误 **问：“内存不足”错误** - 使用较小的模型（1.5B 而不是 7B） - 减少批大小：`-b 512` - 减少上下文长度：`-c 2048` - 启用内存锁定： `--mlock` ### 性能优化 **对于仅 CPU 推断：** ```bash # 优化线程数（通常为核心数 - 2） THREADS=$(($(nproc)-2)) # 启用 BLAS 以实现更快的矩阵运算（如果可用） make LLAMA_BLAS=1 # 使用 Q4 或 Q5 量化模型以提高速度 ``` **为了更好的响应质量：** ```bash # 增加上下文长度 -c 16384 # 增加批大小（如果内存允许） -b 2048 # 使用更高质量的模型量化（Q6，Q8） ``` ### 调试模式 启用详细日志记录： ```bash # 对于 Llama.cpp ./llama-server --log-level DEBUG # 对于 Arcade-MCP export LOG_LEVEL=DEBUG python server.py ``` --- ## 📞 支持 如有问题和疑问： * 打开 GitHub 问题 * 查看现有文档 * 在 [modelcontextprotocol.io](https://modelcontextprotocol.io) 上查看 MCP 规范 --- **由 ❤️ 为本地 AI 社区构建**