# MCP-Server 项目文档

## 项目概述

MCP-Server 是一个基于 Model Context Protocol (MCP) 的服务端和客户端实现，允许大语言模型（LLM）通过结构化协议调用外部工具完成复杂任务。项目主要包含两部分：MCP服务端和TypeScript实现的客户端。

## 系统架构

```
┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│   前端应用    │────▶│  MCP 客户端   │────▶│  MCP 服务端   │
└───────────────┘     └───────────────┘     └───────────────┘
        △                    │                     │
        │                    ▼                     ▼
        │           ┌───────────────┐     ┌───────────────┐
        └───────────│  大语言模型   │     │  外部服务 API │
                    │  (Deepseek)   │     │ (天气、GitHub)│
                    └───────────────┘     └───────────────┘
```

## 核心组件

### 1. MCP 服务端

服务端是工具的提供者，负责注册和执行各种工具。

**主要功能：**

- 工具注册：目前已实现天气预报查询和GitHub用户信息查询工具
- 工具执行：接收客户端请求，执行相应工具并返回结果
- 通信：通过标准输入输出(stdio)与客户端通信

### 2. MCP 客户端

客户端连接大语言模型API和MCP服务端，负责处理用户查询并协调模型调用和工具调用。

**主要功能：**

- 连接MCP服务端并获取可用工具列表
- 与大语言模型API通信（默认使用Deepseek）
- 解析模型输出中的工具调用请求
- 协调工具调用流程并汇总结果
- 提供命令行交互界面
- 提供基于Express的Web API

### 3. Web API

客户端提供了HTTP接口供前端应用调用，支持流式输出和过程可视化。

**主要端点：**

- `/sse`: 处理前端查询请求，返回包含思考过程和结果的流式响应

## 白盒过程可视化

客户端实现了白盒过程展示，让用户可以看到：

1. 意图识别过程
2. 工具选择过程
3. 工具调用参数和结果
4. 最终答案生成过程

## 技术栈

- **后端**：Node.js、TypeScript
- **框架**：Express
- **大语言模型**：Deepseek (通过OpenAI兼容API)
- **通信协议**：Model Context Protocol
- **SDK**：@modelcontextprotocol/sdk

## 使用方法

1. 启动服务端：

```bash
node dist/src/index.js
```

2. 启动客户端并连接到服务端：

```bash
node dist/mcp-client-typescript/src/index.js /path/to/server/script.js
```

3. 访问Web API：

```
POST http://localhost:3000/sse
Content-Type: application/json

{
  "query": "北京今天的天气怎么样？"
}
```

## 配置要求

需要在`.env`文件中设置以下环境变量：

- `LLM_API_KEY`: Deepseek API密钥
- `GAODE_KEY`: 高德地图API密钥（用于天气查询）

## 工作流程

1. 用户发送查询到客户端
2. 客户端将查询发送给大语言模型
3. 大语言模型分析查询并决定是否需要调用工具
4. 如需调用工具，客户端通过MCP协议向服务端发送请求
5. 服务端执行工具并返回结果
6. 客户端将工具结果再次发送给大语言模型生成最终回答
7. 将回答返回给用户

## 结语

MCP-Server项目提供了一个完整的大语言模型工具调用示例实现，展示了如何通过结构化协议让模型访问外部工具和服务，增强模型的能力边界。通过白盒过程可视化，用户可以更好地理解模型的思考过程和工具调用逻辑。