AI导哈

模型上下文协议教学演示

一个教授模型上下文协议(MCP)的教育演示，展示AI助手如何通过JSON-RPC 2.0与外部工具和数据源交互。

  • by MehdiBukhari
  • JavaScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 MehdiBukhari/CURL_TO_CONTEXT

使用说明

从卷曲到语境：掌握MCP

📚 概述

这个教育演示教 模型上下文协议（MCP） -AI助手与外部工具和数据源交互的协议。

你将学到什么

通过此演示，您将了解：

  • ✅ MCP协议基础 -如何定义、列出和调用工具
  • ✅ JSON-RPC 2.0 -MCP使用的请求/响应格式
  • ✅ 运输方式 -stdio（本地）与HTTP（远程）通信
  • ✅ 错误处理 -正确的错误代码和消息
  • ✅ TypeScript开发 -构建和编译MCP服务器/客户端
  • ✅ 真实世界测试 -使用curl、Postman和程序化客户端

🎯 目录

CURL_TO_CONTEXT/
├── README.md                          # This file - Full documentation
├── CHEATSHEET.md                      # Quick reference (print this!)
├── mcp-server/                        # Simple MCP Server Implementation
│   ├── src/
│   │   └── index.ts                   # Math operations MCP server
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md
├── mcp-client-stdio/                  # Client using stdio transport
│   ├── src/
│   │   └── client.ts                  # stdio client implementation
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md
├── mcp-client-remote/                 # Client using HTTP transport
│   ├── src/
│   │   └── client.ts                  # HTTP client implementation
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md
└── examples/                          # JSON-RPC request examples
    ├── tools-list-request.json        # List all tools
    ├── add-request.json               # Addition example
    ├── subtract-request.json          # Subtraction example
    ├── multiply-request.json          # Multiplication example
    ├── divide-request.json            # Division example
    └── README.md                      # Usage guide

🚀 快速开始

先决条件

在开始之前，请确保您已经 Node.js 18+ 安装：

node --version  # Should show v18.x.x or higher

如果未安装，请从下载 nodejs.org

💡 提示： 打印或书签 CHEATSHEET.md 在演示过程中快速参考！

选项A：stdio传输（建议先使用）

最适合： 学习本地MCP通信

步骤1：构建MCP服务器

cd mcp-server
npm install
npm run build

这有什么作用： 将TypeScript服务器编译为JavaScript

步骤2：运行stdio客户端演示

cd ../mcp-client-stdio
npm install
npm run build
npm start

预期产量：

  • ✅ 服务器通过stdio启动
  • ✅ 列出4个数学工具（加、减、乘、除）
  • ✅ 自动执行计算
  • ✅ 演示错误处理

持续时间： 约2分钟

选项B:HTTP传输（远程连接）

最适合： 了解联网的MCP服务器

终端1-启动HTTP服务器：

cd mcp-server
npm install       # If not already done
npm run build     # If not already done
npm run start:http

预期产量：

🚀 Starting MCP Math Server in HTTP mode
✅ HTTP Server running on http://localhost:5001

让这个终端继续运行！

终端2-运行HTTP客户端：

cd mcp-client-remote
npm install
npm run build
npm start

您将看到：

  • 📤 JSON-RPC请求
  • 📥 服务器响应
  • ✅ HTTP上的数学运算
  • ✅ 错误处理示例

持续时间： 约3分钟

快速手动测试（HTTP服务器运行）

尝试以下curl命令直接测试服务器：

列出可用工具：

curl -X POST http://localhost:5001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

计算10+5：

curl -X POST http://localhost:5001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"add","arguments":{"a":10,"b":5}},"id":2}'

测试误差（除以零）：

curl -X POST http://localhost:5001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"divide","arguments":{"a":10,"b":0}},"id":3}'

故障排除

“找不到服务器”错误？

# Make sure you built the server first:
cd mcp-server
npm run build

“连接被拒绝”错误？

# Start the HTTP server in another terminal:
cd mcp-server
npm run start:http

端口5001已在使用中？

# Use a different port:
PORT=3000 npm run start:http
# Then update client:
MCP_SERVER_URL=http://localhost:3000/mcp npm start

📖 关键概念

JSON-RPC 2.0格式

每个MCP消息都遵循以下结构：

{
  "jsonrpc": "2.0",        // Always "2.0"
  "method": "tools/call",   // MCP method name
  "params": {               // Optional parameters
    "name": "add",
    "arguments": {
      "a": 10,
      "b": 5
    }
  },
  "id": 1                   // Unique request ID
}

MCP协议方法

方法 目的 何时使用
initialize 客户端和服务器之间的握手 第一次连接
tools/list 发现可用工具 调用工具之前
tools/call 执行特定工具 执行操作
resources/list 获取可用资源 访问数据源
prompts/list 获取可用提示 模板管理
notifications/ 服务器到客户端更新 实时事件

错误代码（JSON-RPC 2.0）

代码 名称 含义
-32700 解析错误 JSON无效
-32600 无效请求 JSON-RPC格式错误
-32601 找不到方法 未知方法
-32602 参数无效 参数错误
-32603 内部错误 服务器错误

🎯 快速参考

常用命令

列出可用工具：

curl -X POST http://localhost:5001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

调用工具：

curl -X POST http://localhost:5001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"add","arguments":{"a":10,"b":5}},"id":2}'

使用示例文件：

cd examples
curl -X POST http://localhost:5001/mcp \
  -H "Content-Type: application/json" \
  -d @add-request.json

项目命令

命令 位置 目的
npm install 任意目录 安装依赖项
npm run build 任意目录 编译TypeScript
npm start mcp服务器 在stdio模式下运行
npm run start:http mcp服务器 运行HTTP服务器
npm start mcp客户端stdio 运行stdio演示
npm start mcp客户端远程 运行HTTP演示
npm run dev 任意目录 构建+运行
npm run watch mcp服务器 根据更改自动重建

环境变量

# Change server port
PORT=3000 npm run start:http

# Change client server URL
MCP_SERVER_URL=http://localhost:3000/mcp npm start

📚 学习路径

立即采取下一步行动

  1. 审查 CHEATSHEET.md -把这个放在手边，以便快速参考
  2. 修改示例 -更改值 examples/*.json 文件和测试
  3. 添加错误处理 -尝试无效输入并查看响应
  4. 探索代码 -通读 src/index.ts 了解实现的文件

完成此演示后

  1. MCP官方文件 - 模型上下文协议.io
  2. 构建自己的工具 -添加新的运算（模、幂、平方根）
  3. 添加资源 -学习MCP资源管理
  4. 实施提示 -添加提示模板
  5. 真正的融合 -将MCP连接到Claude、GPT或其他AI系统

🔗 额外资源

MCP协议和规范

JSON-RPC 2.0

TypeScript和Node.js

Express.js（HTTP服务器）

测试工具

AI和LLM集成

社区与示例

  • 很棒的MCP -在GitHub上搜索“真棒mcp”
    • MCP资源和项目整理清单
  • MCP社区服务器 - github/modelcontextprotocol/servers
    • MCP服务器实现的官方集合
  • 不和谐/松弛社区 -检查MCP文档中的链接
    • 获得帮助并分享您的项目

相关概念

视频教程

  • YouTube-MCP教程 -搜索“模型上下文协议”
    • 视频演练和解释
  • Anthropic的YouTube频道 - youtube.com/@AnthropicAI
    • 关于MCP和Claude的官方视频

书籍与文章

  • “设计数据密集型应用程序” 马丁·克莱普曼
    • 了解分布式系统和协议
  • “RESTful Web API” 伦纳德·理查森和迈克·阿蒙森
    • API设计原则
  • MDN Web文档 - developer.mozilla.org
    • Web开发参考

🤝 贡献

这是一种教育资源。欢迎捐款：

  • 添加更多数学运算（幂、平方根等）
  • 改进错误消息和验证
  • 添加更详细的示例
  • 创建视频教程或博客文章
  • 翻译文档

📝 许可证

MIT许可证-免费用于教育目的

问题或议题？ 打开一个问题或检查每个目录中的单个README文件以获取更详细的信息。

相关 MCP