AegisGitea-MCP

Security-first, policy-driven MCP gateway for Gitea.

AegisGitea-MCP exposes controlled read and optional write capabilities to AI agents through MCP-compatible endpoints, with strict validation, policy enforcement, tamper-evident audit logging, and secure-by-default runtime controls.

Highlights

Security-first defaults (localhost bind, write mode disabled, no stack traces in production errors).
YAML policy engine with global/per-repository tool allow/deny and optional path restrictions.
Expanded read tools for repositories, commits, diffs, issues, PRs, labels, tags, and releases.
Strict write mode (opt-in + repository whitelist + policy enforcement).
Tamper-evident audit logging with hash-chain integrity validation.
Secret detection/sanitization for outbound payloads.
Structured JSON logging + Prometheus metrics.
Hardened Docker runtime (non-root, no-new-privileges, capability drop, read-only where practical).

Quick Start

1. Install dependencies

make install-dev

2. Configure environment

cp .env.example .env

Set at minimum:

GITEA_URL
GITEA_TOKEN
MCP_API_KEYS

3. Run locally

make run

Server defaults to 127.0.0.1:8080.

Core Commands

make test: run pytest with coverage.
make lint: run Ruff + mypy.
make format: run Black + Ruff autofix.
make docker-up: start hardened prod-profile container.
make docker-down: stop containers.
make validate-audit: validate audit hash chain integrity.

Security Model

Authentication: API keys (Authorization: Bearer <key>).
Authorization: policy engine (policy.yaml) evaluated before tool execution.
Rate limiting: per-IP and per-token.
Output controls: bounded response size and optional secret masking/blocking.
Write controls: WRITE_MODE=false by default, repository whitelist required when enabled.

Documentation

All detailed docs are under docs/:

docs/api-reference.md
docs/policy.md
docs/security.md
docs/audit.md
docs/write-mode.md
docs/deployment.md
docs/observability.md
docs/automation.md
docs/governance.md
docs/roadmap.md
docs/todo.md

Conduct and Governance

Contributor/maintainer conduct: CODE_OF_CONDUCT.md
AI agent behavioral contract: AGENTS.md

License

MIT (see LICENSE).

2.3 KiB Raw Blame History