34218e6fa7
Two small follow-ups from goern's review of #118: - Bump test_smoke.py PROTOCOL_VERSION from 2024-11-05 to 2025-06-18. mcp-go v0.44.0 explicitly supports both, but 2025-06-18 is the current MCP spec version and matches what other clients send today. - Rewrite Option A in extension/README.md so it no longer points to a regenerator script that "lives in commit history" (the script was never committed). Now points to test_smoke.py as the starting reference for the MCP handshake instead. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
71 lines
4 KiB
Markdown
71 lines
4 KiB
Markdown
# Claude Desktop Extension
|
|
|
|
This directory packages `forgejo-mcp` as a [Claude Desktop Extension](https://www.anthropic.com/engineering/desktop-extensions) (`.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
|
|
|
|
```sh
|
|
# 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.
|
|
|
|
```sh
|
|
# 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](https://www.anthropic.com/engineering/desktop-extensions) once the packaging stabilizes — that's the maintainer's call to make.
|
|
- Sign the `.mcpb` (`npx @anthropic-ai/mcpb sign`).
|