openapi: 3.0.3
info:
  title: MCPBridge API
  description: |
    MCPBridge connects any MCP server to any MCP client across network boundaries.
    
    This API allows you to interact with MCP servers through a simple HTTP interface,
    eliminating the need for complex networking, firewalls, and tunneling setups.
    
    ## Authentication
    All requests require an API key in the Authorization header:
    ```
    Authorization: Bearer YOUR_API_KEY
    ```
    
    ## Base URL
    Your personal MCPBridge endpoint:
    ```
    https://your-account.mcpbrid.ge/api/v1
    ```
  version: 1.0.0
  contact:
    name: MCPBridge Support
    url: https://mcpbrid.ge/support
    email: support@mcpbrid.ge
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://your-account.mcpbrid.ge/api/v1
    description: Production server (replace 'your-account' with your actual account name)
  - url: https://demo.mcpbrid.ge/api/v1
    description: Demo server for testing

security:
  - bearerAuth: []

paths:
  /tools:
    get:
      summary: List available tools
      description: Get a list of all tools available from connected MCP servers
      tags:
        - Tools
      responses:
        '200':
          description: List of available tools
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      tools:
                        type: array
                        items:
                          $ref: '#/components/schemas/Tool'
              example:
                success: true
                data:
                  tools:
                    - name: file_reader
                      description: Read file contents
                      inputSchema:
                        type: object
                        properties:
                          path:
                            type: string
                            description: File path to read
                        required: [path]
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /tools/call:
    post:
      summary: Call a tool
      description: Execute a tool with the provided arguments
      tags:
        - Tools
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolCallRequest'
            examples:
              file_reader:
                summary: Read a file
                value:
                  tool: file_reader
                  input:
                    path: /path/to/file.txt
              database_query:
                summary: Query database
                value:
                  tool: database_query
                  input:
                    query: SELECT * FROM users WHERE active = true
                    limit: 10
      responses:
        '200':
          description: Tool execution result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      result:
                        oneOf:
                          - type: string
                          - type: object
                          - type: array
                        description: Tool execution result
                      isError:
                        type: boolean
                        description: Whether the tool execution resulted in an error
                        example: false
              examples:
                success:
                  summary: Successful tool execution
                  value:
                    success: true
                    data:
                      result: "File contents here..."
                      isError: false
                error:
                  summary: Tool execution error
                  value:
                    success: true
                    data:
                      result: "File not found: /path/to/file.txt"
                      isError: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /resources:
    get:
      summary: List available resources
      description: Get a list of all resources available from connected MCP servers
      tags:
        - Resources
      responses:
        '200':
          description: List of available resources
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      resources:
                        type: array
                        items:
                          $ref: '#/components/schemas/Resource'
              example:
                success: true
                data:
                  resources:
                    - uri: file:///path/to/document.md
                      name: Project Documentation
                      description: Main project documentation
                      mimeType: text/markdown
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /resources/read:
    post:
      summary: Read a resource
      description: Read the contents of a specific resource
      tags:
        - Resources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResourceReadRequest'
            example:
              uri: file:///path/to/document.md
      responses:
        '200':
          description: Resource content
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      contents:
                        type: array
                        items:
                          $ref: '#/components/schemas/ResourceContent'
              example:
                success: true
                data:
                  contents:
                    - uri: file:///path/to/document.md
                      mimeType: text/markdown
                      text: "# Project Documentation\n\nThis is the main documentation..."
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /prompts:
    get:
      summary: List available prompts
      description: Get a list of all prompts available from connected MCP servers
      tags:
        - Prompts
      responses:
        '200':
          description: List of available prompts
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      prompts:
                        type: array
                        items:
                          $ref: '#/components/schemas/Prompt'
              example:
                success: true
                data:
                  prompts:
                    - name: code_review
                      description: Review code for issues and improvements
                      arguments:
                        - name: code
                          description: Code to review
                          required: true
                        - name: language
                          description: Programming language
                          required: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /prompts/get:
    post:
      summary: Get a prompt
      description: Get a formatted prompt with the provided arguments
      tags:
        - Prompts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptGetRequest'
            example:
              name: code_review
              arguments:
                code: "function hello() { return 'world'; }"
                language: javascript
      responses:
        '200':
          description: Formatted prompt
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      description:
                        type: string
                        description: Prompt description
                      messages:
                        type: array
                        items:
                          $ref: '#/components/schemas/PromptMessage'
              example:
                success: true
                data:
                  description: "Code review prompt for JavaScript"
                  messages:
                    - role: user
                      content:
                        type: text
                        text: "Please review this JavaScript code: function hello() { return 'world'; }"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /status:
    get:
      summary: Get bridge status
      description: Get the current status of your MCPBridge connection
      tags:
        - Status
      responses:
        '200':
          description: Bridge status
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      connected:
                        type: boolean
                        description: Whether MCP servers are connected
                        example: true
                      servers:
                        type: array
                        items:
                          $ref: '#/components/schemas/ServerStatus'
                      uptime:
                        type: string
                        description: Bridge uptime
                        example: "2d 14h 32m"
              example:
                success: true
                data:
                  connected: true
                  servers:
                    - name: file-server
                      status: connected
                      capabilities: [tools, resources]
                      lastSeen: "2024-01-15T10:30:00Z"
                  uptime: "2d 14h 32m"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: API key for authentication

  schemas:
    Tool:
      type: object
      properties:
        name:
          type: string
          description: Tool name
          example: file_reader
        description:
          type: string
          description: Tool description
          example: Read file contents
        inputSchema:
          type: object
          description: JSON schema for tool input
          additionalProperties: true
      required: [name, description, inputSchema]

    ToolCallRequest:
      type: object
      properties:
        tool:
          type: string
          description: Name of the tool to call
          example: file_reader
        input:
          type: object
          description: Tool input arguments
          additionalProperties: true
          example:
            path: /path/to/file.txt
      required: [tool, input]

    Resource:
      type: object
      properties:
        uri:
          type: string
          description: Resource URI
          example: file:///path/to/document.md
        name:
          type: string
          description: Resource name
          example: Project Documentation
        description:
          type: string
          description: Resource description
          example: Main project documentation
        mimeType:
          type: string
          description: MIME type of the resource
          example: text/markdown
      required: [uri, name, mimeType]

    ResourceReadRequest:
      type: object
      properties:
        uri:
          type: string
          description: URI of the resource to read
          example: file:///path/to/document.md
      required: [uri]

    ResourceContent:
      type: object
      properties:
        uri:
          type: string
          description: Resource URI
          example: file:///path/to/document.md
        mimeType:
          type: string
          description: MIME type of the content
          example: text/markdown
        text:
          type: string
          description: Text content (for text resources)
          example: "# Project Documentation\n\nThis is the main documentation..."
        blob:
          type: string
          format: byte
          description: Binary content (for binary resources)
      required: [uri, mimeType]

    Prompt:
      type: object
      properties:
        name:
          type: string
          description: Prompt name
          example: code_review
        description:
          type: string
          description: Prompt description
          example: Review code for issues and improvements
        arguments:
          type: array
          items:
            $ref: '#/components/schemas/PromptArgument'
          description: Available arguments for the prompt
      required: [name, description, arguments]

    PromptArgument:
      type: object
      properties:
        name:
          type: string
          description: Argument name
          example: code
        description:
          type: string
          description: Argument description
          example: Code to review
        required:
          type: boolean
          description: Whether the argument is required
          example: true
      required: [name, description, required]

    PromptGetRequest:
      type: object
      properties:
        name:
          type: string
          description: Name of the prompt to get
          example: code_review
        arguments:
          type: object
          description: Arguments for the prompt
          additionalProperties: true
          example:
            code: "function hello() { return 'world'; }"
            language: javascript
      required: [name, arguments]

    PromptMessage:
      type: object
      properties:
        role:
          type: string
          enum: [user, assistant, system]
          description: Message role
          example: user
        content:
          type: object
          properties:
            type:
              type: string
              enum: [text, image]
              description: Content type
              example: text
            text:
              type: string
              description: Text content
              example: "Please review this JavaScript code: function hello() { return 'world'; }"
            image:
              type: string
              description: Image data (base64 encoded)
          required: [type]
      required: [role, content]

    ServerStatus:
      type: object
      properties:
        name:
          type: string
          description: Server name
          example: file-server
        status:
          type: string
          enum: [connected, disconnected, error]
          description: Server connection status
          example: connected
        capabilities:
          type: array
          items:
            type: string
            enum: [tools, resources, prompts]
          description: Server capabilities
          example: [tools, resources]
        lastSeen:
          type: string
          format: date-time
          description: Last time the server was seen
          example: "2024-01-15T10:30:00Z"
      required: [name, status, capabilities, lastSeen]

    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
              example: INVALID_REQUEST
            message:
              type: string
              description: Error message
              example: Tool 'invalid_tool' not found
          required: [code, message]
      required: [success, error]

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: INVALID_REQUEST
              message: Missing required parameter 'tool'

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: UNAUTHORIZED
              message: Invalid or missing API key

    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: NOT_FOUND
              message: Resource not found

    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: INTERNAL_ERROR
              message: An unexpected error occurred

tags:
  - name: Tools
    description: Execute tools from connected MCP servers
  - name: Resources
    description: Read resources from connected MCP servers
  - name: Prompts
    description: Use prompts from connected MCP servers
  - name: Status
    description: Check bridge and server status