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.6 KiB

Raw Permalink Blame History

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 (for uvx) or pip.

Run it

With uvx (no install):

GITEA_URL=https://git.hiddenden.cafe \
GITEA_TOKEN=<pat> \
uvx aegis-gitea-mcp

With pip:

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:

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):

{
  "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:

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 for the full variable reference and write-mode.md for the write-mode model.

2.6 KiB Raw Permalink Blame History