# 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 + policy enforcement, with whitelist by default).
- 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

```bash
make install-dev
```

### 2. Configure environment

```bash
cp .env.example .env
```

Set at minimum:
- `GITEA_URL`
- `GITEA_TOKEN`
- `MCP_API_KEYS`

### 3. Run locally

```bash
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; when enabled, use whitelist or opt into `WRITE_ALLOW_ALL_TOKEN_REPOS=true`.

## 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`).