github-agent 0.8.0

GitHub Agent for MCP

GitHub Agent - A2A | AG-UI | MCP

Version: 0.8.0

Overview

GitHub Agent is a powerful Model Context Protocol (MCP) server and Agent-to-Agent (A2A) system designed to interact with GitHub.

It acts as a Supervisor Agent, delegating tasks to a suite of specialized Child Agents, each focused on a specific domain of the GitHub API (e.g., Issues, Pull Requests, Repositories, Actions). This architecture allows for precise and efficient handling of complex GitHub operations.

This repository is actively maintained - Contributions are welcome!

Capabilities:

• Supervisor-Worker Architecture: Orchestrates specialized agents for optimal task execution.
• Comprehensive GitHub Coverage: specialized agents for Issues, PRs, Repos, Actions, Organizations, and more.
• MCP Support: Fully compatible with the Model Context Protocol.
• A2A Integration: Ready for Agent-to-Agent communication.
• Flexible Deployment: Run via Docker, Docker Compose, or locally.

Architecture

System components

---
config:
  layout: dagre
---
flowchart TB
 subgraph subGraph0["Agent Capabilities"]
        Supervisor["Supervisor Agent"]
        Server["A2A Server - Uvicorn/FastAPI"]
        ChildAgents["Child Agents (Specialists)"]
        MCP["GitHub MCP Tools"]
  end
    Supervisor --> ChildAgents
    ChildAgents --> MCP
    User["User Query"] --> Server
    Server --> Supervisor
    MCP --> GitHubAPI["GitHub API"]

     Supervisor:::agent
     ChildAgents:::agent
     Server:::server
     User:::server
    classDef server fill:#f9f,stroke:#333
    classDef agent fill:#bbf,stroke:#333,stroke-width:2px
    style Server stroke:#000000,fill:#FFD600
    style MCP stroke:#000000,fill:#BBDEFB
    style GitHubAPI fill:#E6E6FA
    style User fill:#C8E6C9
    style subGraph0 fill:#FFF9C4

Component Interaction

sequenceDiagram
    participant User
    participant Server as A2A Server
    participant Supervisor as Supervisor Agent
    participant Child as Child Agent (e.g. Issues)
    participant MCP as GitHub MCP Tools
    participant GitHub as GitHub API

    User->>Server: "Create an issue in repo X"
    Server->>Supervisor: Invoke Supervisor
    Supervisor->>Supervisor: Analyze Request & Select Specialist
    Supervisor->>Child: Delegate to Issues Agent
    Child->>MCP: Call create_issue Tool
    MCP->>GitHub: POST /repos/user/repo/issues
    GitHub-->>MCP: Issue Created JSON
    MCP-->>Child: Tool Response
    Child-->>Supervisor: Task Complete
    Supervisor-->>Server: Final Response
    Server-->>User: "Issue #123 created successfully"

Specialized Agents

The Supervisor delegates tasks to these specialized agents:

Agent Name	Description
GitHub_Context_Agent	Provides context about the current user and GitHub status.
GitHub_Actions_Agent	Manages GitHub Actions workflows and runs.
GitHub_Code_Security_Agent	Handles code security scanning and alerts.
GitHub_Dependabot_Agent	Manages Dependabot alerts and configurations.
GitHub_Discussions_Agent	Manages repository discussions.
GitHub_Gists_Agent	Manages GitHub Gists.
GitHub_Git_Agent	Performs low-level Git operations (refs, trees, blobs).
GitHub_Issues_Agent	Manages Issues (create, list, update, comment).
GitHub_Labels_Agent	Manages repository labels.
GitHub_Notifications_Agent	Checks and manages notifications.
GitHub_Organizations_Agent	Manages Organization memberships and settings.
GitHub_Projects_Agent	Manages GitHub Projects (V2).
GitHub_Pull_Requests_Agent	Manages Pull Requests (create, review, merge).
GitHub_Repos_Agent	Manages Repositories (create, list, delete, settings).
GitHub_Secret_Protection_Agent	Manages secret scanning protection.
GitHub_Security_Advisories_Agent	Accesses security advisories.
GitHub_Stargazers_Agent	Views repository stargazers.
GitHub_Users_Agent	Accesses public user information.
GitHub_Copilot_Agent	Assists with coding tasks via Copilot.
GitHub_Support_Docs_Agent	Searches GitHub Support documentation.

Usage

Prerequisites

• Python 3.10+
• A valid GitHub Personal Access Token (PAT) with appropriate permissions.

Installation

pip install github-agent

Or using UV:

uv pip install github-agent

CLI

The github-agent command starts the server.

Argument	Description	Default
--host	Host to bind the server to	0.0.0.0
--port	Port to bind the server to	9000
--mcp-config	Path to MCP configuration file	mcp_config.json
--provider	LLM Provider (openai, anthropic, google, etc.)	openai
--model-id	LLM Model ID	nvidia/nemotron-3-super

Running the Agent Server

github-agent --provider openai --model-id gpt-4o --api-key sk-...

Docker

Build

docker build -t github-agent .

Run using Docker

docker run -d \
  -p 9000:9000 \
  -e LLM_API_KEY=sk-... \
  -e MCP_CONFIG=/app/mcp_config.json \
  knucklessg1/github-agent:latest

Run using Docker Compose

Create a docker-compose.yml:

services:
  github-agent:
    image: knucklessg1/github-agent:latest
    ports:
      - "9000:9000"
    environment:
      - PROVIDER=openai
      - MODEL_ID=gpt-4o
      - LLM_API_KEY=${LLM_API_KEY}
    volumes:
      - ./mcp_config.json:/app/mcp_config.json

Then run:

docker-compose up -d

Repository Owners

MCP Configuration Examples

1. Standard IO (stdio) Deployment

{
  "mcpServers": {
    "github-agent": {
      "command": "uv",
      "args": [
        "run",
        "github-mcp"
      ],
      "env": {
        "AGENT_DESCRIPTION": "<YOUR_AGENT_DESCRIPTION>",
        "AGENT_SYSTEM_PROMPT": "<YOUR_AGENT_SYSTEM_PROMPT>",
        "CONTENTSTOOL": "True",
        "DEFAULT_AGENT_NAME": "<YOUR_DEFAULT_AGENT_NAME>",
        "GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>",
        "GITHUB_URL": "<YOUR_GITHUB_URL>",
        "GITHUB_VERIFY": "<YOUR_GITHUB_VERIFY>",
        "ISSUETOOL": "True",
        "PULLSTOOL": "True",
        "REPOSTOOL": "True"
      }
    }
  }
}

2. Streamable HTTP (SSE) Deployment

{
  "mcpServers": {
    "github-agent": {
      "command": "uv",
      "args": [
        "run",
        "github-mcp",
        "--transport",
        "http",
        "--host",
        "0.0.0.0",
        "--port",
        "8000"
      ],
      "env": {
        "AGENT_DESCRIPTION": "<YOUR_AGENT_DESCRIPTION>",
        "AGENT_SYSTEM_PROMPT": "<YOUR_AGENT_SYSTEM_PROMPT>",
        "CONTENTSTOOL": "True",
        "DEFAULT_AGENT_NAME": "<YOUR_DEFAULT_AGENT_NAME>",
        "GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>",
        "GITHUB_URL": "<YOUR_GITHUB_URL>",
        "GITHUB_VERIFY": "<YOUR_GITHUB_VERIFY>",
        "ISSUETOOL": "True",
        "PULLSTOOL": "True",
        "REPOSTOOL": "True"
      }
    }
  }
}