GitHub Docs MCP Server

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模型和参数

设置

1. 获取OpenAI API密钥

- 访问 OpenAI API - 创建新的API密钥 - 确保你有可用的学分

1. 配置环境变量

   # 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

1. 再进行

   pip install -r requirements.txt

1. 验证安装

   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速率限制并处理：

• 速率限制错误：自动回退到模板
• 令牌限制：智能内容截断
• 成本管理：可配置的令牌限制

🔧 故障排除

常见问题

1. “OpenAI服务不可用”

- 检查API密钥 .env 文件 - 验证OpenAI帐户是否有信用 - 使用OpenAI直接测试API密钥

1. 反应缓慢

- 尝试 gpt-3.5-turbo 以获得更快的响应 - 减少 max_results 在请求中 - 检查网络连接

1. 速率限制错误

- 升级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功能做出贡献时：

1. 使用GPT-4和GPT-3.5涡轮进行测试
2. 确保回退行为正常工作
3. 添加适当的错误处理
4. 更新文档和示例
5. 使用各种存储库类型和问题格式进行测试

📄 许可证

MIT许可证-请参阅 许可证 了解详情。