Files

T

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

5.1 KiB

Raw Blame History

Configuration

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
`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

5.1 KiB Raw Blame History