Llama-Server MCP Proxy

Llama-Server MCP 代理

这个 Node.js 应用程序充当 llama-server 的代理服务。它的主要目的是拦截聊天完成请求，通过模型上下文协议 (MCP) 使用工具能力增强这些请求，并允许大模型迭代地使用这些工具。

它将标准 llama-server GUI 请求（例如获取主页）直接代理到你的本地 llama-server 实例，并特别处理 /v1/chat/completions 请求以启用工具交互。

当前状态

• Brave 搜索可用
• Search1 API 可用
• 文件系统访问存在问题，具体取决于使用的模型
• Puppeteer

主要特性

• MCP 工具集成： 连接到在 mcp-config.json 中定义的 MCP 兼容工具服务。
• 动态系统提示词： 自动生成列出可用工具及其描述的系统提示词，将其注入到大模型的上下文中。
• 迭代工具使用： 允许大模型在单个用户回合中进行多个工具调用。代理处理请求-响应流：
  1. 大模型指示进行工具调用。
  2. 代理检测并解析工具调用。
  3. 代理通过相应的 MCP 客户端执行工具。
  4. 代理将工具结果发送回大模型。
  5. 大模型使用结果继续响应或调用另一个工具。
• 流式传输支持： 维持大模型响应的流式传输（服务器发送事件）到客户端，包括中间消息如"[执行工具...]"和工具结果。
• 错误处理： 转发来自 llama-server 的错误，并为失败的工具执行提供错误消息给大模型和客户端。大模型将分析错误并尝试找到可行的方法。
• 可配置： 使用环境变量配置端口、llama-server URL 和 MCP 配置路径。
• 调试日志： 可选的详细调试日志，通过环境变量启用。

前置要求

• Node.js： 版本 18 或更高（由 @modelcontextprotocol/sdk 依赖指示）。
• llama-server： 运行中的 llama-server 实例（或兼容的类 OpenAI API 端点）。
• MCP 工具服务： 一个或多个 MCP 兼容的工具服务，你希望大模型能够访问。

设置

1. 克隆仓库（或创建项目目录）：

   # 如果你有一个 git 仓库：
   # git clone <your-repo-url>
   # cd llama-server_mcp_proxy
   
   # 如果从头开始，创建一个目录并进入：
   mkdir llama-server_mcp_proxy
   cd llama-server_mcp_proxy
   

2. 创建 package.json： 如果你没有该文件，请创建一个 package.json 文件，内容如下：

   {
     "name": "llama-server-mcp-proxy",
     "version": "1.0.0",
     "description": "A proxy for llama-server to enable MCP tool usage.",
     "main": "llama-server-mcp-proxy.js", 
     "scripts": {
       "start": "node llama-server-mcp-proxy.js"
     },
     "dependencies": {
       "@modelcontextprotocol/sdk": "^1.8.0"
     }
   }
   

3. 安装依赖项： 在项目目录中运行以下命令来安装必要的包：

   npm install
   

   这将使用你的 package.json（以及 package-lock.json，如果存在且一致）来安装 @modelcontextprotocol/sdk。

4. 创建 mcp-config.json： 该文件告诉代理如何连接到你的 MCP 工具服务。默认情况下，它应该与你的代理脚本（例如 llama-server-mcp-proxy.js）位于同一目录中，或者你可以通过 MCP_CONFIG_PATH 环境变量指定其路径。

   作为快速开始示例，将 mcp-config.json.example 重命名为 mcp-config.json

   mcp-config.json.example：

   {
     "mcpServers": {
       "search1api": {
         "command": "npx",
         "args": [
           "search1api-mcp",
           "--port",
           "0", 
           "--api-key",
           "YOUR_SEARCH1API_KEY_PLACEHOLDER" 
         ],
         "env": {
           "DEBUG": "true" 
         }
       },
       "another_tool_server": {
         "command": "path/to/your/tool/server/executable",
         "args": [
           "--some-config-for-tool", "value",
           "--api-key", "ANOTHER_API_KEY_PLACEHOLDER"
         ],
         "env": {}
       }
     }
   }
   

   • mcpServers：一个对象，其中每个键都是你的工具服务的唯一名称（例如"search1api"、"my_custom_tools"）。
   • command：执行以启动 MCP 工具服务的命令。这可以是用于 npx 可运行包的 npx、可执行文件的直接路径或脚本。
   • args：传递给命令的参数数组。
     • --port 0 通常用于让 MCP 服务选择一个可用的端口用于 stdio 通信。
     • 将 YOUR_SEARCH1API_KEY_PLACEHOLDER 和其他占位符替换为你的实际 API 密钥或必要的配置。
   • env：一个可选的环境变量对象，用于为 MCP 服务进程设置。

   通过复制示例并填入你的实际 API 密钥和路径来创建你的实际 mcp-config.json。

5. 将 mcp-config.json 添加到 .gitignore： 为了防止意外提交你的敏感 API 密钥，在项目根目录中创建或更新 .gitignore 文件：

   node_modules/
   mcp-config.json
   *.log
   # 添加你想忽略的其他文件/目录
   

6. 保存代理代码： 将前面步骤中提供的 JavaScript 代理代码保存到一个文件中，例如 llama-server-mcp-proxy.js（如 package.json 中所引用的）。

运行代理

1. 确保 llama-server 正在运行。 代理需要连接到它。默认情况下，它假设 llama-server 在 http://localhost:8080。

2. 启动代理服务： 在项目目录中打开终端并运行：

   npm start
   

   或直接使用 Node：

   node llama-server-mcp-proxy.js
   

   你应该看到控制台输出显示代理已启动、它连接到的 MCP 服务以及可用的工具。

3. 配置环境变量（可选）： 你可以使用环境变量自定义代理的行为：

   • PORT：代理服务将监听的端口（默认值：9090）。
   • LLAMA_SERVER_URL：你运行的 llama-server 实例的 URL（默认值：http://localhost:8080）。
   • MCP_CONFIG_PATH：mcp-config.json 文件的完整路径（默认值：相对于脚本的 ./mcp-config.json）。
   • MCP_PROXY_DEBUG：设置为 true 以获得详细的调试日志（默认值：false）。
   • LLAMA_SERVER_TIMEOUT：向 llama-server 发送请求的超时时间（毫秒）（默认值：60000）。

   示例（Linux/macOS）：

   PORT=9000 LLAMA_SERVER_URL=http://127.0.0.1:8081 MCP_PROXY_DEBUG=true node llama-server-mcp-proxy.js
   

   示例（Windows PowerShell）：

   $env:PORT="9000"; $env:LLAMA_SERVER_URL="http://127.0.0.1:8081"; $env:MCP_PROXY_DEBUG="true"; node llama-server-mcp-proxy.js
   

用法

1. 代理服务运行后，将你的大模型 GUI 客户端（例如访问通常与 llama-server 通信的网页 UI 的浏览器）指向代理的地址和端口（例如，如果代理在端口 9090 上运行，则为 http://localhost:9090）。
2. 像往常一样与大模型交互。
3. 当你要求大模型执行可能受益于某个已配置工具的任务时，它应该：
   • 表示其使用工具的意图。
   • 输出格式为 TOOL_NAME(ARG_NAME="ARG_VALUE", ...) 或可能是 XML 格式的工具调用。
4. 代理将：
   • 检测此工具调用。
   • 在流中显示 "[Executing tool: TOOL_NAME...]" 消息。
   • 执行该工具。
   • 在流中显示 "[Tool Result for TOOL_NAME]: ...RAW_RESULT..." 消息。
   • 将结果反馈给大模型。
5. 大模型随后将使用工具的结果来制定其最终响应，或决定调用另一个工具。

识别的工具调用格式

代理在大模型完成其当前响应段（由 [DONE] 指示）后，尝试识别大模型输出中的工具调用，主要有两种格式：

1. 简单函数风格：

   示例：news(query="latest AI research", max_results=3)

2. XML 风格：

   <tool_call>
       <tool>tool_name</tool>
       <params>
           <param1>value1</param1>
           <param2>value2</param2>
       </params>
   </tool_call>
   

代理将相应地为每种格式解析参数。

故障排除

• "Tool ... not found in any connected MCP server":
  • 确保大模型输出的工具名称与代理启动时列出的工具名称完全匹配（这些工具名称来自你的 MCP 服务）。
  • 检查 mcp-config.json 中工具服务命令或配置是否存在拼写错误。
  • 验证你的 MCP 工具服务是否正确启动并成功注册了它们的工具。检查代理启动时的控制台输出以查看连接消息。
• 代理错误 / llama-server 错误（500、502 等）:
  • 确保 llama-server 正在运行且可在 LLAMA_SERVER_URL 处访问。
  • 检查 llama-server 自身的日志以了解任何问题。
  • 启用 MCP_PROXY_DEBUG=true 以从代理获得更详细的日志。
• 工具执行错误（例如 "402 Payment Required"）: 这些错误来自 MCP 工具服务本身。代理会将它们报告给大模型，大模型应该理想地尝试不同的方法或通知你。
• "Socket hang up" / ECONNRESET: 如果 llama-server 意外关闭连接，可能会出现这种情况。如果代理发送了格式不正确的请求（例如不正确的 JSON 结构、有问题的标头）或 llama-server 本身遇到内部错误，就可能发生这种情况。来自代理和 llama-server 的调试日志至关重要。

依赖项

• @modelcontextprotocol/sdk: 版本 ^1.8.0（及其在 package-lock.json 中列出的传递依赖项）。

---