From 276037b1ad877fa2990c2aed5bafb90a737da9d6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?d=20=F0=9F=94=B9?= <liusway405@gmail.com>
Date: Mon, 11 May 2026 21:01:52 +0800
Subject: [PATCH] docs(complete): align publish CLI flags with implementation
 (closes #767) (#1278)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

`complete.md` documents three flags for `mcp-publisher publish` that the
CLI does not actually parse:

- `--file=PATH` — Path to server.json
- `--registry=URL` — Registry URL override
- `--dry-run` — Validate without publishing

Reading
[`cmd/publisher/commands/publish.go`](https://github.com/modelcontextprotocol/registry/blob/main/cmd/publisher/commands/publish.go)
and
[`cmd/publisher/main.go`](https://github.com/modelcontextprotocol/registry/blob/main/cmd/publisher/main.go)
confirms the actual interface is a single positional `PATH` argument
(default `./server.json`):

```go
serverFile := \"server.json\"
if len(args) > 0 && !strings.HasPrefix(args[0], \"-\") {
    serverFile = args[0]
}
```

Registry URL is bound at login time via the saved token, and \"validate
without publishing\" is a separate `mcp-publisher validate` subcommand.
The bug user in #767 hit \"server.json not found\" precisely because
`--file .registry/server.json` is filtered out by the
`HasPrefix(args[0], \"-\")` check, leaving the default lookup in place.

## Background

The canonical reference at
[`docs/reference/cli/commands.md`](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/cli/commands.md)
was already updated to the correct positional shape. `complete.md` (the
concatenated single-file mirror of `docs/` used for LLM/quickstart
consumption) had drifted out of sync — these were the only remaining
`--file` references in the repo outside of test fixtures.

Per the discussion on the prior flag-implementation attempt in #771,
maintainers preferred fixing the documentation over adding the
unimplemented flags:

> @domdomegg: I'd lean towards removing the options from the docs.

This PR closes that loop on the last stale doc surface.

## Changes

`complete.md`: the `mcp-publisher publish` block now matches
`docs/reference/cli/commands.md` line-for-line (positional `PATH`, no
spurious flags, no dry-run example).

```diff
-mcp-publisher publish [options]
+mcp-publisher publish [PATH]

-- \`--file=PATH\` - Path to server.json (default: \`./server.json\`)
-- \`--registry=URL\` - Registry URL override
-- \`--dry-run\` - Validate without publishing
+- \`PATH\` - Path to server.json (default: \`./server.json\`)

-# Dry run validation
-mcp-publisher publish --dry-run
-
 # Custom file location
-mcp-publisher publish --file=./config/server.json
+mcp-publisher publish ./config/server.json
```

Closes #767.

## Out of scope

- `cmd/publisher/README.md:17` still shows `./bin/mcp-publisher publish
--registry=http://localhost:8080` in the contributor quickstart. The
flag is silently ignored at runtime (caught by the same
`HasPrefix(\"-\")` filter). Happy to fold that fix into this PR or send
a follow-up — flagging here in case a maintainer prefers one option.
- `complete.md` is missing `mcp-publisher validate` and `mcp-publisher
status` sections that exist in `docs/reference/cli/commands.md`. Out of
scope for this single-concern PR; if there's interest, a broader sync
would be a separate PR.

## Test plan

- [x] `grep -r -- '--file' .` outside test fixtures returns 0 hits after
the change
- [x] `grep -r 'mcp-publisher publish --' docs/ complete.md` shows only
legitimate flags (`--registry` on `login`)
- [x] No code changes — `make check` not exercised since this is
doc-only

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: d 🔹 <258577966+voidborne-d@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 complete.md | 18 +++++++-----------
 1 file changed, 7 insertions(+), 11 deletions(-)

diff --git a/complete.md b/complete.md
index 2355e4b..e9040fa 100644
--- a/complete.md
+++ b/complete.md
@@ -1991,30 +1991,26 @@ For detailed guidance on the publishing process, see the [publishing guide](../.
 
 **Usage:**
 ```bash
-mcp-publisher publish [options]
+mcp-publisher publish [PATH]
 ```
 
 **Options:**
-- `--file=PATH` - Path to server.json (default: `./server.json`)
-- `--registry=URL` - Registry URL override
-- `--dry-run` - Validate without publishing
+- `PATH` - Path to server.json (default: `./server.json`)
 
 **Process:**
 1. Validates `server.json` against schema
-2. Verifies package ownership (see [Official Registry Requirements](../server-json/official-registry-requirements.md))
-3. Checks namespace authentication
-4. Publishes to registry
+2. Publishes the `server.json` to the registry server URL specified in the login token
+3. Server: Verifies package ownership (see [Official Registry Requirements](../server-json/official-registry-requirements.md))
+4. Server: Checks namespace authentication
+5. Server: Publishes to registry
 
 **Example:**
 ```bash
 # Basic publish
 mcp-publisher publish
 
-# Dry run validation
-mcp-publisher publish --dry-run
-
 # Custom file location
-mcp-publisher publish --file=./config/server.json
+mcp-publisher publish ./config/server.json
 ```
 
 ### `mcp-publisher logout`