llama-server MCP proxy

呼叫服务器MCP代理

此Node.js应用程序充当以下对象的代理服务器 llama-server其主要目的是拦截聊天完成请求，通过模型上下文协议（MCP）用工具功能增强它们，并允许语言模型（LLM）迭代使用这些工具。

它代表标准 llama-server GUI请求（如获取主页）直接发送到本地 llama-server 实例和具体流程 /v1/chat/completions 请求启用工具交互。

当前状态

• 勇敢的搜索工作
• search1 API作品
• 文件系统访问存在问题，具体取决于所使用的模型
• 操纵者

主要特点

• MCP工具集成： 连接到中定义的MCP兼容工具服务器 mcp-config.json.
• 动态系统提示： 自动生成一个系统提示，列出可用工具及其描述，并将其注入LLM的上下文中。
• 迭代工具使用： 允许LLM在单个用户回合中进行多个工具调用。代理处理请求-响应流：

1. LLM表示工具调用。 1. 代理检测并解析工具调用。 1. 代理通过相应的MCP客户端执行该工具。 1. 代理将工具的结果发送回LLM。 1. LLM使用结果继续其响应或调用另一个工具。

• 流媒体支持： 维护向客户端发送的LLM响应（服务器发送事件）的流式传输，包括“\[执行工具…\]”等中间消息和工具结果。
• 错误处理： 转发来自的错误 llama-server 并向LLM和客户端提供工具执行失败的错误消息。法学硕士将分析错误并尝试找到可行的方法。
• 可配置： 使用端口的环境变量， llama-server URL和MCP配置路径。
• 调试日志记录： 通过环境变量进行可选的详细调试日志记录。

先决条件

• Node.js： 版本18或更高（如所示 @modelcontextprotocol/sdk 依赖关系）。
• llama-server: 正在运行的实例 llama-server （或兼容的类似OpenAI的API端点）。
• MCP工具服务器： 您希望LLM访问的一个或多个MCP兼容工具服务器。

设置

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

   # If you have a git repository:
   # git clone 
   # cd llama-server_mcp_proxy

   # If starting from scratch, create a directory and navigate into it:
   mkdir llama-server_mcp_proxy
   cd llama-server_mcp_proxy

1. 创建 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"
     }
   }

1. 安装依赖关系：

在项目目录中运行以下命令以安装必要的软件包：

   npm install

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

1. 创建 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服务器进程设置的环境变量的可选对象。

创建您的实际 mcp-config.json 通过复制示例并填充真实的API键和路径。

1. 添加 mcp-config.json 向 .gitignore:

为了防止意外提交敏感的API密钥，请创建或更新 .gitignore 项目根目录中的文件：

   node_modules/
   mcp-config.json
   *.log
   # Add other files/directories you want to ignore

1. 保存代理代码：

将前面步骤中提供的JavaScript代理代码保存到文件中， llama-server-mcp-proxy.js （如参考 package.json).

运行代理

1. 确保 llama-server 正在运行。

代理需要连接到它。默认情况下，它假定 llama-server 是在 http://localhost:8080.

1. 启动代理服务器：

在项目目录中打开终端并运行：

   npm start

或者直接使用Node：

   node llama-server-mcp-proxy.js

您应该看到控制台输出，指示代理已启动，它连接到哪些MCP服务器，以及可用的工具。

1. 配置环境变量（可选）：

您可以使用环境变量自定义代理的行为：

- PORT：代理服务器将侦听的端口（默认值： 9090). - LLAMA_SERVER_URL：您跑步的URL llama-server 实例（默认值： 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. 一旦代理服务器正在运行， 指向您的LLM GUI客户端（例如，您的浏览器正在访问通常与之对话的web UI llama-server)发送到代理的地址和端口 （例如。， http://localhost:9090 如果代理正在端口9090上运行）。
2. 像往常一样与LLM互动。
3. 当您要求LLM执行可以从配置的工具之一中受益的任务时，它应该：

- 表明其使用工具的意图。 - 以以下格式输出工具调用 TOOL_NAME(ARG_NAME="ARG_VALUE", ...) 或者可能是XML格式。

1. 代理人将：

- 检测此工具调用。 - 在流中显示“\[执行工具：tool_NAME…\]”消息。 - 执行工具。 - 在流中显示“\[工具名称的工具结果\]：…RAW_Result…”消息。 - 将结果反馈给LLM。

1. 然后，LLM将使用该工具的结果来制定其最终响应，或决定调用另一个工具。

识别工具调用格式

在LLM完成其当前响应段（由表示）后，代理尝试以两种主要格式识别LLM输出中的工具调用 [DONE]):

1. 简单功能风格：

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

1. XML样式：

   
       tool_name
       

           
value1

           
value2

       

   

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

故障排除

• “工具…在任何连接的MCP服务器中都找不到”:

- 确保LLM输出的工具名称与代理启动时列出的工具名称（来自MCP服务器）完全匹配。 - 检查你的 mcp-config.json 用于工具服务器命令或配置中的拼写错误。 - 验证您的MCP工具服务器是否正确启动并成功注册其工具。启动代理时，检查其控制台输出是否有连接消息。

• 代理错误/ llama-server 错误（500、502等）:

- 确保 llama-server 正在运行，可在 LLAMA_SERVER_URL. - 检查 llama-server的日志记录任何问题。 - 启用 MCP_PROXY_DEBUG=true 从代理获取更详细的日志。

• 工具执行错误（例如，“402需要付款”）：这些错误来自MCP工具服务器本身。代理将向LLM报告这些情况，LLM最好尝试不同的方法或通知您。
• “插座挂断”/ ECONNRESET：如果发生以下情况，可能会出现这种情况 llama-server 意外关闭连接。如果代理发送格式错误的请求（例如，不正确的JSON结构、有问题的标头），或者 llama-server 它本身会遇到内部错误。来自代理和 llama-server 至关重要。

依赖项

• @modelcontextprotocol/sdk：版本 ^1.8.0 （及其传递依赖关系如所列 package-lock.json).

______________________________________________________________________