From 198fd3905b666f522a86db89d9eefdd94856a924 Mon Sep 17 00:00:00 2001
From: latte <latte@hiddenden.cafe>
Date: Sat, 14 Feb 2026 16:10:43 +0100
Subject: [PATCH] add readme.md

---
 README.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8229c60
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+# 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`).