# AegisGitea MCP documentation

AegisGitea MCP is a full-access [Model Context Protocol](https://modelcontextprotocol.io) bridge
to the whole Gitea API: one tool per operation of the pinned Gitea 28.1.0 swagger (537) plus
`gitea_api_request`, 538 tools in total. It serves them over stdio and streamable HTTP, with
admin-token and per-user OAuth authentication, a hash-chained audit log and bounded, secret-masked
results. Everything is enabled by default; you restrict it with configuration and the scope of
the Gitea token.

Gitea content is untrusted: results are labelled as data and clients must never treat them as
instructions (see the [README](../README.md#security-notice-gitea-content-is-untrusted)).

Requires Python 3.10 or newer. License: MIT.

## Documents

| Document | Description |
|---|---|
| [README](../README.md) | Overview, quick start, scopes, auth modes, client configs |
| [Getting started](getting-started.md) | Fresh clone to a working server, the `setup` command |
| [Configuration](configuration.md) | Every environment variable, default and validation rule |
| [Tool inventory](tools.md) | Generated list of all tools with method, path and flags |
| [Raw API tool](raw-api.md) | `gitea_api_request` for endpoints newer than the pinned spec |
| [Architecture](architecture.md) | Catalog, executor, server, transports, auth, request flow |
| [Deployment](deployment.md) | Docker, reverse proxy and TLS, OAuth application, upgrades |
| [Hardening](hardening.md) | Checklist for running a full-access server |
| [Audit logging](audit-logging.md) | Event fields, integrity validation, rotation |
| [Troubleshooting](troubleshooting.md) | Startup problems, error kinds, OAuth and HTTP issues |
| [Packaging](packaging.md) | Building and the dev and stable package channels |
| [Security](security.md) | Threat model and security controls |
| [Roadmap](roadmap.md) | State of the project and known limits |
| [ADRs](adr/0001-full-access-by-default.md) | Architecture decision records 0001 to 0006 |
| [Codebase audit and chunk plan](audit.md) | Audit of the 0.x code and the plan for 1.0.0 |
| [Research notes](research/sdk-oauth-gitea.md) | SDK, OAuth and Gitea facts with sources |

## Quick start

```bash
git clone https://git.hiddenden.cafe/Hiddenden/AegisGitea-MCP.git
cd AegisGitea-MCP
uv sync
uv run aegis-gitea-mcp setup          # verifies Gitea, writes .env, prints client configs
MCP_TRANSPORT=http uv run aegis-gitea-mcp serve
curl http://127.0.0.1:8080/health
```

The tool inventory and the README tool summary are generated by `scripts/check_docs.py`; CI
fails when they drift from the catalog.