curl到上下文

Name: curl到上下文
Author: MehdiBukhari

作者：MehdiBukhari3 星标更新：2025-10-28

安装使用来源：spider==github.com

项目介绍

从Curl到Context：掌握MCP

📚 概述

本教育演示介绍了模型上下文协议（MCP）——一种用于AI助手与外部工具和数据源交互的协议。

你将学到的内容

通过完成此演示，您将了解：

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

🎯 内容

CURL_TO_CONTEXT/
├── README.md                          # 本文件 - 完整文档
├── CHEATSHEET.md                      # 快速参考（打印这个！）
├── mcp-server/                        # 简单的MCP服务器实现
│   ├── src/
│   │   └── index.ts                   # 数学操作MCP服务器
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md
├── mcp-client-stdio/                  # 使用标准输入输出传输的客户端
│   ├── src/
│   │   └── client.ts                  # 标准输入输出客户端实现
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md
├── mcp-client-remote/                 # 使用HTTP传输的客户端
│   ├── src/
│   │   └── client.ts                  # HTTP客户端实现
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md
└── examples/                          # JSON-RPC请求示例
    ├── tools-list-request.json        # 列出所有工具
    ├── add-request.json               # 加法示例
    ├── subtract-request.json          # 减法示例
    ├── multiply-request.json          # 乘法示例
    ├── divide-request.json            # 除法示例
    └── README.md                      # 使用指南

🚀 快速开始

先决条件

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

node --version  # 应显示v18.x.x或更高版本

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

💡 提示：打印或收藏CHEATSHEET.md，以便在完成演示时快速参考！

选项A：标准输入输出传输（推荐首先尝试）

最佳用途：学习本地MCP通信

步骤1：构建MCP服务器

cd mcp-server
npm install
npm run build

这会做什么：将TypeScript服务器编译成JavaScript

步骤2：运行标准输入输出客户端演示

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

预期输出：

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

持续时间：约2分钟

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

最佳用途：理解网络化的MCP服务器

终端1 - 启动HTTP服务器：

cd mcp-server
npm install       # 如果尚未执行
npm run build     # 如果尚未执行
npm run start:http

预期输出：

🚀 在HTTP模式下启动MCP数学服务器
✅ HTTP服务器正在运行于 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}'

故障排除

“找不到服务器”错误？

# 确保先构建了服务器：
cd mcp-server
npm run build

“连接被拒绝”错误？

# 在另一个终端启动HTTP服务器：
cd mcp-server
npm run start:http

端口5001已被占用？

# 使用不同的端口：
PORT=3000 npm run start:http
# 然后更新客户端：
MCP_SERVER_URL=http://localhost:3000/mcp npm start

📖 关键概念

JSON-RPC 2.0 格式

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

{
  "jsonrpc": "2.0",        // 始终为 "2.0"
  "method": "tools/call",   // MCP方法名称
  "params": {               // 可选参数
    "name": "add",
    "arguments": {
      "a": 10,
      "b": 5
    }
  },
  "id": 1                   // 唯一请求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-server	在标准输入输出模式下运行
`npm run start:http`	mcp-server	运行HTTP服务器
`npm start`	mcp-client-stdio	运行标准输入输出演示
`npm start`	mcp-client-remote	运行HTTP演示
`npm run dev`	任意目录	构建+运行
`npm run watch`	mcp-server	更改时自动重建

环境变量

# 更改服务器端口
PORT=3000 npm run start:http

# 更改客户端服务器URL
MCP_SERVER_URL=http://localhost:3000/mcp npm start

📚 学习路径

立即下一步

查看CHEATSHEET.md —— 保持此文件便于快速参考
修改示例 —— 更改examples/*.json文件中的值并测试
添加错误处理 —— 尝试无效输入并查看响应
探索代码 —— 阅读src/index.ts文件以了解实现

完成本演示后

官方MCP文档 —— modelcontextprotocol.io
构建自己的工具 —— 添加新操作（模数、幂、平方根）
添加资源 —— 学习MCP资源管理
实现提示 —— 添加提示模板
真实集成 —— 将MCP连接到Claude、GPT或其他AI系统

🔗 额外资源

MCP协议及规范

官方MCP文档 —— modelcontextprotocol.io
- 协议规范、概念和最佳实践
MCP GitHub仓库 —— github.com/modelcontextprotocol
- 官方SDK、示例和讨论
MCP TypeScript SDK —— npmjs.com/package/@modelcontextprotocol/sdk
- 本演示中使用的SDK
MCP规范 —— spec.modelcontextprotocol.io
- 详细的协议规范

JSON-RPC 2.0

JSON-RPC 2.0规范 —— jsonrpc.org/specification
- MCP使用的协议格式的官方规范
JSON-RPC最佳实践 —— jsonrpc.org/historical/json-rpc-over-http.html
- JSON-RPC通过HTTP的指导方针

TypeScript & Node.js

TypeScript手册 —— typescriptlang.org/docs/handbook
- 学习TypeScript基础知识
Node.js文档 —— nodejs.org/docs
- 官方Node.js文档和指南
Node.js最佳实践 —— github.com/goldbergyoni/nodebestpractices
- 综合的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端点的命令行工具
Postman学习 —— learning.postman.com
- API测试和文档平台
HTTPie —— httpie.io
- 用户友好的curl替代品

AI & LLM集成

Anthropic Claude API —— docs.anthropic.com
- 将MCP与Claude集成
OpenAI API —— platform.openai.com/docs
- 连接到GPT模型
LangChain —— python.langchain.com
- 构建LLM应用程序的框架

社区&示例

Awesome MCP —— 在GitHub上搜索“awesome-mcp”
- 收集的MCP资源和项目列表
MCP社区服务器 —— github.com/modelcontextprotocol/servers
- 官方的MCP服务器实现集合
Discord/Slack社区 —— 查看MCP文档中的链接
- 获取帮助并分享你的项目

视频教程

YouTube - MCP教程 —— 搜索“Model Context Protocol”
- 视频讲解和解释
Anthropic的YouTube频道 —— youtube.com/@AnthropicAI
- 关于MCP和Claude的官方视频

书籍&文章

《设计数据密集型应用》 —— Martin Kleppmann著
- 理解分布式系统和协议
《RESTful Web APIs》 —— Leonard Richardson & Mike Amundsen著
- API设计原则
MDN Web Docs —— developer.mozilla.org
- Web开发参考

🤝 贡献

这是一个教育资源。欢迎贡献：

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

📝 许可

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

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