docs: local vs server quickstart, authz model, packaging

Reframe the README around two transports and add a local stdio quickstart with uvx/pip and Claude Desktop / Claude Code wiring. New docs: local-quickstart.md and packaging.md (uv build/publish). Document resource-type-aware authorization and classified gitea_request in security.md; stdio env vars + audit-log fallback in configuration.md; local install in deployment.md; core+adapters in architecture.md. Add the missing root AGENTS.md contract, update CLAUDE.md with the core/adapter layout, fail-closed invariants, and the branching flow (HEAD -> feature -> dev -> main). Update roadmap/todo and .env.example. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-27 11:17:01 +02:00
parent 2859a7f917
commit 385b442b6f
13 changed files with 520 additions and 31 deletions
@@ -0,0 +1,98 @@
+# Local quickstart (stdio)
+
+The local transport runs AegisGitea-MCP on your own machine as a single-user MCP
+server over stdio. It authenticates with **your** Gitea Personal Access Token
+(PAT) — there is no OAuth, no public endpoint, and no web stack to install.
+
+## What you need
+
+- A Gitea instance URL (`GITEA_URL`).
+- A Gitea Personal Access Token (`GITEA_TOKEN`) with least privilege:
+  - `read:repository`
+  - `write:repository` only if you intend to enable `WRITE_MODE`.
+- [`uv`](https://docs.astral.sh/uv/) (for `uvx`) or `pip`.
+
+## Run it
+
+With `uvx` (no install):
+
+```bash
+GITEA_URL=https://git.hiddenden.cafe \
+GITEA_TOKEN=<pat> \
+uvx aegis-gitea-mcp
+```
+
+With pip:
+
+```bash
+pip install aegis-gitea-mcp
+GITEA_URL=https://git.hiddenden.cafe GITEA_TOKEN=<pat> aegis-gitea-mcp
+```
+
+A local `.env` file is also supported — drop `GITEA_URL` and `GITEA_TOKEN` in it
+and just run `aegis-gitea-mcp`.
+
+If a required variable is missing the server exits with a clear message instead
+of a traceback.
+
+## Wire it into a client
+
+Claude Code:
+
+```bash
+claude mcp add aegis-gitea \
+  -e GITEA_URL=https://git.hiddenden.cafe \
+  -e GITEA_TOKEN=<pat> \
+  -- uvx aegis-gitea-mcp
+```
+
+Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "aegis-gitea": {
+      "command": "uvx",
+      "args": ["aegis-gitea-mcp"],
+      "env": {
+        "GITEA_URL": "https://git.hiddenden.cafe",
+        "GITEA_TOKEN": "<pat>"
+      }
+    }
+  }
+}
+```
+
+## What still applies locally
+
+The local adapter is single-user and trusts the PAT owner, so it skips the
+per-user repository-permission probe used by the public server. Everything else
+is identical to the server:
+
+- **Policy engine** (`policy.yaml`) — same allow/deny rules.
+- **`WRITE_MODE`** — off by default; writes are denied unless explicitly enabled
+  and whitelisted.
+- **`gitea_request`** full-API escape hatch — same write classifier, known-path
+  gate, and admin/credential denylist.
+- **Secret sanitization** of tool output.
+- **Tamper-evident audit log** — written to a per-user path when the container
+  default is not writable:
+  - Windows: `%LOCALAPPDATA%\aegis-gitea-mcp\audit.log`
+  - Linux/macOS: `$XDG_STATE_HOME/aegis-gitea-mcp/audit.log` or
+    `~/.local/state/aegis-gitea-mcp/audit.log`
+  - Override with `AUDIT_LOG_PATH`.
+
+## Enabling writes locally
+
+Writes are opt-in, exactly as on the server:
+
+```bash
+GITEA_URL=https://git.hiddenden.cafe \
+GITEA_TOKEN=<pat-with-write-repository> \
+WRITE_MODE=true \
+WRITE_REPOSITORY_WHITELIST=acme/app,acme/docs \
+uvx aegis-gitea-mcp
+```
+
+See [configuration.md](configuration.md) for the full variable reference and
+[write-mode.md](write-mode.md) for the write-mode model.