2.6 KiB
AegisGitea MCP documentation
AegisGitea MCP is a full-access Model Context Protocol 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).
Requires Python 3.10 or newer. License: MIT.
Documents
| Document | Description |
|---|---|
| README | Overview, quick start, scopes, auth modes, client configs |
| Getting started | Fresh clone to a working server, the setup command |
| Configuration | Every environment variable, default and validation rule |
| Tool inventory | Generated list of all tools with method, path and flags |
| Raw API tool | gitea_api_request for endpoints newer than the pinned spec |
| Architecture | Catalog, executor, server, transports, auth, request flow |
| Deployment | Docker, reverse proxy and TLS, OAuth application, upgrades |
| Hardening | Checklist for running a full-access server |
| Audit logging | Event fields, integrity validation, rotation |
| Troubleshooting | Startup problems, error kinds, OAuth and HTTP issues |
| Packaging | Building and the dev and stable package channels |
| Security | Threat model and security controls |
| Roadmap | State of the project and known limits |
| ADRs | Architecture decision records 0001 to 0006 |
| Codebase audit and chunk plan | Audit of the 0.x code and the plan for 1.0.0 |
| Research notes | SDK, OAuth and Gitea facts with sources |
Quick start
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.