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 📚 学习成果
该项目展示了：
- REST API设计 -具有验证和错误处理功能的Express服务器
- MCP服务器实现 -工具注册、stdio传输、API包装
- MCP客户端使用情况 -进程生成、工具调用、连接管理
- 错误传播 -错误如何从API流出→ MCP服务器→ 客户端
- 开发工作流程 -多组件系统，界面清晰
🛠️ 故障排除
常见问题
“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📄 许可证
麻省理工学院-欢迎将其用于学习和实验。