Agentic Orch

带有增强型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

📋 先决条件

1. Python 3.13+
2. UV包装管理器：从安装 紫外线文件
3. 谷歌ADK：从 谷歌ADK
4. Google API密钥：从 谷歌人工智能工作室
5. GitHub个人访问令牌:

- 首选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.查询处理

当您向代理发出查询时：

1. 代理使用可用工具将查询发送到Gemini
2. Gemini分析查询并决定调用哪些工具
3. 代理通过MCP服务器执行工具调用
4. 工具结果被发送回Gemini
5. 双子座综合了最终的反应

5.迭代细化

代理可以按顺序进行多个工具调用，以回答复杂的查询。

自定义MCP服务器

添加新工具

要向MCP服务器添加新工具，请执行以下操作：

1. 添加工具定义 在 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"]
    }
)

1. 机具处理程序 在 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...

🚀 部署

生产注意事项

1. 安全：使用特定于环境的令牌和API密钥
2. 监控：添加日志记录和错误跟踪
3. 速率限制：实现GitHub API速率限制处理
4. 扩展：考虑并发请求限制

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"]

🎯 后续步骤

1. 🔌 多MCP集成：添加更多MCP服务器（Jira、Slack、Linear）
2. 🤖 高级工作流：构建复杂的自动化场景
3. 📊 分析：添加存储库指标和报告
4. 🔔 通知：与团队沟通工具集成
5. 🌐 API网关：通过REST API展示代理功能

📚 其他资源

• 谷歌ADK文档
• MCP协议规范
• UV包装管理器指南

📝 许可证

该项目用于示范和教育目的。根据生产用例的需要进行调整。

______________________________________________________________________

🎉 准备好自动化你的GitHub工作流程了吗？ 从开始 adk web 并开始与您的个人GitHub自动化代理对话！