Hiddenden/AegisGitea-MCP
3
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: local vs server quickstart, authz model, packaging

Browse Source 
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>
This commit is contained in:
Latte
2026-06-27 11:17:01 +02:00
parent 2859a7f917
commit 385b442b6f
13 changed files with 520 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/configuration.md
+33 -1
View File
@@ -6,6 +6,37 @@ Copy `.env.example` to `.env` and set values before starting:
cp .env.example .env
```
## Local stdio transport (`aegis-gitea-mcp`)
The local single-user server reads only two variables; a local `.env` file is
supported via python-dotenv.
| Variable | Required | Default | Description |
|---|---|---|---|
| `GITEA_URL` | Yes | - | Base URL of your Gitea instance |
| `GITEA_TOKEN` | Yes | - | Your Gitea Personal Access Token (the local identity) |
| `AUDIT_LOG_PATH` | No | per-user state path | Audit log location (see below) |
The local adapter forces `OAUTH_MODE=false` and defaults `AUTH_ENABLED=false`
(no API-key requirement) — the operator is the trusted PAT owner. `WRITE_MODE`,
`WRITE_REPOSITORY_WHITELIST`, `POLICY_FILE_PATH`, `SECRET_DETECTION_MODE`,
`RAW_API_ENABLED`, and `RAW_API_ALLOW_SENSITIVE` all behave exactly as on the
server.
**Audit-log fallback.** When `AUDIT_LOG_PATH` is unset, the container default
(`/var/log/aegis-mcp/audit.log`) is replaced with a writable per-user path:
- Windows: `%LOCALAPPDATA%\aegis-gitea-mcp\audit.log`
- Linux/macOS: `$XDG_STATE_HOME/aegis-gitea-mcp/audit.log`, else
`~/.local/state/aegis-gitea-mcp/audit.log`
## Raw API dispatch (`gitea_request`)
| Variable | Required | Default | Description |
|---|---|---|---|
| `RAW_API_ENABLED` | No | `true` | Enable the generic `gitea_request` escape hatch |
| `RAW_API_ALLOW_SENSITIVE` | No | `false` | Opt in to the admin/credential surface (`/admin`, `*tokens*`, `*secrets*`, `*hooks*`, `*keys*`, `applications/oauth2`, runner registration). Admin calls additionally require a verified site administrator. |
## OAuth/OIDC Settings (Primary)
| Variable | Required | Default | Description |
@@ -67,6 +98,7 @@ cp .env.example .env
These are retained for compatibility but not used for OAuth-protected MCP tool execution:
- `GITEA_TOKEN`
- `GITEA_TOKEN` — note: in **service-PAT** server mode and in the **local stdio**
transport this is required and is the API identity (see above).
- `MCP_API_KEYS`
- `AUTH_ENABLED`