86 lines
2.3 KiB
Markdown
86 lines
2.3 KiB
Markdown
# 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
|
|
|
|
```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, 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`).
|