MCP Arithmetic Learning Lab

MCP算术学习实验

一个完整的端到端学习项目，展示了具有三个相互连接的组件的模型上下文协议（MCP）。

🏗️ 架构概述

┌─────────────────┐    HTTP     ┌─────────────────┐    stdio    ┌─────────────────┐
│                 │ ◄────────── │                 │ ◄────────── │                 │
│ Arithmetic API  │             │  MCP Server     │             │  Test Client    │
│ (Express)       │ ──────────► │ (@mcp/sdk)      │ ──────────► │ (@mcp/sdk)      │
│                 │  REST calls │                 │  MCP tools  │                 │
└─────────────────┘             └─────────────────┘             └─────────────────┘
     Port 3001                    stdio transport               spawns MCP server

📁 项目结构

mcp-arith-lab/
├── README.md                 # This file
├── .gitignore               # Node.js gitignore  
├── .nvmrc                   # Node version (18.20.0)
├── arithmetic-api/          # Express REST API
│   ├── package.json
│   └── server.js           # HTTP endpoints: /add, /sub, /mul, /div
├── mcp-arith-server/       # MCP server wrapping API
│   ├── package.json
│   └── mcp-server.js       # MCP tools via stdio transport
└── mcp-test-client/        # Test client for MCP server
    ├── package.json
    └── client.js           # Spawns server, calls tools

🚀 快速开始

1.安装依赖项

# Install all dependencies
cd mcp-arith-lab

# Arithmetic API
cd arithmetic-api
npm install

# MCP Server  
cd ../mcp-arith-server
npm install

# Test Client
cd ../mcp-test-client  
npm install

cd ..

2.启动API（终端1）

cd arithmetic-api
npm start

预期产量：

🧮 Arithmetic API running at http://localhost:3001
Available endpoints:
  GET/POST /health - Health check
  GET/POST /add   - Addition (a + b)
  GET/POST /sub   - Subtraction (a - b)
  GET/POST /mul   - Multiplication (a * b)
  GET/POST /div   - Division (a / b)

3.测试客户端（终端2）

cd mcp-test-client

# Test addition
npm run start:add
# Expected: ✅ [add] 10, 20 => 30

# Test division  
npm run start:div
# Expected: ✅ [div] 10, 2 => 5

# Test subtraction
npm run start:sub  
# Expected: ✅ [sub] 15, 5 => 10

# Test multiplication
npm run start:mul
# Expected: ✅ [mul] 6, 7 => 42

🔧 API测试

使用curl直接测试算术API：

# Health check
curl http://localhost:3001/health
# {"ok":true}

# Addition (query params)
curl "http://localhost:3001/add?a=15&b=25"  
# {"operation":"add","a":15,"b":25,"result":40}

# Subtraction (JSON body)
curl -X POST http://localhost:3001/sub \\
  -H "Content-Type: application/json" \\
  -d '{"a": 20, "b": 8}'
# {"operation":"sub","a":20,"b":8,"result":12}

# Division by zero (error case)
curl "http://localhost:3001/div?a=10&b=0"
# {"error":"Division by zero"}

# Invalid input (error case)  
curl "http://localhost:3001/mul?a=hello&b=5"
# {"error":"Both a and b must be valid numbers"}

🔍 MCP服务器测试

MCP服务器可以单独测试：

cd mcp-test-client

# List available tools
node client.js
# 📋 Available tools:
#   add - Add two numbers
#   sub - Subtract second number from first number  
#   mul - Multiply two numbers
#   div - Divide first number by second number

# Call specific tools
node client.js add 100 50    # ✅ [add] 100, 50 => 150
node client.js div 100 0     # ❌ Error: Failed to call arithmetic API: Division by zero

⚙️ 配置

环境变量

• API_BASE -算术API的基本URL（默认值： http://localhost:3001)
• PORT -API服务器端口（默认值： 3001)

用法示例

# Use different API URL
API_BASE=http://localhost:8080 node client.js add 5 3

# Run API on different port
PORT=8080 npm start  # in arithmetic-api/

🔌 与MCP主机集成

要将此MCP服务器与Claude Desktop或其他MCP主机一起使用，请添加以下配置：

Claude桌面配置

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "arithmetic": {
      "command": "node", 
      "args": ["/absolute/path/to/mcp-arith-lab/mcp-arith-server/mcp-server.js"],
      "env": {
        "API_BASE": "http://localhost:3001"
      }
    }
  }
}

其他MCP主机

使用这些参数：

• 命令: node
• 参数: ["/path/to/mcp-server.js"]
• 运输: stdio
• 环境: API_BASE=http://localhost:3001

🧪 错误处理示例

该系统演示了正确的错误传播：

# API errors propagate through MCP
node client.js div 10 0
# ❌ Error: Failed to call arithmetic API: Division by zero

# Invalid tool names  
node client.js invalid 1 2
# ❌ Tool call failed: Unknown tool: invalid

# Missing arguments
node client.js add 1  
# ❌ Usage: node client.js   

📚 学习成果

该项目展示了：

1. REST API设计 -具有验证和错误处理功能的Express服务器
2. MCP服务器实现 -工具注册、stdio传输、API包装
3. MCP客户端使用情况 -进程生成、工具调用、连接管理
4. 错误传播 -错误如何从API流出→ MCP服务器→ 客户端
5. 开发工作流程 -多组件系统，界面清晰

🛠️ 故障排除

常见问题

“ECONNREFUSED”错误

• 确保算术API正在端口3001上运行
• 检查是否有其他服务正在使用该端口

“spawn ENOENT”错误

• 验证Node.js是否已安装并位于PATH中
• 检查脚本的文件权限

MCP连接超时

• 确保MCP服务器脚本路径正确
• 验证是否安装了依赖项

调试模式

启用详细日志记录：

# MCP server debug output goes to stderr
cd mcp-test-client
node client.js add 1 2 2>debug.log

📄 许可证

麻省理工学院-欢迎将其用于学习和实验。