docs: README for Consumers of the Image (#9) #30

Merged

piscis merged 1 commit from piscis/forgejo-issue-9-implement into main

2026-09-30 17:35:26 +00:00

piscis commented

2026-09-30 17:24:31 +00:00

Owner

Closes #9

Summary

Replaces the empty README with documentation for Consumers, one section per item in the ticket:

README.md
├── What this is      # multi-arch build of Upstream (ADR 0001), Codeberg mirror note (ADR 0002),
│                     # licenses: repo MIT, Image contains Upstream's GPL-3.0 software, source = Upstream at the Pin commit
├── Quick start       # docker run -i --rm -e FORGEJO_URL -e FORGEJO_ACCESS_TOKEN …:3, plus an initialize check
├── Claude Code setup # stdio .mcp.json + the equivalent `claude mcp add --scope project`
├── HTTP mode         # CMD override: --transport http --host 0.0.0.0 --allowed-hosts localhost; client URL + header
├── Tags              # :3 vs :3.2.0-rN, Rebuilds, Renovate bump PRs (#8)
└── For maintainers   # pin.env, raising the Pin for a Rebuild, make verify-pin/build/smoke-test, how CI publishes

Tokens only ever come from the environment: -e NAME pass-through for stdio, and "Authorization": "token ${FORGEJO_ACCESS_TOKEN}" (expanded by Claude Code, single-quoted for claude mcp add) for HTTP. In HTTP mode the server gets no token at all; Upstream's default passthrough auth uses the caller's header.

Evidence

Every Consumer snippet was pulled out of README.md and run verbatim against code.vicoli.de/vicoli-oss/forgejo-mcp:3, with a clean empty DOCKER_CONFIG (no docker login) and the local Image removed first so it was pulled anonymously. FORGEJO_URL=https://code.vicoli.de; FORGEJO_ACCESS_TOKEN was mapped from the environment and never written anywhere.

Snippet	Result
Quick start `docker run -i --rm -e FORGEJO_URL -e FORGEJO_ACCESS_TOKEN …:3`	anonymous pull OK, `Connection verification successful`, `MCP server ready for stdio communication`
Quick start `initialize` check	`{"jsonrpc":"2.0","id":1,"result":{…,"serverInfo":{"name":"Forgejo MCP Server","version":"3.2.0"}}}`
Claude Code stdio `.mcp.json`	`claude -p --strict-mcp-config --mcp-config <snippet>` called `mcp__forgejo__get_my_user_info` and got the right login
`claude mcp add --scope project forgejo -- docker run …`	writes the same entry as the `.mcp.json` snippet, with 0 token occurrences in the file; `claude mcp list` shows it as Pending approval (the README says so). Without `--scope project` it shows `✔ Connected`
HTTP `docker run -d … --transport http --host 0.0.0.0 --allowed-hosts localhost`	starts and listens on `[::]:8080`. curl `initialize` to `http://localhost:8080/mcp` with the header → 200. Without the header → 401. Via `127.0.0.1` → 403 (the README says to use `localhost`)
HTTP `.mcp.json`	`claude -p` called `get_my_user_info` and got the right login. The same config with `FORGEJO_ACCESS_TOKEN` unset fails ("token is not configured"), so the header comes from the environment
`claude mcp add --scope project --transport http … --header 'Authorization: token ${FORGEJO_ACCESS_TOKEN}'`	the written `.mcp.json` equals the README's HTTP snippet (jq diff), with 0 token occurrences. Local scope: `✔ Connected`
`docker rm -f forgejo-mcp`	removes the server

Maintainer snippet: make verify-pin build smoke-test PLATFORMS=linux/arm64 → smoke-test [linux/arm64]: PASS: 156 tools listed.

I also checked the glossary terms (Upstream, Upstream Version, Image, Rebuild, Consumer, Pin): they're capitalised as defined, "pin" is never used as a verb, and "MCP client" is only used for the software that connects to the server.

Merge Danger

Door: two-way

Docs only; no build, CI or Image change.

Blast Radius: none

Merging touches no Pin values, so CI builds and smoke-tests but publishes nothing.

Closes #9 ## Summary Replaces the empty README with documentation for Consumers, one section per item in the ticket: ```text README.md ├── What this is # multi-arch build of Upstream (ADR 0001), Codeberg mirror note (ADR 0002), │ # licenses: repo MIT, Image contains Upstream's GPL-3.0 software, source = Upstream at the Pin commit ├── Quick start # docker run -i --rm -e FORGEJO_URL -e FORGEJO_ACCESS_TOKEN …:3, plus an initialize check ├── Claude Code setup # stdio .mcp.json + the equivalent `claude mcp add --scope project` ├── HTTP mode # CMD override: --transport http --host 0.0.0.0 --allowed-hosts localhost; client URL + header ├── Tags # :3 vs :3.2.0-rN, Rebuilds, Renovate bump PRs (#8) └── For maintainers # pin.env, raising the Pin for a Rebuild, make verify-pin/build/smoke-test, how CI publishes ``` Tokens only ever come from the environment: `-e NAME` pass-through for stdio, and `"Authorization": "token ${FORGEJO_ACCESS_TOKEN}"` (expanded by Claude Code, single-quoted for `claude mcp add`) for HTTP. In HTTP mode the server gets no token at all; Upstream's default passthrough auth uses the caller's header. ## Evidence Every Consumer snippet was pulled out of README.md and run verbatim against `code.vicoli.de/vicoli-oss/forgejo-mcp:3`, with a clean empty `DOCKER_CONFIG` (no `docker login`) and the local Image removed first so it was pulled anonymously. `FORGEJO_URL=https://code.vicoli.de`; `FORGEJO_ACCESS_TOKEN` was mapped from the environment and never written anywhere. | Snippet | Result | |---|---| | Quick start `docker run -i --rm -e FORGEJO_URL -e FORGEJO_ACCESS_TOKEN …:3` | anonymous pull OK, `Connection verification successful`, `MCP server ready for stdio communication` | | Quick start `initialize` check | `{"jsonrpc":"2.0","id":1,"result":{…,"serverInfo":{"name":"Forgejo MCP Server","version":"3.2.0"}}}` | | Claude Code stdio `.mcp.json` | `claude -p --strict-mcp-config --mcp-config <snippet>` called `mcp__forgejo__get_my_user_info` and got the right login | | `claude mcp add --scope project forgejo -- docker run …` | writes the same entry as the `.mcp.json` snippet, with 0 token occurrences in the file; `claude mcp list` shows it as *Pending approval* (the README says so). Without `--scope project` it shows `✔ Connected` | | HTTP `docker run -d … --transport http --host 0.0.0.0 --allowed-hosts localhost` | starts and listens on `[::]:8080`. curl `initialize` to `http://localhost:8080/mcp` with the header → 200. Without the header → 401. Via `127.0.0.1` → 403 (the README says to use `localhost`) | | HTTP `.mcp.json` | `claude -p` called `get_my_user_info` and got the right login. The same config with `FORGEJO_ACCESS_TOKEN` unset fails ("token is not configured"), so the header comes from the environment | | `claude mcp add --scope project --transport http … --header 'Authorization: token ${FORGEJO_ACCESS_TOKEN}'` | the written `.mcp.json` equals the README's HTTP snippet (jq diff), with 0 token occurrences. Local scope: `✔ Connected` | | `docker rm -f forgejo-mcp` | removes the server | Maintainer snippet: `make verify-pin build smoke-test PLATFORMS=linux/arm64` → `smoke-test [linux/arm64]: PASS: 156 tools listed`. I also checked the glossary terms (Upstream, Upstream Version, Image, Rebuild, Consumer, Pin): they're capitalised as defined, "pin" is never used as a verb, and "MCP client" is only used for the software that connects to the server. ## Merge Danger **Door:** two-way Docs only; no build, CI or Image change. **Blast Radius:** none Merging touches no Pin values, so CI builds and smoke-tests but publishes nothing.

piscis added 1 commit

2026-09-30 17:24:31 +00:00

docs: README for Consumers of the Image (#9 )

ci / build (pull_request) Successful in 19s

Details

693adfe030

What the Image is (licenses, Upstream at the Pin, Codeberg mirror), quick
start over stdio, Claude Code setup, HTTP mode, tags, and a maintainer
section on the Pin, local builds and releases.

piscis merged commit 955ef09e89 into main

2026-09-30 17:35:26 +00:00

piscis deleted branch piscis/forgejo-issue-9-implement

2026-09-30 17:35:26 +00:00

piscis referenced this pull request from a commit

2026-09-30 17:35:27 +00:00

Merge pull request 'docs: README for Consumers of the Image (#9)' (#30) from piscis/forgejo-issue-9-implement into main