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

如果未安装，请从下载

💡 提示： 打印或书签 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协议方法

错误代码（JSON-RPC 2.0）

🎯 快速参考

常用命令

列出可用工具：

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

项目命令

环境变量

# 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协议和规范

• MCP官方文件 - 模型上下文协议.io

- 协议规范、概念和最佳实践

• MCP GitHub存储库 -

- 官方SDK、示例和讨论

• MCP TypeScript SDK -

- 本演示中使用的SDK

• MCP规范 - spec.modelcontextprotocol.io

- 详细协议规范

JSON-RPC 2.0

• JSON-RPC 2.0规范 - jsonrpc.org/规范

- MCP使用的协议格式的官方规范

• JSON-RPC最佳实践 - jsonrpc.org/historial/json-rpc-overhttp.html

- 基于HTTP的JSON-RPC指南

TypeScript和Node.js

• TypeScript手册 - 打字组织/文件/手册

- 学习TypeScript基础知识

• Node.js文档 -

- Node.js官方文档和指南

• Node.js最佳实践 -

- 全面的Node.js最佳实践

Express.js（HTTP服务器）

• Express.js指南 - expressjs.com/en/guide

- Express.js官方文档

• Express.js最佳实践 - expressjs.com/en/advanced/best-practice-performance.html

- 生产最佳实践

测试工具

• curl文档 - curl.se/docs

- 用于测试HTTP端点的命令行工具

• 邮差学习 - learning.postman.com

- API测试和文档平台

• HTTPie - httpie.io

- curl的用户友好替代品

AI和LLM集成

• API人类克劳德 - docs.anthopic.com

- 将MCP与Claude集成

• OpenAI API - platform.openai.com/docs

- 与GPT模型连接

• LangChain - python.langchain.com

- 构建LLM应用程序的框架

社区与示例

• 很棒的MCP -在GitHub上搜索“真棒mcp”

- MCP资源和项目整理清单

• MCP社区服务器 -

- MCP服务器实现的官方集合

• 不和谐/松弛社区 -检查MCP文档中的链接

- 获得帮助并分享您的项目

相关概念

• 协议缓冲区 - protobuf.dev

- 替代序列化格式

• gRPC - grpc.io

- 现代RPC框架

• 图查询语言 - graphql.org

- API的查询语言

• WebSockets - developer.mozilla.org/en-US/docs/Web/API/Webockets_API开发人员

- 实时双向通信

视频教程

• YouTube-MCP教程 -搜索“模型上下文协议”

- 视频演练和解释

• Anthropic的YouTube频道 - youtube.com/@AnthropicAI

- 关于MCP和Claude的官方视频

书籍与文章

• “设计数据密集型应用程序” 马丁·克莱普曼

- 了解分布式系统和协议

• “RESTful Web API” 伦纳德·理查森和迈克·阿蒙森

- API设计原则

• MDN Web文档 - developer.mozilla.org

- Web开发参考

🤝 贡献

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

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

📝 许可证

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

______________________________________________________________________

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