街机MCP

街机MCP 是一座连接 llama.cpp服务器型号 随着 MCP工具，实现结构化工具执行、进度跟踪和可扩展的本地AI工作流。

______________________________________________________________________

🚀 概述

Arcade MCP支持本地运行 llama.cpp 该模型通过简单和模块化的服务器界面与MCP兼容工具进行交互。

本项目旨在：

本地LLM工具编排
由MCP驱动的代理工作流
高性能轻量级推理设置
工具增强推理实验

______________________________________________________________________

🏗️ 建筑

Claude MCP工作流程（官方图表）

Claude MCP Workflow

*显示完整消息流的官方Claude MCP架构：用户→ 服务器→ MCP客户端→ MCP 服务器→ 克劳德→ github。这演示了工具发现（ListToolsRequest/Result）、查询处理（query+Tools）、工具执行（CallToolRequest/ReResult）和响应合成如何在MCP协议中协同工作。*

Llama.cpp服务器正在运行

Llama Server

*Llama.cpp服务器在端口8080上本地运行，加载了GGUF模型，显示上下文窗口（8192个令牌）、批处理、启用连续批处理和多线程推理。服务器提供 /v1/chat/completions MCP集成的终点。*

CLI聊天界面

CLI Chat

*命令行界面显示与MCP驱动的代理的实时交互。用户可以通过自然语言查询他们的GitHub存储库、文件系统和其他工具。该界面显示工具执行进度、结果和格式化的响应。*

网络搜索工具

Web Search

MCP Web代理——ARIA

咏叹调 是一个web代理，它将所有CLI工具包装在一个干净的GUI中，因此您可以完全跳过终端。支持 / 斜线命令用于手动选择工具，或根据您的查询自动选择正确的工具。 ⚠️ ARIA仍在积极开发中——自动工具选择在低端模型上可能表现不一致。建议使用高端模型以获得最佳结果。

______________________________________________________________________

基本知识

网络搜索

斜杠命令

______________________________________________________________________

技能

代码审查

文档

摘要

系统架构概述

┌─────────────────────────────────────────────────────────────────────────┐
│                          ARCADE-MCP SYSTEM                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────┐      ┌──────────────┐      ┌─────────────┐                │
│  │   User   │────▶│  Our Server  │────▶│ MCP Client  │                │
│  │   (CLI)  │      │   (Arcade)   │      │             │                │
│  └──────────┘      └──────────────┘      └─────────────┘                │
│                           │                      │                      │
│                           │                      ▼                      │
│                           │              ┌─────────────┐                │
│                           │              │ MCP Server  │                │
│                           │              │   (Tools)   │                │
│                           │              └─────────────┘                │
│                           │                      │                      │
│                           ▼                      │                      │
│                    ┌──────────────┐              │                      │
│                    │    Claude    │◀────────────┘                      │
│                    │  (llama.cpp) │                                     │
│                    │   Port 8080  │                                     │
│                    └──────────────┘                                     │
│                           │                                             │
│                           ▼                                             │
│                    ┌──────────────┐                                     │
│                    │   External   │                                     │
│                    │   Services   │                                     │
│                    │  (Weather,   │                                     │
│                    │   Time,      │                                     │
│                    │   Web(FS)    │                                     │
│                    └──────────────┘                                     │
└─────────────────────────────────────────────────────────────────────────┘

______________________________________________________________________

📊 设置架构图

要显示架构图，您需要将三个图像上传到您的存储库：

创建一个 docs/images/ 目录 在您的存储库中：

   mkdir -p docs/images

添加以下截图/图片:

- claude-mcp-diagram.png -Claude MCP官方工作流程图（使用您提供的屏幕截图） - llama-server.png -终端中运行的llama.cpp服务器截图 - chat-cmd.png -CLI聊天界面运行截图

截图:

对于 llama-server.png:

- 使用您的模型运行llama.cpp服务器 - 截图显示服务器启动输出、端口绑定和模型加载

对于 chat-cmd.png:

- 运行Arcade MCP CLI聊天界面 - 与它互动（例如，问“我有什么存储库？”） - 截图显示工具执行时的对话

上传到GitHub:

   git add docs/images/*.png
   git commit -m "Add architecture diagrams"
   git push

这些图像将自动显示在README中：

https://raw.githubusercontent.com/ProjectArcade/Arcade-MCP/main/docs/images/

______________________________________________________________________

🚀 快速开始

安装步骤

克隆并设置llama.cpp:

   git clone https://github.com/ggerganov/llama.cpp
   cd llama.cpp
   make -j

克隆街机MCP:

   git clone https://github.com/ProjectArcade/Arcade-MCP.git
   cd Arcade-MCP

安装依赖项:

   pip install -r requirements.txt
   # or
   uv pip install -r requirements.txt

下载模型 然后把它放进去 models/:

   # Example: Download a small model
   wget https://huggingface.co/... -O models/1.5b-instruct.gguf

启动llama.cpp服务器:

   ./build/bin/llama-server -m ./models/1.5b-instruct.gguf --port 8080

启动街机MCP （在新航站楼中）：

   python server.py

开始聊天！ CLI将提示您输入。

______________________________________________________________________

📦 需求

Linux或macOS（支持WSL）
llama.cpp 使用服务器二进制文件编译
GGUF模型文件
Python运行时（适用于Arcade MCP服务器）
配置的MCP工具

______________________________________________________________________

🧠 模型设置

将您的GGUF模型放入 models/ 目录。

例子：

models/1.5b-instruct.gguf

______________________________________________________________________

⚙️ 启动llama.cpp服务器

运行以下命令以启动本地推理服务器：

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网桥服务器：

python server.py

或者：

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存储库查询

用户输入：“我有哪些存储库？”
服务器处理：接收查询，初始化MCP客户端
工具发现：MCP客户端向MCP服务器请求可用工具
克劳德分析：查询+工具发送到llama.cpp模型
工具选择：克劳德回应道 ToolUse 为了 github_list_repos
工具执行：MCP客户端调用MCP服务器→ GitHub API
结果处理：通过链返回的GitHub数据
响应综合：Claude格式化最终的人类可读响应
用户输出：“您的存储库是：街机mcp、studybuddy……”

______________________________________________________________________

✨ 特性

完全局部推理 （无云依赖）
MCP工具执行管道 结构化沟通
流媒体进度支持 用于实时反馈
模块化和可扩展的架构 便于添加工具
兼容小型和大型GGUF型号 （用1.5B-70B+测试）
连续配料 为了提高性能
多线程推理 利用可用的CPU内核
会话管理 保持对话的连续性
错误处理和恢复 在每一层
工具感知提示 用于精确的函数调用

______________________________________________________________________

🔄 MCP工作流示例

以下是当你问“我有什么存储库？”时会发生的情况：

┌─────────────────────────────────────────────────────────────────────────┐
│                        Message Flow Timeline                            │
└─────────────────────────────────────────────────────────────────────────┘

1. USER INPUT
   You: "What repositories do I have?"
        ↓

2. SERVER PROCESSING
   Arcade Server receives query
   → Initializes MCP Client
        ↓

3. TOOL DISCOVERY
   MCP Client ──[ListToolsRequest]──▶ MCP Server
   MCP Server ──[ListToolsResult]───▶ MCP Client
   
   Available tools:
   ✓ github_list_repos
   ✓ github_get_file
   ✓ filesystem_read
        ↓

4. QUERY TO CLAUDE
   Server ──[Query + Available Tools]──▶ llama.cpp
        ↓

5. TOOL SELECTION
   llama.cpp analyzes query
   → Determines: Need to call github_list_repos
   llama.cpp ──[ToolUse: github_list_repos]──▶ Server
        ↓

6. TOOL EXECUTION
   Server ──[CallToolRequest]──▶ MCP Server
   MCP Server ──[GitHub API Call]──▶ GitHub
   GitHub ──[Repository Data]──▶ MCP Server
   MCP Server ──[CallToolResult]──▶ Server
        ↓

7. RESPONSE SYNTHESIS
   Server ──[ToolResult Data]──▶ llama.cpp
   llama.cpp formats human-readable response
        ↓

8. USER OUTPUT
   Agent: "Your repositories are:
          • arcade-mcp - MCP integration for llama.cpp
          • studybuddy - AI-powered study platform
          • lykon - Custom web browser"

🛠 发展

构建llama.cpp

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
make -j

安装Python依赖项

pip install -r requirements.txt

或使用 uv:

uv pip install -r requirements.txt

核心模块

core/chat.py -聊天会话管理和对话处理

管理对话历史记录
处理用户输入/输出格式
会话状态管理

core/claude.py -与llama.cpp LLM集成

API与llama.cpp服务器的通信
请求/响应处理
上下文窗口管理

core/mcp_chat.py -MCP专用聊天界面

使用MCP协议的网桥聊天
工具调用编排
响应综合

core/cli.py -命令行界面

用户交互循环
漂亮的打印和格式化
进度指示器

core/tools.py -工具定义

工具注册
输入模式验证
执行处理程序

主文件

server.py -应用程序入口点

初始化所有组件
启动CLI界面
处理优雅关机

mcp_client.py -MCP客户端

连接到MCP服务器
工具发现（列出工具请求/结果）
工具执行（调用工具请求/结果）

mcp_server.py -MCP服务器

注册可用工具
处理工具执行请求
将结果返回给客户端

______________________________________________________________________

📄 许可证

GNU通用公共许可证

🤝 贡献

欢迎投稿！请在提交pull请求之前打开一个问题来讨论主要更改。

开发指南

工具实施遵循MCP规范
添加全面的错误处理
包括文档字符串和类型提示
使用多种型号尺寸进行测试
更新新功能的文档

______________________________________________________________________

⭐ 视觉

Arcade MCP旨在为建筑提供坚实的基础 具有工具访问权限的本地AI代理，支持消费类硬件上的实验、研究和生产级工作流程。

通过结合效率 llama.cpp 借助MCP的可扩展性，我们能够：

隐私优先的人工智能 -所有处理都在本地进行
经济高效的部署 -无API成本
可定制的工作流程 -根据您的特定需求构建工具
研究友好 -尝试代理架构
生产就绪 -可扩展且可靠，适用于实际应用

______________________________________________________________________

❓ 故障排除和常见问题

常见问题

Q： llama.cpp服务器无法启动

# Check if port 8080 is already in use
lsof -i :8080

# Kill existing process
kill -9 

# Or use a different port
./llama-server -m model.gguf --port 8081

Q：启动Arcade MCP时“连接被拒绝”

确保llama.cpp服务器首先运行
检查端口8080是否可访问： curl http://127.0.0.1:8080
验证防火墙设置没有阻止本地连接

Q：型号太慢/CPU使用率高

# Reduce thread count
-t 4  # Use only 4 threads instead of auto-detection

# Reduce context length
-c 4096  # Instead of 8192

# Disable mlock if low on RAM
# Remove --mlock flag

Q：未发现MCP工具

检查 tools/ 目录存在并包含Python文件
验证每个工具是否符合MCP规范
检查服务器日志中的工具注册错误

Q： “内存不足”错误

使用较小的型号（1.5B而不是7B）
减少批量大小： -b 512
缩短上下文长度： -c 2048
启用内存锁定： --mlock

性能优化

对于仅CPU推理：

# Optimize thread count (typically cores - 2)
THREADS=$(($(nproc)-2))

# Enable BLAS for faster matrix ops (if available)
make LLAMA_BLAS=1

# Use Q4 or Q5 quantized models for speed

为了获得更好的响应质量：

# Increase context length
-c 16384

# Increase batch size (if RAM allows)
-b 2048

# Use higher quality model quantization (Q6, Q8)

调试模式

启用详细日志记录：

# For llama.cpp
./llama-server --log-level DEBUG

# For Arcade-MCP
export LOG_LEVEL=DEBUG
python server.py

______________________________________________________________________

📞 支持

对于问题和疑问：

打开GitHub问题
检查现有文档
审查MCP规范模型上下文协议.io

______________________________________________________________________

建于❤️ 对于当地的人工智能社区

Arcade MCP

快速接入

详细介绍

街机MCP

🚀 概述

🏗️ 建筑

Claude MCP工作流程（官方图表）

Llama.cpp服务器正在运行

CLI聊天界面

网络搜索工具

MCP Web代理——ARIA

基本知识

网络搜索

斜杠命令

技能

代码审查

文档

摘要

系统架构概述

📊 设置架构图

🚀 快速开始

安装步骤

📦 需求

🧠 模型设置

⚙️ 启动llama.cpp服务器

参数注释

🔌 启动Arcade MCP服务器

🌐 访问

🔄 工作流示例

GitHub存储库查询

✨ 特性

🔄 MCP工作流示例

🛠 发展

构建llama.cpp

安装Python依赖项

核心模块

主文件

📄 许可证

🤝 贡献

开发指南

⭐ 视觉

❓ 故障排除和常见问题

常见问题

性能优化

调试模式

📞 支持

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP