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

2.3 KiB

Raw Blame History

Deployment

Secure Defaults

Default bind is 127.0.0.1.
Binding 0.0.0.0 requires ALLOW_INSECURE_BIND=true.
Write mode disabled by default.
Policy checks run before tool execution.
OAuth-protected MCP challenge responses are enabled by default for tool calls.

Local stdio install (single user)

The local transport needs only the core package (no web stack):

pip install aegis-gitea-mcp            # or: uvx aegis-gitea-mcp
GITEA_URL=https://git.hiddenden.cafe GITEA_TOKEN=<pat> aegis-gitea-mcp

It authenticates with your Gitea PAT, runs policy + WRITE_MODE + audit, and serves over stdio for Claude Desktop / Claude Code. See local-quickstart.md.

Local Development (HTTP server)

make install-dev
cp .env.example .env
make run

The HTTP server requires the web stack. From a published package that is the [server] extra:

pip install 'aegis-gitea-mcp[server]'
aegis-gitea-mcp-server

Docker

Use docker/Dockerfile:

Multi-stage image build.
Non-root runtime user.
Production env flags (NODE_ENV=production, ENVIRONMENT=production).
Only required app files copied.
Healthcheck on /health.

Run examples:

docker compose --profile prod up -d
docker compose --profile dev up -d

CI/CD (Gitea Workflows)

Workflows live in .gitea/workflows/:

lint.yml: ruff + format checks + mypy.
test.yml: lint + tests + coverage fail-under 80.
docker.yml: lint + test + docker smoke-test gating; image publish on push to main/dev and on approved PR review targeting main/dev; tags include commit SHA plus latest (main) or dev (dev).

Docker publish settings:

vars.PUSH_IMAGE=true enables registry push.
vars.REGISTRY_IMAGE sets the target image name (for example registry.example.com/org/aegis-gitea-mcp).
vars.REGISTRY_HOST is optional and overrides the login host detection.
secrets.REGISTRY_USER and secrets.REGISTRY_TOKEN are required when push is enabled.

Production Recommendations

Place MCP behind TLS reverse proxy.
Set PUBLIC_BASE_URL=https://<your-mcp-domain> so OAuth metadata advertises HTTPS endpoints.
Restrict inbound traffic to expected clients.
Persist and monitor audit logs.
Monitor /metrics and auth-failure events.
Rotate OAuth client credentials when required.

2.3 KiB Raw Blame History