MCP认证与安全概念验证
目的在将远程MCP服务器集成到主e2b2学习平台之前，测试并验证其认证模式。
🎯 项目背景
这个概念验证（PoC）是……的一部分 e2b2智能学习平台 项目。主要平台采用MCP（模型上下文协议）工具，通过Claude桌面提供个性化的编程教育。
为何存在此概念验证（PoC）：
- 验证基于令牌的远程MCP服务器身份认证
- 启用安全功能的测试开发工作流程
- 了解Replit的部署流程
- 为主项目提供参考实现
- 确保身份验证不妨碍快速开发
与主项目的连接：
- 主要项目地点：
../v3/ - 主要项目使用了8个核心的MCP工具（见
../v3/docs/) - 这个概念验证（PoC）验证了将包裹这些工具的认证层
- 从这个概念验证（PoC）中获得的经验将应用于生产架构中
📋 这个概念验证（PoC）的作用
一个具备以下功能的最小化MCP服务器：
- ✅ 表示“正确”或“已确认”。 2个简单工具 (问候生成器和消息回显)
- ✅ 表示“正确”或“对”的意思。 基于令牌的认证 （可选，开发时可禁用）
- ✅ SSE传输 用于远程连接
- ✅ 用户上下文注入 （模拟学生身份识别）
- ✅（勾选标记，表示正确、确认或完成） 文档齐全的代码 （作为主要实现的示例）
🏗️ 架构概述
┌─────────────────┐
│ Claude Desktop │ (or OpenAI client)
└────────┬────────┘
│ HTTP + Bearer Token
▼
┌─────────────────┐
│ Auth Middleware│ ◄── Validates token, extracts user
└────────┬────────┘
│ Adds user context
▼
┌─────────────────┐
│ MCP Server │ ◄── Tools receive authenticated user
└─────────────────┘
│
▼
┌─────────────────┐
│ Tool Handlers │ ◄── get_greeting, echo_message
└─────────────────┘关键设计决策：
- 基于令牌的认证 （非OAuth）为简化概念验证（PoC）而采用
- 环境变量 用于身份验证的切换（便于本地开发）
- 用户上下文 传递给所有工具（主项目的模式）
- 最小化依赖 (FastMCP，Uvicorn，python-dotenv)
📚 文档结构
docs/
├── 01_CONTEXT.md # Why this PoC exists, relationship to main project
├── 02_AUTHENTICATION.md # Authentication architecture and decisions
├── 03_LOCAL_DEVELOPMENT.md # Local setup and testing
├── 04_REPLIT_DEPLOYMENT.md # Deploying to Replit
├── 05_CLIENT_SETUP.md # Connecting Claude Desktop / OpenAI
└── 06_LESSONS_LEARNED.md # Findings to apply to main project🚀 快速入门
先决条件
- Python 3.10及以上版本
- pip 或 uv 包管理器
- Claude Desktop（或兼容OpenAI的客户端）
本地开发（无需认证）
# 1. Navigate to project
cd /path/to/v3_3_auth_and_sec
# 2. Install dependencies
pip install -r requirements.txt
# 3. Run server
python server.py服务器运行于 http://localhost:8000
本地开发（带认证）
# 1. Create environment file
cp .env.example .env
# 2. Edit .env and set AUTH_ENABLED=true
# 3. Run server
python server.py测试工具
选项1：Claude桌面版 (见 docs/05_CLIENT_SETUP.md)
{
"mcpServers": {
"auth-poc": {
"command": "python",
"args": ["/absolute/path/to/server.py"]
}
}
}选项2：MCP检查器
npx @modelcontextprotocol/inspector python server.py选项3：带认证的直接HTTP
curl http://localhost:8000/tools \
-H "Authorization: Bearer tok_test1_abc123"📁 项目结构
v3_3_auth_and_sec/
├── README.md # This file - project overview
├── requirements.txt # Python dependencies
├── .env.example # Example configuration
├── .env # Your local config (git-ignored)
├── .gitignore # Ignore patterns
│
├── server.py # Main MCP server (well-documented)
├── auth_middleware.py # Authentication logic (well-documented)
├── tools.py # Tool implementations (well-documented)
│
└── docs/ # Comprehensive documentation
├── 01_CONTEXT.md
├── 02_AUTHENTICATION.md
├── 03_LOCAL_DEVELOPMENT.md
├── 04_REPLIT_DEPLOYMENT.md
├── 05_CLIENT_SETUP.md
└── 06_LESSONS_LEARNED.md🔑 认证流程
sequenceDiagram
participant Client as Claude Desktop
participant Middleware as Auth Middleware
participant Server as MCP Server
participant Tool as Tool Handler
Client->>Middleware: Request + Bearer Token
Middleware->>Middleware: Validate Token
Middleware->>Middleware: Extract User Info
Middleware->>Server: Request + User Context
Server->>Tool: Execute with User
Tool-->>Client: Response with User Data🧪 测试检查清单
- \[ \] 本地服务器无需认证即可运行
- \[ \] 本地服务器以启用认证的方式运行
- \[ \] Claude Desktop 本地连接（无需认证）
- \[ \] Claude Desktop 本地连接（已认证）
- \[ \] 成功部署到Replit
- \[ \] Claude Desktop 连接到 Replit（需认证）
- \[ \] 多个用户可以使用不同的令牌进行连接
- \[ \] 无效令牌将被明确拒绝并提示错误
📖 需要理解的关键文件
server.py- 入口点，展示FastMCP与认证中间件的集成方式auth_middleware.py- 核心认证逻辑，用户提取tools.py- 使用用户上下文的示例工具docs/02_AUTHENTICATION.md- 深入探讨认证架构
🎓 学习目标
完成这个概念验证（PoC）后，你应该能够理解：
- ✅ 如何为FastMCP服务器添加身份验证
- ✅ 如何在开发环境和生产环境之间切换身份验证
- ✅ 如何将用户上下文注入到MCP工具处理程序中
- ✅ 如何在Replit上部署经过身份验证的MCP服务器
- ✅ 如何将远程认证服务器连接到Claude桌面
- ✅ 应用于主e2b2平台的模式
🔄 证明概念（PoC）后的下一步行动
- 在本地验证 - 确保认证按预期工作
- 部署到Replit - 测试远程认证
- 记录学习成果 - 更新
docs/06_LESSONS_LEARNED.md - 应用于主项目 - 将图案融入到
../v3/
🤝 开发说明
代码风格：
- 所有函数的全面文档字符串
- 对复杂逻辑的行内注释
- 为了清晰起见，使用类型提示
- 清晰的变量名
这段代码被故意写得注释过多 作为主要项目实施的参考。
🔗 相关文档
- 主要项目：
../v3/README.md - MCP规范：https://modelcontextprotocol.io
- FastMCP 文档：https://github.com/jlowin/fastmcp
- Replit 文档：https://docs.replit.com
📞 有问题吗？
如果您遇到问题：
- 查阅相关文档
docs/ - 审查代码中的注释
.py文件 - 咨询
docs/06_LESSONS_LEARNED.md对于已知问题 - 请参考主项目的架构文档
______________________________________________________________________
项目状态概念验证阶段（PoC Phase） 最后更新时间2025年10月11日 主要项目e2b2 学习平台../v3/)