olemd/forgejo-mcp-broker
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
forgejo-mcp-broker/README.md
Ole-Morten Duesund c18120c470 docs(deploy): Caddy front-end example + walkthrough (forgejo-mcp-broker-r2c) 
Adds deploy/caddy/Caddyfile and docs/deploy-caddy.md, the front-end
half of the production deployment that pairs with deploy-podman.md.

Caddyfile:
  - reverse_proxy with flush_interval -1 (mandatory for /mcp SSE)
  - structured JSON access log to a separate file
  - validated with `caddy validate` and formatted with `caddy fmt`
  - omits explicit X-Forwarded-{For,Proto,Host} since Caddy forwards
    them by default (caddy validate flags them as redundant)

deploy-caddy.md walks operators through:
  - why a reverse proxy at all (TLS, SSE, future rate limits)
  - the host-header trap and why FJMCP_BROKER_PUBLIC_URL is the
    trusted source of issuer URLs (cross-references the existing
    TestDiscovery_IssuerIgnoresHostHeader regression)
  - SSE buffering as the most common deployment foot-gun
  - optional rate-limit recipe via caddy-ratelimit (defers to backlog
    issue -ttl)
  - troubleshooting for the four failure modes the broker has actually
    seen during dev: wrong issuer, buffered SSE, unreachable upstream,
    TLS conflict

README updated to link both deploy guides and the deploy/ subtree.

Closes forgejo-mcp-broker-r2c.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 17:49:25 +02:00

2.5 KiB
Raw Permalink Blame History

forgejo-mcp-broker

OAuth 2.1 authorization server and MCP session broker for forgejo-mcp.

Lets MCP clients such as Claude.ai connect to a Forgejo instance through a single public HTTPS endpoint, with per-user authentication delegated to Forgejo's own OAuth2 provider. The broker handles the OAuth dance, then spawns a dedicated forgejo-mcp --transport stdio subprocess for each authenticated session, scoped to the authenticated user's Forgejo access token.

Status: Planning. No code yet. See docs/design.md for the architecture and docs/plan.md for the phased implementation plan.

How it fits

Claude.ai ──HTTPS──▶ Caddy ──▶ fjmcp-broker ──stdio──▶ forgejo-mcp  ──▶ Forgejo API
                                  (this)              (one per user     (per-user
                                                       session)          token)
  • fjmcp-broker (this project): one long-running process. Handles OAuth discovery, dynamic client registration, the authorization-code flow against Forgejo, session lifecycle, and stdio-to-streamable-HTTP bridging.
  • forgejo-mcp (existing project): used as-is. Spawned per-session with the authenticated user's FORGEJO_ACCESS_TOKEN in the environment.
  • Caddy: terminates TLS for the public hostname and reverse-proxies to the broker.

Why a broker instead of adding OAuth to forgejo-mcp?

Process-level isolation. Each user's Forgejo token lives in exactly one subprocess — the broker never needs to demultiplex tokens inside a single shared client. This keeps forgejo-mcp's sync.Once singleton-client pattern valid and avoids a refactor of every tool handler. Full trade-off in docs/design.md.

Quick map

File What
docs/design.md Architecture, components, token flow, deployment, security
docs/plan.md Seven-phase implementation plan with acceptance criteria
docs/deploy-podman.md End-to-end production deploy with rootless podman + Quadlet
docs/deploy-caddy.md Caddy reverse-proxy front-end (TLS, SSE, host-header defense)
Containerfile Multi-stage build; bundles broker + pinned forgejo-mcp
deploy/podman/ Quadlet unit and example env file
deploy/caddy/ Example Caddyfile

License

MIT © 2026 Ole-Morten Duesund.