AI导哈

本地AI开发工具桥接服务

一个Python MCP stdio服务器，允许Windsurf通过/completion端点调用本地llama.cpp llama-server，适用于低VRAM机器的本地AI开发工具实验和调试。

  • by waqasm86
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 waqasm86/windsurf-llama-cpp-mcp-bridge

使用说明

Windsurf llama.cpp MCP大桥

一个小Python MCP stdio服务器 这让 帆板运动 打电话给当地人 llama.cpp llama-server 穿过 /completion 终点。

Windsurf  ->  MCP over stdio  ->  Python bridge  ->  llama.cpp llama-server  ->  local GGUF model

该项目旨在用于可重复的本地AI开发人员工具实验、低VRAM机器和客户工程风格的调试。

工作的

  • 用于Windsurf的MCP stdio集成。
  • 本地 llama.cpp /completion 电话。
  • complete 用于一般完井的工具。
  • review_code 代码审查提示工具。
  • llama_health 端点可达性检查工具。
  • 安全日志记录：所有日志都转到 stderr；JSON-RPC响应保持不变 stdout.
  • 低VRAM llama-server 启动脚本。

需求

  • Python 3.11+
  • requests
  • A建成 llama.cpp llama-server 二进制
  • 局部GGUF模型
  • 支持MCP的风帆

安装

git clone https://github.com/waqasm86/windsurf-llama-cpp-mcp-bridge.git
cd windsurf-llama-cpp-mcp-bridge

python3.11 -m venv .venv
source .venv/bin/activate
pip install -r mcp-server/requirements.txt

启动llama.cpp

复制示例配置并编辑路径：

cp llama/config.example.env llama/config.env
nano llama/config.env

然后启动本地模型服务器：

./llama/start_llama_server.sh

默认端点为：

http://127.0.0.1:8090/completion

快速手动测试：

curl -s http://127.0.0.1:8090/completion \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Say hello in one line.","n_predict":32,"temperature":0.2,"stream":false}'

配置Windsurf

复制 windsurf-config/mcp.json 进入您的Windsurf MCP配置位置，然后将此占位符替换为您的真实绝对路径：

/ABSOLUTE/PATH/TO/windsurf-llama-cpp-mcp-bridge/mcp-server/server_stdio.py

配置示例：

{
  "mcpServers": {
    "local-llama-stdio": {
      "command": "/usr/bin/env",
      "args": [
        "python3.11",
        "-u",
        "/ABSOLUTE/PATH/TO/windsurf-llama-cpp-mcp-bridge/mcp-server/server_stdio.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "LLAMA_COMPLETION_URL": "http://127.0.0.1:8090/completion",
        "LLAMA_TIMEOUT_S": "120"
      },
      "autoRestart": true,
      "disabled": false
    }
  }
}

编辑MCP配置后重新启动Windsurf。

无风浪条件下的烟雾测试

测试初始化和工具发现：

./mcp-server/smoke_test_stdio.sh

测试实际完成后 llama-server 正在运行：

cd mcp-server
printf '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"complete","arguments":{"prompt":"Say hello in one line.","max_tokens":64,"temperature":0.2}}}\n' \
  | LLAMA_COMPLETION_URL="http://127.0.0.1:8090/completion" python3.11 -u server_stdio.py

可用工具

complete

输入：

{
  "prompt": "Explain MCP in one paragraph.",
  "max_tokens": 256,
  "temperature": 0.7
}

review_code

输入：

{
  "language": "python",
  "code": "def add(a,b): return a+b",
  "max_tokens": 512
}

llama_health

检查是否已配置 /completion 端点是可访问的。

故障排除

症状 可能原因 修复
Windsurf显示没有工具 路径错误 mcp.json 使用绝对路径 server_stdio.py
MCP进程启动然后退出 缺少Python依赖关系 运行 pip install -r mcp-server/requirements.txt
工具调用表示llama.cpp无法访问 llama-server 未运行或端口不匹配 启动 ./llama/start_llama_server.sh 并保持港口 8090 对齐
JSON损坏/无响应 日志打印到stdout 保持所有日志打开 stderr 只有
CUDA内存不足 GPU层太多或上下文太大 减少 GPU_LAYERS, CTX_SIZE，或 BATCH_SIZE 在 llama/config.env
生成速度慢 CPU回退或低端GPU 减小模型大小、使用较小的量化或较低的上下文/批大小

客户工程演示说明

此仓库有意支持可调试性而非复杂性。它展示了AI编码工具集成的完整部署路径：

  1. 启动本地模型运行时。
  2. 在Windsurf上注册MCP stdio服务器。
  3. 将工具暴露到IDE。
  4. 将工具调用路由到本地推理端点。
  5. 返回结构化MCP响应。
  6. 通过清除日志和冒烟测试调试常见的部署失败。

许可证

添加您喜欢的许可证，例如MIT。

相关 MCP