registry/cmd/publisher/main.go
Preeti Dewani bb84ea69e8
Publisher-managed "deleted" support (#893)
(Updated auto-generated PR description from @tadasant / Claude on Feb
22, 2026)

## Motivation and Context

Fixes #637

Server lifecycle management (deprecation and yanking) is a standard
requirement for package registries. Use cases like rebranding, security
vulnerabilities, and end-of-life servers demand the ability to mark
servers as deprecated or deleted, with optional messaging to guide
consumers toward alternatives.

## Changes

### New API endpoints

- **`PATCH /v0/servers/{serverName}/versions/{version}/status`** —
Update the lifecycle status of a single server version
- **`PATCH /v0/servers/{serverName}/status`** — Update the lifecycle
status of all versions of a server in a single transaction

Both endpoints accept:
```json
{
  "status": "active|deprecated|deleted",
  "statusMessage": "Optional message (max 500 chars) explaining the change"
}
```

### New CLI command

- **`mcp-publisher status <serverName> [version]`** — Update server
lifecycle status from the command line
  - `--status` (required): `active`, `deprecated`, or `deleted`
  - `--message`: Optional status message
- `--all-versions`: Apply to all versions of the server (replaces the
`<version>` argument)

### API response changes

`RegistryExtensions` now includes two new fields:
- `statusChangedAt` — Timestamp of the last status change
- `statusMessage` — Optional free-form message (e.g., deprecation
reason, migration guidance)

### List endpoint changes

- New `include_deleted` query parameter on `GET /v0/servers` — defaults
to `false`, hiding deleted servers from listings
- When `updated_since` is provided, `include_deleted` is automatically
set to `true` for incremental sync

### Database

- Migration `013_add_status_fields.sql`: Adds `status_changed_at` (NOT
NULL, initialized from `published_at`) and `status_message` columns to
the `servers` table

### Design decisions (from review discussion)

- **Dedicated status endpoints** rather than overloading the existing
edit endpoint
- **Bidirectional status transitions** — all transitions between
`active`, `deprecated`, and `deleted` are allowed
- **`statusMessage` as free-form text** — no structured `nextName` or
`alternativeUrl` fields (per maintainer feedback, to avoid complexity
around chaining, trust transfer, etc.)
- **Publish permission** grants status change access (not limited to
admin/edit)
- **Status message auto-cleared** when transitioning back to `active`
Good, now I have the full picture. Here's the addendum:

### Consumer-facing API changes

The new status fields live inside
`_meta["io.modelcontextprotocol.registry/official"]` on every
`ServerResponse`. This is the existing `RegistryExtensions` object — two
new fields are added alongside the existing ones:

**Before:**
```json
{
  "server": { "name": "com.example/my-server", "...": "..." },
  "_meta": {
    "io.modelcontextprotocol.registry/official": {
      "status": "active",
      "publishedAt": "2025-06-01T00:00:00Z",
      "updatedAt": "2025-06-15T00:00:00Z",
      "isLatest": true
    }
  }
}
```

**After:**
```json
{
  "server": { "name": "com.example/my-server", "...": "..." },
  "_meta": {
    "io.modelcontextprotocol.registry/official": {
      "status": "deprecated",
      "statusChangedAt": "2026-02-01T12:00:00Z",
      "statusMessage": "Deprecated in favor of com.example/my-server-v2",
      "publishedAt": "2025-06-01T00:00:00Z",
      "updatedAt": "2026-02-01T12:00:00Z",
      "isLatest": true
    }
  }
}
```

| New field | Type | Present when |
|-----------|------|-------------|
| `statusChangedAt` | `string` (RFC3339) | Always — initialized to
`publishedAt` for existing records |
| `statusMessage` | `string` (max 500 chars) | Only when set —
`null`/omitted for active servers (auto-cleared on transition to active)
|

These fields appear on **every endpoint that returns a
`ServerResponse`**: `GET /v0/servers`, `GET /v0/servers/{name}`, `GET
/v0/servers/{name}/versions/{version}`, and the new PATCH status
endpoints.

### List endpoint filtering

`GET /v0/servers` gains an `include_deleted` query parameter:

| Scenario | Behavior |
|----------|----------|
| No `include_deleted` param | Deleted servers hidden (default `false`)
|
| `include_deleted=true` | Deleted servers included in results |
| `updated_since` provided | `include_deleted` forced to `true` for
incremental sync |

## How Has This Been Tested?

- Unit tests for status handler (`status_test.go`) covering status
transitions, permission checks, validation errors, and the all-versions
endpoint
- Unit tests for the CLI command (`status_test.go`)
- Integration with existing server/edit handler tests
- Database layer tests for the new status update and query methods
- Tested locally with `make dev-compose`

## Types of changes

- [x] New feature (non-breaking change which adds functionality)

## Checklist

- [x] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [x] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [x] I have added appropriate error handling
- [x] I have added or updated documentation as needed

## Open items from review

- [ ] `include_deleted` silent override: When `updated_since` is
provided and `include_deleted=false` is explicitly passed, should return
a 400 error rather than silently overriding
([thread](https://github.com/modelcontextprotocol/registry/pull/893#discussion_r2100879360))
— agreed upon but may not yet be implemented
2026-02-27 09:00:07 -08:00

171 lines
7.3 KiB
Go

package main
import (
"fmt"
"log"
"os"
"github.com/modelcontextprotocol/registry/cmd/publisher/commands"
)
// Version info for the MCP Publisher tool
// These variables are injected at build time via ldflags by goreleaser
var (
// Version is the current version of the MCP Publisher tool
Version = "dev"
// BuildTime is the time at which the binary was built
BuildTime = "unknown"
// GitCommit is the git commit that was compiled
GitCommit = "unknown"
)
func main() {
if len(os.Args) < 2 {
printUsage()
os.Exit(1)
}
// Check for help flag for subcommands
if len(os.Args) >= 3 && (os.Args[2] == "--help" || os.Args[2] == "-h") {
printCommandHelp(os.Args[1])
return
}
var err error
switch os.Args[1] {
case "init":
err = commands.InitCommand()
case "login":
err = commands.LoginCommand(os.Args[2:])
case "logout":
err = commands.LogoutCommand()
case "publish":
err = commands.PublishCommand(os.Args[2:])
case "status":
err = commands.StatusCommand(os.Args[2:])
case "validate":
err = commands.ValidateCommand(os.Args[2:])
case "--version", "-v", "version":
log.Printf("mcp-publisher %s (commit: %s, built: %s)", Version, GitCommit, BuildTime)
return
case "--help", "-h", "help":
printUsage()
default:
fmt.Fprintf(os.Stderr, "Unknown command: %s\n\n", os.Args[1])
printUsage()
os.Exit(1)
}
if err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}
}
func printUsage() {
_, _ = fmt.Fprintln(os.Stdout, "MCP Registry Publisher Tool")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "Usage:")
_, _ = fmt.Fprintln(os.Stdout, " mcp-publisher <command> [arguments]")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "Commands:")
_, _ = fmt.Fprintln(os.Stdout, " init Create a server.json file template")
_, _ = fmt.Fprintln(os.Stdout, " login Authenticate with the registry")
_, _ = fmt.Fprintln(os.Stdout, " logout Clear saved authentication")
_, _ = fmt.Fprintln(os.Stdout, " publish Publish server.json to the registry")
_, _ = fmt.Fprintln(os.Stdout, " status Update the status of a server version")
_, _ = fmt.Fprintln(os.Stdout, " validate Validate server.json without publishing")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "Use 'mcp-publisher <command> --help' for more information about a command.")
}
func printCommandHelp(command string) {
switch command {
case "init":
_, _ = fmt.Fprintln(os.Stdout, "Create a server.json file template")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "Usage:")
_, _ = fmt.Fprintln(os.Stdout, " mcp-publisher init")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "This command creates a server.json file in the current directory with")
_, _ = fmt.Fprintln(os.Stdout, "auto-detected values from your project (package.json, git remote, etc.).")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "After running init, edit the generated server.json to customize your")
_, _ = fmt.Fprintln(os.Stdout, "server's metadata before publishing.")
case "login":
_, _ = fmt.Fprintln(os.Stdout, "Authenticate with the registry")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "Usage:")
_, _ = fmt.Fprintln(os.Stdout, " mcp-publisher login <method> [options]")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "Methods:")
_, _ = fmt.Fprintln(os.Stdout, " github Interactive GitHub authentication")
_, _ = fmt.Fprintln(os.Stdout, " github-oidc GitHub Actions OIDC authentication")
_, _ = fmt.Fprintln(os.Stdout, " dns DNS-based authentication (requires --domain)")
_, _ = fmt.Fprintln(os.Stdout, " http HTTP-based authentication (requires --domain)")
_, _ = fmt.Fprintln(os.Stdout, " none Anonymous authentication (for testing)")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "Examples:")
_, _ = fmt.Fprintln(os.Stdout, " mcp-publisher login github")
_, _ = fmt.Fprintln(os.Stdout, " mcp-publisher login dns --domain example.com --private-key <key>")
case "logout":
_, _ = fmt.Fprintln(os.Stdout, "Clear saved authentication")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "Usage:")
_, _ = fmt.Fprintln(os.Stdout, " mcp-publisher logout")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "This command removes the saved authentication token from your system.")
case "publish":
_, _ = fmt.Fprintln(os.Stdout, "Publish server.json to the registry")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "Usage:")
_, _ = fmt.Fprintln(os.Stdout, " mcp-publisher publish [server.json]")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "Arguments:")
_, _ = fmt.Fprintln(os.Stdout, " server.json Path to the server.json file (default: ./server.json)")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "You must be logged in before publishing. Run 'mcp-publisher login' first.")
case "status":
_, _ = fmt.Fprintln(os.Stdout, "Update the status of a server version")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "Usage:")
_, _ = fmt.Fprintln(os.Stdout, " mcp-publisher status --status <active|deprecated|deleted> [flags] <server-name> [version]")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "Flags (must come before positional arguments):")
_, _ = fmt.Fprintln(os.Stdout, " --status string New status: active, deprecated, or deleted (required)")
_, _ = fmt.Fprintln(os.Stdout, " --message string Optional message explaining the status change")
_, _ = fmt.Fprintln(os.Stdout, " --all-versions Apply status change to all versions of the server")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "Arguments:")
_, _ = fmt.Fprintln(os.Stdout, " server-name Full server name (e.g., io.github.user/my-server)")
_, _ = fmt.Fprintln(os.Stdout, " version Server version to update (required unless --all-versions is set)")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "Examples:")
_, _ = fmt.Fprintln(os.Stdout, " # Deprecate a specific version")
_, _ = fmt.Fprintln(os.Stdout, " mcp-publisher status --status deprecated --message \"Please upgrade to 2.0.0\" \\")
_, _ = fmt.Fprintln(os.Stdout, " io.github.user/my-server 1.0.0")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, " # Delete a version with security issues")
_, _ = fmt.Fprintln(os.Stdout, " mcp-publisher status --status deleted --message \"Critical security vulnerability\" \\")
_, _ = fmt.Fprintln(os.Stdout, " io.github.user/my-server 1.0.0")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, " # Restore a version to active")
_, _ = fmt.Fprintln(os.Stdout, " mcp-publisher status --status active io.github.user/my-server 1.0.0")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, " # Deprecate all versions")
_, _ = fmt.Fprintln(os.Stdout, " mcp-publisher status --status deprecated --all-versions --message \"Project archived\" \\")
_, _ = fmt.Fprintln(os.Stdout, " io.github.user/my-server")
_, _ = fmt.Fprintln(os.Stdout)
_, _ = fmt.Fprintln(os.Stdout, "You must be logged in before updating status. Run 'mcp-publisher login' first.")
default:
fmt.Fprintf(os.Stderr, "Unknown command: %s\n", command)
printUsage()
}
}