Albin05/agenticOrch

Google ADK Agent with Enhanced GitHub MCP Server

Complete GitHub Automation Suite - A powerful agent system that combines Google ADK with a comprehensive GitHub MCP server for enterprise-level repository management, issue tracking, pull request workflows, and more.

🏗️ Architecture Overview

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]

Project Structure

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

📋 Prerequisites

1. Python 3.13+
2. UV Package Manager: Install from uv docs
3. Google ADK: Get from Google ADK
4. Google API Key: Get from Google AI Studio
5. GitHub Personal Access Token:
   • Go to https://github.com/settings/tokens
   • Click "Generate new token (classic)"
   • Select scopes: repo, read:user, read:org, delete_repo (for advanced features)
   • Copy the token

🚀 Quick Setup

Step 1: Clone and Setup Environment

# Clone the repository
git clone <your-repo-url>
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

Step 2: Configure GitHub MCP Server

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

⚠️ Important: Replace ghp_your_github_token_here with your actual GitHub Personal Access Token.

Step 3: Configure Google ADK Agent

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

⚠️ Important: Replace your_google_api_key_here with your actual Google API Key.

Step 4: Start the Complete System

# 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!

📊 Project Structure

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

👩‍💻 Usage

Running the Complete System

# 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!

Example Conversations

Repository Creation:

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!

Complex Workflow:

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!

Manual Testing

Test individual components:

# Test MCP server directly
cd gitHub-mcp-server
uv run main.py

# Test ADK agent configuration
cd ../adk_agent
adk run agent.py

🔧 Available Tools (30+)

Your enhanced GitHub MCP server provides enterprise-level automation capabilities:

🏢 Repository Management

• get_repository_info() - Get detailed repo information
• create_repository() - Create new repositories
• delete_repository() - ⚠️ CAUTION Delete repositories permanently
• update_repository_settings() - Modify description, privacy, features
• list_user_repositories() - List user's repositories
• search_repositories() - Search GitHub for repositories
• list_repository_contents() - Browse files and directories

📁 File Operations

• create_file() - Create individual files with content
• update_file() - Modify existing files
• delete_file() - Remove files from repository
• get_file_content() - Read file contents
• create_multiple_files() - Bulk upload multiple files in one commit

🐛 Issue Management

• list_repository_issues() - List issues (basic)
• list_all_repository_issues() - Enhanced with detailed metadata
• create_repository_issue() - Create new issues
• update_issue() - New - Update title, description, labels, assignees
• add_issue_comment() - New - Add comments to issues

🔄 Pull Request Workflows

• list_pull_requests() - New - List PRs with comprehensive details
• create_pull_request() - New - Create pull requests
• get_pull_request_details() - New - Get detailed PR information
• merge_pull_request() - New - Merge pull requests
• close_pull_request() - New - Close PRs without merging

🌿 Branch Management

• list_branches() - New - List all repository branches
• create_branch() - New - Create branches from existing ones
• delete_branch() - New - Delete branches
• get_branch_info() - New - Get detailed branch information
• protect_branch() - New - Enable branch protection rules
• unprotect_branch() - New - Remove branch protection

🏷️ Organization Tools

• list_labels() - New - List repository labels
• create_label() - New - Create custom labels with colors
• delete_label() - New - Remove labels
• update_label() - New - Modify existing labels
• list_milestones() - New - List project milestones
• create_milestone() - New - Create milestones with due dates
• delete_milestone() - New - Remove milestones

How It Works

1. Agent Initialization

The agent initializes with Google's Gemini model and prepares to connect to the MCP server.

2. MCP Server Connection

The agent spawns the GitHub MCP server as a subprocess and establishes a bidirectional communication channel using stdio.

3. Tool Discovery

The agent queries the MCP server for available tools and converts them to Google GenAI function declarations.

4. Query Processing

When you give the agent a query:

1. The agent sends the query to Gemini with available tools
2. Gemini analyzes the query and decides which tools to call
3. The agent executes tool calls via the MCP server
4. Tool results are sent back to Gemini
5. Gemini synthesizes a final response

5. Iterative Refinement

The agent can make multiple tool calls in sequence to answer complex queries.

Customizing the MCP Server

Adding New Tools

To add a new tool to the MCP server:

1. Add tool definition in 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"]
    }
)

2. Implement tool handler in 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))]

Advanced Configuration

Adjusting Agent Behavior

In google_adk_agent.py, you can modify:

# 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
    )
)

Error Handling

The MCP server includes error handling for:

• HTTP errors from GitHub API
• Missing authentication
• Invalid parameters
• Rate limiting

🐛 Troubleshooting

Common Issues and Solutions

❌ Issue: GITHUB_TOKEN environment variable is required ✅ Solution: Ensure your .env file in gitHub-mcp-server/ contains a valid GitHub token.

❌ Issue: Connection closed in ADK web interface ✅ Solution: Check if the MCP server starts correctly: cd gitHub-mcp-server && uv run main.py

❌ Issue: GitHub API error: 401 Unauthorized ✅ Solution: Verify your GitHub token is valid and has correct scopes at https://github.com/settings/tokens

❌ Issue: ModuleNotFoundError: No module named 'google.adk' ✅ Solution: Install Google ADK: pip install google-adk

❌ Issue: MCP tools not showing in agent ✅ Solution: Restart both MCP server and ADK web interface. Check that paths in agent.py are correct.

Debug Mode

Enable debug logging in your agent:

# Set environment variable for verbose logging
export ADK_LOG_LEVEL=DEBUG

# Run with debug output
adk web --debug

Testing Individual Tools

Test the MCP server tools directly:

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

💬 Example Conversations

Here are real conversation examples you can try with your agent:

Repository Management

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'

Complex Workflows

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

Issue Management

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...

Repository Analysis

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...

🚀 Deployment

Production Considerations

1. Security: Use environment-specific tokens and API keys
2. Monitoring: Add logging and error tracking
3. Rate Limiting: Implement GitHub API rate limit handling
4. Scaling: Consider concurrent request limits

Docker Deployment

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

🎯 Next Steps

1. 🔌 Multi-MCP Integration: Add more MCP servers (Jira, Slack, Linear)
2. 🤖 Advanced Workflows: Build complex automation scenarios
3. 📊 Analytics: Add repository metrics and reporting
4. 🔔 Notifications: Integrate with team communication tools
5. 🌐 API Gateway: Expose agent capabilities via REST API

📚 Additional Resources

• Google ADK Documentation
• MCP Protocol Specification
• GitHub REST API Documentation
• UV Package Manager Guide

📝 License

This project is for demonstration and educational purposes. Adapt as needed for your production use case.

🎉 Ready to automate your GitHub workflows? Start with adk web and begin conversing with your personal GitHub automation agent!