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. 安装依赖

pip install -r requirements.txt

如果网络不好，使用国内镜像：

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. 运行

# 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 编码，设置环境变量：

set PYTHONIOENCODING=utf-8

Q: pip 安装失败

A: 使用国内镜像源：

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 配置中。