使用说明
MCP 代理
一个Node.js工具调用代理，它与模型上下文协议（MCP）服务器集成，并使用OpenRouter AI进行智能对话和工具执行。
概述
这个项目展示了如何构建一个能够：
- 使用OpenRouter AI（GPT-3.5-turbo）进行互动对话
- 根据用户请求自动检测何时使用工具
- 调用MCP（模型上下文协议）服务器工具来执行特定任务
- 在多次交互中保持对话上下文
特点/特性
- OpenRouter 集成使用OpenRouter API访问支持函数调用的GPT-3.5-turbo
- MCP服务器通信连接到本地MCP服务器以执行工具
- 工具调用自动检测何时使用
generate_movie_story工具 - 会话管理正确管理带有会话ID头的MCP会话
- SSE 支持处理JSON和服务器发送事件（SSE）响应
- **交互式命令行界面 (CLI)**用于实时对话的命令行界面
先决条件
- Node.js（v14或更高版本）
- 一个有效的OpenRouter API密钥
- 一个正在运行的MCP服务器
http://localhost:3000/mcp
安装
- 克隆仓库：
git clone <repository-url>
cd mcp-agent
- 安装依赖项：
npm install
- 创建一个
.env项目根目录下的文件：
OPENROUTER_API_KEY=your_openrouter_api_key_here
配置
环境变量
创建一个 .env 包含以下变量的文件：
| 变量 | 描述 | 必需 |
|---|---|---|
OPENROUTER_API_KEY 您的OpenRouter API密钥 |
是 |
MCP 服务器
代理期望在（某个位置）运行MCP服务器 http://localhost:3000/mcp 提供了以下工具：
- 生成电影故事生成一个随机的电影故事创意
用法
启动代理
使用以下命令运行代理：
npm start
或者直接使用 Node.js：
node agent.js
互动聊天
一旦开始，您就可以输入信息与人工智能进行互动：
=== MCP Tool-Calling Agent ===
Connected to OpenRouter AI with MCP server integration
Type your message or 'exit' to quit
You: Give me a creative movie idea
代理将自动检测何时使用 generate_movie_story 工具并通过MCP服务器执行它。
退出
类型 exit 退出应用程序：
You: exit
Goodbye!
项目结构
mcp-agent/
├── agent.js # Main agent implementation
├── list-models.js # Utility to list available OpenRouter models
├── package.json # Project dependencies and scripts
├── .env # Environment variables (not tracked in git)
└── README.md # This file
它是如何工作的
1. 工具定义
代理定义了AI模型可以使用的工具：
const TOOL_DEFINITION = {
name: "generate_movie_story",
description: "Generates a random movie story idea...",
parameters: { /* ... */ }
};
2. 对话流程
- 用户发送了一条消息
- 消息已使用可用工具发送至OpenRouter AI
- AI决定是调用工具还是直接回应
- 如果需要工具：
- 代理初始化MCP会话
- 通过MCP服务器执行该工具
- 将工具结果发送回AI
- AI利用工具数据生成最终响应
- 响应显示给用户
3. MCP 通讯
代理使用JSON-RPC 2.0协议与MCP服务器进行通信：
- 初始化建立会话并接收会话ID
- 工具调用使用会话ID执行请求的工具
可用脚本
npm start- 启动代理npm test- 运行测试（尚未实现）
依赖项
- dotenv（用于加载环境变量的库） (^17.2.3) - 环境变量管理
API 参考文档
OpenRouter
- 终端（或终点）:
https://openrouter.ai/api/v1/chat/completions - 模型：
openai/gpt-3.5-turbo - 特点/特性函数调用，对话历史
MCP 服务器
- 终端节点：
http://localhost:3000/mcp - 协议；议定书；规程JSON-RPC 2.0
- 方法：
initialize- 开始一个新的会话tools/call- 执行工具
错误处理
该代理包含全面的错误处理机制：
- MCP服务器连接错误
- OpenRouter API错误
- SSE解析错误
- 工具执行失败
所有错误都带有描述性信息记录到控制台。
故障排除
“MCP服务器未返回会话ID”
确保您的MCP服务器正在运行并且已正确配置以返回 mcp-session-id 头球
“OpenRouter API错误：401”
检查你的 OPENROUTER_API_KEY 在……中 .env 文件有效且处于活动状态。
“MCP 工具调用失败”
验证您的MCP服务器是否实现了 generate_movie_story 正确地使用工具。
未来改进/增强
- [ ] 添加对多种工具的支持
- [ ] 实现对话历史记录持久化
- [ ] 添加流式响应支持
- [ ] 创建单元测试
- [ ] 添加日志系统
- [ ] 对不同AI模型的支持
- [ ] 网页界面
做出贡献
欢迎贡献！请随时提交拉取请求。
许可证
ISC（International Security Council，国际安全理事会）
作者
你的名字
致谢
- OpenRouter（开放路由器） - AI模型路由服务
- 模型上下文协议 - MCP规范
