openapi: "3.1.0"
info:
  title: AegisGitea MCP
  description: >
    AI access to your self-hosted Gitea instance via the AegisGitea MCP server.
    Each user authenticates with their own Gitea account via OAuth2.
  version: "0.2.0"

servers:
  - url: "https://YOUR_MCP_SERVER_DOMAIN"
    description: >
      Replace YOUR_MCP_SERVER_DOMAIN with the public hostname of your AegisGitea-MCP instance.

components:
  securitySchemes:
    gitea_oauth:
      type: oauth2
      flows:
        authorizationCode:
          # Replace YOUR_GITEA_DOMAIN with your self-hosted Gitea instance hostname.
          authorizationUrl: "https://YOUR_GITEA_DOMAIN/login/oauth/authorize"
          # The token URL must point to the MCP server's OAuth proxy endpoint.
          tokenUrl: "https://YOUR_MCP_SERVER_DOMAIN/oauth/token"
          scopes:
            read:repository: "Read access to Gitea repositories"
            write:repository: "Write access to Gitea repositories"

security:
  - gitea_oauth:
      - read:repository

paths:
  /mcp/tools:
    get:
      operationId: listTools
      summary: List available MCP tools
      description: Returns all tools available on this MCP server. Public endpoint, no authentication required.
      security: []
      responses:
        "200":
          description: List of available MCP tools
          content:
            application/json:
              schema:
                type: object
                properties:
                  tools:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        description:
                          type: string

  /mcp/tool/call:
    post:
      operationId: callTool
      summary: Execute an MCP tool
      description: >
        Execute a named MCP tool with the provided arguments.
        The authenticated user's Gitea token is used for all Gitea API calls,
        so only repositories and data accessible to the user will be returned.
      security:
        - gitea_oauth:
            - read:repository
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - tool
                - arguments
              properties:
                tool:
                  type: string
                  description: Name of the MCP tool to execute
                  example: list_repositories
                arguments:
                  type: object
                  description: Tool-specific arguments
                  example: {}
                correlation_id:
                  type: string
                  description: Optional correlation ID for request tracing
      responses:
        "200":
          description: Tool execution result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  result:
                    type: object
                  correlation_id:
                    type: string
        "401":
          description: Authentication required or token invalid
        "403":
          description: Policy denied the request
        "404":
          description: Tool not found
        "429":
          description: Rate limit exceeded