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 018f56a4ad feat(deploy): rootless podman + Quadlet deployment (forgejo-mcp-broker-8yd) 
Adds a multi-stage Containerfile, Quadlet unit, and operator
walkthrough for a production deploy. The broker spawns forgejo-mcp
per session, so the image bundles both binaries — broker built from
this repo, forgejo-mcp pinned via FORGEJO_MCP_VERSION build-arg
(default 2.18.0).

Image stages:
  1. golang:alpine compiles the broker with ldflags-stamped buildinfo
  2. golang:alpine clones forgejo-mcp at the pinned tag and compiles it
  3. distroless static-nonroot copies both binaries; uid 65532

Persistent state via the named volume `fjmcp-state` mounted at /data.
SQLite WAL + SHM sidecars live alongside broker.db on the same volume,
so a container swap or image upgrade preserves all OAuth clients,
issued tokens, and refresh-token history. Verified end-to-end:

  podman run --rm -d -v fjmcp-test-state:/data ... fjmcp-broker:test
  curl /healthz                              # store: ok, broker.db created
  podman stop fjmcp-test
  podman run --rm -d -v fjmcp-test-state:/data ... fjmcp-broker:test
  curl /healthz                              # store: ok, same broker.db

  ls volume       → broker.db, broker.db-shm, broker.db-wal all present

Quadlet unit (deploy/podman/fjmcp-broker.container) drops into
~/.config/containers/systemd/, reads secrets from a 0600 env file
outside the unit, publishes :8080 on loopback for Caddy to front.

Makefile gains `image` and `image-run` targets. README links to the
new docs/deploy-podman.md walkthrough.

Closes forgejo-mcp-broker-8yd.

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

2.3 KiB
Raw 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
Containerfile Multi-stage build; bundles broker + pinned forgejo-mcp
deploy/podman/ Quadlet unit and example env file

License

MIT © 2026 Ole-Morten Duesund.