# MCP 演示项目 - 官方SDK版本
这是一个基于**官方 MCP Python SDK** 的 Model Context Protocol (MCP) 演示项目，展示了如何使用真正的MCP协议构建服务器。
## 🆕 版本说明
### v2.0 - MCP SDK版本 (当前版本)
- ✅ 使用**官方 MCP Python SDK (v1.13.1)**
- ✅ 真正的 MCP 协议实现 (STDIO 传输)
- ✅ 支持与 Claude Desktop 等MCP客户端连接
- ✅ 现代化的工具和资源定义
### v1.0 - FastAPI版本 (遗留)
- 🔧 基于 FastAPI 的 RESTful API 模拟
- 📁 文件: `main.py`, `mcp_server.py` (旧版本)
- ⚠️ 非真正的MCP协议，仅为概念演示
## 🚀 快速开始
### 方式一：使用PowerShell脚本 (推荐)
```powershell
# 启动MCP SDK服务器
.\start_mcp_sdk.ps1
# 运行客户端测试
.\test_mcp_sdk.ps1
```
### 方式二：手动操作
```bash
# 1. 激活虚拟环境
venv\Scripts\activate
# 2. 安装依赖
pip install -r requirements.txt
# 3. 启动MCP服务器
python mcp_server_sdk.py
# 4. 运行测试 (新终端)
python test_mcp_sdk.py
```
## 🛠️ 功能特性
### 工具 (Tools)
- **calculator** - 数学计算工具
- 支持基本运算: `+`, `-`, `*`, `/`
- 支持数学函数: `sin`, `cos`, `tan`, `log`, `sqrt`, `abs`, `pow`
- 支持常数: `pi`, `e`
- 安全执行环境，防止恶意代码
- **text_analyzer** - 文本分析工具
- 字符、词汇、句子统计
- 词频分析 (前10个高频词)
- 阅读时间估算
- 支持中英文混合文本
- **file_reader** - 文件读取工具
- 安全的文件访问 (限制在项目目录内)
- 支持多种文件类型: `.txt`, `.md`, `.json`, `.py`, `.js`, `.html`, `.css`, `.xml`
- 文件大小限制: 2048字节
- 自动编码检测 (UTF-8/GBK)
### 资源 (Resources)
- **config://server** - 服务器配置信息
- **status://server** - 服务器运行状态
- **logs://server** - 服务器日志信息
## 📋 测试结果示例
```
🚀 开始 MCP SDK 服务器测试
============================================================
📋 测试: 获取工具列表
✅ 成功获取工具列表 - 发现 3 个工具
🧮 测试: 计算器工具
✅ 简单加法: 2 + 3 = 5
✅ 混合运算: 10 * 5 - 2 = 48
✅ 平方根函数: sqrt(16) = 4.0
✅ 三角函数: sin(pi/2) = 1.0
⚠️ 除零错误测试: 正确处理错误
📝 测试: 文本分析工具
✅ 字符数: 170, 词数: 15, 句子数: 2
✅ 预计阅读时间: 0.1 分钟
📁 测试: 文件读取工具
✅ 成功读取依赖文件，大小: 68 字节
⚠️ README文件太大 (超过2048字节限制)
📚📖 测试: 资源功能
✅ 成功获取3个资源并读取配置、状态、日志
⚠️ 测试: 错误处理
✅ 正确处理不存在的工具和资源
```
## 🔌 与 Claude Desktop 集成
要将此MCP服务器连接到Claude Desktop，请按以下步骤配置：
### 1. 打开Claude Desktop配置文件
```bash
# Windows
notepad "%APPDATA%\Claude\claude_desktop_config.json"
# macOS/Linux
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
### 2. 添加服务器配置
```json
{
"mcpServers": {
"mcpdemo": {
"command": "python",
"args": [
"C:\\Users\\Administrator\\learn\\mcpdemo\\mcp_server_sdk.py"
]
}
}
}
```
### 3. 重启Claude Desktop
重启后，您就可以在Claude Desktop中使用这些工具了！
## 📁 项目文件结构
```
mcpdemo/
├── mcp_server_sdk.py # 🆕 MCP SDK服务器 (主要文件)
├── test_mcp_sdk.py # 🆕 MCP SDK客户端测试
├── start_mcp_sdk.ps1 # 🆕 MCP SDK启动脚本
├── test_mcp_sdk.ps1 # 🆕 MCP SDK测试脚本
├── requirements.txt # 更新的依赖列表
├── mcp_server.log # 服务器日志文件
│
├── main.py # 🔧 旧版本 FastAPI服务器
├── mcp_server.py # 🔧 旧版本 MCP模拟实现
├── tools.py # 🔧 旧版本 工具定义
├── config.py # 🔧 旧版本 配置文件
├── client_test.py # 🔧 旧版本 REST客户端测试
│
├── setup_and_run.ps1 # 旧版本启动脚本
├── test_with_venv.ps1 # 旧版本测试脚本
└── README.md # 本文件
```
## 🔧 技术栈
- **MCP SDK**: 1.13.1+ (官方Python实现)
- **Python**: 3.10+
- **传输协议**: STDIO (标准输入输出)
- **消息格式**: JSON-RPC 2.0
- **日志**: 文件日志 + 标准错误输出
## ⚡ 性能和限制
- **文件大小限制**: 2048字节 (可配置)
- **支持的文件类型**: 文本文件、代码文件、标记语言
- **并发支持**: 单客户端连接 (MCP STDIO特性)
- **内存使用**: 轻量级，适合本地开发
## 🛡️ 安全特性
- **表达式沙箱**: 数学计算使用受限的执行环境
- **路径验证**: 文件访问限制在项目目录内
- **输入验证**: 所有工具参数都经过验证
- **错误处理**: 完善的异常捕获和用户友好的错误信息
## 🔍 调试和开发
- **日志文件**: `mcp_server.log` - 包含详细的服务器运行日志
- **测试覆盖**: 完整的工具、资源和错误处理测试
- **开发模式**: 支持热重载和详细错误信息
## 📚 学习资源
- [MCP 官方文档](https://modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Claude Desktop MCP指南](https://docs.anthropic.com/claude/docs/mcp)
## 🤝 贡献
欢迎提交Issue和Pull Request！
## 📄 许可证
本项目仅供学习和演示使用。
