呼叫服务器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-serverURL和MCP配置路径。 - 调试日志记录: 通过环境变量进行可选的详细调试日志记录。
先决条件
- Node.js: 版本18或更高(如所示
@modelcontextprotocol/sdk依赖关系)。 llama-server: 正在运行的实例llama-server(或兼容的类似OpenAI的API端点)。- MCP工具服务器: 您希望LLM访问的一个或多个MCP兼容工具服务器。
设置
- 克隆存储库(或创建项目目录):```bash
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` 包含以下内容的文件:```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"
}
}
- 安装依赖关系:
在项目目录中运行以下命令以安装必要的软件包:```bash
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`:**```json
{
"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键和路径。
- 添加
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. **启动代理服务器:**
在项目目录中打开终端并运行:```bash
npm start
或者直接使用Node:```bash
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):```bash
PORT=9000 LLAMA_SERVER_URL=http://127.0.0.1:8081 MCP_PROXY_DEBUG=true node llama-server-mcp-proxy.js
示例(Windows PowerShell):```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上运行)。
1. 像往常一样与LLM互动。
1. 当您要求LLM执行可以从配置的工具之一中受益的任务时,它应该:
- 表明其使用工具的意图。
- 以以下格式输出工具调用 `TOOL_NAME(ARG_NAME="ARG_VALUE", ...)` 或者可能是XML格式。
1. 代理人将:
- 检测此工具调用。
- 在流中显示“\[执行工具:tool_NAME…\]”消息。
- 执行工具。
- 在流中显示“\[工具名称的工具结果\]:…RAW_Result…”消息。
- 将结果反馈给LLM。
1. 然后,LLM将使用该工具的结果来制定其最终响应,或决定调用另一个工具。
## 识别工具调用格式
在LLM完成其当前响应段(由表示)后,代理尝试以两种主要格式识别LLM输出中的工具调用 `[DONE]`):
1. **简单功能风格:**```tool_name(param1="value1", param2="value2")
例子: news(query="latest AI research", max_results=3)
- XML样式:
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).
