openapi.yaml

openapi: 3.1.0
info:
  title: Agent Browser API
  description: API for managing MCP servers and tools
  version: 1.0.0
servers:
  - url: http://localhost:8080
    description: Local development server

# Global security definitions
security:
  - ApiKeyAuth: []

paths:
  /api/health:
    get:
      summary: System health check
      description: Get the health status of the system
      operationId: healthCheck
      responses:
        '200':
          description: System is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "ok"
  
  /api/config/export:
    get:
      summary: Export configuration
      description: Export the current system configuration
      operationId: exportConfig
      responses:
        '200':
          description: Configuration exported successfully
          content:
            application/json:
              schema:
                type: object
  
  /api/mcp/servers:
    post:
      summary: Add a new MCP server
      description: Create a new MCP server with the given details
      operationId: addMCPServer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - url
              properties:
                name:
                  type: string
                  example: "Test Server"
                url:
                  type: string
                  example: "http://mcp-server-example.com"
      responses:
        '201':
          description: Server created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPServer'
        '400':
          description: Invalid request body
        '409':
          description: Server with this URL already exists
    
    get:
      summary: List all MCP servers
      description: Get a list of all registered MCP servers
      operationId: listMCPServers
      responses:
        '200':
          description: List of MCP servers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MCPServer'
                maxItems: 1000
  
  /api/mcp/servers/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: MCP server ID
    
    get:
      summary: Get a specific server
      description: Get details of a specific MCP server by ID
      operationId: getMCPServer
      responses:
        '200':
          description: MCP server details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPServer'
        '404':
          description: Server not found
    
    put:
      summary: Update a specific server
      description: Update the details of a specific MCP server
      operationId: updateMCPServer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "Updated Server Name"
                url:
                  type: string
                  example: "http://updated-url.example.com"
      responses:
        '200':
          description: Server updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPServer'
        '404':
          description: Server not found
    
    delete:
      summary: Remove a specific server
      description: Delete a specific MCP server by ID
      operationId: removeMCPServer
      responses:
        '204':
          description: Server removed successfully
        '404':
          description: Server not found
  
  /api/mcp/tools:
    get:
      summary: List all tools
      description: Get a list of all available tools
      operationId: listAllTools
      responses:
        '200':
          description: List of all tools
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tool'
                maxItems: 1000
        '501':
          description: Not implemented yet
  
  /api/mcp/servers/{id}/tools:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: MCP server ID
    
    get:
      summary: List tools for a specific server
      description: Get a list of tools for a specific MCP server
      operationId: listServerTools
      responses:
        '200':
          description: List of tools for the server
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tool'
                maxItems: 1000
        '404':
          description: Server not found
        '501':
          description: Not implemented yet
  
  /api/mcp/rediscover-tools:
    post:
      summary: Rediscover all tools
      description: Trigger a rediscovery of all tools across all servers
      operationId: rediscoverAllTools
      responses:
        '202':
          description: Rediscovery initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "rediscovery_initiated_for_all_servers"
  
  /api/mcp/servers/{id}/rediscover-tools:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: MCP server ID
    
    post:
      summary: Rediscover tools for a specific server
      description: Trigger a rediscovery of tools for a specific MCP server
      operationId: rediscoverServerTools
      responses:
        '202':
          description: Rediscovery initiated for server
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "rediscovery_initiated"
                  server_id:
                    type: integer
        '404':
          description: Server not found

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    MCPServer:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: "Test Server"
        url:
          type: string
          example: "http://mcp-server-example.com"
        created_at:
          type: string
          format: date-time
          example: "2023-04-11T14:30:00Z"
        last_check:
          type: string
          format: date-time
          example: "2023-04-11T14:35:00Z"
        last_check_error:
          type: string
          nullable: true
          example: null
    
    Tool:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 101
        server_id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: "Example Tool"
        description:
          type: string
          example: "A tool for performing example operations"
        schema:
          type: object
          example: {}
        created_at:
          type: string
          format: date-time
          example: "2023-04-11T14:40:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2023-04-11T14:40:00Z"