Latte
385b442b6f
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>
105 lines
5.1 KiB
Markdown
105 lines
5.1 KiB
Markdown
# Configuration
|
|
|
|
Copy `.env.example` to `.env` and set values before starting:
|
|
|
|
```bash
|
|
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 |
|
|
|---|---|---|---|
|
|
| `GITEA_URL` | Yes | - | Base URL of your Gitea instance |
|
|
| `OAUTH_MODE` | No | `false` | Enables OAuth-oriented validation settings |
|
|
| `GITEA_OAUTH_CLIENT_ID` | Yes when `OAUTH_MODE=true` | - | OAuth client id |
|
|
| `GITEA_OAUTH_CLIENT_SECRET` | Yes when `OAUTH_MODE=true` | - | OAuth client secret |
|
|
| `OAUTH_EXPECTED_AUDIENCE` | No | empty | Additional accepted JWT audience beyond the MCP resource and Gitea client id |
|
|
| `OAUTH_CACHE_TTL_SECONDS` | No | `300` | OIDC discovery/JWKS cache TTL |
|
|
| `OAUTH_STATE_SECRET` | Yes when `OAUTH_MODE=true` | - | HMAC secret for signed OAuth state wrappers; must be at least 32 characters (e.g. `openssl rand -hex 32`) |
|
|
| `OAUTH_REDIRECT_ALLOWLIST` | No | empty | Additional allowed redirect URIs for OAuth clients |
|
|
|
|
## MCP Server Settings
|
|
|
|
| Variable | Required | Default | Description |
|
|
|---|---|---|---|
|
|
| `MCP_HOST` | No | `127.0.0.1` | Interface to bind to |
|
|
| `MCP_PORT` | No | `8080` | Port to listen on |
|
|
| `PUBLIC_BASE_URL` | No | empty | Public HTTPS base URL advertised in OAuth metadata (recommended behind reverse proxy) |
|
|
| `ALLOW_INSECURE_BIND` | No | `false` | Explicit opt-in required for `0.0.0.0` bind |
|
|
| `LOG_LEVEL` | No | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
|
|
| `STARTUP_VALIDATE_GITEA` | No | `true` | Validate OIDC discovery endpoint at startup |
|
|
| `DCR_ENABLED` | No | `true` | Enable dynamic client registration at `/register` |
|
|
| `DCR_STORAGE_PATH` | No | `/var/lib/aegis-mcp/dcr_clients.json` | Persisted OAuth client registry path. Written with owner-only (`0o600`) permissions on POSIX hosts |
|
|
|
|
## Security and Limits
|
|
|
|
| Variable | Required | Default | Description |
|
|
|---|---|---|---|
|
|
| `MAX_AUTH_FAILURES` | No | `5` | Failed auth attempts before rate limiting |
|
|
| `AUTH_FAILURE_WINDOW` | No | `300` | Window in seconds for auth failure counting |
|
|
| `RATE_LIMIT_PER_MINUTE` | No | `60` | Per-IP request limit |
|
|
| `TOKEN_RATE_LIMIT_PER_MINUTE` | No | `120` | Per-token request limit |
|
|
| `MAX_FILE_SIZE_BYTES` | No | `1048576` | Max file payload returned by read tools |
|
|
| `MAX_TOOL_RESPONSE_ITEMS` | No | `200` | Max list items in tool responses |
|
|
| `MAX_TOOL_RESPONSE_CHARS` | No | `20000` | Max chars in text fields |
|
|
| `REQUEST_TIMEOUT_SECONDS` | No | `30` | Upstream timeout for Gitea calls |
|
|
| `SECRET_DETECTION_MODE` | No | `mask` | `off`, `mask`, `block` |
|
|
| `REPO_AUTHZ_CACHE_TTL_SECONDS` | No | `60` | TTL for cached per-user repository permission checks |
|
|
|
|
## Write Mode
|
|
|
|
| Variable | Required | Default | Description |
|
|
|---|---|---|---|
|
|
| `WRITE_MODE` | No | `false` | Enables write tools |
|
|
| `WRITE_REPOSITORY_WHITELIST` | Required if write mode enabled and allow-all disabled | empty | Comma-separated `owner/repo` allow list |
|
|
| `WRITE_ALLOW_ALL_TOKEN_REPOS` | No | `false` | Allow all repos accessible by token |
|
|
|
|
## Automation
|
|
|
|
| Variable | Required | Default | Description |
|
|
|---|---|---|---|
|
|
| `AUTOMATION_ENABLED` | No | `false` | Enables automation endpoints |
|
|
| `AUTOMATION_SCHEDULER_ENABLED` | No | `false` | Enables scheduler loop |
|
|
| `AUTOMATION_STALE_DAYS` | No | `30` | Age threshold for stale issue checks |
|
|
|
|
## Legacy Compatibility Variables
|
|
|
|
These are retained for compatibility but not used for OAuth-protected MCP tool execution:
|
|
|
|
- `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`
|