# MCP 记事本工具 📝

一个完整的 MCP (Model Context Protocol) 工具演示项目，实现"用户提出打开记事本 → 模型生成 Function Call → 程序解析 → MCP 调用 → 记事本打开 → 模型回复"的完整流程。

## 📁 项目结构

```
mcp-notepad-project/
├── mcp_server.py        # MCP Server - 提供 open_notepad 工具
├── mcp_client.py        # MCP Client - 连接 Server 并调用工具
├── model_adapters.py    # 模型适配器 - 解析 OpenAI/Anthropic 的 Function Call
├── main.py              # 主程序 - 串联完整流程（单次调用）
├── chat.py              # 交互式对话 - 可以反复与模型对话
├── .env                 # API Key 配置（自动读取）
├── .gitignore           # Git 忽略规则（保护 .env 不上传）
├── mcp_config.json      # MCP 配置文件
├── requirements.txt     # 依赖列表
└── README.md            # 本文件
```

## 🚀 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

如果网络不好，使用国内镜像：
```bash
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
```

### 2. 配置 API Key

编辑 `.env` 文件，填入你的 API Key：

```
DEEPSEEK_API_KEY=sk-xxxxx       # 推荐！国内免费
OPENAI_API_KEY=sk-xxxxx         # OpenAI
ANTHROPIC_API_KEY=sk-ant-xxxxx  # Anthropic
```

### 3. 运行

```bash
# DeepSeek（默认，国内免费推荐）
python main.py --provider deepseek
python chat.py --provider deepseek

# OpenAI
python main.py --provider openai
python chat.py --provider openai

# Anthropic (Claude)
python main.py --provider anthropic
python chat.py --provider anthropic
```

## 🔧 核心架构

```
用户提问 "打开记事本"
       ↓
  Python 客户端 (main.py / chat.py)
       ↓
  调用 AI 模型 API (OpenAI / Anthropic / DeepSeek)
       ↓
  模型返回 Function Call (JSON)
       ↓
  model_adapters.py 解析 Function Call
  ┌─────────────────┬──────────────────┐
  │   OpenAI 格式    │  Anthropic 格式   │
  │ tool_calls[].   │ content[].       │
  │ function.name   │ name             │
  │ function.args   │ input            │
  │ (字符串)         │ (字典)            │
  └────────┬────────┴────────┬─────────┘
           ↓                 ↓
     ParsedToolCall (统一格式)
           ↓
  mcp_client.py 通过 MCP 协议调用
           ↓
  mcp_server.py 执行 subprocess.Popen("notepad.exe")
           ↓
  记事本打开！结果返回给模型
           ↓
  模型回复 "已为您打开记事本"
```

## 📖 关键概念解释

### MCP (Model Context Protocol)
- 一个开放协议，让 AI 模型能通过标准化接口调用外部工具
- 类似于 USB 接口：只要遵循协议，任何"设备"（工具）都能插上"电脑"（模型）

### Function Call
- AI 模型不直接执行操作，而是生成一个"函数调用"的 JSON
- 程序解析这个 JSON，执行对应操作，再把结果返回给模型

### 两种格式的区别

| 特性 | OpenAI | Anthropic |
|------|--------|-----------|
| 位置 | `message.tool_calls` | `message.content[type=tool_use]` |
| 参数格式 | JSON 字符串 | 字典对象 |
| 调用ID | `call_xxx` | `toolu_xxx` |
| 结果格式 | `role: "tool"` | `type: "tool_result"` |
| 工具定义 | `function.parameters` | `input_schema` |

## ⚠️ 常见问题

### Q: 运行时出现 UnicodeEncodeError
A: Windows 默认使用 GBK 编码，设置环境变量：
```bash
set PYTHONIOENCODING=utf-8
```

### Q: pip 安装失败
A: 使用国内镜像源：
```bash
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
```

### Q: 没有 API Key 怎么办？
A: 推荐使用 DeepSeek，注册即送免费额度：https://platform.deepseek.com/api_keys

### Q: 如何在 Claude Code 中使用这个 MCP Server？
A: 将 mcp_config.json 的内容添加到 Claude Code 的 MCP 配置中。