星战科技xingzhan.cloud
返回市场
MCP客户端节点JS

MCP客户端节点JS

作者：ConardLi96 星标更新：2025-04-17
安装使用来源：spider==github.com

项目介绍

项目介绍

MCP客户端是一个基于Node.js的实现，使用模型上下文协议（采用函数调用方式），允许您的应用程序连接到各种MCP服务器并通过大型语言模型（LLM）与它们进行交互。MCP（模型上下文协议）是一种开放协议，用于标准化应用程序向LLM提供上下文的方式。

核心功能

  • 支持连接到任何符合MCP标准的服务器
  • 支持兼容OpenAI API格式的LLM能力
  • 自动发现并使用服务器提供的工具
  • 包括API请求和工具调用在内的全面日志系统
  • 交互式命令行界面
  • 支持工具调用及结果处理

系统要求

  • Node.js 17或更高版本
  • LLM API密钥（目前不支持Olama）
  • 使用磁盘空间存储日志文件（位于）logs/目录

安装

1. 克隆仓库

git clone https://github.com/ConardLi/mcp-client-nodejs.git
cd mcp-client-nodejs

2. 安装依赖

npm install

所需依赖：

  • @modelcontextprotocol/sdk
  • openai
  • dotenv
  • Typescript（开发依赖）
  • @Types/nodes（开发依赖）

3. 配置环境变量

复制示例环境变量文件并设置您的LLM API密钥：

cp .env.example .env

然后编辑.env文件，填写您的LLM API密钥、模型提供商API地址和模型名称：

OPENAI_API_KEY=your_api_key_here
MODEL_NAME=xxx
BASE_URL=xxx

4. 编译项目

npm run build

使用说明

启动MCP客户端，您可以使用以下方法：

1. 直接指定服务器脚本路径

node build/index.js <服务器脚本路径>

其中 <服务器脚本路径> 指的是MCP服务器脚本的路径，可以是JavaScript（.js）或Python（.py）文件。

2. 使用配置文件

node build/index.js <服务器标识符> <配置文件路径>

其中 <服务器标识符> 是配置文件中定义的服务器名称，<配置文件路径> 是包含服务器定义的JSON文件的路径。

{
  "mcpServers": {
    "time": {
      "command": "node",
      "args": [
        "/Users/xxx/mcp/dist/index.js"
      ],
      "description": "自定义 Node.js MCP服务器"
    },
    "mongodb": {
      1. "command": "npx",
      2. "args": [
      3. "mcp-mongo-server",
      4. "mongodb://localhost:27017/studentManagement?authSource=admin"
      5. ]
      6. }
      7. },
      8. "defaultServer": "mongodb",
      9. "system": "自定义系统提示词"
     10. }

3. 使用npm包（npx）

您可以通过NPX直接运行此包，无需本地克隆和构建：

# 直接连接脚本
$ npx mcp-client-nodejs /path/to/mcp-server.js

# 通过配置文件连接
$ npx mcp-client-nodejs mongodb ./mcp-servers.json

注意：与模型相关的信息需要在当前运行目录的.env目录中进行配置

示例

直接连接到JavaScript MCP服务器：

node build/index.js /path/to/weather-server/build/index.js

直接连接到Python MCP服务器：

node build/index.js /path/to/mcp-server.py

通过配置文件连接到服务器：

node build/index.js mongodb ./mcp-servers.json

使用NPX运行：

# 直接连接脚本
$ npx mcp-client-nodejs /path/to/mcp-server.js
# 通过配置文件连接
$ npx mcp-client-nodejs mongodb ./mcp-servers.json

工作原理

  1. 服务器连接客户端连接到指定的MCP服务器
  2. 工具发现自动检索服务器提供的可用工具列表
  3. 查询处理：
    • 将用户查询发送给LLM
    • LLM决定是否使用工具
    • 如果有必要，客户端通过服务器执行工具调用
    • 返回工具结果给LLM
    • LLM提供最终响应
  4. 交互循环用户可以连续输入查询，直到输入“quit”退出

日志系统

MCP客户端包括一个全面的日志系统，详细记录所有关键操作和通信。日志文件保存在logs/目录下，以JSON格式存储，便于查询和分析。

日志类型

  • LLM的请求和响应 - 记录与LLM API的所有通信
  • 工具调用和结果 - 记录所有工具调用参数和返回结果
  • 错误消息 - 记录系统运行期间出现的任何错误

日志命名和格式

日志文件统一命名为[index] [log_type] YYYY-MM-DD HH:MM:SS.json，包括序列号、日志类型和时间戳，便于按时间顺序查看整个会话。

架构设计

MCP客户端基于模块化的客户端服务器架构：

  • 传输层使用Stdio传输机制与服务器通信
  • 协议层使用MCP协议处理请求/响应和工具调用
  • 模型层通过OpenAI SDK提供LLM能力

核心组件

  • MCPClient类管理服务器连接、处理查询和调用工具
  • 客户端对象由MCP SDK提供的客户端实现
  • StdioClientTransport基于标准输入/输出的传输实现

最佳实践

  • 错误处理使用TypeScript类型系统进行更好的错误检测
  • 安全性安全地将API密钥存储在.env文件中
  • 工具权限注意工具的权限和安全性

故障排除

服务器路径问题

  • 确保服务器脚本路径正确
  • 如果相对路径不起作用，请使用绝对路径
  • Windows用户，请确保在路径中使用正斜杠(/)或转义的反斜杠(\)
  • 验证服务器文件具有正确的扩展名(.js或.py)

响应时间

  • 第一次响应可能需要长达30秒才能返回
  • 这是在服务器初始化、查询处理和工具执行过程中发生的正常现象
  • 后续响应通常更快

常见错误信息

  • Error: Cannot find module检查构建文件夹并确保TypeScript编译成功
  • Connection refused确保服务器正在运行且路径正确
  • Tool execution failed验证工具所需的环境变量是否已设置
  • OPENAI_API_KEY is not set检查您的.env文件和环境变量
  • TypeError确保使用了正确的工具参数类型

许可证

Apache许可证2.0