49 lines
2.6 KiB
Markdown
49 lines
2.6 KiB
Markdown
# 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.
|