GitHub文档MCP服务器
一个模型上下文协议（MCP）服务器，使用OpenAI GPT-4或GPT-3.5-turbo为GitHub存储库提供AI驱动的问答功能。
🤖 OpenAI集成
该服务器与OpenAI的GPT模型集成，为有关GitHub存储库的问题提供智能、上下文感知的答案。AI分析存储库文档、代码和问题，以生成全面的响应。
特性
- AI驱动的响应：使用GPT-4或GPT-3.5 turbo生成智能答案
- 上下文感知：分析存储库文档、代码片段和问题
- Markdown格式：返回格式正确、结构正确的答案
- 源链接：包括返回原始GitHub文件和问题的链接
- 后备支援：如果OpenAI API失败，则优雅地返回到模板响应
- 可配置的：支持不同的OpenAI模型和参数
设置
- 获取OpenAI API密钥
- 访问 OpenAI API - 创建新的API密钥 - 确保你有可用的学分
- 配置环境变量
# Copy the example environment file
cp .env.example .env
# Edit .env and add your keys
OPENAI_API_KEY=your_openai_api_key_here
GITHUB_TOKEN=your_github_token_here
# Optional: Configure model preferences
OPENAI_MODEL=gpt-4 # or gpt-3.5-turbo
OPENAI_MAX_TOKENS=1500
OPENAI_TEMPERATURE=0.3- 再进行
pip install -r requirements.txt- 验证安装
python validate_openai.py🚀 用法
启动服务器
python -m src.github_docs_mcp.main服务器将于启动 http://localhost:8000
检查服务状态
curl http://localhost:8000/status此端点显示包括OpenAI集成在内的所有服务的状态：
{
"server": {
"name": "github-docs-qa",
"version": "1.0.0",
"status": "running"
},
"services": {
"openai_service": {
"status": "healthy",
"model": "gpt-4",
"features": {
"ai_answers": true,
"fallback_answers": true
}
}
}
}提出问题
向发送POST请求 /ask 对于存储库问题：
curl -X POST http://localhost:8000/ask \
-H "Content-Type: application/json" \
-d '{
"repository": "microsoft/vscode",
"question": "How do I create a VS Code extension?",
"include_code": true,
"include_issues": false,
"max_results": 5
}'响应格式
AI生成Markdown格式的响应：
- 结构化答案 带有标题和部分
- 代码示例 使用适当的语法高亮显示
- 源链接 到原始GitHub文件
- 上下文信息 基于存储库内容
示例响应：
{
"question": "How do I create a VS Code extension?",
"repository": "microsoft/vscode",
"sources": [...],
"confidence": 0.85,
"processing_time_ms": 2500
}🔄 回退行为
当OpenAI API不可用或出现故障时，服务器会自动返回到基于模板的响应：
- 没有API密钥：使用具有源内容的结构化模板
- API错误：优雅地处理速率限制和其他错误
- 网络问题：继续为请求提供回退响应
🧪 测试
测试OpenAI集成：
# Run validation checks
python validate_openai.py
# Test integration with live server
python test_openai_integration.py
# Run full test suite
python test_runner.py📊 监控
通过以下方式监控OpenAI的使用情况：
- 服务状态:
/status端点显示AI服务运行状况 - 服务器日志：AI交互的详细记录
- 响应分析：检查AI与回退响应
⚙️ 配置
OpenAI模型
支持的型号：
gpt-4（推荐，质量更高）gpt-3.5-turbo（速度更快，成本更低）
参数
- 最大令牌数：控制响应长度（默认值：1500）
- 温度：控制创造力（默认值：事实回答为0.3）
- 超时：API调用超时（自动配置）
速率限制
服务器遵守OpenAI速率限制并处理：
- 速率限制错误：自动回退到模板
- 令牌限制：智能内容截断
- 成本管理：可配置的令牌限制
🔧 故障排除
常见问题
- “OpenAI服务不可用”
- 检查API密钥 .env 文件 - 验证OpenAI帐户是否有信用 - 使用OpenAI直接测试API密钥
- 反应缓慢
- 尝试 gpt-3.5-turbo 以获得更快的响应 - 减少 max_results 在请求中 - 检查网络连接
- 速率限制错误
- 升级OpenAI计划以获得更高的限额 - 如果需要，实现请求排队 - 在OpenAI仪表板中监控使用情况
调试模式
启用详细日志记录：
DEBUG=true LOG_LEVEL=debug python -m src.github_docs_mcp.main🛡️ 安全
- API密钥：从不将API密钥提交到版本控制
- 环境变量：将敏感数据存储在
.env文件 - 请求验证：所有输入都经过验证和消毒
- 错误处理：敏感信息不会在错误消息中暴露
📈 演出
典型响应时间：
- GPT-4：2-5秒
- GPT-3.5涡轮增压：1-3秒
- 后备方案：\<1秒
优化提示：
- 使用
gpt-3.5-turbo适用于速度关键型应用 - 限制
max_results减小上下文大小 - 缓存常见问题
- 监控代币使用情况以优化成本
🤝 贡献
在为OpenAI功能做出贡献时：
- 使用GPT-4和GPT-3.5涡轮进行测试
- 确保回退行为正常工作
- 添加适当的错误处理
- 更新文档和示例
- 使用各种存储库类型和问题格式进行测试
📄 许可证
MIT许可证-请参阅 许可证 了解详情。