MCP OAuth服务器
一个支持OAuth 2.1身份验证的生产就绪模型上下文协议（MCP）服务器，使用Python和FastMCP构建。
      
概述
此MCP服务器演示了使用PKCE（代码交换证明密钥）访问第三方API的安全OAuth 2.1身份验证。它被设计为在MCP主机（如Visual Studio Code）中本地运行，可以部署为Docker容器。
运输：此服务器根据MCP规范2025-06-18使用HTTP传输（带SSE的流式HTTP）。有关从stdio迁移的详细信息，请参阅 HTTP传输指南.
主要特点
- HTTP传输：根据MCP规范2025-06-18，具有服务器发送事件（SSE）的流式HTTP
- OAuth 2.1身份验证：完全实现PKCE支持的安全身份验证
- RFC 8414授权元数据：服务器公开OAuth元数据以供客户端自动发现
- RFC 8707资源指示器：实施资源指示器以增强令牌安全性
- 结构化错误响应：OAuth元数据中的JSON-RPC错误启用客户端自动化
- MCP协议合规性：遵循最新的MCP规范（2025-06-18）
- OAuth资源服务器：根据MCP规范分类为OAuth资源服务器
- MCP采样支持：演示LLM驱动的代码分析的客户端采样功能
- 结构化工具输出：工具支持结构化输出模式以实现类型安全
- 提示模板：GitHub用户分析的可重用提示，具有增强的元数据
- 工具集成：用于获取GitHub用户数据和使用LLM分析代码的自定义工具
- Docker支持：采用最佳实践的容器化部署
- 综合测试：pytest提供全面的测试覆盖
- 类型安全：使用mypy验证完成类型提示
- 生产就绪：日志记录、错误处理和配置管理
建筑
┌─────────────────────────────────────────────────────────────┐
│ MCP Host (VS Code) │
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ AI Assistant (with Sampling Support) │ │
│ └────────────┬──────────────────┬────────────────────┘ │
│ │ MCP Protocol │ Sampling Requests │
└───────────────┼──────────────────┼──────────────────────────┘
│ │
▼ │
┌─────────────────────────────────┼────────────────────────────┐
│ Docker Container (MCP │Server) │
│ │ │
│ ┌──────────────────────────────▼──────────────────────┐ │
│ │ MCP Server (FastMCP) │ │
│ │ - GitHubProvider (OAuth 2.1 with PKCE) │ │
│ │ - GitHub API Client │ │
│ │ - Prompt: github_user_summary │ │
│ │ - Tool: get_github_user_info (OAuth) │ │
│ │ - Tool: analyze_code_with_llm (Sampling) │ │
│ └──────────────────────────────────────────────────────┘ │
└──────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ GitHub OAuth & API (HTTPS) │
└─────────────────────────────────────────────────────────────┘快速开始
先决条件
- Python 3.12
- Docker（可选，用于容器化部署）
- GitHub OAuth应用程序凭据（用于完整功能）
1.克隆存储库
git clone https://github.com/huberp/mcp-oauth-mcpserver-blueprint.git
cd mcp-oauth-mcpserver-blueprint2.设置环境
Linux/macOS：
./scripts/setup.sh窗户：
.\scripts\setup.ps1这将：
- 创建Python虚拟环境
- 安装所有依赖项
- 创建一个
.env模板中的文件
3.配置OAuth凭据
📖 有关详细的设置说明，请参阅
编辑 .env 使用您的GitHub OAuth应用程序凭据的文件：
OAUTH_CLIENT_ID=your_github_client_id
OAUTH_CLIENT_SECRET=your_github_client_secret
OAUTH_AUTHORIZATION_URL=https://github.com/login/oauth/authorize
OAUTH_TOKEN_URL=https://github.com/login/oauth/access_token
OAUTH_SCOPES=read:user,repo快速入门-创建GitHub OAuth应用程序：
- 转到GitHub设置→ 开发者设置→ OAuth应用程序
- 点击“新建OAuth应用程序”
- 填写详细信息：
- 应用程序名称：MCP OAuth服务器（或您的首选名称） - 主页网址：http://localhost:8000 - 授权回调URL:http://localhost:8000/oauth/callback
- 复制客户端ID并生成客户端密钥
💡 需要帮助？ 检查 全面的设置指南 有关分步说明、故障排除和测试。
4.运行测试
Linux/macOS：
./scripts/test.sh窗户：
.\scripts\test.ps15.运行服务器
服务器可以在两种模式下运行：
背景模式（建议开发）：
在后台启动服务器并写入PID文件以便于管理。
Linux/macOS：
./scripts/run.sh窗户：
.\scripts\run.ps1前台模式（用于调试）：
在当前终端窗口中运行服务器。按Ctrl+C停止。
Linux/macOS：
./scripts/run.sh --foreground窗户：
.\scripts\run.ps1 -Foreground停止后台服务器：
Linux/macOS：
./scripts/stop.sh窗户：
.\scripts\stop.ps1服务器将在以下位置可用：
- MCP端点：
http://localhost:8000/mcp - OAuth授权：
http://localhost:8000/oauth/authorize - 健康检查：
http://localhost:8000/health - 韵律学：
http://localhost:8000/metrics - 服务器信息：
http://localhost:8000/info
Docker部署
构建Docker镜像
Linux/macOS：
./scripts/build-docker.sh窗户：
.\scripts\build-docker.ps1使用Docker Compose运行（推荐）
对于具有自动环境加载和易于管理的开发：
docker-compose up服务器将在以下时间可用 http://localhost:8000/mcp.
使用Docker运行（生产环境）
对于生产部署或手动控制：
docker run --env-file .env -p 8000:8000 mcp-oauth-server:latest备注：端口映射(-p 8000:8000)需要从您的主机访问HTTP服务器。
用法
可用组件
提示： github_user_summary
生成GitHub用户配置文件和存储库的全面摘要。
参数：
username（可选）：要分析的GitHub用户名（默认为经过身份验证的用户）
MCP主机中的示例用法：
Use the github_user_summary prompt to analyze my GitHub profile工具： get_github_user_info
使用OAuth获取经过身份验证的GitHub用户信息和存储库。
参数：
include_repos（boolean，默认值：true）：是否包含存储库数据repo_limit（整数，默认值：10）：要获取的最大存储库数量（1-100）
退货：
- 用户资料信息（登录名、姓名、个人简介、关注者等）
- 包含详细信息（名称、描述、语言、星号、分支）的存储库列表
MCP主机中的示例用法：
Use the get_github_user_info tool to fetch my GitHub profile and top 10 repositories工具： analyze_code_with_llm （需要采样能力）
使用MCP采样在语言模型的帮助下分析代码片段。此工具通过请求客户端的语言模型分析代码或提供见解来演示MCP采样功能。
参数：
code（字符串，必填）：要分析的代码片段或数据analysis_type（字符串，默认值：“explain”）：要执行的分析类型
- explain：解释代码的作用 - review：审查代码并提供反馈 - suggest_improvements：建议对代码进行改进 - find_bugs：分析潜在的错误或问题 - security_review：审查安全漏洞
max_tokens（整数，默认值：500）:LLM响应的最大令牌数（100-2000）
要求：
- 客户必须支持MCP
sampling能力 - 无需OAuth身份验证
退货：
- 模型信息分析结果
- 基于所选分析类型的见解
MCP主机中的示例用法：
Use the analyze_code_with_llm tool to explain this code:
def fibonacci(n):
if n <= 1:
return n
return fibonacci(n-1) + fibonacci(n-2)注： 如果客户端不支持采样，此工具将返回错误。支持的客户端包括Claude Desktop和支持MCP的VS Code。
HTTP端点
服务器为监视和信息提供了额外的HTTP端点：
/health -健康检查
用于监视服务器状态的健康检查终结点。
方法： 获取
答复：
{
"status": "healthy",
"server": "mcp-oauth-server",
"version": "0.1.0",
"uptime_seconds": 123.45,
"timestamp": "2025-11-01T10:51:40.812895Z"
}使用案例：
- Kubernetes/Docker健康检查
- 监控工具
- 负载平衡器运行状况检查
/metrics -服务器指标
提供工具调用统计和操作数据的度量端点。
方法： 获取
答复：
{
"server": "mcp-oauth-server",
"version": "0.1.0",
"uptime_seconds": 123.45,
"tool_calls": {
"total": 42,
"by_tool": {
"get_user_info": 15,
"get_github_user_info": 27
}
},
"timestamp": "2025-11-01T10:51:40.817726Z"
}使用案例：
- 性能监控
- 使用情况分析
- 调试工具使用模式
/info -服务器信息
提供全面服务器元数据的信息端点。
方法： 获取
答复：
{
"server": {
"name": "mcp-oauth-server",
"version": "0.1.0",
"environment": "production",
"debug": false
},
"github": {
"repository": "huberp/mcp-oauth-mcpserver-blueprint",
"url": "https://github.com/huberp/mcp-oauth-mcpserver-blueprint"
},
"oauth": {
"configured": true,
"provider": "GitHub",
"scopes": ["read:user", "repo"]
},
"http": {
"host": "0.0.0.0",
"port": 8000,
"path": "/mcp"
},
"api": {
"base_url": "https://api.github.com",
"timeout": 30
},
"timestamp": "2025-11-01T10:51:40.815391Z"
}使用案例：
- 服务发现
- 配置验证
- 诊断和故障排除
MCP主机配置（VS代码）
备注：此服务器根据MCP规范2025-06-18使用HTTP传输（带SSE的流式HTTP）。有关迁移的详细信息，请参阅 HTTP传输指南.
将此添加到VS Code中的MCP设置中(.vscode/mcp.json 或您的MCP配置文件）：
{
"mcpServers": {
"mcp-oauth-server": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
}
}重要：服务器必须在MCP客户端连接之前运行。使用以下命令启动服务器：
# Using scripts (recommended)
./scripts/run.sh
# Or with Docker
docker-compose upMCP服务器测试
此存储库包括使用MCP Inspector CLI对MCP服务器进行自动测试。工作流在每个推送和拉取请求上运行，验证服务器是否正确报告了其可用的提示和工具。
MCP测试工作流程
这 mcp-tester.yml 工作流：
- 用途
@modelcontextprotocol/inspectorCLI用于测试MCP服务器 - 列出所有可用的工具和提示
- 在工作流结果中生成汇总表
- 在主分支、开发分支和副分支推送时自动运行
查看测试结果： 检查GitHub Actions中的工作流摘要，查看MCP服务器报告的所有提示和工具的表。
使用MCP检查员进行手动测试：
服务器现在使用HTTP传输，因此在使用检查器进行测试之前，您需要先启动服务器。
选项1：快速启动（自动启动服务器）
Linux/macOS：
./runlocal/run-inspector.sh --start-server窗户：
.\runlocal\run-inspector.ps1 -StartServer选项2：手动服务器管理
Linux/macOS：
# 1. Start the server in background
./scripts/run.sh
# 2. Run the inspector (configured for HTTP transport)
./runlocal/run-inspector.sh
# 3. Stop the server when done
./scripts/stop.sh窗户：
# 1. Start the server in background
.\scripts\run.ps1
# 2. Run the inspector (configured for HTTP transport)
.\runlocal\run-inspector.ps1
# 3. Stop the server when done
.\scripts\stop.ps1配置文件：
runlocal/config.json-MCP检查器配置（HTTP传输）.vscode/mcp.json-VS代码MCP客户端配置（HTTP传输）
两种配置都连接到 http://localhost:8000/mcp 默认情况下。
发展
项目结构
.
├── src/mcp_server/ # Main application code
│ ├── __init__.py # Package initialization
│ ├── config.py # Configuration management
│ ├── api_client.py # GitHub API client
│ ├── server.py # MCP server implementation
│ └── main.py # Application entry point
├── tests/ # Test suite
│ ├── __init__.py
│ ├── conftest.py # Test fixtures
│ ├── test_config.py # Configuration tests
│ ├── test_api_client.py # API client tests
│ └── test_sampling.py # Sampling capability tests
├── scripts/ # Utility scripts
│ ├── setup.sh/ps1 # Environment setup
│ ├── test.sh/ps1 # Run tests
│ ├── run.sh/ps1 # Run server
│ └── build-docker.sh/ps1 # Build Docker image
├── docs/ # Documentation
│ ├── RESEARCH.md # Research and implementation notes
│ ├── setup-auth-github.md # GitHub OAuth setup guide
│ ├── AUTHORIZATION_GUIDE.md # Complete authorization guide
│ ├── AUTHORIZATION_QUICK_REFERENCE.md # Quick reference
│ ├── AUTHORIZATION_FLOW_SUMMARY.md # Authorization flow summary
│ ├── HTTP_TRANSPORT_GUIDE.md # HTTP transport migration guide
│ ├── MCP_AUTHORIZATION_ANALYSIS.md # Technical analysis
│ ├── IMPLEMENTATION_SUMMARY.md # Implementation summary
│ ├── SPEC_UPDATE_2025-06-18.md # MCP spec update notes
│ └── sampling.md # Sampling feature documentation
├── runlocal/ # Local development tools
│ ├── config.json # MCP Inspector configuration
│ ├── run-inspector.sh # Inspector runner (Linux/macOS)
│ └── run-inspector.ps1 # Inspector runner (Windows)
├── .github/
│ ├── workflows/ # GitHub Actions CI/CD
│ │ ├── ci.yml # Main CI pipeline
│ │ ├── test.yml # Comprehensive test suite
│ │ └── mcp-tester.yml # MCP server validation
│ └── copilot-instructions.md # Copilot guidelines
├── Dockerfile # Multi-stage Docker build
├── docker-compose.yml # Docker Compose configuration
├── pyproject.toml # Python project configuration
├── .env.example # Environment template
├── .gitignore # Git ignore rules
└── README.md # This file运行测试
该项目包括使用pytest进行全面的单元测试：
# Run all tests
pytest
# Run with coverage
pytest --cov=src/mcp_server
# Run specific test file
pytest tests/test_config.py
# Run with verbose output
pytest -v代码质量
自动代码质量（推荐）
我们使用预提交挂钩来自动执行代码质量标准：
# Install pre-commit (one-time setup)
pip install pre-commit
pre-commit install
# Pre-commit will now run automatically on git commit
# To manually run on all files:
pre-commit run --all-files预提交钩子包括：
- 拉夫：镶边和格式化（取代黑色+Flake8+isort）
- 米皮：类型检查
- 标准检查：尾随空格、文件末尾、YAML/JSON/TOML验证
- 安全：私钥检测
- 码头工人：Dockerfile linting
- 外壳：Shell脚本验证
VS代码集成
为了获得VS Code的最佳开发体验：
- 安装推荐的扩展 （VS Code会提示您）：
- charliermarsh.ruff -Ruff linter和格式化器 - ms-python.python -Python支持 - 中列出的其他有用扩展 .vscode/extensions.json
- 保存时自动格式化 已在中配置
.vscode/settings.json
- 编辑工作 支持：安装EditorConfig扩展，以确保所有编辑器的格式一致
手动代码质量检查
如果你不想使用预提交钩子：
# Format code with Ruff
ruff format src/ tests/
# Lint and auto-fix with Ruff
ruff check --fix src/ tests/
# Type checking
mypy src/
# Run all quality checks
./scripts/test.sh # or test.ps1 on Windows备注：Ruff用一个更快的linter和格式化器替换了Black、Flake8、isort和其他工具。
环境变量
| 变量 | 描述 | 默认值 | 必填 |
|---|---|---|---|
OAUTH_CLIENT_ID | OAuth客户端ID | - | 是 |
OAUTH_CLIENT_SECRET | OAuth客户端机密 | - | 是 |
OAUTH_AUTHORIZATION_URL | OAuth授权端点 | https://github.com/login/oauth/authorize | 没有 |
OAUTH_TOKEN_URL | OAuth令牌端点 | https://github.com/login/oauth/access_token | 没有 |
OAUTH_SCOPES | 逗号分隔的OAuth作用域 | 读：用户 | 否 |
OAUTH_REDIRECT_URI | OAuth回调URL | http://localhost:8000/oauth/callback | 没有 |
OAUTH_ISSUER | OAuth发行者URL（RFC 8414） | https://github.com | 没有 |
OAUTH_GRANT_TYPES_SUPPORTED | 支持的授权类型 | 授权码、刷新令牌 | 否 |
OAUTH_CODE_CHALLENGE_METHODS_SUPPORTED | 支持PKCE方法 | S256 | 否 |
OAUTH_RESPONSE_TYPES_SUPPORTED | OAuth响应类型 | 代码 | 否 |
OAUTH_TOKEN_ENDPOINT_AUTH_METHODS | 令牌端点身份验证方法 | client_secret_post，client_secret-basic | 否 |
API_BASE_URL | API基础URL | https://api.github.com | 没有 |
API_TIMEOUT | API请求超时（秒） | 30 | 否 |
SERVER_NAME | MCP服务器名称 | MCP-oauth服务器 | 否 |
SERVER_VERSION | 服务器版本 | 0.1.0 | 否 |
SERVER_HOST | HTTP服务器主机 | 0.0.0.0 | 否 |
SERVER_PORT | HTTP服务器端口 | 8000 | 否 |
SERVER_PATH | MCP端点路径 | /MCP | 否 |
LOG_LEVEL | 日志记录级别 | 信息 | 否 |
ENVIRONMENT | 环境名称 | 开发 | 否 |
DEBUG | 启用调试模式 | false | 否 |
授权
此服务器实现 OAuth 2.1与PKCE 并遵循MCP规范2025-06-18进行授权。
关键授权功能
- ✅ RFC 8414合规性：公开用于客户端自动发现的授权服务器元数据
- ✅ RFC 8707资源指示器：仅限于特定资源的令牌
- ✅ RFC 7636 PKCE 标准：用于增强安全性的代码交换证明密钥
- ✅ 结构化错误响应：客户端自动化OAuth元数据中的JSON-RPC错误
授权流程
当客户端在没有身份验证的情况下调用受保护的工具时，服务器会返回结构化错误响应：
{
"code": -32001,
"message": "Authentication required",
"data": {
"type": "oauth2",
"grant_type": "authorization_code",
"authorization_url": "https://github.com/login/oauth/authorize",
"token_url": "https://github.com/login/oauth/access_token",
"scopes": ["read:user"],
"code_challenge_method": "S256",
"resource": "https://api.github.com"
}
}这使MCP客户端能够自动发现OAuth端点并启动身份验证流。
获取授权元数据
服务器公开符合RFC 8414的授权元数据：
from mcp_server.config import settings
metadata = settings.get_authorization_metadata()
# Returns: issuer, authorization_endpoint, token_endpoint,
# scopes_supported, grant_types_supported, etc.面向开发者
📖 完整授权指南：参见 文档/授权_指南.md 用于：
- 详细的授权流程图
- 逐步实现OAuth
- 客户端集成示例
- 常见问题排查
- 安全最佳实践
快速链接：
安全考虑
- OAuth 2.1与PKCE：防止授权码拦截攻击（RFC 7636）
- 资源指示器（RFC 8707）：令牌仅限于特定资源，防止令牌滥用
- 授权元数据（RFC 8414）：客户端可以安全地发现OAuth端点
- 结构化错误响应：OAuth错误遵循具有机器可读元数据的MCP规范
- 没有硬编码的秘密：通过环境变量管理的所有凭据
- 非root Docker用户：容器以非特权用户身份运行
- 许可证管理：访问令牌的安全存储和自动刷新
- 最小依赖性：减少攻击面
- 仅限HTTPS：所有外部通信都使用安全协议
📖 安全最佳实践：参见 授权指南 详细的安全建议。
故障排除
OAuth身份验证问题
如果您遇到OAuth身份验证错误：
- 验证凭据：确保您的OAuth凭据在
.env是正确的 - 检查回拨URL：OAuth应用程序中的回调URL必须匹配
- 检查范围：验证是否配置了所需的OAuth作用域
- 令牌到期：代币过期；使用刷新流获取新令牌
- 授权元数据：启动时检查服务器日志中的OAuth配置
📖 详细故障排除：参见 授权指南-故障排除 用于：
- 错误代码解释
- 逐步解决指南
- 常见配置问题
- PKCE故障排除
服务器连接问题
- 端口冲突：确保没有其他服务正在使用所需的端口
- Docker问题：检查Docker日志：
docker-compose logs -f - 环境变量：验证
.env文件已正确加载
测试失败
# Run tests with verbose output
pytest -v
# Run a specific test
pytest tests/test_config.py::test_oauth_scopes_list -v
# Skip slow tests
pytest -m "not slow"贡献
我们欢迎社区的贡献！请查看我们的 贡献指南 有关以下内容的详细信息：
- 行为准则
- 开发设置和工作流程
- 代码风格和测试要求
- 拉取请求流程
- 提交消息准则
贡献者快速入门：
- 分叉存储库
- 创建要素分支：
git checkout -b feature/amazing-feature - 按照我们的要求进行更改 编码规范
- 运行测试：
./scripts/test.sh - 提交您的更改：
git commit -m 'feat: Add amazing feature' - 推到分支：
git push origin feature/amazing-feature - 打开拉取请求
有关详细指南，请阅读 贡献.md.
许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。
资源
MCP规范
OAuth资源
Python库
支持
对于问题、疑问或贡献，请：
- 打开一个问题
- 检查 用于身份验证设置
- 检查 文档 详细的实施说明
致谢
- 模型上下文协议团队为优秀的规范
- FastMCP用于高级Python实现
- Authlib提供强大的OAuth支持
- 开源社区提供灵感和最佳实践