Model Context Protocol (MCP) Implementation

Model Context Protocol (MCP) 实现

本项目实现了用于构建 AI 工具的 Model Context Protocol (MCP)。它提供了一个模块化框架，可用于创建兼容 MCP 的服务端和客户端。

---

🔍 什么是 Model Context Protocol (MCP)？

Model Context Protocol (MCP) 是一种开放协议，可让 AI 助手与外部工具和数据源交互。

主要功能

• 列出可用工具及其能力
• 使用参数调用工具
• 以一致的方式处理错误
• 以标准化格式处理工具结果

📚 如需详细概述，请参阅 MCP 说明。

---

✨ 功能

类别	功能
核心	✅ JSON-RPC 2.0 消息处理 ✅ 协议初始化 ✅ 能力协商
工具	✅ 使用 JSON Schema 注册工具 ✅ 工具调用与验证 ✅ 标准化错误处理
传输	✅ 支持 STDIO ✅ 支持 HTTP+SSE
测试	✅ 测试客户端

---

📁 项目结构

src/
├── core/           # Core MCP server implementation
├── transports/     # Transport layer implementations (stdio, HTTP+SSE)
├── tools/          # Tool definitions and handlers
├── examples/       # Example servers and clients
│   └── public/     # Static files for HTTP server
└── index.js        # Main entry point for the library

---

🚀 快速入门

前置条件

• Node.js 20.x 或更高版本
• npm 或 pnpm

安装

# Clone the repository
git clone https://github.com/AshikNesin/learn-mcp-by-building
cd learn-mcp-by-building

# Install dependencies
npm install
# or
pnpm install

---

🏃‍♂️ 运行示例

STDIO 服务端和客户端

运行 STDIO 服务端：

npm run server:stdio
# or
node src/examples/stdio-server.js

使用 STDIO 客户端进行测试：

npm run client:stdio
# or
node src/examples/stdio-client.js

同时运行二者以查看完整测试：

npm run test:stdio
# or
node src/examples/stdio-client.js | node src/examples/stdio-server.js

HTTP+SSE 服务端和客户端

运行 HTTP+SSE 服务端：

npm run server:sse
# or
node src/examples/http-sse-server.js --port 5000

可用选项：

• --port：监听端口（默认值：5000）
• --host：绑定主机（默认值：localhost）
• --path：端点路径（默认值：/sse）
• --cors：启用 CORS（默认值：true）
• --serve-static：从 src/examples/public 提供静态文件（默认值：true）

使用 HTTP+SSE 客户端进行测试：

npm run client:sse
# or
node src/examples/http-sse-client.js --server http://localhost:5000/sse

运行后，你还可以在浏览器中访问 http://localhost:5000 打开 Web 客户端界面：

该界面提供了与 MCP 服务交互的便捷方式，采用并排布局，展示计算器控件和实时日志。

🔍 使用 MCP Inspector

你可以使用官方 MCP Inspector 调试服务端：

npm run debug

MCP Inspector 提供可视化界面，用于监控和调试 MCP 服务端：

---

🧮 计算器工具

运算 ➕ add ➖ subtract ✖️ multiply ➗ divide

参数 operation - 运算类型 a - 第一个操作数 b - 第二个操作数

错误处理 除以零 无效运算 类型验证 缺少参数

---

🧑‍💻 使用 MCP 框架进行开发

创建新的服务端

import { McpServer } from '../core/index.js';
import { StdioTransport } from '../transports/index.js';
import { calculatorToolDefinition, handleCalculatorTool } from '../tools/index.js';

// Create server instance
const server = new McpServer(
  { name: 'my-server', version: '1.0.0' },
  { capabilities: { tools: { listChanged: true } } }
);

// Register tool handlers
server.setRequestHandler('tools/list', () => ({ tools: [calculatorToolDefinition] }));
server.setRequestHandler('tools/call', async (params) => {
  if (params.name === 'calculator') {
    return handleCalculatorTool(params.arguments);
  }
  throw new Error(`Tool ${params.name} not found`);
});

// Start the server
const transport = new StdioTransport();
server.connect(transport)
  .then(() => console.error('Server ready!'));

创建新的工具

1. 在 src/tools/ 中创建一个新文件：

// src/tools/my-tool.js
export const myToolDefinition = {
  name: 'my-tool',
  description: 'Description of my tool',
  inputSchema: {
    type: 'object',
    properties: {
      // Define parameters
    },
    required: []
  }
};

export async function handleMyTool(args) {
  // Implement tool logic
  return {
    content: [
      {
        type: 'text',
        text: 'Result from my tool'
      }
    ]
  };
}

2. 在 src/tools/index.js 中导出该工具：

export * from './my-tool.js';

---

🛠️ 协议功能

• ✅ 能力协商
• ✅ 工具列表变更通知
• ✅ 标准化错误处理
• ✅ JSON Schema 验证
• ✅ 结构化工具结果
• ✅ 传输层抽象

---

📚 外部资源

• MCP 协议规范
• JSON-RPC 2.0 规范
• MCP GitHub 仓库

---

📝 许可证

MIT