server-definition.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://mcpmux.com/schemas/server-definition.json",
  "title": "MCP Server Definition (Contributor Schema)",
  "description": "Contributor-provided server definition for McpMux Registry. Platform-managed fields (badges, hosting_type, verification, sponsored) are computed by the bundler and stored separately in _platform.",
  "type": "object",
  "required": ["id", "name", "transport"],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9]+\\.[a-z0-9][a-z0-9-]*$",
      "description": "Unique identifier: {tld}.{publisher}-{name} (e.g., com.cloudflare-docs, community.linear). One publisher can have multiple servers."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Human-readable display name"
    },
    "alias": {
      "type": "string",
      "pattern": "^[a-z0-9-]+$",
      "description": "Short alias for CLI usage"
    },
    "description": {
      "type": "string",
      "description": "Short description of what the server does"
    },
    "icon": {
      "type": "string",
      "description": "Emoji or URL to icon image"
    },
    "schema_version": {
      "type": "string",
      "description": "Schema version this definition conforms to"
    },
    "transport": {
      "$ref": "#/$defs/transport"
    },
    "auth": {
      "$ref": "#/$defs/auth"
    },
    "categories": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Array of category IDs"
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Searchable tags"
    },
    "contributor": {
      "$ref": "#/$defs/contributor"
    },
    "links": {
      "type": "object",
      "properties": {
        "repository": {
          "type": "string",
          "format": "uri",
          "description": "Source code repository URL"
        },
        "homepage": {
          "type": "string",
          "format": "uri",
          "description": "Project homepage URL"
        },
        "documentation": {
          "type": "string",
          "format": "uri",
          "description": "Documentation URL"
        }
      }
    },
    "platforms": {
      "type": "array",
      "items": {
        "enum": ["all", "windows", "macos", "linux"]
      },
      "description": "Supported platforms"
    },
    "capabilities": {
      "type": "object",
      "properties": {
        "tools": { "type": "boolean" },
        "resources": { "type": "boolean" },
        "prompts": { "type": "boolean" },
        "read_only_mode": {
          "type": "boolean",
          "default": false,
          "description": "Server supports read-only operation (no write/destructive actions)"
        }
      },
      "description": "MCP capabilities supported"
    },
    "media": {
      "type": "object",
      "properties": {
        "screenshots": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uri"
          },
          "maxItems": 5,
          "default": [],
          "description": "Screenshot URLs for visual preview"
        },
        "demo_video": {
          "type": "string",
          "format": "uri",
          "description": "Demo video URL (YouTube, Vimeo, etc.)"
        },
        "banner": {
          "type": "string",
          "format": "uri",
          "description": "Banner image for featured display (recommended: 1200x400px)"
        }
      },
      "description": "Rich media content for better discovery and user experience"
    },
    "changelog_url": {
      "type": "string",
      "format": "uri",
      "description": "URL to changelog or release notes"
    }
  },
  "$defs": {
    "transport": {
      "type": "object",
      "required": ["type"],
      "oneOf": [
        {
          "properties": {
            "type": { "const": "stdio" },
            "command": {
              "type": "string",
              "minLength": 1,
              "description": "Command to execute"
            },
            "args": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Command arguments"
            },
            "env": {
              "type": "object",
              "additionalProperties": { "type": "string" },
              "description": "Environment variables"
            },
            "cwd": {
              "type": "string",
              "description": "Working directory for command execution"
            },
            "metadata": {
              "$ref": "#/$defs/metadata"
            }
          },
          "required": ["type", "command"],
          "additionalProperties": false
        },
        {
          "properties": {
            "type": { "const": "http" },
            "url": {
              "type": "string",
              "format": "uri",
              "description": "HTTP endpoint URL (supports Streamable HTTP)"
            },
            "metadata": {
              "$ref": "#/$defs/metadata"
            }
          },
          "required": ["type", "url"],
          "additionalProperties": false
        }
      ]
    },
    "metadata": {
      "type": "object",
      "properties": {
        "inputs": {
          "type": "array",
          "items": { "$ref": "#/$defs/input" },
          "description": "User inputs required for this server"
        }
      }
    },
    "input": {
      "type": "object",
      "required": ["id", "label"],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[A-Z0-9_]+$",
          "description": "Uppercase identifier (e.g., API_KEY)"
        },
        "label": {
          "type": "string",
          "description": "Human-readable label"
        },
        "type": {
          "enum": ["text", "number", "boolean", "url", "select", "file_path", "directory_path"],
          "default": "text",
          "description": "Input field type"
        },
        "required": {
          "type": "boolean",
          "default": false,
          "description": "Whether this input is required"
        },
        "secret": {
          "type": "boolean",
          "default": false,
          "description": "Whether this input contains sensitive data"
        },
        "description": {
          "type": "string",
          "description": "Help text for this input"
        },
        "default": {
          "type": "string",
          "description": "Default value for this input (used when user provides no value)"
        },
        "placeholder": {
          "type": "string",
          "description": "Placeholder text"
        },
        "obtain": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri",
              "description": "URL where user can obtain this value"
            },
            "instructions": {
              "type": "string",
              "description": "Step-by-step instructions"
            },
            "button_label": {
              "type": "string",
              "description": "Button label for obtain link"
            }
          },
          "description": "Instructions for obtaining this input value"
        },
        "options": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["value", "label"],
            "properties": {
              "value": { "type": "string", "description": "Option value" },
              "label": { "type": "string", "description": "Display label" },
              "description": { "type": "string", "description": "Optional description" }
            },
            "additionalProperties": false
          },
          "description": "Predefined options for select input type"
        }
      },
      "additionalProperties": false
    },
    "auth": {
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": {
          "enum": ["none", "api_key", "optional_api_key", "oauth", "basic"],
          "description": "Authentication type: none (no auth), api_key (required), optional_api_key (enhanced if provided), oauth, basic"
        },
        "instructions": {
          "type": "string",
          "description": "Human-readable authentication instructions"
        }
      }
    },
    "contributor": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Contributor display name or GitHub username"
        },
        "github": {
          "type": "string",
          "description": "GitHub username (without @)"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Contributor website or profile URL"
        }
      },
      "description": "Person or org who contributed this server definition to the registry"
    }
  }
}