forgejo-mcp/extension

Claude Desktop Extension

This directory packages forgejo-mcp as a Claude Desktop Extension (.mcpb format), so users of the Claude Desktop app can install Forgejo MCP support with a drag-and-drop or file-picker install rather than hand-editing claude_desktop_config.json.

The server binary itself is unchanged — this is purely packaging. Existing usage paths (CLI invocation, mcpServers config, claude mcp add) keep working identically.

What's here

• manifest.json — the extension manifest (schema version 0.3). Includes the full tools list discovered from the binary's tools/list response.
• test_smoke.py — verifies the bundled binary boots and that the manifest's tools array matches the binary's actual tools/list. The most likely drift bug for an extension wrapping someone else's binary is the manifest's tool list falling out of sync; this catches it.
• bin/ — destination for the binary at build time (gitignored).

Build

# 1. Build the binary into the extension's bin/ directory
go build -o extension/bin/forgejo-mcp .

# 2. Pack the extension
npx @anthropic-ai/mcpb pack extension/ extension/forgejo-mcp.mcpb

The resulting forgejo-mcp.mcpb is a single file users can drag into Claude Desktop's Extensions settings (or sideload via the file picker — drag-and-drop has been intermittent in some Claude Desktop versions).

Test

The smoke test verifies the bundled binary's tools/list matches the manifest's declared tools.

# Required: a valid token for whichever Forgejo instance the test will hit.
# A read-only token is sufficient — no write operations are performed.
export FORGEJO_ACCESS_TOKEN="your-token"

# Optional: override the default test URL (https://codeberg.org).
# export FORGEJO_MCP_TEST_URL="https://your-forgejo.example"

python3 extension/test_smoke.py

If FORGEJO_ACCESS_TOKEN is not set, the test prints a SKIP: message and exits 0 — appropriate for unattended CI without secrets.

What the smoke test catches:

• Binary fails to start
• Binary's tools/list response omits a tool the manifest declares (or vice versa)
• Manifest is malformed JSON

What it doesn't catch:

• Sideload UX in Claude Desktop (no headless mode for that)
• Configuration form rendering
• End-to-end "user calls a tool, it does the right thing" — that's living human verification

Updating the manifest's tools list when the binary's tools change

When the binary gains or loses a tool, the manifest's tools array needs updating. Two paths:

Option A: regenerate from the binary. Build the new binary, then write a small one-shot script that performs the MCP handshake, calls tools/list, and rewrites the array in manifest.json from the response. test_smoke.py in this directory shows the same handshake and is a useful starting point.

Option B: edit by hand. When changes are small (one or two tools), editing directly is fine. The smoke test will fail loudly if the result diverges from the binary.

After either path: npx @anthropic-ai/mcpb validate manifest.json, then python3 extension/test_smoke.py.

Versioning

The manifest's version field tracks the upstream binary version it was packaged against. Bump it when the bundled binary version changes. It does not need to match a Git tag exactly — Claude Desktop uses it to detect upgrades and display version info to users.

Possible follow-ups (not part of the initial extension scaffolding)

• Hook the .mcpb build into .goreleaser.yml so a pre-built archive is produced on each release alongside the platform binaries.
• Add cross-platform binary bundling via the manifest's server.mcp_config.platform_overrides field, populated from goreleaser's per-platform builds.
• Submit to Anthropic's curated extensions directory once the packaging stabilizes — that's the maintainer's call to make.
• Sign the .mcpb (npx @anthropic-ai/mcpb sign).