内容
# MCP指南
一个包含基本MCP客户端和MCP服务器（基于SDK和JSON-RPC实现）的代码库，旨在帮助每个人从零开始学习MCP。
## 项目结构
- `mcp-client.ts`：一个命令行接口（CLI）客户端，连接到MCP服务器，并使用OpenAI的API处理用户查询并与可用工具进行交互。
- `mcp-server-v1.ts`：使用`@modelcontextprotocol/sdk`库实现的MCP服务器。它通过标准输入输出提供天气工具（`get-alerts`和`get-forecast`）。
- `mcp-server-v2.ts`：另一个MCP服务器实现，类似于`v1`，但使用与SDK略有不同的服务器设置。它同样通过标准输入输出提供天气工具。
- `mcp-server-protocol.ts`：作为HTTP服务器实现的MCP服务器，使用Express.js。它手动实现基于JSON-RPC的MCP，通过HTTP端点提供相同的天气工具。
- `utils.ts`：包含与NWS API交互的实用函数，包括发起请求和格式化警报数据。
- `types.ts`：定义TypeScript类型和Zod模式，用于验证与NWS API相关的参数和结构化数据。
## 特性
- **多种服务器实现**：
- 基于标准输入输出的MCP服务器（v1和v2使用SDK）。
- 基于HTTP的MCP服务器（手动协议实现）。
- **天气工具**：
- `get-alerts`：获取指定美国州的天气警报。
- `get-forecast`：获取特定纬度和经度的天气预报。
- **OpenAI集成**：客户端使用OpenAI模型理解自然语言查询并决定调用哪个工具。
- **动态服务器连接**：客户端可以连接到多个配置的MCP服务器。
## 设置
1. **安装依赖**：
```bash
npm install
```
2. **环境变量**：
在项目根目录创建一个`.env`文件，并添加你的OpenAI API密钥：
```
OPENAI_API_KEY=your_openai_api_key_here
# 可选：指定不同的OpenAI模型或基础URL
# OPENAI_MODEL=gpt-3.5-turbo
# OPENAI_BASE_URL=https://api.openai.com/v1
```
## 运行服务器
你可以使用以下命令运行不同的服务器实现：
- **MCP服务器V1（标准输入输出）**：
```bash
tsx mcp-server-v1.ts
```
- **MCP服务器V2（标准输入输出）**：
```bash
tsx mcp-server-v2.ts
```
- **MCP服务器（HTTP）**：
```bash
tsx mcp-server-protocol.ts
```
该服务器通常运行在`http://localhost:3000`。
## 运行客户端
客户端在`mcp-client.ts`中配置。默认情况下，它尝试连接到配置中标记为`isOpen: true`的服务器。
要运行客户端：
```bash
tsx mcp-client.ts
```
连接后，你可以输入与天气相关的查询，例如：
- "CA的天气警报是什么？"
- "获取纬度34.05和经度-118.24的天气预报"
客户端将与连接的MCP服务器和OpenAI进行交互，以提供所请求的信息。输入`quit`以退出客户端。
## 工作原理
1. `mcp-client.ts`启动并连接到配置的MCP服务器。
2. 它列出每个连接服务器的可用工具。
3. 当用户输入查询时，客户端将此查询及可用工具列表发送给OpenAI模型。
4. OpenAI模型确定是否有工具可以满足请求。
5. 如果选择了某个工具，客户端将使用OpenAI模型识别的参数调用相应的MCP服务器上的工具。
6. MCP服务器执行该工具（例如，通过调用NWS API）并返回结果。
7. 客户端接收工具的结果，并将其与原始查询和对话历史一起发送回OpenAI模型。
8. OpenAI模型根据工具的输出生成最终响应给用户。
9. 客户端显示此响应。
## 注意事项
- NWS API主要提供美国境内位置的数据。
- `mcp-server-v1.ts`和`mcp-server-v2.ts`使用`@modelcontextprotocol/sdk`以便于通过标准输入输出实现MCP。
- `mcp-server-protocol.ts`演示了通过HTTP手动实现MCP，涉及直接处理JSON-RPC消息。
- 客户端和服务器组件均实现了错误处理。
- 客户端可以扩展以支持更多服务器或不同类型的传输（例如，SSE）。
MCP 市场