feat!: full-access Gitea MCP server (1.0.0): full API coverage, stdio + streamable HTTP, admin and per-user OAuth #71

Merged

Latte merged 70 commits from feat/full-api-coverage into dev 2026-10-14 17:25:25 +00:00

Conversation 0 Commits 70 Files Changed 216

+71303 -16609

Latte commented 2026-10-14 16:25:51 +00:00

Owner

Copy link

Copy source

Rebuilds AegisGitea-MCP as a complete, full-access MCP bridge to the Gitea API. Breaking change: all tool names, the HTTP adapter, the YAML policy and API keys change (version 1.0.0.dev0). Design decisions are in docs/adr/0001-0006, the audit and chunk plan in docs/audit.md.

What changes

• 538 tools: one per operation of the pinned Gitea 28.1.0 swagger (spec/gitea-swagger.v1.json), generated into catalog/tools.json (gitea_<domain>_<action>), plus gitea_api_request for endpoints newer than the spec. Everything is enabled by default, including admin, secrets, deletes and Sudo. READ_ONLY, TOOLSETS and DISABLED_TOOLS restrict exposure.
• Official MCP Python SDK v2 (low-level Server, since FastMCP/MCPServer cannot take raw JSON schemas): stdio and streamable HTTP from one codebase, /health readiness endpoint.
• Auth: admin-token mode (stdio, static bearer on HTTP, constant-time compare) and per-user OAuth (our server is the OAuth AS for MCP clients with dynamic client registration and a consent page, and a Gitea OAuth client upstream; calls run with the user's own Gitea token, identity in every result; encrypted token store). A non-loopback bind refuses to start without auth.
• Executor: path encoding verified against the live instance, pagination metadata, binary/text handling, sanitized error mapping, exact secret redaction, untrusted-content labelling on every result.
• aegis-gitea-mcp setup: verifies reachability, admin rights and token scopes, registers the OAuth app, writes .env (0600) without echoing secrets, prints client configs for Claude, Claude Code, Mistral Le Chat and local tools plus a compose and reverse-proxy snippet.
• Removed: FastAPI adapter, hand-rolled JSON-RPC, YAML policy engine, resource-type gate, dead API keys, automation and metrics.

Verification

• Unit: 1553 passed, coverage 98% (gate raised to 90%).
• Live integration against a disposable digest-pinned Gitea 28.1.0: scenario tests (org, repo, issue, PR, review, merge, release, secrets, variables, webhooks, admin, Sudo, packages, a real Actions run via act_runner), a sweep calling all 538 tools against a pinned per-tool baseline (521 with a 2xx; the rest documented in docs/integration-coverage.md), per-user mode, the setup command.
• MCP smoke tests over stdio, streamable HTTP and the built image with real SDK clients.
• Security phase: threat model in docs/security.md, 19 review findings fixed or waived with reasons (docs/security-findings.md), dedicated tests/security suite; pip-audit, ruff S, gitleaks and Trivy clean.
• CI: 8 jobs (gitleaks, lint, test-unit, test-integration, test-mcp, build-and-push, docs-check, security), green on the feature branch.

Known limitations and owner follow-ups

• gitea_user_create_token, gitea_user_get_tokens, gitea_user_delete_access_token require basic auth with a password (Gitea rule) and return 401 through this server.
• The tool list is large (538); for clients that struggle, use TOOLSETS.
• Reserve the aegis-gitea-mcp name on PyPI; docs install from the Gitea package index.
• Enable "require approval for workflows from forks" in the repository settings (docs/deployment.md).

Rebuilds AegisGitea-MCP as a complete, full-access MCP bridge to the Gitea API. Breaking change: all tool names, the HTTP adapter, the YAML policy and API keys change (version 1.0.0.dev0). Design decisions are in docs/adr/0001-0006, the audit and chunk plan in docs/audit.md. ## What changes - 538 tools: one per operation of the pinned Gitea 28.1.0 swagger (`spec/gitea-swagger.v1.json`), generated into `catalog/tools.json` (`gitea_<domain>_<action>`), plus `gitea_api_request` for endpoints newer than the spec. Everything is enabled by default, including admin, secrets, deletes and Sudo. `READ_ONLY`, `TOOLSETS` and `DISABLED_TOOLS` restrict exposure. - Official MCP Python SDK v2 (low-level `Server`, since FastMCP/`MCPServer` cannot take raw JSON schemas): stdio and streamable HTTP from one codebase, `/health` readiness endpoint. - Auth: admin-token mode (stdio, static bearer on HTTP, constant-time compare) and per-user OAuth (our server is the OAuth AS for MCP clients with dynamic client registration and a consent page, and a Gitea OAuth client upstream; calls run with the user's own Gitea token, identity in every result; encrypted token store). A non-loopback bind refuses to start without auth. - Executor: path encoding verified against the live instance, pagination metadata, binary/text handling, sanitized error mapping, exact secret redaction, untrusted-content labelling on every result. - `aegis-gitea-mcp setup`: verifies reachability, admin rights and token scopes, registers the OAuth app, writes `.env` (0600) without echoing secrets, prints client configs for Claude, Claude Code, Mistral Le Chat and local tools plus a compose and reverse-proxy snippet. - Removed: FastAPI adapter, hand-rolled JSON-RPC, YAML policy engine, resource-type gate, dead API keys, automation and metrics. ## Verification - Unit: 1553 passed, coverage 98% (gate raised to 90%). - Live integration against a disposable digest-pinned Gitea 28.1.0: scenario tests (org, repo, issue, PR, review, merge, release, secrets, variables, webhooks, admin, Sudo, packages, a real Actions run via act_runner), a sweep calling all 538 tools against a pinned per-tool baseline (521 with a 2xx; the rest documented in docs/integration-coverage.md), per-user mode, the setup command. - MCP smoke tests over stdio, streamable HTTP and the built image with real SDK clients. - Security phase: threat model in docs/security.md, 19 review findings fixed or waived with reasons (docs/security-findings.md), dedicated `tests/security` suite; pip-audit, ruff S, gitleaks and Trivy clean. - CI: 8 jobs (gitleaks, lint, test-unit, test-integration, test-mcp, build-and-push, docs-check, security), green on the feature branch. ## Known limitations and owner follow-ups - `gitea_user_create_token`, `gitea_user_get_tokens`, `gitea_user_delete_access_token` require basic auth with a password (Gitea rule) and return 401 through this server. - The tool list is large (538); for clients that struggle, use `TOOLSETS`. - Reserve the `aegis-gitea-mcp` name on PyPI; docs install from the Gitea package index. - Enable "require approval for workflows from forks" in the repository settings (docs/deployment.md).

Latte added 70 commits 2026-10-14 16:25:51 +00:00

docs: phase 0 audit, chunk plan, ADRs and pinned Gitea 28.1.0 swagger ... 8b7bb7205c

Inventory and gap analysis of the 0.2.0 codebase against the full Gitea API
and the official gitea-mcp toolset, the B1..B11 + security chunk plan, ADRs
0001-0006 for the full-access rebuild, SDK/OAuth research notes, and the
instance swagger pinned for tool generation. The audit-logging doc moves to
docs/audit-logging.md.

build: switch to uv, hatchling and ruff-only tooling c0b22c531e

refactor!: remove legacy adapters, policy engine and API-key auth ... 4ac9626eb5

Removes the FastAPI server, hand-rolled MCP protocol, tool registry and
tools, YAML policy, resource-type authz, API-key and OAuth proxy modules,
automation, observability, cache, the old Gitea client and stdio adapter,
the key-management scripts and their tests (ADR 0006).

feat: new settings, CLI skeleton and interface skeletons ... b82e2866cb

Adds the pydantic-settings Settings with validated GITEA_URL, OAuth scopes
and toolsets, the argparse CLI skeleton, catalog.model, identity and
GiteaAPIError. Test fixtures now isolate env, cwd and state paths in tmp.

docs: rewrite contributor contract for the full-access model c246f5c267

test: add live-Gitea integration harness (opt-in, Docker) 465a365d89

feat: add the aegis-gitea-mcp setup command ... 1d223e6799

Verifies the Gitea instance, token and scopes, registers or reuses the aegis-gitea-mcp OAuth app, generates missing secrets and writes a 0600 env file from the template. Prints client configs and deployment snippets without any secret value.

test: fix integration harness lint findings a807a70556

feat: generate the tool catalog from the pinned swagger ... 041b3ea7ff

Adds scripts/generate_catalog.py (with --check), the naming rules, schema conversion, the committed tools.json for all 537 operations and the load_catalog() loader.

feat: add Gitea request executor with result envelope, pagination and redaction 9e50859133

ci: single Gitea Actions pipeline, uv-based image, scoped docker cleanup ... 1a039e32ab

Replace lint/test/docker workflows with ci.yml (gitleaks, lint, test-unit, test-integration, test-mcp, build-and-push, docs-check, security). Rebuild the Dockerfile as a digest-pinned multi-stage uv build running as uid 1000, add .dockerignore, a hardened compose file and a gitleaks config. The integration harness now falls back to /etc/hostname and /proc/self to find its own container.

fix: key slash encoding on route, redact more request secrets, bound JSON depth and uploads ... 156e963e21

Slash safety is decided per (path template, parameter) so single-segment
routes such as releases/tags/{tag} and editorconfig/{filepath} keep %2F.
Adds authorization_header, remote_password, mirror_password, mirror_token and
the AWS key fields to the redacted request fields. Deeply nested JSON from
Gitea is treated as text instead of raising RecursionError, and base64
uploads are capped before decoding.

fix: annotate POST render endpoints read-only and irreversible POSTs destructive 6b11d29919

test: satisfy lint in catalog override test 6c9b2b74ca

fix: harden setup against plain http, untrusted output and unsafe values ... 517c675048

Require consent before sending the token over plain http to a non-loopback
host, strip control characters from server-supplied text, restrict env values
and tokens to printable ASCII, validate the URLs like other env values and
fsync the directory after the atomic replace.

fix: keep the harness admin password out of the docker exec argv 72462105f5

docs: document result redaction, credential-issuing operations and path encoding 10c8b21cf5

docs: correct the module lists in AGENTS.md and CLAUDE.md 581ca67bf8

feat: add MCP server core, stdio and streamable HTTP transports and serve command ... c9e2c481e7

Low-level SDK server built from the catalog plus gitea_api_request, with TOOLSETS/READ_ONLY/DISABLED_TOOLS filters, schema validation without value echo, one audit event per call, static bearer verifier, identity resolver hook, /health, DNS-rebinding protection, rate limiting and fail-closed startup checks.

feat: add docs drift check 68bd8700dc

docs: rewrite README and docs for the full-access design, generate tool inventory 7c7cfc05ff

docs: regenerate tool inventory after annotation overrides e139ae826f

fix: serialize the admin login lookup so concurrent first calls send one request c73a7cc3ce

fix: report an invalid --port with a short message instead of listing every choice a3222d5ebe

fix: fail closed on an unwritable audit log, bound the rate limiter and harden startup ... cf3d2e17d3

The audit logger is opened at startup (exit 2 on failure) and obtained before
every call, which is refused with audit_unavailable otherwise. Audit records only
take validated path and sudo values and use the request id as correlation id. The
rate limiter evicts idle keys, caps tracked keys, audits the first excess per key
and window and uses the settings passed to the app. FORWARDED_ALLOW_IPS is now a
setting, and startup warns about a missing host allow-list and unavailable OAuth.

fix: keep the embedded env template in sync with .env.example cfbf1fb893

test: add MCP smoke tests over stdio and streamable HTTP, from source and from the built image 5e144772b2

feat: add per-user OAuth mode proxying sign-in to Gitea ... 566d0b65dd

Authorization server for MCP clients (SDK provider with dynamic client
registration, PKCE, refresh rotation and revocation) that signs users in
through Gitea and runs tool calls with the user's own Gitea token.

- consent page with CSRF protection and a browser-binding cookie on the
  Gitea callback (confused-deputy protection for the shared Gitea app)
- encrypted token store (Fernet, HKDF-derived key, 0600, atomic writes,
  symlink and corrupt-file refusal); our tokens stored only as hashes
- tokens bound to the MCP endpoint resource and the gitea scope; the
  static bearer keeps working next to OAuth
- code replay and refresh token reuse revoke the grant
- automatic upstream refresh with per-session locking; invalid_grant
  ends the session and never falls back to the admin token
- OAuth-only deployments (no GITEA_TOKEN, no bearer) may start
- rate limit on the OAuth endpoints, query strings dropped from access logs

test: cover the per-user OAuth flow, threat cases, store and startup 7286440d64

fix: drop the obsolete OAuth-unavailable startup warning test e02cede9f2

fix: redact identity secrets through a public hook and mask issued agm_ tokens ... ce5ae6caa5

Identity gains a redact field that the executor honours, so the OAuth
resolver no longer needs an executor subclass overriding private
internals. Opaque agm_ tokens issued by our authorization server are now
masked by the secret patterns wherever they appear in content.

docs: security threat model and review findings 5baf73f38b

fix: cap and type-check the unauthenticated consent POST body (SEC-01) d5ca530db3

fix: redact stored webhook authorization headers and other secret fields by key name (SEC-02) 5b622e64e2

fix: write-ahead audit entry so calls stop when the audit log stops accepting writes (SEC-03) 43eebd3089

fix: record the calling client and only schema-known names in audit entries (SEC-12, SEC-18) fd5e4b71f3

fix: create the audit log 0600 in a 0700 directory and refuse symlinks (SEC-11) 7307214ab6

fix: load ./.env only when private and owned, add --env-file and AEGIS_ENV_FILE (SEC-04) 79aa4f7fc0

fix: add OAUTH_REDIRECT_ALLOWLIST for client registration and waive the open default (SEC-05) 8be859243d

fix: require a matching Origin on consent and name the binding cookie per flow (SEC-17, SEC-19) 782d416e46

fix: rate limit /token and /revoke, bucket IPv6 by /64 and warn about untrusted forwarded headers (SEC-08) f57c237bed

fix: quota pending sign-ins and registrations per address, keep young clients, write the store off the loop (SEC-09) 87f048cc4d

fix: reject whitespace and control characters in base URLs and warn on plain http Gitea (SEC-10) d96c3ac604

fix: refuse a token store directory owned by another user or left writable (SEC-13) 6f7a3c0e5b

ci: pin actions to commit SHAs, guard Docker jobs from forks, scan the image, gate publish on security (SEC-06, SEC-07, SEC-14, SEC-15, SEC-16) 766968fa42

test: security suite for auth, startup, redaction; fix: mask secrets in object keys fef80a5b21

fix: redact a data field in Action secret responses; test: secret echo suite 421a6507c0

fix: reject a trailing newline in sudo; test: malformed input suite 984673e8cf

fix: do not echo setting values in configuration errors; test: stdio and config redaction 0f5f5cdd95

ci: raise the coverage gate to 90 percent; docs: reconcile OAuth docs with the implementation d7cac91175

docs: record S2 results, mark findings fixed or waived, update the security model f86b9b529c

test: integration helpers and org, team and repo scenarios through the MCP server 51c766b231

test: issue, pull request, release, secret, variable and webhook scenarios 825c3c93e2

test: admin, sudo, notification, user and package scenarios 29b12bfe0d

test: Actions run scenario on an act_runner container 22c8157ca4

test: sweep every tool through the MCP server against a seeded Gitea 303bd9aa21

test: per-user OAuth mode against the live instance fed75b17c8

test: setup command against the live instance ae6d83c3bd

test: integration coverage report, suite docs and harness isolation fix 446ec11954

test: sweep checks the audit trail and keeps the unit test free of em dashes 8786502b8c

docs: fix the claude mcp add form, pin the package index, document known limitations ... 59d0e43aae

The --env option swallowed the server name, so the stdio command is reordered. uvx now always
names the project registry because the package name is not registered on public PyPI.
README gains a Known limitations section, the READ_ONLY wording is corrected, packaging.md
warns about --extra-index-url and the Le Chat admin requirement is mentioned.

docs: describe the write-ahead audit model and bring the contract files up to date 8ff67f5859

ci: build under a per-run local tag, untag registry refs only, gate the image push on every test job 4e108771f8

docs: describe the per-run build tag and the push gate 84b361962e

test: pin the sweep outcome per tool in a baseline, seed a GPG key, fail loudly when seeding finds no run 9e51f72ec9

test: manage runners at every scope, rerun and delete a completed run, fail when the runner is required 7dc749d7cd

test: merged-commit lookup, scheduled auto-merge cancel and repository transfer answers 84fa29e380

test: write failure paths, expired OAuth token, non-admin admin-tool refusals and webhook credential leak checks d1b9a4845e

test: regenerate the coverage report and the sweep baseline, document the baseline and the runner policy 79bce1d210

ci: keep the publish workflow comment free of em dashes 3fead4e121

Latte merged commit a4800951ef into dev 2026-10-14 17:25:25 +00:00

Latte deleted branch feat/full-api-coverage 2026-10-14 17:25:26 +00:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

Compat/Breaking

Breaking change, not backwards compatible

Kind/Bug

Something is not working

Kind/Chore

Maintenance, deps, CI/CD

Kind/Documentation

Documentation changes

Kind/Enhancement

Improve existing functionality

Kind/Feature

New functionality

Kind/Refactor

Code restructuring, no behavior change

Kind/Security

Security-related issue

Priority/Critical

Must be addressed immediately

Priority/High

Important, address soon

Priority/Low

Nice to have

Priority/Medium

Normal priority

Reviewed/Confirmed

Issue has been confirmed

Reviewed/Duplicate

Already tracked elsewhere

Reviewed/Won't Fix

Acknowledged but won't be addressed

Status/Blocked

Blocked by an external dependency

Status/In Progress

Currently being worked on

Status/Need More Info

Needs more information to proceed

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

Barback Bot Bartender Doorman Bot Latte (Latte) mixologist Bot Sommelier Bot

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Hiddenden/AegisGitea-MCP#71