带有增强型GitHub MCP服务器的Google ADK代理
完整的GitHub自动化套件 -一个强大的代理系统，将Google ADK与全面的GitHub MCP服务器相结合，用于企业级存储库管理、问题跟踪、拉取请求工作流等。
🏗️ 架构概述
graph TB
U[User Query] --> A[Google ADK Agent]
A --> M[GitHub MCP Server]
M --> G[GitHub API]
A -.-> |"🔧 30+ Tools Available"| T[Tool Categories]
T --> R[Repository Management]
T --> I[Issue Tracking]
T --> P[Pull Requests]
T --> B[Branch Management]
T --> L[Labels & Milestones]
T --> F[File Operations]项目结构
agenticOrch/
├── adk_agent/
│ ├── agent.py # Google ADK Agent Configuration
│ ├── .env # ADK Environment Variables
│ └── __init__.py
├── gitHub-mcp-server/
│ ├── main.py # Complete GitHub MCP Server
│ ├── .env # GitHub Token Configuration
│ ├── pyproject.toml # Dependencies
│ └── uv.lock # Dependency Lock File
└── README.md # This comprehensive guide📋 先决条件
- 首选https://github.com/settings/tokens - 点击“生成新令牌（经典）” - 选择范围： repo, read:user, read:org, delete_repo （用于高级功能） - 复制令牌
🚀 快速设置
步骤1：克隆和设置环境
# Clone the repository
git clone
cd agenticOrch
# Install UV package manager (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install Google ADK
pip install google-adk步骤2：配置GitHub MCP服务器
cd gitHub-mcp-server
# Install dependencies using UV
uv sync
# Create environment file with your GitHub token
echo "GITHUB_TOKEN=ghp_your_github_token_here" > .env
# Test the MCP server (should start without errors)
uv run main.py⚠️ 重要：替换 ghp_your_github_token_here 使用您实际的GitHub个人访问令牌。
步骤3：配置Google ADK代理
cd ../adk_agent
# Create environment file with Google API key
cat > .env << EOF
GOOGLE_GENAI_USE_VERTEXAI=0
GOOGLE_API_KEY=your_google_api_key_here
EOF
# Install additional dependencies (if needed)
pip install python-dotenv pathlib⚠️ 重要：替换 your_google_api_key_here 使用您的实际Google API密钥。
步骤4：启动整个系统
# From the agenticOrch directory, start ADK web interface
adk web
# Open browser to: http://127.0.0.1:8000
# Select 'adk_agent' from the available apps
# Start conversing with your GitHub automation agent!📊 项目结构
agenticOrch/
├── adk_agent/
│ ├── agent.py # Google ADK Agent Configuration
│ ├── .env # ADK Environment Variables (Google API Key)
│ └── __init__.py
├── gitHub-mcp-server/
│ ├── main.py # Complete GitHub MCP Server (30+ tools)
│ ├── .env # GitHub Personal Access Token
│ ├── pyproject.toml # UV Dependencies (PyGithub, MCP)
│ └── uv.lock # Dependency Lock File
└── README.md # This comprehensive guide👩💻 用法
运行完整系统
# Navigate to your project directory
cd agenticOrch
# Start the ADK web interface
adk web
# Open browser to: http://127.0.0.1:8000
# Select 'adk_agent' from available applications
# Begin chatting with your GitHub automation agent!对话示例
存储库创建：
You: "Create a new repository called 'my-ai-project' with description 'Testing automation'"
Agent: I'll create that repository for you.
[Uses create_repository tool]
✅ Created repository 'username/my-ai-project' successfully!复杂的工作流程：
You: "Create a feature branch, add a README.md file, then create a PR"
Agent: I'll set up the complete workflow for you.
[Uses create_branch, create_file, create_pull_request tools]
✅ Feature branch created, README added, PR #15 opened for review!手动测试
测试单个组件：
# Test MCP server directly
cd gitHub-mcp-server
uv run main.py
# Test ADK agent configuration
cd ../adk_agent
adk run agent.py🔧 可用工具（30+）
您增强的GitHub MCP服务器提供企业级自动化功能：
🏢 库管理
get_repository_info()-获取详细的回购信息create_repository()-创建新存储库delete_repository()- ⚠️ 小心 永久删除存储库update_repository_settings()-修改描述、隐私、功能list_user_repositories()-列出用户的存储库search_repositories()-在GitHub上搜索存储库list_repository_contents()-浏览文件和目录
📁 文件操作
create_file()-创建包含内容的单个文件update_file()-修改现有文件delete_file()-从存储库中删除文件get_file_content()-读取文件内容create_multiple_files()-在一次提交中批量上传多个文件
🐛 问题管理
list_repository_issues()-列出问题（基本）list_all_repository_issues()- 增强 包含详细的元数据create_repository_issue()-创建新问题update_issue()- 新 -更新标题、描述、标签、受让人add_issue_comment()- 新 -为问题添加评论
🔄 Pull请求工作流
list_pull_requests()- 新 -列出PR的详细信息create_pull_request()- 新 -创建拉取请求get_pull_request_details()- 新 -获取详细的公关信息merge_pull_request()- 新 -合并拉取请求close_pull_request()- 新 -关闭PR而不合并
🌿 分行管理
list_branches()- 新 -列出所有存储库分支create_branch()- 新 -从现有分支创建分支delete_branch()- 新 -删除分支get_branch_info()- 新 -获取详细的分行信息protect_branch()- 新 -启用分支保护规则unprotect_branch()- 新 -移除分支保护
🏷️ 组织工具
list_labels()- 新 -列出存储库标签create_label()- 新 -使用颜色创建自定义标签delete_label()- 新 -删除标签update_label()- 新 -修改现有标签list_milestones()- 新 -列出项目里程碑create_milestone()- 新 -创建具有截止日期的里程碑delete_milestone()- 新 -删除里程碑
运作原理
1.代理初始化
代理使用谷歌的Gemini模型进行初始化，并准备连接到MCP服务器。
2.MCP服务器连接
代理将GitHub MCP服务器作为子进程生成，并使用stdio建立双向通信通道。
3.工具发现
代理向MCP服务器查询可用工具，并将其转换为Google GenAI函数声明。
4.查询处理
当您向代理发出查询时：
- 代理使用可用工具将查询发送到Gemini
- Gemini分析查询并决定调用哪些工具
- 代理通过MCP服务器执行工具调用
- 工具结果被发送回Gemini
- 双子座综合了最终的反应
5.迭代细化
代理可以按顺序进行多个工具调用，以回答复杂的查询。
自定义MCP服务器
添加新工具
要向MCP服务器添加新工具，请执行以下操作：
- 添加工具定义 在
list_tools():
Tool(
name="get_commits",
description="Get recent commits from a repository",
inputSchema={
"type": "object",
"properties": {
"owner": {"type": "string", "description": "Repository owner"},
"repo": {"type": "string", "description": "Repository name"},
"limit": {"type": "integer", "description": "Number of commits", "default": 10}
},
"required": ["owner", "repo"]
}
)- 机具处理程序 在
call_tool():
elif name == "get_commits":
owner = arguments["owner"]
repo = arguments["repo"]
limit = arguments.get("limit", 10)
url = f"{GITHUB_API_BASE}/repos/{owner}/{repo}/commits"
params = {"per_page": limit}
response = await client.get(url, headers=headers, params=params)
response.raise_for_status()
commits = response.json()
result = [{
"sha": commit["sha"][:7],
"message": commit["commit"]["message"],
"author": commit["commit"]["author"]["name"],
"date": commit["commit"]["author"]["date"]
} for commit in commits]
return [TextContent(type="text", text=json.dumps(result, indent=2))]高级配置
调整代理行为
在 google_adk_agent.py，您可以修改：
# Change the model
agent = GitHubMCPAgent(
api_key=api_key,
model_name="gemini-2.0-flash-exp" # or "gemini-1.5-pro", etc.
)
# Adjust max iterations
result = await agent.run_agent(query, max_iterations=10)
# Modify temperature for more/less creative responses
response = self.client.models.generate_content(
model=self.model_name,
contents=conversation,
config=types.GenerateContentConfig(
tools=[tool_config],
temperature=0.7 # 0.0 = deterministic, 1.0 = creative
)
)错误处理
MCP服务器包括以下错误处理：
- 来自GitHub API的HTTP错误
- 缺少身份验证
- 无效参数
- 速率限制
🐛 故障排除
常见问题及解决方法
❌ 问题: GITHUB_TOKEN environment variable is required ✅ 解决方案：确保您的 .env 文件在 gitHub-mcp-server/ 包含有效的GitHub令牌。
❌ 问题: Connection closed 在ADK web界面中 ✅ 解决方案：检查MCP服务器是否正确启动： cd gitHub-mcp-server && uv run main.py
❌ 问题: GitHub API error: 401 Unauthorized ✅ 解决方案：验证您的GitHub令牌是否有效，并且在以下位置具有正确的作用域https://github.com/settings/tokens
❌ 问题: ModuleNotFoundError: No module named 'google.adk' ✅ 解决方案：安装谷歌ADK： pip install google-adk
❌ 问题：代理中未显示MCP工具 ✅ 解决方案：重新启动MCP服务器和ADK web界面。检查路径 agent.py 是正确的。
调试模式
在代理中启用调试日志记录：
# Set environment variable for verbose logging
export ADK_LOG_LEVEL=DEBUG
# Run with debug output
adk web --debug测试单个工具
直接测试MCP服务器工具：
cd gitHub-mcp-server
# Test server connection
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' | uv run main.py
# Check available tools
echo '{"jsonrpc": "2.0", "method": "tools/list", "params": {}, "id": 2}' | uv run main.py💬 对话示例
以下是你可以与你的经纪人尝试的真实对话示例：
库管理
You: "Create a new private repository called 'ai-experiments' with description 'Testing AI automation tools'"
Agent: I'll create a private repository for your AI experiments.
[Creates repository using create_repository tool]
✅ Successfully created private repository 'username/ai-experiments'复杂的工作流程
You: "Create a feature branch called 'user-authentication', add a login.py file with basic auth code, then create a PR to main branch"
Agent: I'll help you set up a complete feature branch workflow.
[Creates branch, adds file, creates PR using multiple tools]
✅ Feature branch created, code added, PR #123 opened and ready for review问题管理
You: "List all open issues in microsoft/vscode that have the 'bug' label, then create a summary"
Agent: Let me fetch the bug reports from VS Code repository.
[Lists and analyzes issues]
📊 Found 45 open bug issues. Common themes: editor performance, extension compatibility...存储库分析
You: "Search for popular React testing libraries, get info on the top 3, and compare their features"
Agent: I'll research React testing libraries for you.
[Searches repositories, analyzes top results]
📈 Compared Jest, React Testing Library, and Enzyme. Here's what I found...🚀 部署
生产注意事项
- 安全：使用特定于环境的令牌和API密钥
- 监控：添加日志记录和错误跟踪
- 速率限制：实现GitHub API速率限制处理
- 扩展：考虑并发请求限制
Docker部署
FROM python:3.13-slim
WORKDIR /app
COPY . .
# Install UV and dependencies
RUN pip install uv google-adk
RUN cd gitHub-mcp-server && uv sync
# Set environment variables
ENV GITHUB_TOKEN=""
ENV GOOGLE_API_KEY=""
# Expose ADK web port
EXPOSE 8000
CMD ["adk", "web", "--host", "0.0.0.0"]🎯 后续步骤
- 🔌 多MCP集成：添加更多MCP服务器（Jira、Slack、Linear）
- 🤖 高级工作流：构建复杂的自动化场景
- 📊 分析：添加存储库指标和报告
- 🔔 通知：与团队沟通工具集成
- 🌐 API网关：通过REST API展示代理功能
📚 其他资源
📝 许可证
该项目用于示范和教育目的。根据生产用例的需要进行调整。
______________________________________________________________________
🎉 准备好自动化你的GitHub工作流程了吗？ 从开始 adk web 并开始与您的个人GitHub自动化代理对话！