github-agent 0.28.0__tar.gz → 0.30.0__tar.gz

{github_agent-0.28.0/github_agent.egg-info → github_agent-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-agent
-Version: 0.28.0
+Version: 0.30.0
 Summary: GitHub Agent for MCP
 Author-email: Audel Rouhi <knucklessg1@gmail.com>
 License: MIT
@@ -9,10 +9,10 @@ Classifier: License :: Public Domain
 Classifier: Environment :: Console
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
-Requires-Python: <3.14,>=3.11
+Requires-Python: <3.15,>=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: agent-utilities[agent,logfire]>=0.45.0
+Requires-Dist: agent-utilities[agent,logfire]>=0.48.0
 Provides-Extra: test
 Requires-Dist: pytest-xdist>=3.6.0; extra == "test"
 Requires-Dist: pytest; extra == "test"
@@ -41,7 +41,11 @@ Dynamic: license-file
 ![PyPI - Wheel](https://img.shields.io/pypi/wheel/github-agent)
 ![PyPI - Implementation](https://img.shields.io/pypi/implementation/github-agent)
 
-*Version: 0.28.0*
+*Version: 0.30.0*
+
+> **Documentation** — Installation, deployment, and usage across the MCP, API, and
+> CLI interfaces, including the integrated A2A agent server, are maintained in the
+> [official documentation](https://knuckles-team.github.io/github-agent/).
 
 ---
 
@@ -195,6 +199,21 @@ docker run -d \
 
 ---
 
+<!-- BEGIN GENERATED: additional-deployment-options -->
+### Additional Deployment Options
+
+`github-agent` can also run as a **local container** (Docker / Podman / `uv`) or be
+consumed from a **remote deployment**. The
+[Deployment guide](https://knuckles-team.github.io/github-agent/deployment/) has full, copy-paste
+`mcp_config.json` for all four transports — **stdio**, **streamable-http**,
+**local container / uv**, and **remote URL**:
+
+- **Local container / uv** — launch the server from `mcp_config.json` via `uvx`,
+  `docker run`, or `podman run`, or point at a local streamable-http container by `url`.
+- **Remote URL** — connect to a server deployed behind Caddy at
+  `http://github-mcp.arpa/mcp` using the `"url"` key.
+<!-- END GENERATED: additional-deployment-options -->
+
 ## Agent
 
 This repository features a fully integrated Pydantic AI Graph Agent. It communicates over the **Agent Control Protocol (ACP)** and interacts seamlessly with the **Agent Web UI (AG-UI)** and Terminal interface.
@@ -318,6 +337,22 @@ python -m pip install github-agent[all]
 
 ---
 
+## Documentation
+
+The complete documentation is published as the
+[official documentation site](https://knuckles-team.github.io/github-agent/) and is the
+recommended reference for installation, deployment, and day-to-day operation.
+
+| Page | Contents |
+|---|---|
+| [Installation](https://knuckles-team.github.io/github-agent/installation/) | pip, source, extras, prebuilt Docker image |
+| [Deployment](https://knuckles-team.github.io/github-agent/deployment/) | run the MCP and agent servers, Compose, Caddy + Technitium, env config |
+| [Usage](https://knuckles-team.github.io/github-agent/usage/) | the MCP tools, the `Api` client, the CLI |
+| [Overview](https://knuckles-team.github.io/github-agent/overview/) | supervisor architecture and specialized agents |
+| [Concepts](https://knuckles-team.github.io/github-agent/concepts/) | concept registry (`CONCEPT:GH-*`) |
+
+---
+
 ## Repository Owners
 
 <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" />

github_agent-0.28.0/PKG-INFO → github_agent-0.30.0/README.md

@@ -1,24 +1,3 @@
-Metadata-Version: 2.4
-Name: github-agent
-Version: 0.28.0
-Summary: GitHub Agent for MCP
-Author-email: Audel Rouhi <knucklessg1@gmail.com>
-License: MIT
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: License :: Public Domain
-Classifier: Environment :: Console
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3
-Requires-Python: <3.14,>=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: agent-utilities[agent,logfire]>=0.45.0
-Provides-Extra: test
-Requires-Dist: pytest-xdist>=3.6.0; extra == "test"
-Requires-Dist: pytest; extra == "test"
-Requires-Dist: pytest-asyncio; extra == "test"
-Dynamic: license-file
-
 # Github Agent
 ## CLI or API | MCP | Agent
 
@@ -41,7 +20,11 @@ Dynamic: license-file
 ![PyPI - Wheel](https://img.shields.io/pypi/wheel/github-agent)
 ![PyPI - Implementation](https://img.shields.io/pypi/implementation/github-agent)
 
-*Version: 0.28.0*
+*Version: 0.30.0*
+
+> **Documentation** — Installation, deployment, and usage across the MCP, API, and
+> CLI interfaces, including the integrated A2A agent server, are maintained in the
+> [official documentation](https://knuckles-team.github.io/github-agent/).
 
 ---
 
@@ -195,6 +178,21 @@ docker run -d \
 
 ---
 
+<!-- BEGIN GENERATED: additional-deployment-options -->
+### Additional Deployment Options
+
+`github-agent` can also run as a **local container** (Docker / Podman / `uv`) or be
+consumed from a **remote deployment**. The
+[Deployment guide](https://knuckles-team.github.io/github-agent/deployment/) has full, copy-paste
+`mcp_config.json` for all four transports — **stdio**, **streamable-http**,
+**local container / uv**, and **remote URL**:
+
+- **Local container / uv** — launch the server from `mcp_config.json` via `uvx`,
+  `docker run`, or `podman run`, or point at a local streamable-http container by `url`.
+- **Remote URL** — connect to a server deployed behind Caddy at
+  `http://github-mcp.arpa/mcp` using the `"url"` key.
+<!-- END GENERATED: additional-deployment-options -->
+
 ## Agent
 
 This repository features a fully integrated Pydantic AI Graph Agent. It communicates over the **Agent Control Protocol (ACP)** and interacts seamlessly with the **Agent Web UI (AG-UI)** and Terminal interface.
@@ -318,6 +316,22 @@ python -m pip install github-agent[all]
 
 ---
 
+## Documentation
+
+The complete documentation is published as the
+[official documentation site](https://knuckles-team.github.io/github-agent/) and is the
+recommended reference for installation, deployment, and day-to-day operation.
+
+| Page | Contents |
+|---|---|
+| [Installation](https://knuckles-team.github.io/github-agent/installation/) | pip, source, extras, prebuilt Docker image |
+| [Deployment](https://knuckles-team.github.io/github-agent/deployment/) | run the MCP and agent servers, Compose, Caddy + Technitium, env config |
+| [Usage](https://knuckles-team.github.io/github-agent/usage/) | the MCP tools, the `Api` client, the CLI |
+| [Overview](https://knuckles-team.github.io/github-agent/overview/) | supervisor architecture and specialized agents |
+| [Concepts](https://knuckles-team.github.io/github-agent/concepts/) | concept registry (`CONCEPT:GH-*`) |
+
+---
+
 ## Repository Owners
 
 <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" />

{github_agent-0.28.0 → github_agent-0.30.0}/github_agent/agent_server.py

@@ -4,7 +4,7 @@ import os
 import sys
 import warnings
 
-__version__ = "0.28.0"
+__version__ = "0.30.0"
 
 logging.basicConfig(
     level=logging.INFO,

github_agent-0.30.0/github_agent/api/api_client_orgs.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python
+from urllib.parse import urlparse
+
+from agent_utilities.decorators import require_auth
+from agent_utilities.exceptions import (
+    ParameterError,
+)
+from pydantic import ValidationError
+
+from github_agent.api.api_client_base import BaseApiClient
+from github_agent.github_input_models import (
+    OrgListModel,
+    OrgMemberModel,
+    OrgUpdateModel,
+)
+from github_agent.github_response_models import (
+    Organization,
+    OrganizationMembership,
+    OrganizationSummary,
+    Repository,
+    Response,
+    User,
+)
+
+
+class OrganizationCreationNotSupportedError(Exception):
+    """Raised when organization creation is requested against github.com.
+
+    github.com does not expose an API to create organizations — they can only
+    be created through the web UI. The POST /admin/organizations endpoint
+    exists only on GitHub Enterprise Server.
+    """
+
+
+class Api(BaseApiClient):
+    @require_auth
+    def get_organization(self, org: str) -> Response:
+        """Get an organization's full profile.
+
+        GET /orgs/{org}
+        https://docs.github.com/en/rest/orgs/orgs#get-an-organization
+        """
+        response = self._session.get(
+            url=f"{self.url}/orgs/{org}",
+            headers=self.headers,
+            verify=self.verify,
+            proxies=self.proxies,
+        )
+        response.raise_for_status()
+        try:
+            parsed_data = Organization(**response.json())
+            return Response(response=response, data=parsed_data)
+        except ValidationError as e:
+            raise ParameterError(f"Invalid parameters: {e.errors()}") from e
+
+    @require_auth
+    def list_organizations(self, **kwargs) -> Response:
+        """List organizations.
+
+        With scope='member' (default): organizations the authenticated user
+        belongs to.
+        GET /user/orgs
+        https://docs.github.com/en/rest/orgs/orgs#list-organizations-for-the-authenticated-user
+
+        With scope='all': every organization, in ascending ID order. GitHub
+        paginates this endpoint with a 'since' ID cursor — pass the highest
+        organization ID from the previous page to fetch the next one.
+        GET /organizations
+        https://docs.github.com/en/rest/orgs/orgs#list-organizations
+        """
+        model = OrgListModel(**kwargs)
+        endpoint = "/user/orgs" if model.scope == "member" else "/organizations"
+        response, data = self._fetch_all_pages(endpoint, model)
+        try:
+            parsed_data = [OrganizationSummary(**item) for item in data]
+            return Response(response=response, data=parsed_data)
+        except ValidationError as e:
+            raise ParameterError(f"Invalid parameters: {e.errors()}") from e
+
+    @require_auth
+    def update_organization(self, org: str, **kwargs) -> Response:
+        """Update an organization's profile and member settings.
+
+        Accepts the documented mutable fields (validated by OrgUpdateModel):
+        billing_email, company, email, twitter_username, location, name,
+        description, blog, has_organization_projects, has_repository_projects,
+        default_repository_permission, members_can_create_repositories,
+        members_can_create_public/private/internal_repositories,
+        members_can_create_pages, members_can_fork_private_repositories,
+        web_commit_signoff_required.
+
+        PATCH /orgs/{org}
+        https://docs.github.com/en/rest/orgs/orgs#update-an-organization
+        """
+        try:
+            model = OrgUpdateModel(**kwargs)
+        except ValidationError as e:
+            raise ParameterError(f"Invalid parameters: {e.errors()}") from e
+        response = self._session.patch(
+            url=f"{self.url}/orgs/{org}",
+            json=model.model_dump(exclude_none=True),
+            headers=self.headers,
+            verify=self.verify,
+            proxies=self.proxies,
+        )
+        response.raise_for_status()
+        try:
+            parsed_data = Organization(**response.json())
+            return Response(response=response, data=parsed_data)
+        except ValidationError as e:
+            raise ParameterError(f"Invalid parameters: {e.errors()}") from e
+
+    @require_auth
+    def delete_organization(self, org: str) -> Response:
+        """Schedule an organization for deletion. IRREVERSIBLE.
+
+        GitHub responds 202 Accepted and deletes the organization, all of its
+        repositories, and all of its data asynchronously. The MCP layer gates
+        this action behind allow_destructive / GITHUB_ALLOW_DESTRUCTIVE.
+
+        DELETE /orgs/{org}
+        https://docs.github.com/en/rest/orgs/orgs#delete-an-organization
+        """
+        response = self._session.delete(
+            url=f"{self.url}/orgs/{org}",
+            headers=self.headers,
+            verify=self.verify,
+            proxies=self.proxies,
+        )
+        response.raise_for_status()
+        return Response(response=response, data={"status": "deletion_scheduled"})
+
+    @require_auth
+    def create_organization(
+        self, login: str, admin: str, profile_name: str | None = None
+    ) -> Response:
+        """Create an organization — GitHub Enterprise Server ONLY.
+
+        POST /admin/organizations (site-admin API)
+        https://docs.github.com/en/enterprise-server@latest/rest/enterprise-admin/orgs#create-an-organization
+
+        github.com does NOT expose an API to create organizations; on
+        github.com they can only be created through the web UI
+        (https://github.com/account/organizations/new). When this client
+        points at api.github.com this method raises
+        OrganizationCreationNotSupportedError instead of calling the API.
+
+        Args:
+            login: The organization's username.
+            admin: The login of the user who will manage this organization.
+            profile_name: The organization's display name.
+        """
+        host = urlparse(self.url).hostname or ""
+        if host == "api.github.com":
+            raise OrganizationCreationNotSupportedError(
+                "github.com organizations cannot be created via the API — "
+                "create them in the web UI at "
+                "https://github.com/account/organizations/new. "
+                "POST /admin/organizations is only available on GitHub "
+                "Enterprise Server (point GITHUB_URL at your enterprise "
+                "instance's API, e.g. https://ghe.example.com/api/v3)."
+            )
+        payload: dict = {"login": login, "admin": admin}
+        if profile_name is not None:
+            payload["profile_name"] = profile_name
+        response = self._session.post(
+            url=f"{self.url}/admin/organizations",
+            json=payload,
+            headers=self.headers,
+            verify=self.verify,
+            proxies=self.proxies,
+        )
+        response.raise_for_status()
+        try:
+            parsed_data = OrganizationSummary(**response.json())
+            return Response(response=response, data=parsed_data)
+        except ValidationError as e:
+            raise ParameterError(f"Invalid parameters: {e.errors()}") from e
+
+    @require_auth
+    def create_organization_repository(self, org: str, name: str, **kwargs) -> Response:
+        """Create a repository in an organization.
+
+        Accepts the same payload fields as create_repository (which posts to
+        /user/repos): description, homepage, private, visibility, has_issues,
+        has_projects, has_wiki, auto_init, gitignore_template,
+        license_template, etc.
+
+        POST /orgs/{org}/repos
+        https://docs.github.com/en/rest/repos/repos#create-an-organization-repository
+        """
+        try:
+            payload = {"name": name, **kwargs}
+            response = self._session.post(
+                url=f"{self.url}/orgs/{org}/repos",
+                json=payload,
+                headers=self.headers,
+                verify=self.verify,
+                proxies=self.proxies,
+            )
+            response.raise_for_status()
+            parsed_data = Repository(**response.json())
+            return Response(response=response, data=parsed_data)
+        except ValidationError as e:
+            raise ParameterError(f"Invalid parameters: {e.errors()}") from e
+
+    @require_auth
+    def get_organization_membership(self, org: str, username: str) -> Response:
+        """Get a user's organization membership (state and role).
+
+        GET /orgs/{org}/memberships/{username}
+        https://docs.github.com/en/rest/orgs/members#get-organization-membership-for-a-user
+        """
+        response = self._session.get(
+            url=f"{self.url}/orgs/{org}/memberships/{username}",
+            headers=self.headers,
+            verify=self.verify,
+            proxies=self.proxies,
+        )
+        response.raise_for_status()
+        try:
+            parsed_data = OrganizationMembership(**response.json())
+            return Response(response=response, data=parsed_data)
+        except ValidationError as e:
+            raise ParameterError(f"Invalid parameters: {e.errors()}") from e
+
+    @require_auth
+    def set_organization_membership(
+        self, org: str, username: str, role: str = "member"
+    ) -> Response:
+        """Add a user to an organization or update their role.
+
+        Invites the user when they are not yet a member (membership state
+        'pending' until accepted). Role is 'member' or 'admin'.
+
+        PUT /orgs/{org}/memberships/{username}
+        https://docs.github.com/en/rest/orgs/members#set-organization-membership-for-a-user
+        """
+        response = self._session.put(
+            url=f"{self.url}/orgs/{org}/memberships/{username}",
+            json={"role": role},
+            headers=self.headers,
+            verify=self.verify,
+            proxies=self.proxies,
+        )
+        response.raise_for_status()
+        try:
+            parsed_data = OrganizationMembership(**response.json())
+            return Response(response=response, data=parsed_data)
+        except ValidationError as e:
+            raise ParameterError(f"Invalid parameters: {e.errors()}") from e
+
+    @require_auth
+    def remove_organization_member(self, org: str, username: str) -> Response:
+        """Remove a user from an organization (repositories access included).
+
+        Destructive: the MCP layer gates this action behind
+        allow_destructive / GITHUB_ALLOW_DESTRUCTIVE. GitHub responds 204.
+
+        DELETE /orgs/{org}/members/{username}
+        https://docs.github.com/en/rest/orgs/members#remove-an-organization-member
+        """
+        response = self._session.delete(
+            url=f"{self.url}/orgs/{org}/members/{username}",
+            headers=self.headers,
+            verify=self.verify,
+            proxies=self.proxies,
+        )
+        response.raise_for_status()
+        return Response(response=response, data={"status": "removed"})
+
+    @require_auth
+    def get_org_members(self, **kwargs) -> Response:
+        """List members for an organization."""
+        model = OrgMemberModel(**kwargs)
+        response, data = self._fetch_all_pages(f"/orgs/{model.org}/members", model)
+        try:
+            parsed_data = [User(**item) for item in data]
+            return Response(response=response, data=parsed_data)
+        except ValidationError as e:
+            raise ParameterError(f"Invalid parameters: {e.errors()}") from e
+
+    @require_auth
+    def get_org_teams(self, org: str) -> Response:
+        """List teams for an organization."""
+        response = self._session.get(
+            url=f"{self.url}/orgs/{org}/teams",
+            headers=self.headers,
+            verify=self.verify,
+            proxies=self.proxies,
+        )
+        response.raise_for_status()
+        return Response(response=response, data=response.json())