Ole-Morten Duesund
c18120c470
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>
39 lines
2.5 KiB
Markdown
39 lines
2.5 KiB
Markdown
# forgejo-mcp-broker
|
|
|
|
OAuth 2.1 authorization server and MCP session broker for [forgejo-mcp](https://codeberg.org/goern/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`](docs/design.md) for the architecture and [`docs/plan.md`](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`](docs/design.md).
|
|
|
|
## Quick map
|
|
|
|
| File | What |
|
|
|---|---|
|
|
| [`docs/design.md`](docs/design.md) | Architecture, components, token flow, deployment, security |
|
|
| [`docs/plan.md`](docs/plan.md) | Seven-phase implementation plan with acceptance criteria |
|
|
| [`docs/deploy-podman.md`](docs/deploy-podman.md) | End-to-end production deploy with rootless podman + Quadlet |
|
|
| [`docs/deploy-caddy.md`](docs/deploy-caddy.md) | Caddy reverse-proxy front-end (TLS, SSE, host-header defense) |
|
|
| [`Containerfile`](Containerfile) | Multi-stage build; bundles broker + pinned forgejo-mcp |
|
|
| [`deploy/podman/`](deploy/podman/) | Quadlet unit and example env file |
|
|
| [`deploy/caddy/`](deploy/caddy/) | Example Caddyfile |
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE) © 2026 Ole-Morten Duesund.
|