MCP Client Repl

MCP客户端REPL

一个交互式REPL（读取-评估-打印循环）客户端，用于与 模型上下文协议 （MCP）服务器通过命令行。

概述

此工具提供了一个用户友好的命令行界面，用于连接到MCP服务器并与之交互。它支持多种传输方法，允许您列出可用工具、调用工具和交互式管理连接。

特性

• 多种运输支持：通过stdio、SSE（服务器发送事件）或流式HTTP连接
• 交互式REPL：易于使用的命令行界面
• 自动连接：启动时使用环境变量自动连接
• 工具管理：从连接的MCP服务器列出和调用工具
• 基于环境的配置：通过配置连接 .env 文件
• API密钥验证：支持MCP服务器使用 x-api-key 标头身份验证
• 增强的错误处理：开发人员友好的错误消息，附有详细的解释和恢复说明

错误处理

REPL包括对常见MCP错误代码的全面错误处理。当发生错误时，您将收到详细信息，包括：

• 错误代码：数字MCP错误代码
• 描述：错误是什么意思
• 常见原因：为什么通常会出现此错误
• 如何处理：解决问题的分步说明

支持的错误代码

错误输出示例

Failed to connect via HTTP:
Error: Authentication failed

📋 MCP Error Details:
   Code: -32000
   Name: Authentication Error
   Description: Missing or invalid authentication token
   Common Cause: The API key or authentication credentials are missing or invalid
   How to Handle: Check your MCP_API_KEY environment variable or provide a valid API key when connecting

先决条件

• Node.js（建议使用v18或更高版本）
• npm或纱线

安装

1. 克隆存储库：

git clone 
cd mcp-client-repl

1. 安装依赖项：

npm install

用法

启动REPL

运行以下命令以启动REPL：

npm start

您可以选择指定一个不同的环境文件在启动时加载：

npm start .env-stdio     # Load .env-stdio file
npm start .env-sse       # Load .env-sse file
npm start .env-http      # Load .env-http file

或使用 --help 查看使用信息：

npm start -- --help

环境变量（可选）

创建 .env 项目根目录中的文件，以在启动时启用自动连接：

MCP_SERVER_URL=https://your-mcp-server.com/sse
MCP_TRANSPORT=sse  # or 'http' or 'stdio'
MCP_API_KEY=your-api-key-here  # Optional

设置这些环境变量后，REPL将在启动时自动尝试连接。

命令

连接到服务器

SSE连接：

mcp> connect sse https://your-server.com/sse

带API密钥的SSE：

mcp> connect sse https://your-server.com/sse your-api-key

HTTP连接：

mcp> connect http https://your-server.com/mcp

stdio连接（本地脚本）：

mcp> connect stdio path/to/your/server.js

在服务器配置之间切换

您可以使用以下命令在不同的MCP服务器配置之间动态切换 connectenv 命令。当您有多个环境文件（例如。， .env-stdio, .env-sse, .env-http)并希望在不重新启动REPL的情况下在它们之间切换：

mcp> connectenv .env-sse
Loading environment variables from .env-sse
Environment variables loaded from .env-sse
Disconnected from current server
Attempting automatic sse connection from config to http://localhost:3000/sse
Connected via SSE to http://localhost:3000/sse

此命令将：

1. 断开与当前服务器的连接（如果已连接）
2. 从指定文件加载新的环境变量
3. 使用加载的配置自动连接到新服务器

列出可用工具

基本列表：

mcp> tools

模式的完整细节：

mcp> tools full

调用工具

使用JSON参数调用工具：

mcp> call get_weather {"city": "San Francisco"}

复杂参数示例：

mcp> call generate_image {"prompt": "A beautiful sunset over mountains", "style": "photorealistic"}

检查状态

mcp> status

示例会话

$ npm start
Node MCP Client REPL. Type 'help' for commands.

mcp> connect sse https://example.com/mcp/sse my-api-key
Connecting via SSE to https://example.com/mcp/sse
Connected via SSE to https://example.com/mcp/sse
Available tools:
- get_weather: Get current weather information for a location
- search_images: Search for images based on query
- generate_text: Generate text based on prompt

mcp> tools full
Available tools (full details):
[
  {
    "name": "get_weather",
    "description": "Get current weather information for a location",
    "input_schema": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string"
        }
      },
      "required": ["city"]
    }
  }
]

mcp> call get_weather {"city": "New York"}
Invoking tool: get_weather with arguments: {"city":"New York"}
Tool result: ...

mcp> exit
Disconnected from https://example.com/mcp/sse

项目结构

mcp-client-repl/
├── src/
│   └── mcp-client-repl.ts    # Main REPL implementation
├── package.json               # Dependencies and scripts
├── tsconfig.json              # TypeScript configuration
└── README.md                  # This file

使用的技术

• TypeScript：类型安全的JavaScript
• 多伦多证券交易所：TypeScript执行引擎
• @模型上下文协议/sdk：官方Node.js MCP SDK
• Dotenv。：环境变量管理
• 读取行：命令行界面

许可证

国际学生委员会

贡献

欢迎投稿！请随时提交拉取请求。

故障排除

常见问题及解决方法

身份验证错误（-32000）

• 检查API密钥是否正确，并在环境变量或connect命令中正确设置
• 验证MCP服务器是否需要 x-api-key 头球

无效会话（-32001）

• 使用 disconnect 命令后面跟着 connect 重新初始化会话
• 或使用 connectenv 重新加载配置并重新连接

未找到方法（-32002）

• 使用 tools 查看所有可用工具的命令
• 检查工具名称中的拼写错误

无效参数（-32003）

• 使用 tool 查看预期的参数架构
• 验证JSON格式是否正确，是否包含所有必填字段

分析错误（-32005）

• 检查JSON语法，特别是引号和括号
• 例子： call get_weather {"city": "New York"} 不 call get_weather {city: New York}

备注

• 在连接之前，请确保您的MCP服务器正在运行且可访问
• 确保您对基于stdio的连接具有正确的权限
• 所有错误都包括详细的恢复说明，以帮助您快速解决问题