Minimal MCP (Engineers Hub Ltd In House Project)

最小MCP

模型上下文协议（MCP）服务器和客户端的最小实现 教育和发展目的。

项目结构

minimal-mcp/
├── server/          # MCP Server (TypeScript)
├── client/          # MCP Client (Python)
└── README.md

先决条件

• Node.js 22+
• Python 3.13+
• TypeScript

服务器安装程序

再进行

cd server
npm install

构建服务器

npm run build

测试服务器

npm run inspector

打开终端中显示的URL（通常 http://localhost:6274/)测试 服务器工具。

客户端设置

创建虚拟环境

cd client
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

再进行

pip install -r requirements.txt

配置环境

创建 .env 使用您的OpenAI API密钥文件：

echo "OPENAI_API_KEY=your_openai_api_key_here" > .env

运行客户端

python client.py

可用工具

MCP服务器提供三个工具：

1. calculate_sum：将两个数字相加

- 参数： a （数字）， b （编号） - 例子： calculate_sum(42, 58) → 100

1. 反向振铃：反转文本字符串

- 参数： text （字符串） - 例子： reverse_string('Hello MCP') → 'PCM olleH'

1. get_current时间：返回当前ISO时间戳

- 参数：无 - 例子： get_current_time() → '2025-08-24T01:52:39.749Z'

使用方法

方法1：直接客户端测试

运行Python客户端测试所有工具：

cd client
python client.py

这将自动：

1. 连接到MCP服务器
2. 使用示例数据执行所有三个工具
3. 显示结果

方法2:Claude代码集成

将MCP服务器添加到Claude Code配置中：

{
  "mcpServers": {
    "minimal-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/minimal-mcp/server/build/index.js"]
    }
  }
}

然后在Claude Code中使用：

Using the minimal-mcp tools:
1. Calculate the sum of 123 and 456
2. Reverse the text "Model Context Protocol"
3. Get the current time

方法3:MCP检查员

使用官方MCP检查员进行交互式测试：

cd server
npm run inspector

打开终端中显示的URL，在浏览器中交互式测试工具。

发展

服务器开发

cd server
npm run watch  # Auto-rebuild on changes

添加新工具

编辑 server/src/index.ts 添加新工具：

1. 将工具定义添加到 tools 数组：

{
  name: "your_tool_name",
  description: "Description of what the tool does",
  inputSchema: {
    type: "object",
    properties: {
      param: { type: "string", description: "Parameter description" }
    },
    required: ["param"]
  }
}

1. 在中添加工具处理程序 CallToolRequestSchema 开关外壳：

case "your_tool_name":
  const { param } = args as { param: string };
  // Your tool logic here
  return {
    content: [
      {
        type: "text",
        text: `Result: ${param}`
      }
    ]
  };

1. 重建服务器：

npm run build

故障排除

权限不足

chmod +x server/build/index.js

检查员端口问题

检查器会自动查找可用端口。如果你看到不同的端口 输出中的数字（例如，6277上的代理，6274上的web UI），这是正常的。使用 终端输出中显示的URL。

未找到模块

检查Node.js版本并确保安装了所有依赖项：

node --version  # Should be 22+
npm install

建筑

系统概述

graph TB
    subgraph "Claude Code Environment"
        CC[Claude Code]
        MCP_CLIENT[MCP Client]
    end

    subgraph "Minimal MCP Server"
        SERVER[MCP Server Process]
        TOOLS[Tool Handlers]
        subgraph "Available Tools"
            CALC[calculate_sum]
            REV[reverse_string]
            TIME[get_current_time]
        end
    end

    subgraph "Communication Layer"
        STDIO[stdio Transport]
    end

    CC --> MCP_CLIENT
    MCP_CLIENT  STDIO
    STDIO  SERVER
    SERVER --> TOOLS
    TOOLS --> CALC
    TOOLS --> REV
    TOOLS --> TIME

    style CC fill:#3b82f6,color:#fff
    style SERVER fill:#10b981,color:#fff
    style STDIO fill:#f59e0b,color:#fff

序列图

sequenceDiagram
    participant User
    participant Claude as Claude Code
    participant Client as MCP Client
    participant Server as Minimal MCP Server
    participant Tool as Tool Handler

    Note over User,Tool: Tool Discovery & Registration
    User->>Claude: Start Claude Code
    Claude->>Client: Initialize MCP Client
    Client->>Server: Connect via stdio
    Server->>Client: Send available tools list
    Client->>Claude: Register tools

    Note over User,Tool: Tool Execution Flow
    User->>Claude: "Calculate 42 + 58"
    Claude->>Client: Call calculate_sum(42, 58)
    Client->>Server: Tool execution request
    Server->>Tool: Execute calculate_sum
    Tool->>Tool: Process: 42 + 58 = 100
    Tool->>Server: Return result
    Server->>Client: Send response
    Client->>Claude: Return tool result
    Claude->>User: Display: "The sum of 42 and 58 is 100"

    Note over User,Tool: Error Handling
    User->>Claude: "Invalid request"
    Claude->>Client: Invalid tool call
    Client->>Server: Send invalid request
    Server->>Client: Return error
    Client->>Claude: Handle error
    Claude->>User: Display error message

演示

安装和设置

方法1：Claude代码集成

将MCP服务器直接添加到Claude Code中：

claude mcp add minimal-mcp-server minimal-mcp-server

方法2：全局npm安装

全局安装并手动配置：

# Install the package globally
npm install -g minimal-mcp-server

# Then add to Claude Code configuration manually
# (or use other MCP-compatible clients)

Claude Code的手动配置：

{
  "mcpServers": {
    "minimal-mcp-server": {
      "command": "minimal-mcp-server"
    }
  }
}

现场测试结果

以下是Claude Code集成的实际测试结果：

1.计算总和

Input: calculate_sum(42, 58)
Output: "The sum of 42 and 58 is 100"

2.反向字符串

Input: reverse_string("Hello MCP World")
Output: "Reversed text: dlroW PCM olleH"

3.获取当前时间

Input: get_current_time()
Output: "Current time: 2025-08-24T02:19:17.244Z"

Python客户端测试

您还可以使用附带的Python客户端进行测试：

cd client
python client.py

输出示例：

🚀 Initializing MCP agent and connecting to services...
✅ Created 1 new sessions
🧠 Agent ready with tools: calculate_sum, reverse_string, get_current_time
🔧 Tool call: calculate_sum with input: {'a': 42, 'b': 58}
📄 Tool result: The sum of 42 and 58 is 100
🔧 Tool call: reverse_string with input: {'text': 'Hello MCP'}
📄 Tool result: Reversed text: PCM olleH
🔧 Tool call: get_current_time with input: {}
📄 Tool result: Current time: 2025-08-24T02:16:40.654Z

许可证

麻省理工学院