openapi: 3.0.0
info:
  title: Model Context Protocol Registry API
  description: API for the Model Context Protocol Registry
  version: "0.1.0"
  
servers:
  - url: /
    description: Default server
  
tags:
  - name: health
    description: Health checking operations
  - name: servers
    description: Server registry operations

paths:
  /v0/health:
    get:
      tags:
        - health
      summary: Health check endpoint
      description: Returns the health status of the API
      operationId: healthCheck
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  github_client_id:
                      type: string
                      example: "your_github_client_id"
  /v0/ping:
    get:
      tags:
        - health
      summary: API version check
      description: Returns the API version and status
      operationId: pingCheck
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  version:
                    type: string
                    example: "0.1.0"
        '405':
          description: Method not allowed
          
  /v0/servers:
    get:
      tags:
        - servers
      summary: List registered servers
      description: Returns a paginated list of registered servers
      operationId: listServers
      parameters:
        - name: cursor
          in: query
          description: Pagination cursor (UUID)
          required: false
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          description: Maximum number of items to return (1-100, default 30)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 30
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  servers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Server'
                  metadata:
                    $ref: '#/components/schemas/PaginationMetadata'
        '400':
          description: Invalid cursor or limit parameter
        '405':
          description: Method not allowed
          
  /v0/publish:
    post:
      tags:
        - servers
      summary: Publish a server to the registry
      description: Adds a new server to the MCP registry with authentication
      operationId: publishServer
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                server_detail:
                  $ref: '#/components/schemas/ServerDetail'
                repo_ref:
                  type: string
                  description: Repository reference used for authentication (defaults to server name if not provided)
      responses:
        '201':
          description: Server published successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Server publication successful
                  id:
                    type: string
                    example: 1234567890abcdef12345678
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Name is required
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Authentication is required for publishing
        '405':
          description: Method not allowed
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Failed to publish server details
                    
  /v0/servers/{id}:
    get:
      tags:
        - servers
      summary: Get server details
      description: Returns details of a specific server by ID
      operationId: getServerDetails
      parameters:
        - name: id
          in: path
          description: Server ID (UUID)
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Server'
        '400':
          description: Invalid ID format
        '404':
          description: Server not found
        '405':
          description: Method not allowed

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "JWT Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\""
  
  schemas:
    Server:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        name:
          type: string
          example: "Example MCP Server"
        url:
          type: string
          format: uri
          example: "https://example.com/mcp"
        description:
          type: string
          example: "An example MCP server"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          
    PaginationMetadata:
      type: object
      properties:
        next_cursor:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        count:
          type: integer
          example: 30