registry/cmd/publisher/commands/status.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

375 lines
11 KiB
Go

package commands
import (
"bufio"
"bytes"
"context"
"encoding/json"
"errors"
"flag"
"fmt"
"io"
"net/http"
"net/url"
"os"
"path/filepath"
"strings"
)
// StatusUpdateRequest represents the request body for status update endpoints
type StatusUpdateRequest struct {
Status string `json:"status"`
StatusMessage *string `json:"statusMessage,omitempty"`
}
// AllVersionsStatusResponse represents the response from the all-versions status endpoint
type AllVersionsStatusResponse struct {
UpdatedCount int `json:"updatedCount"`
}
// VersionInfo holds version and status for display
type VersionInfo struct {
Version string
Status string
}
// ServerResponseMeta represents the _meta field in API responses
type ServerResponseMeta struct {
Official *struct {
Status string `json:"status"`
} `json:"io.modelcontextprotocol.registry/official,omitempty"`
}
// SingleServerResponse represents the response from a single server version endpoint
type SingleServerResponse struct {
Server struct {
Version string `json:"version"`
} `json:"server"`
Meta ServerResponseMeta `json:"_meta"`
}
// ServerListResponse represents the response from the versions list endpoint
type ServerListResponse struct {
Servers []SingleServerResponse `json:"servers"`
}
func StatusCommand(args []string) error {
// Parse command flags
fs := flag.NewFlagSet("status", flag.ExitOnError)
status := fs.String("status", "", "New status: active, deprecated, or deleted (required)")
message := fs.String("message", "", "Optional status message explaining the change")
allVersions := fs.Bool("all-versions", false, "Apply status change to all versions of the server")
yes := fs.Bool("yes", false, "Skip confirmation prompt for bulk operations")
fs.BoolVar(yes, "y", false, "Skip confirmation prompt for bulk operations (shorthand)")
if err := fs.Parse(args); err != nil {
return err
}
// Validate required arguments
if *status == "" {
return errors.New("--status flag is required (active, deprecated, or deleted)")
}
// Validate status value
validStatuses := map[string]bool{"active": true, "deprecated": true, "deleted": true}
if !validStatuses[*status] {
return fmt.Errorf("invalid status '%s'. Must be one of: active, deprecated, deleted", *status)
}
// Get server name from positional args
remainingArgs := fs.Args()
if len(remainingArgs) < 1 {
return errors.New("server name is required\n\nUsage: mcp-publisher status --status <active|deprecated|deleted> [flags] <server-name> [version]")
}
serverName := remainingArgs[0]
var version string
// Get version if provided (required unless --all-versions is set)
if !*allVersions {
if len(remainingArgs) < 2 {
return errors.New("version is required unless --all-versions flag is set\n\nUsage: mcp-publisher status --status <active|deprecated|deleted> [flags] <server-name> <version>")
}
version = remainingArgs[1]
}
// Load saved token
homeDir, err := os.UserHomeDir()
if err != nil {
return fmt.Errorf("failed to get home directory: %w", err)
}
tokenPath := filepath.Join(homeDir, TokenFileName)
tokenData, err := os.ReadFile(tokenPath)
if err != nil {
if os.IsNotExist(err) {
return errors.New("not authenticated. Run 'mcp-publisher login <method>' first")
}
return fmt.Errorf("failed to read token: %w", err)
}
var tokenInfo map[string]string
if err := json.Unmarshal(tokenData, &tokenInfo); err != nil {
return fmt.Errorf("invalid token data: %w", err)
}
token := tokenInfo["token"]
registryURL := tokenInfo["registry"]
if registryURL == "" {
registryURL = DefaultRegistryURL
}
// Update status
if *allVersions {
return updateAllVersionsStatus(registryURL, serverName, *status, *message, token, *yes)
}
return updateVersionStatus(registryURL, serverName, version, *status, *message, token)
}
func updateVersionStatus(registryURL, serverName, version, status, statusMessage, token string) error {
// Fetch current status to show "from → to"
currentStatus, err := fetchVersionStatus(registryURL, serverName, version, token)
if err != nil {
return fmt.Errorf("failed to fetch current status: %w", err)
}
_, _ = fmt.Fprintf(os.Stdout, "Updating %s version %s: %s → %s\n", serverName, version, currentStatus, status)
if err := updateServerStatus(registryURL, serverName, version, status, statusMessage, token); err != nil {
return fmt.Errorf("failed to update status: %w", err)
}
_, _ = fmt.Fprintln(os.Stdout, "✓ Successfully updated status")
return nil
}
func updateAllVersionsStatus(registryURL, serverName, status, statusMessage, token string, skipConfirm bool) error {
if !strings.HasSuffix(registryURL, "/") {
registryURL += "/"
}
// Fetch all versions to show current statuses and get count for confirmation
versions, err := fetchAllVersionsStatus(registryURL, serverName, token)
if err != nil {
return fmt.Errorf("failed to fetch current versions: %w", err)
}
if len(versions) == 0 {
return errors.New("no versions found for this server")
}
// Show what will be updated
_, _ = fmt.Fprintf(os.Stdout, "This will update %d version(s) of %s:\n", len(versions), serverName)
for _, v := range versions {
_, _ = fmt.Fprintf(os.Stdout, " %s: %s → %s\n", v.Version, v.Status, status)
}
// Prompt for confirmation unless -y/--yes was provided
if !skipConfirm {
_, _ = fmt.Fprint(os.Stdout, "Continue? [y/N] ")
reader := bufio.NewReader(os.Stdin)
response, err := reader.ReadString('\n')
if err != nil {
return fmt.Errorf("failed to read response: %w", err)
}
response = strings.TrimSpace(strings.ToLower(response))
if response != "y" && response != "yes" {
return errors.New("operation cancelled")
}
}
// Build the request body
requestBody := StatusUpdateRequest{
Status: status,
}
if statusMessage != "" {
requestBody.StatusMessage = &statusMessage
}
jsonData, err := json.Marshal(requestBody)
if err != nil {
return fmt.Errorf("error serializing request: %w", err)
}
// URL encode the server name
encodedServerName := url.PathEscape(serverName)
statusURL := registryURL + "v0/servers/" + encodedServerName + "/status"
req, err := http.NewRequestWithContext(context.Background(), http.MethodPatch, statusURL, bytes.NewBuffer(jsonData))
if err != nil {
return fmt.Errorf("error creating request: %w", err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return fmt.Errorf("error sending request: %w", err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
return fmt.Errorf("error reading response: %w", err)
}
if resp.StatusCode != http.StatusOK {
return fmt.Errorf("server returned status %d: %s", resp.StatusCode, body)
}
// Parse response to get updated count
var response AllVersionsStatusResponse
if err := json.Unmarshal(body, &response); err != nil {
// If we can't parse the response, just report success
_, _ = fmt.Fprintln(os.Stdout, "✓ Successfully updated all versions")
return nil
}
_, _ = fmt.Fprintf(os.Stdout, "✓ Successfully updated %d version(s)\n", response.UpdatedCount)
return nil
}
func updateServerStatus(registryURL, serverName, version, status, statusMessage, token string) error {
if !strings.HasSuffix(registryURL, "/") {
registryURL += "/"
}
// Build the request body
requestBody := StatusUpdateRequest{
Status: status,
}
if statusMessage != "" {
requestBody.StatusMessage = &statusMessage
}
jsonData, err := json.Marshal(requestBody)
if err != nil {
return fmt.Errorf("error serializing request: %w", err)
}
// URL encode the server name and version
encodedServerName := url.PathEscape(serverName)
encodedVersion := url.PathEscape(version)
statusURL := registryURL + "v0/servers/" + encodedServerName + "/versions/" + encodedVersion + "/status"
req, err := http.NewRequestWithContext(context.Background(), http.MethodPatch, statusURL, bytes.NewBuffer(jsonData))
if err != nil {
return fmt.Errorf("error creating request: %w", err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return fmt.Errorf("error sending request: %w", err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
return fmt.Errorf("error reading response: %w", err)
}
if resp.StatusCode != http.StatusOK {
return fmt.Errorf("server returned status %d: %s", resp.StatusCode, body)
}
return nil
}
func fetchVersionStatus(registryURL, serverName, version, token string) (string, error) {
if !strings.HasSuffix(registryURL, "/") {
registryURL += "/"
}
encodedServerName := url.PathEscape(serverName)
encodedVersion := url.PathEscape(version)
fetchURL := registryURL + "v0/servers/" + encodedServerName + "/versions/" + encodedVersion + "?include_deleted=true"
req, err := http.NewRequestWithContext(context.Background(), http.MethodGet, fetchURL, nil)
if err != nil {
return "", fmt.Errorf("error creating request: %w", err)
}
req.Header.Set("Authorization", "Bearer "+token)
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return "", fmt.Errorf("error sending request: %w", err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
return "", fmt.Errorf("error reading response: %w", err)
}
if resp.StatusCode != http.StatusOK {
return "", fmt.Errorf("server returned status %d: %s", resp.StatusCode, body)
}
// Parse the response to extract status
var response SingleServerResponse
if err := json.Unmarshal(body, &response); err != nil {
return "", fmt.Errorf("error parsing response: %w", err)
}
if response.Meta.Official == nil {
return "", errors.New("server response missing status information")
}
return response.Meta.Official.Status, nil
}
func fetchAllVersionsStatus(registryURL, serverName, token string) ([]VersionInfo, error) {
if !strings.HasSuffix(registryURL, "/") {
registryURL += "/"
}
encodedServerName := url.PathEscape(serverName)
fetchURL := registryURL + "v0/servers/" + encodedServerName + "/versions?include_deleted=true"
req, err := http.NewRequestWithContext(context.Background(), http.MethodGet, fetchURL, nil)
if err != nil {
return nil, fmt.Errorf("error creating request: %w", err)
}
req.Header.Set("Authorization", "Bearer "+token)
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return nil, fmt.Errorf("error sending request: %w", err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
return nil, fmt.Errorf("error reading response: %w", err)
}
if resp.StatusCode != http.StatusOK {
return nil, fmt.Errorf("server returned status %d: %s", resp.StatusCode, body)
}
var response ServerListResponse
if err := json.Unmarshal(body, &response); err != nil {
return nil, fmt.Errorf("error parsing response: %w", err)
}
var versions []VersionInfo
for _, s := range response.Servers {
status := "unknown"
if s.Meta.Official != nil {
status = s.Meta.Official.Status
}
versions = append(versions, VersionInfo{
Version: s.Server.Version,
Status: status,
})
}
return versions, nil
}