# MCP GitHub Agent

## Overview

A tool-using agent that exposes GitHub-shaped tools in the style of the Model Context Protocol. `GET /tools` lists `list_issues`, `get_pr` and `summarize`, and `POST /call` invokes one of them. Merging a pull request through an apply action is refused, so the agent can read and summarize but not change a repository. A versioned `/v1` ops API adds workspaces, tenant isolation, job approval and audit records.

- **Built with:** Python, pytest, GitHub Actions
- **Scope:** Local laptop lab with tests; it does not call a hosted model and refuses merges and production apply.

<!-- project-guide:start -->
## Project guide

[Project architecture](PROJECT_ARCHITECTURE.md) · [Interview questions and answers](INTERVIEW_QA.md)

Use the architecture document for the component diagram, implementation boundaries, and verification entry points. The interview guide includes source-backed answers and project walkthroughs.

### Implementation map

| Component | Responsibility |
| --- | --- |
| [`src/mcpgh/main.py`](src/mcpgh/main.py) | HTTP handlers: `GET /healthz`, `GET /tools`, `POST /call` |
| [`src/mcpgh/mcp.py`](src/mcpgh/mcp.py) | Functions: `list_tools`, `call` |
| [`requirements.txt`](requirements.txt) | Implementation or supporting configuration |
| [`src/mcpgh/__init__.py`](src/mcpgh/__init__.py) | Implementation or supporting configuration |
| [`tests/test_mcp.py`](tests/test_mcp.py) | Executable checks and regression examples |
| [`.github/workflows/ci.yml`](.github/workflows/ci.yml) | GitHub Actions job definitions |
| [`README.md`](README.md) | Project explanations or operating notes |

### Local setup and verification

From the repository root (the commands follow the checked-in manifests):

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -m pytest -q
```

To serve the FastAPI application locally, install the server separately if it is not already available:

```bash
python -m pip install uvicorn
PYTHONPATH=src python -m uvicorn mcpgh.main:app --reload
```

<!-- project-guide:end -->

Level: 10 — MCP & Tool-Using Agents

Skills: Python, GitHub-shaped tools

Tools: list_issues, get_pr, summarize. Merge via apply is refused.

```bash
pip install -r requirements.txt
pytest -q
```

This is a local laptop proof. It does not call a hosted model and it does not apply production changes.

## Ops plane

Workspaces, tenant isolation, job approval, and audit live under `/v1`. Production apply is refused. See `docs/ARCHITECTURE.md`.

## Documentation checks

Project architecture, interview guides, and local source links are checked automatically on pushes and pull requests. Run the same check locally:

```bash
python3 .github/scripts/validate_project_docs.py
```

See [service improvements and local run instructions](docs/UPGRADES.md).