Skip to content
Back to search

mcp-client-nodejs

Node.js Client Implementation for Model Context Protocol (MCP)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/conardli--mcp-client-nodejs/badge.svg)](/listings/conardli--mcp-client-nodejs)

HTML

<a href="/listings/conardli--mcp-client-nodejs"><img src="/api/listings/conardli--mcp-client-nodejs/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. 克隆仓库

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

2. 安装依赖

npm install

所需依赖项: - @modelcontextprotocol/sdk - openai - dotenv - typescript(开发依赖) - @types/node(开发依赖)

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 235 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ## 项目介绍
  2. MCP Client 是一个基于 Model Context Protocol 的 Node.js 客户端实现(使用 Function Calling),它允许您的应用连接到各种 MCP 服务器,并通过大语言模型(LLM)与这些服务器交互。MCP(模型上下文协议)是一个开放协议,用于标准化应用程序向 LLM 提供上下文的方式。
  3. ![](./public/arc.png)
  4. ## 核心特性
  5. - 支持连接任何符合 MCP 标准的服务器
  6. - 支持兼容 OpenAI API 格式的 LLM 能力
  7. - 自动发现和使用服务器提供的工具
  8. - 完善的日志记录系统,包括 API 请求和工具调用
  9. - 交互式命令行界面
  10. - 支持工具调用和结果处理
  11. ## 系统要求
  12. - Node.js 17 或更高版本
  13. - LLM API 密钥(暂不支持 Ollama)
  14. - 磁盘空间用于存储日志文件(位于 `logs/` 目录)
  15. ## 安装
  16. ### 1. 克隆仓库
  17. ```bash
  18. git clone https://github.com/ConardLi/mcp-client-nodejs.git
  19. cd mcp-client-nodejs
  20. ```
  21. ### 2. 安装依赖
  22. ```bash
  23. npm install
  24. ```
  25. 所需依赖项:
  26. - @modelcontextprotocol/sdk
  27. - openai
  28. - dotenv
  29. - typescript(开发依赖)
  30. - @types/node(开发依赖)
  31. ### 3. 配置环境变量
  32. 复制示例环境变量文件并设置您的 LLM API 密钥:
  33. ```bash
  34. cp .env.example .env
  35. ```
  36. 然后编辑 `.env` 文件,填入您的 LLM API 密钥、模型提供商 API 地址、以及模型名称:
  37. ```
  38. OPENAI_API_KEY=your_api_key_here
  39. MODEL_NAME=xxx
  40. BASE_URL=xxx
  41. ```
  42. ### 4. 编译项目
  43. ```bash
  44. npm run build
  45. ```
  46. ## 使用方法
  47. 要启动 MCP 客户端,您可以使用以下几种方式:
  48. ### 1. 直接指定服务器脚本路径
  49. ```bash
  50. node build/index.js <服务器脚本路径>
  51. ```
  52. 其中 `<服务器脚本路径>` 是指向 MCP 服务器脚本的路径,可以是 JavaScript (.js) 或 Python (.py) 文件。
  53. ### 2. 使用配置文件
  54. ```bash
  55. node build/index.js <服务器标识符> <配置文件路径>
  56. ```
  57. 其中 `<服务器标识符>` 是配置文件中定义的服务器名称,`<配置文件路径>` 是包含服务器定义的 JSON 文件的路径。
  58. ```json
  59. {
  60. "mcpServers": {
  61. "time": {
  62. "command": "node",
  63. "args": [
  64. "/Users/xxx/mcp/dist/index.js"
  65. ],
  66. "description": "自定义 Node.js MCP服务器"
  67. },
  68. "mongodb": {
  69. "command": "npx",
  70. "args": [
  71. "mcp-mongo-server",
  72. "mongodb://localhost:27017/studentManagement?authSource=admin"
  73. ]
  74. }
  75. },
  76. "defaultServer": "mongodb",
  77. "system": "自定义系统提示词"
  78. }
  79. ```
  80. ### 3. 使用 npm 包(npx)
  81. 您可以直接通过 npx 运行这个包,无需本地克隆和构建:
  82. ```bash
  83. # 直接连接脚本
  84. $ npx mcp-client-nodejs /path/to/mcp-server.js
  85. # 通过配置文件连接
  86. $ npx mcp-client-nodejs mongodb ./mcp-servers.json
  87. ```
  88. > 注意:需要在当前运行目录的 .env 配置模型相关信息
  89. ### 示例
  90. 直接连接 JavaScript MCP 服务器:
  91. ```bash
  92. node build/index.js /path/to/weather-server/build/index.js
  93. ```
  94. 直接连接 Python MCP 服务器:
  95. ```bash
  96. node build/index.js /path/to/mcp-server.py
  97. ```
  98. 使用配置文件连接服务器:
  99. ```bash
  100. node build/index.js mongodb ./mcp-servers.json
  101. ```
  102. 使用 npx 运行:
  103. ```bash
  104. # 直接连接脚本
  105. $ npx mcp-client-nodejs /path/to/mcp-server.js
  106. # 通过配置文件连接
  107. $ npx mcp-client-nodejs mongodb./mcp-servers.json
  108. ```
  109. ![](./public/demo.png)
  110. ## 工作原理
  111. ![](./public/time-arc2.png)
  112. 1. **服务器连接**:客户端连接到指定的 MCP 服务器
  113. 2. **工具发现**:自动获取服务器提供的可用工具列表
  114. 3. **查询处理**:
  115. - 将用户查询发送给 LLM
  116. - LLM 决定是否需要使用工具
  117. - 如果需要,客户端通过服务器执行工具调用
  118. - 将工具结果返回给 LLM
  119. - LLM 提供最终回复
  120. 4. **交互式循环**:用户可以不断输入查询,直到输入"quit"退出
  121. ## 日志系统
  122. MCP Client 包含一个全面的日志系统,详细记录所有关键操作和通信。日志文件保存在 `logs/` 目录中,以 JSON 格式存储,方便查询和分析。
  123. ![](./public/logs.png)
  124. ### 日志类型
  125. - **LLM 的请求和响应** - 记录与 LLM API 的所有通信
  126. - **工具调用和结果** - 记录所有工具调用参数和返回结果
  127. - **错误信息** - 记录系统运行期间的任何错误
  128. ### 日志命名和格式
  129. 日志文件连统命名为 `[index] [log_type] YYYY-MM-DD HH:MM:SS.json`,包含序号、日志类型和时间戳,方便按时间顺序查看整个会话。
  130. ## 架构设计
  131. ![](./public/code-arc.png)
  132. MCP Client 基于模块化的客户端-服务器架构:
  133. - **传输层**:使用 Stdio 传输机制与服务器通信
  134. - **协议层**:使用 MCP 协议处理请求/响应和工具调用
  135. - **模型层**:通过 OpenAI SDK 提供 LLM 能力
  136. ### 核心组件
  137. - **MCPClient 类**:管理服务器连接、处理查询和工具调用
  138. - **Client 对象**:MCP SDK 提供的客户端实现
  139. - **StdioClientTransport**:基于标准输入/输出的传输实现
  140. ## 最佳实践
  141. - **错误处理**:使用 TypeScript 类型系统进行更好的错误检测
  142. - **安全性**:在 .env 文件中安全存储 API 密钥
  143. - **工具权限**:注意工具的权限和安全性
  144. ## 故障排除
  145. ### 服务器路径问题
  146. - 确保服务器脚本路径正确
  147. - 如果相对路径不起作用,请使用绝对路径
  148. - Windows 用户请确保在路径中使用正斜杠(/)或转义的反斜杠(\\)
  149. - 验证服务器文件具有正确的扩展名(.js 或 .py)
  150. ### 响应时间
  151. - 第一次响应可能需要最多 30 秒才能返回
  152. - 这是正常现象,发生在服务器初始化、查询处理和工具执行期间
  153. - 后续响应通常会更快
  154. ### 常见错误消息
  155. - `Error: Cannot find module`:检查构建文件夹并确保 TypeScript 编译成功
  156. - `Connection refused`:确保服务器正在运行且路径正确
  157. - `Tool execution failed`:验证工具所需的环境变量是否已设置
  158. - `OPENAI_API_KEY is not set`:检查您的 .env 文件和环境变量
  159. - `TypeError`:确保为工具参数使用正确的类型
  160. ## 许可证
  161. Apache License 2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.