Document adopting the Image via .mcp.json #32

New issue

Closed

opened 2026-09-30 17:32:01 +00:00 by piscis · 0 comments

piscis commented

2026-09-30 17:32:01 +00:00

Owner

What to build

A Consumer landing on the README can adopt the Image in their own project by copying one .mcp.json snippet. The README already has a "Claude Code setup" section (from #9); this ticket brings it in line with this repo's own dogfooded config from the blocking ticket and fills in what's missing.

Update the existing section:

Snippet: replace it with this repo's project MCP config exactly: docker run --rm -i --pull=always, :3, bare -e FORGEJO_ACCESS_TOKEN, and -e FORGEJO_URL=${FORGEJO_URL:-https://code.vicoli.de}. Update the claude mcp add one-liner to match.
Prose: FORGEJO_URL now has a default, so "export both variables" becomes "export FORGEJO_ACCESS_TOKEN; set FORGEJO_URL only to point at another instance".

Add to that section (each point one or two sentences):

Prerequisites: Docker and a Forgejo personal access token.
The token is read from FORGEJO_ACCESS_TOKEN in the environment Claude Code starts in; if you already keep your token under another name, add e.g. export FORGEJO_ACCESS_TOKEN=$FORGEJO_TOKEN to your shell profile.
Token scopes are the only guardrail: Upstream has no read-only mode or tool filtering, so grant the smallest scopes that cover your use.
The same command/args work in any stdio MCP client (only Claude Code's .mcp.json is shown).
Gotcha: if Forgejo runs on the Consumer's own machine, localhost inside the container is not the host; use host.docker.internal.

Already covered, leave as is: exact pinning to X.Y.Z-rN (Tags section), HTTP mode.

Out of scope (decided): per-client snippets, CI check of the snippet, ADR, glossary changes.

Acceptance criteria

The README snippet and the claude mcp add line match this repo's project MCP config exactly
The Claude Code setup section covers every "Add" point above, and no longer says both variables must be exported
Wording uses glossary terms (Image, Consumer, Upstream)

Blocked by

## What to build A Consumer landing on the README can adopt the Image in their own project by copying one `.mcp.json` snippet. The README already has a "Claude Code setup" section (from #9); this ticket brings it in line with this repo's own dogfooded config from the blocking ticket and fills in what's missing. Update the existing section: - **Snippet**: replace it with this repo's project MCP config exactly: `docker run --rm -i --pull=always`, `:3`, bare `-e FORGEJO_ACCESS_TOKEN`, and `-e FORGEJO_URL=${FORGEJO_URL:-https://code.vicoli.de}`. Update the `claude mcp add` one-liner to match. - **Prose**: `FORGEJO_URL` now has a default, so "export both variables" becomes "export `FORGEJO_ACCESS_TOKEN`; set `FORGEJO_URL` only to point at another instance". Add to that section (each point one or two sentences): - Prerequisites: Docker and a Forgejo personal access token. - The token is read from `FORGEJO_ACCESS_TOKEN` in the environment Claude Code starts in; if you already keep your token under another name, add e.g. `export FORGEJO_ACCESS_TOKEN=$FORGEJO_TOKEN` to your shell profile. - **Token scopes are the only guardrail**: Upstream has no read-only mode or tool filtering, so grant the smallest scopes that cover your use. - The same `command`/`args` work in any stdio MCP client (only Claude Code's `.mcp.json` is shown). - Gotcha: if Forgejo runs on the Consumer's own machine, `localhost` inside the container is not the host; use `host.docker.internal`. Already covered, leave as is: exact pinning to `X.Y.Z-rN` (Tags section), HTTP mode. Out of scope (decided): per-client snippets, CI check of the snippet, ADR, glossary changes. ## Acceptance criteria - [ ] The README snippet and the `claude mcp add` line match this repo's project MCP config exactly - [ ] The Claude Code setup section covers every "Add" point above, and no longer says both variables must be exported - [ ] Wording uses glossary terms (Image, Consumer, Upstream) ## Blocked by - #31

piscis added the

ready-for-agent

label

2026-09-30 17:32:02 +00:00

piscis added a new dependency

2026-09-30 17:32:02 +00:00

#31 Dogfood the Image as this repo's Forgejo MCP server

piscis referenced this issue from a commit

2026-09-30 18:54:10 +00:00

docs: adopt the Image via .mcp.json with --pull=always (#32, #35)

piscis referenced this issue from a pull request that will close it,

2026-09-30 18:54:19 +00:00