From 06d5c0653b3de4adb14a05b882862121b017cdac Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Fri, 22 May 2026 12:38:46 +0300 Subject: [PATCH] chore(053): refresh registry server.json + publish guide (WP-D2) - Bump version from 0.21.2 to 0.33.1 (latest release tag) - Add title, websiteUrl fields - Populate remotes[] with streamable-http transport at localhost:8080/mcp (packages[] stays empty: Homebrew/GitHub-release/go-install channels have no matching registryType in the schema; Docker server image not yet published) - Add docs/mcp-registry-publishing.md with mcp-publisher CLI steps, GitHub namespace auth, validate/publish commands, and CI automation notes --- docs/mcp-registry-publishing.md | 109 ++++++++++++++++++++++++++++++++ server.json | 12 +++- 2 files changed, 119 insertions(+), 2 deletions(-) create mode 100644 docs/mcp-registry-publishing.md diff --git a/docs/mcp-registry-publishing.md b/docs/mcp-registry-publishing.md new file mode 100644 index 00000000..f9cef094 --- /dev/null +++ b/docs/mcp-registry-publishing.md @@ -0,0 +1,109 @@ +# Publishing MCPProxy to the MCP Registry + +This guide covers how to publish (or update) the `server.json` at the repo root to the official [MCP Registry](https://registry.modelcontextprotocol.io). This is a manual step that requires authentication as the namespace owner — it cannot be automated without a GitHub OIDC workflow scoped to the `smart-mcp-proxy` org. + +## Prerequisites + +Install the `mcp-publisher` CLI (macOS/Linux): + +```bash +brew install mcp-publisher +``` + +Verify the install: + +```bash +mcp-publisher --help +``` + +## Authenticate + +The namespace `io.github.smart-mcp-proxy` maps to the GitHub organisation `smart-mcp-proxy`. You must be logged in to GitHub as a member of that org (or in a GitHub Actions workflow on one of its repos with `id-token: write`). + +**Interactive login (browser):** + +```bash +mcp-publisher login github +``` + +This opens a GitHub OAuth flow and stores a token at `~/.config/mcp-publisher/token.json`. + +**CI/CD login (GitHub Actions OIDC — no browser):** + +```yaml +permissions: + id-token: write + +- run: mcp-publisher login github-oidc +``` + +## Validate Before Publishing + +Run the validator against the repo-root `server.json` before pushing: + +```bash +mcp-publisher validate server.json +``` + +The tool checks JSON syntax, schema compliance, and registry-specific semantic rules (namespace format, version format, etc.) and reports all issues at once with JSON-path locations. + +You can also validate offline using `check-jsonschema`: + +```bash +uvx check-jsonschema --schemafile \ + https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json \ + server.json +``` + +## Publish + +From the repo root: + +```bash +mcp-publisher publish server.json +``` + +The CLI will: + +1. Re-validate `server.json` against the schema. +2. Submit to `https://registry.modelcontextprotocol.io`. +3. The registry verifies that the authenticated GitHub identity has rights to the `io.github.smart-mcp-proxy` namespace. +4. On success, the entry is live immediately. + +## Update an Existing Entry + +Bump `version` in `server.json` to match the new release tag (strip the `v` prefix — use `0.34.0` not `v0.34.0`), then re-run `mcp-publisher publish`. Each version is stored as a separate immutable record; the latest version becomes the default. + +## Deprecate or Remove a Version + +```bash +# Deprecate a specific version +mcp-publisher status --status deprecated \ + --message "Upgrade to 0.34.0" \ + io.github.smart-mcp-proxy/mcpproxy-go 0.33.1 + +# Hide a version from default listings (e.g. security issue) +mcp-publisher status --status deleted \ + --message "Critical bug fixed in 0.34.0" \ + io.github.smart-mcp-proxy/mcpproxy-go 0.33.1 +``` + +## What Requires the User + +- **GitHub authentication**: Only a member/owner of the `smart-mcp-proxy` GitHub org can authenticate for the `io.github.smart-mcp-proxy` namespace. There is no way to delegate or automate this without adding a GitHub Actions workflow with `id-token: write` permission to the release pipeline. +- **Automating via CI**: To run `mcp-publisher login github-oidc` + `mcp-publisher publish` in the release workflow, add a new job after the `release` job in `.github/workflows/release.yml`, grant `id-token: write` in its `permissions` block, and run the two commands against the tagged `server.json`. The OIDC token is valid for the duration of the workflow run only. + +## Registry Schema Notes + +- `version` must be a plain semantic version string (`0.33.1`) — no `v` prefix, no ranges. +- `packages[]` is empty because none of the supported `registryType` values (`npm`, `pypi`, `oci`, `nuget`, `mcpb`) match MCPProxy's distribution channels (Homebrew tap, GitHub release tarballs, `.deb`/`.rpm`, `go install`). The Docker server-edition image at `ghcr.io/smart-mcp-proxy/mcpproxy-server` is not yet published to releases (gated behind `if: false` in the release workflow). +- `remotes[]` describes the actual MCP transport: a locally-run `mcpproxy serve` instance that exposes a Streamable HTTP endpoint at `http://localhost:8080/mcp`. MCP clients that support HTTP transport connect directly to this address. +- If a Docker image for the server edition is published in a future release, add an `oci` entry to `packages[]` pointing at `ghcr.io/smart-mcp-proxy/mcpproxy-server:{version}` with `"transport": {"type": "stdio"}` and the appropriate `runtimeArguments` for `docker run`. + +## References + +- [MCP Registry](https://registry.modelcontextprotocol.io) +- [server.json format spec](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/generic-server-json.md) +- [Official registry requirements](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/official-registry-requirements.md) +- [CLI commands reference](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/cli/commands.md) +- [JSON Schema](https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json) diff --git a/server.json b/server.json index a4b136d1..dcfbe025 100644 --- a/server.json +++ b/server.json @@ -1,11 +1,19 @@ { "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.smart-mcp-proxy/mcpproxy-go", + "title": "MCPProxy", "description": "Smart MCP proxy with BM25 tool discovery, quarantine security, and ~99% token savings", + "websiteUrl": "https://mcpproxy.app", "repository": { "url": "https://github.com/smart-mcp-proxy/mcpproxy-go", "source": "github" }, - "version": "0.21.2", - "packages": [] + "version": "0.33.1", + "packages": [], + "remotes": [ + { + "type": "streamable-http", + "url": "http://localhost:8080/mcp" + } + ] }