openapi: 3.1.0
info:
  title: Fundamental Group MCP Server
  version: 0.5.0
  description: |
    OpenAPI description of the public Fundamental Group Model Context Protocol
    (MCP) server. The server speaks JSON-RPC 2.0 over a single HTTP endpoint
    using the MCP Streamable HTTP transport
    (https://modelcontextprotocol.io/specification/2025-06-18/basic/transports).

    All operations POST a JSON-RPC envelope to the same URL. This document is
    published so ai-plugin.json's `api.openapi` block resolves to a real spec
    and to give AI crawlers a machine-readable description of the three
    public tools. The MCP `.well-known/mcp.json` manifest remains the
    authoritative machine surface for MCP clients.
  contact:
    name: Fundamental Group
    email: info@fundamentalmedia.com
    url: https://fundamentalgroup.net/mcp
  license:
    name: Proprietary
    url: https://fundamentalgroup.net/terms-of-use
servers:
  - url: https://lavzugkeuethatxainhv.supabase.co/functions/v1
    description: Production MCP server (Streamable HTTP transport)
tags:
  - name: MCP
    description: JSON-RPC 2.0 methods exposed by the MCP server.
paths:
  /mcp:
    post:
      tags: [MCP]
      operationId: mcpJsonRpc
      summary: MCP JSON-RPC endpoint
      description: |
        Single JSON-RPC 2.0 endpoint. The `method` field selects the
        operation; see the `JsonRpcRequest` schema and the per-method
        examples for `initialize`, `tools/list`, and `tools/call`.
        No authentication is required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
            examples:
              initialize:
                summary: Initialize the MCP session
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: initialize
                  params:
                    protocolVersion: "2025-06-18"
                    capabilities: {}
                    clientInfo:
                      name: example-client
                      version: "1.0.0"
              toolsList:
                summary: List available tools
                value:
                  jsonrpc: "2.0"
                  id: 2
                  method: tools/list
              callAbout:
                summary: Call about_fundamental_group
                value:
                  jsonrpc: "2.0"
                  id: 3
                  method: tools/call
                  params:
                    name: about_fundamental_group
                    arguments: {}
              callSearch:
                summary: Call search_website_pages
                value:
                  jsonrpc: "2.0"
                  id: 4
                  method: tools/call
                  params:
                    name: search_website_pages
                    arguments:
                      query: alphix
                      limit: 10
              callGet:
                summary: Call get_website_page
                value:
                  jsonrpc: "2.0"
                  id: 5
                  method: tools/call
                  params:
                    name: get_website_page
                    arguments:
                      slug: about
              callGetCompanyFacts:
                summary: Call get_company_facts (filtered slice)
                value:
                  jsonrpc: "2.0"
                  id: 6
                  method: tools/call
                  params:
                    name: get_company_facts
                    arguments:
                      section: offices
              callListInsights:
                summary: Call list_insights
                value:
                  jsonrpc: "2.0"
                  id: 7
                  method: tools/call
                  params:
                    name: list_insights
                    arguments:
                      limit: 5
              callGetInsight:
                summary: Call get_insight
                value:
                  jsonrpc: "2.0"
                  id: 8
                  method: tools/call
                  params:
                    name: get_insight
                    arguments:
                      slug: esg-advertising-remains-at-a-record-low-in-europe
      responses:
        '200':
          description: JSON-RPC 2.0 response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
            text/event-stream:
              schema:
                type: string
                description: Server-Sent Events stream carrying JSON-RPC responses.
        '400':
          description: Malformed JSON-RPC request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
components:
  schemas:
    JsonRpcRequest:
      type: object
      required: [jsonrpc, method]
      properties:
        jsonrpc:
          type: string
          const: "2.0"
        id:
          oneOf:
            - type: string
            - type: integer
        method:
          type: string
          description: MCP method name (e.g. `initialize`, `tools/list`, `tools/call`).
          examples: [initialize, tools/list, tools/call]
        params:
          type: object
          additionalProperties: true
    JsonRpcResponse:
      type: object
      required: [jsonrpc]
      properties:
        jsonrpc:
          type: string
          const: "2.0"
        id:
          oneOf:
            - type: string
            - type: integer
            - type: 'null'
        result:
          type: object
          additionalProperties: true
        error:
          type: object
          properties:
            code: { type: integer }
            message: { type: string }
            data: {}
    ToolContent:
      type: object
      description: An MCP content block returned by a tool call.
      properties:
        type:
          type: string
          enum: [text, image, resource]
        text:
          type: string
    ToolCallResult:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/ToolContent'
        isError:
          type: boolean
        structuredContent:
          type: object
          additionalProperties: true
    AboutFundamentalGroupArgs:
      type: object
      additionalProperties: false
      description: about_fundamental_group takes no arguments.
    SearchWebsitePagesArgs:
      type: object
      additionalProperties: false
      required: [query]
      properties:
        query:
          type: string
          minLength: 1
          description: Search term matched against title, meta, slug, canonical URL, tags, and body content.
        page_type:
          type: string
          minLength: 1
          description: Optional filter — exact page_type (e.g. `alphix`, `technology`, `static`).
        updated_after:
          type: string
          format: date-time
          description: Optional ISO-8601 timestamp; only return pages updated after this time.
        limit:
          type: integer
          minimum: 1
          maximum: 50
          default: 20
        cursor:
          type: string
          description: Opaque pagination cursor from a previous response's `next_cursor`.
    GetWebsitePageArgs:
      type: object
      additionalProperties: false
      required: [slug]
      properties:
        slug:
          type: string
          minLength: 1
          description: |
            Page identifier. Accepts a canonical DB slug (`technology-alphix-order-bridge`),
            a URL path (`technology/alphix/order-bridge`, leading/trailing slashes optional),
            or a full `https://www.fundamentalgroup.net/...` URL.
        format:
          type: string
          enum: [structured, markdown, both]
          default: both
          description: Output format for page content.
