github-agent 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Knuckles Team
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,229 @@
1
+ Metadata-Version: 2.4
2
+ Name: github-agent
3
+ Version: 0.1.1
4
+ Summary: GitHub Agent for MCP
5
+ Author-email: Audel Rouhi <knucklessg1@gmail.com>
6
+ License: MIT
7
+ Classifier: Development Status :: 5 - Production/Stable
8
+ Classifier: License :: Public Domain
9
+ Classifier: Environment :: Console
10
+ Classifier: Operating System :: POSIX :: Linux
11
+ Classifier: Programming Language :: Python :: 3
12
+ Requires-Python: >=3.10
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Requires-Dist: pydantic-ai-slim[a2a,ag-ui,anthropic,fastmcp,google,huggingface,openai,web]>=1.32.0
16
+ Requires-Dist: pydantic-ai-skills
17
+ Requires-Dist: fastapi>=0.128.0
18
+ Requires-Dist: fastmcp
19
+ Requires-Dist: uvicorn
20
+ Requires-Dist: fastapi
21
+ Dynamic: license-file
22
+
23
+ # GitHub Agent - A2A | AG-UI | MCP
24
+
25
+ ![PyPI - Version](https://img.shields.io/pypi/v/github-agent)
26
+ ![MCP Server](https://badge.mcpx.dev?type=server 'MCP Server')
27
+ ![PyPI - Downloads](https://img.shields.io/pypi/dd/github-agent)
28
+ ![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/github-agent)
29
+ ![GitHub forks](https://img.shields.io/github/forks/Knuckles-Team/github-agent)
30
+ ![GitHub contributors](https://img.shields.io/github/contributors/Knuckles-Team/github-agent)
31
+ ![PyPI - License](https://img.shields.io/pypi/l/github-agent)
32
+ ![GitHub](https://img.shields.io/github/license/Knuckles-Team/github-agent)
33
+
34
+ ![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/github-agent)
35
+ ![GitHub pull requests](https://img.shields.io/github/issues-pr/Knuckles-Team/github-agent)
36
+ ![GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed/Knuckles-Team/github-agent)
37
+ ![GitHub issues](https://img.shields.io/github/issues/Knuckles-Team/github-agent)
38
+
39
+ ![GitHub top language](https://img.shields.io/github/languages/top/Knuckles-Team/github-agent)
40
+ ![GitHub language count](https://img.shields.io/github/languages/count/Knuckles-Team/github-agent)
41
+ ![GitHub repo size](https://img.shields.io/github/repo-size/Knuckles-Team/github-agent)
42
+ ![GitHub repo file count (file type)](https://img.shields.io/github/directory-file-count/Knuckles-Team/github-agent)
43
+ ![PyPI - Wheel](https://img.shields.io/pypi/wheel/github-agent)
44
+ ![PyPI - Implementation](https://img.shields.io/pypi/implementation/github-agent)
45
+
46
+ *Version: 0.1.1*
47
+
48
+ ## Overview
49
+
50
+ **GitHub Agent** is a powerful **Model Context Protocol (MCP)** server and **Agent-to-Agent (A2A)** system designed to interact with GitHub.
51
+
52
+ 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.
53
+
54
+ This repository is actively maintained - Contributions are welcome!
55
+
56
+ ### Capabilities:
57
+ - **Supervisor-Worker Architecture**: Orchestrates specialized agents for optimal task execution.
58
+ - **Comprehensive GitHub Coverage**: specialized agents for Issues, PRs, Repos, Actions, Organizations, and more.
59
+ - **MCP Support**: Fully compatible with the Model Context Protocol.
60
+ - **A2A Integration**: Ready for Agent-to-Agent communication.
61
+ - **Flexible Deployment**: Run via Docker, Docker Compose, or locally.
62
+
63
+ ## Architecture
64
+
65
+ ### System components
66
+
67
+ ```mermaid
68
+ ---
69
+ config:
70
+ layout: dagre
71
+ ---
72
+ flowchart TB
73
+ subgraph subGraph0["Agent Capabilities"]
74
+ Supervisor["Supervisor Agent"]
75
+ Server["A2A Server - Uvicorn/FastAPI"]
76
+ ChildAgents["Child Agents (Specialists)"]
77
+ MCP["GitHub MCP Tools"]
78
+ end
79
+ Supervisor --> ChildAgents
80
+ ChildAgents --> MCP
81
+ User["User Query"] --> Server
82
+ Server --> Supervisor
83
+ MCP --> GitHubAPI["GitHub API"]
84
+
85
+ Supervisor:::agent
86
+ ChildAgents:::agent
87
+ Server:::server
88
+ User:::server
89
+ classDef server fill:#f9f,stroke:#333
90
+ classDef agent fill:#bbf,stroke:#333,stroke-width:2px
91
+ style Server stroke:#000000,fill:#FFD600
92
+ style MCP stroke:#000000,fill:#BBDEFB
93
+ style GitHubAPI fill:#E6E6FA
94
+ style User fill:#C8E6C9
95
+ style subGraph0 fill:#FFF9C4
96
+ ```
97
+
98
+ ### Component Interaction
99
+
100
+ ```mermaid
101
+ sequenceDiagram
102
+ participant User
103
+ participant Server as A2A Server
104
+ participant Supervisor as Supervisor Agent
105
+ participant Child as Child Agent (e.g. Issues)
106
+ participant MCP as GitHub MCP Tools
107
+ participant GitHub as GitHub API
108
+
109
+ User->>Server: "Create an issue in repo X"
110
+ Server->>Supervisor: Invoke Supervisor
111
+ Supervisor->>Supervisor: Analyze Request & Select Specialist
112
+ Supervisor->>Child: Delegate to Issues Agent
113
+ Child->>MCP: Call create_issue Tool
114
+ MCP->>GitHub: POST /repos/user/repo/issues
115
+ GitHub-->>MCP: Issue Created JSON
116
+ MCP-->>Child: Tool Response
117
+ Child-->>Supervisor: Task Complete
118
+ Supervisor-->>Server: Final Response
119
+ Server-->>User: "Issue #123 created successfully"
120
+ ```
121
+
122
+ ## Specialized Agents
123
+
124
+ The Supervisor delegates tasks to these specialized agents:
125
+
126
+ | Agent Name | Description |
127
+ |:-----------|:------------|
128
+ | `GitHub_Context_Agent` | Provides context about the current user and GitHub status. |
129
+ | `GitHub_Actions_Agent` | Manages GitHub Actions workflows and runs. |
130
+ | `GitHub_Code_Security_Agent` | Handles code security scanning and alerts. |
131
+ | `GitHub_Dependabot_Agent` | Manages Dependabot alerts and configurations. |
132
+ | `GitHub_Discussions_Agent` | Manages repository discussions. |
133
+ | `GitHub_Gists_Agent` | Manages GitHub Gists. |
134
+ | `GitHub_Git_Agent` | Performs low-level Git operations (refs, trees, blobs). |
135
+ | `GitHub_Issues_Agent` | Manages Issues (create, list, update, comment). |
136
+ | `GitHub_Labels_Agent` | Manages repository labels. |
137
+ | `GitHub_Notifications_Agent` | Checks and manages notifications. |
138
+ | `GitHub_Organizations_Agent` | Manages Organization memberships and settings. |
139
+ | `GitHub_Projects_Agent` | Manages GitHub Projects (V2). |
140
+ | `GitHub_Pull_Requests_Agent` | Manages Pull Requests (create, review, merge). |
141
+ | `GitHub_Repos_Agent` | Manages Repositories (create, list, delete, settings). |
142
+ | `GitHub_Secret_Protection_Agent` | Manages secret scanning protection. |
143
+ | `GitHub_Security_Advisories_Agent` | Accesses security advisories. |
144
+ | `GitHub_Stargazers_Agent` | Views repository stargazers. |
145
+ | `GitHub_Users_Agent` | Accesses public user information. |
146
+ | `GitHub_Copilot_Agent` | Assists with coding tasks via Copilot. |
147
+ | `GitHub_Support_Docs_Agent` | Searches GitHub Support documentation. |
148
+
149
+ ## Usage
150
+
151
+ ### Prerequisites
152
+ - Python 3.10+
153
+ - A valid GitHub Personal Access Token (PAT) with appropriate permissions.
154
+
155
+ ### Installation
156
+
157
+ ```bash
158
+ pip install github-agent
159
+ ```
160
+ Or using UV:
161
+ ```bash
162
+ uv pip install github-agent
163
+ ```
164
+
165
+ ### CLI
166
+
167
+ The `github-agent` command starts the server.
168
+
169
+ | Argument | Description | Default |
170
+ |:---|:---|:---|
171
+ | `--host` | Host to bind the server to | `0.0.0.0` |
172
+ | `--port` | Port to bind the server to | `9000` |
173
+ | `--mcp-config` | Path to MCP configuration file | `mcp_config.json` |
174
+ | `--provider` | LLM Provider (openai, anthropic, google, etc.) | `openai` |
175
+ | `--model-id` | LLM Model ID | `qwen/qwen3-4b-2507` |
176
+
177
+ ### Running the Agent Server
178
+
179
+ ```bash
180
+ github-agent --provider openai --model-id gpt-4o --api-key sk-...
181
+ ```
182
+
183
+ ## Docker
184
+
185
+ ### Build
186
+
187
+ ```bash
188
+ docker build -t github-agent .
189
+ ```
190
+
191
+ ### Run using Docker
192
+
193
+ ```bash
194
+ docker run -d \
195
+ -p 9000:9000 \
196
+ -e OPENAI_API_KEY=sk-... \
197
+ -e MCP_CONFIG=/app/mcp_config.json \
198
+ knucklessg1/github-agent:latest
199
+ ```
200
+
201
+ ### Run using Docker Compose
202
+
203
+ Create a `docker-compose.yml`:
204
+
205
+ ```yaml
206
+ services:
207
+ github-agent:
208
+ image: knucklessg1/github-agent:latest
209
+ ports:
210
+ - "9000:9000"
211
+ environment:
212
+ - PROVIDER=openai
213
+ - MODEL_ID=gpt-4o
214
+ - OPENAI_API_KEY=${OPENAI_API_KEY}
215
+ volumes:
216
+ - ./mcp_config.json:/app/mcp_config.json
217
+ ```
218
+
219
+ Then run:
220
+ ```bash
221
+ docker-compose up -d
222
+ ```
223
+
224
+ ## Repository Owners
225
+
226
+ <img width="100%" height="180em" src="https://github-readme-stats.vercel.app/api?username=Knucklessg1&show_icons=true&hide_border=true&&count_private=true&include_all_commits=true" />
227
+
228
+ ![GitHub followers](https://img.shields.io/github/followers/Knucklessg1)
229
+ ![GitHub User's stars](https://img.shields.io/github/stars/Knucklessg1)
@@ -0,0 +1,207 @@
1
+ # GitHub Agent - A2A | AG-UI | MCP
2
+
3
+ ![PyPI - Version](https://img.shields.io/pypi/v/github-agent)
4
+ ![MCP Server](https://badge.mcpx.dev?type=server 'MCP Server')
5
+ ![PyPI - Downloads](https://img.shields.io/pypi/dd/github-agent)
6
+ ![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/github-agent)
7
+ ![GitHub forks](https://img.shields.io/github/forks/Knuckles-Team/github-agent)
8
+ ![GitHub contributors](https://img.shields.io/github/contributors/Knuckles-Team/github-agent)
9
+ ![PyPI - License](https://img.shields.io/pypi/l/github-agent)
10
+ ![GitHub](https://img.shields.io/github/license/Knuckles-Team/github-agent)
11
+
12
+ ![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/github-agent)
13
+ ![GitHub pull requests](https://img.shields.io/github/issues-pr/Knuckles-Team/github-agent)
14
+ ![GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed/Knuckles-Team/github-agent)
15
+ ![GitHub issues](https://img.shields.io/github/issues/Knuckles-Team/github-agent)
16
+
17
+ ![GitHub top language](https://img.shields.io/github/languages/top/Knuckles-Team/github-agent)
18
+ ![GitHub language count](https://img.shields.io/github/languages/count/Knuckles-Team/github-agent)
19
+ ![GitHub repo size](https://img.shields.io/github/repo-size/Knuckles-Team/github-agent)
20
+ ![GitHub repo file count (file type)](https://img.shields.io/github/directory-file-count/Knuckles-Team/github-agent)
21
+ ![PyPI - Wheel](https://img.shields.io/pypi/wheel/github-agent)
22
+ ![PyPI - Implementation](https://img.shields.io/pypi/implementation/github-agent)
23
+
24
+ *Version: 0.1.1*
25
+
26
+ ## Overview
27
+
28
+ **GitHub Agent** is a powerful **Model Context Protocol (MCP)** server and **Agent-to-Agent (A2A)** system designed to interact with GitHub.
29
+
30
+ 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.
31
+
32
+ This repository is actively maintained - Contributions are welcome!
33
+
34
+ ### Capabilities:
35
+ - **Supervisor-Worker Architecture**: Orchestrates specialized agents for optimal task execution.
36
+ - **Comprehensive GitHub Coverage**: specialized agents for Issues, PRs, Repos, Actions, Organizations, and more.
37
+ - **MCP Support**: Fully compatible with the Model Context Protocol.
38
+ - **A2A Integration**: Ready for Agent-to-Agent communication.
39
+ - **Flexible Deployment**: Run via Docker, Docker Compose, or locally.
40
+
41
+ ## Architecture
42
+
43
+ ### System components
44
+
45
+ ```mermaid
46
+ ---
47
+ config:
48
+ layout: dagre
49
+ ---
50
+ flowchart TB
51
+ subgraph subGraph0["Agent Capabilities"]
52
+ Supervisor["Supervisor Agent"]
53
+ Server["A2A Server - Uvicorn/FastAPI"]
54
+ ChildAgents["Child Agents (Specialists)"]
55
+ MCP["GitHub MCP Tools"]
56
+ end
57
+ Supervisor --> ChildAgents
58
+ ChildAgents --> MCP
59
+ User["User Query"] --> Server
60
+ Server --> Supervisor
61
+ MCP --> GitHubAPI["GitHub API"]
62
+
63
+ Supervisor:::agent
64
+ ChildAgents:::agent
65
+ Server:::server
66
+ User:::server
67
+ classDef server fill:#f9f,stroke:#333
68
+ classDef agent fill:#bbf,stroke:#333,stroke-width:2px
69
+ style Server stroke:#000000,fill:#FFD600
70
+ style MCP stroke:#000000,fill:#BBDEFB
71
+ style GitHubAPI fill:#E6E6FA
72
+ style User fill:#C8E6C9
73
+ style subGraph0 fill:#FFF9C4
74
+ ```
75
+
76
+ ### Component Interaction
77
+
78
+ ```mermaid
79
+ sequenceDiagram
80
+ participant User
81
+ participant Server as A2A Server
82
+ participant Supervisor as Supervisor Agent
83
+ participant Child as Child Agent (e.g. Issues)
84
+ participant MCP as GitHub MCP Tools
85
+ participant GitHub as GitHub API
86
+
87
+ User->>Server: "Create an issue in repo X"
88
+ Server->>Supervisor: Invoke Supervisor
89
+ Supervisor->>Supervisor: Analyze Request & Select Specialist
90
+ Supervisor->>Child: Delegate to Issues Agent
91
+ Child->>MCP: Call create_issue Tool
92
+ MCP->>GitHub: POST /repos/user/repo/issues
93
+ GitHub-->>MCP: Issue Created JSON
94
+ MCP-->>Child: Tool Response
95
+ Child-->>Supervisor: Task Complete
96
+ Supervisor-->>Server: Final Response
97
+ Server-->>User: "Issue #123 created successfully"
98
+ ```
99
+
100
+ ## Specialized Agents
101
+
102
+ The Supervisor delegates tasks to these specialized agents:
103
+
104
+ | Agent Name | Description |
105
+ |:-----------|:------------|
106
+ | `GitHub_Context_Agent` | Provides context about the current user and GitHub status. |
107
+ | `GitHub_Actions_Agent` | Manages GitHub Actions workflows and runs. |
108
+ | `GitHub_Code_Security_Agent` | Handles code security scanning and alerts. |
109
+ | `GitHub_Dependabot_Agent` | Manages Dependabot alerts and configurations. |
110
+ | `GitHub_Discussions_Agent` | Manages repository discussions. |
111
+ | `GitHub_Gists_Agent` | Manages GitHub Gists. |
112
+ | `GitHub_Git_Agent` | Performs low-level Git operations (refs, trees, blobs). |
113
+ | `GitHub_Issues_Agent` | Manages Issues (create, list, update, comment). |
114
+ | `GitHub_Labels_Agent` | Manages repository labels. |
115
+ | `GitHub_Notifications_Agent` | Checks and manages notifications. |
116
+ | `GitHub_Organizations_Agent` | Manages Organization memberships and settings. |
117
+ | `GitHub_Projects_Agent` | Manages GitHub Projects (V2). |
118
+ | `GitHub_Pull_Requests_Agent` | Manages Pull Requests (create, review, merge). |
119
+ | `GitHub_Repos_Agent` | Manages Repositories (create, list, delete, settings). |
120
+ | `GitHub_Secret_Protection_Agent` | Manages secret scanning protection. |
121
+ | `GitHub_Security_Advisories_Agent` | Accesses security advisories. |
122
+ | `GitHub_Stargazers_Agent` | Views repository stargazers. |
123
+ | `GitHub_Users_Agent` | Accesses public user information. |
124
+ | `GitHub_Copilot_Agent` | Assists with coding tasks via Copilot. |
125
+ | `GitHub_Support_Docs_Agent` | Searches GitHub Support documentation. |
126
+
127
+ ## Usage
128
+
129
+ ### Prerequisites
130
+ - Python 3.10+
131
+ - A valid GitHub Personal Access Token (PAT) with appropriate permissions.
132
+
133
+ ### Installation
134
+
135
+ ```bash
136
+ pip install github-agent
137
+ ```
138
+ Or using UV:
139
+ ```bash
140
+ uv pip install github-agent
141
+ ```
142
+
143
+ ### CLI
144
+
145
+ The `github-agent` command starts the server.
146
+
147
+ | Argument | Description | Default |
148
+ |:---|:---|:---|
149
+ | `--host` | Host to bind the server to | `0.0.0.0` |
150
+ | `--port` | Port to bind the server to | `9000` |
151
+ | `--mcp-config` | Path to MCP configuration file | `mcp_config.json` |
152
+ | `--provider` | LLM Provider (openai, anthropic, google, etc.) | `openai` |
153
+ | `--model-id` | LLM Model ID | `qwen/qwen3-4b-2507` |
154
+
155
+ ### Running the Agent Server
156
+
157
+ ```bash
158
+ github-agent --provider openai --model-id gpt-4o --api-key sk-...
159
+ ```
160
+
161
+ ## Docker
162
+
163
+ ### Build
164
+
165
+ ```bash
166
+ docker build -t github-agent .
167
+ ```
168
+
169
+ ### Run using Docker
170
+
171
+ ```bash
172
+ docker run -d \
173
+ -p 9000:9000 \
174
+ -e OPENAI_API_KEY=sk-... \
175
+ -e MCP_CONFIG=/app/mcp_config.json \
176
+ knucklessg1/github-agent:latest
177
+ ```
178
+
179
+ ### Run using Docker Compose
180
+
181
+ Create a `docker-compose.yml`:
182
+
183
+ ```yaml
184
+ services:
185
+ github-agent:
186
+ image: knucklessg1/github-agent:latest
187
+ ports:
188
+ - "9000:9000"
189
+ environment:
190
+ - PROVIDER=openai
191
+ - MODEL_ID=gpt-4o
192
+ - OPENAI_API_KEY=${OPENAI_API_KEY}
193
+ volumes:
194
+ - ./mcp_config.json:/app/mcp_config.json
195
+ ```
196
+
197
+ Then run:
198
+ ```bash
199
+ docker-compose up -d
200
+ ```
201
+
202
+ ## Repository Owners
203
+
204
+ <img width="100%" height="180em" src="https://github-readme-stats.vercel.app/api?username=Knucklessg1&show_icons=true&hide_border=true&&count_private=true&include_all_commits=true" />
205
+
206
+ ![GitHub followers](https://img.shields.io/github/followers/Knucklessg1)
207
+ ![GitHub User's stars](https://img.shields.io/github/stars/Knucklessg1)
@@ -0,0 +1 @@
1
+ __version__ = "0.1.0"