openapi: 3.1.0
info:
  title: AI Readiness Kit — MCP Server API
  version: 1.0.0
  summary: Model Context Protocol endpoint for the AI Readiness Kit
  description: |
    The AI Readiness Kit exposes a **Model Context Protocol (MCP) server** at
    `https://ai.silverbackmarketing.com/api/mcp`.

    This is a single JSON-RPC 2.0 endpoint using the MCP **Streamable HTTP**
    transport (protocol version `2025-03-26`). All interaction happens via
    `POST` requests with a JSON-RPC body; responses are returned as
    Server-Sent Events (`text/event-stream`) containing JSON-RPC messages.
    `GET` requests return `405 Method Not Allowed`.

    **No authentication is required.** There is no API key and no signup.
    Rate limits may apply at extreme volume.

    ### What the server provides
    - **6 tools** — generate AI readiness files for any domain, list output
      files, read per-file specifications, fetch the full skill workflow,
      fetch the site-classification guide, and convert rag-index JSON to JSONL.
    - **2 resources** — `ai-readiness://skill` (the full SKILL.md workflow) and
      `ai-readiness://file-specs` (detailed specs for all output files), both
      served as `text/markdown`.
    - **1 prompt** — `generate-ai-readiness(url)`, which starts the full
      workflow for a website URL or domain.

    ### Recommended usage
    MCP-capable clients (Claude Code, Cursor, VS Code/Copilot, OpenAI Codex,
    Google Antigravity, Claude Desktop via `mcp-remote`) should connect using
    their native MCP configuration rather than raw HTTP:

    ```json
    { "mcpServers": { "ai-readiness": { "type": "http",
        "url": "https://ai.silverbackmarketing.com/api/mcp" } } }
    ```

    Setup guide with per-client configs: https://ai.silverbackmarketing.com/#mcp

    This OpenAPI document describes the raw JSON-RPC surface for clients and
    integrators that are not MCP-native.
  contact:
    name: Silverback Marketing
    email: info@silverbackmarketing.com
    url: https://silverbackmarketing.com/contact/
  license:
    name: MIT
    url: https://github.com/silverbackmarketing/ai-readiness/blob/main/LICENSE
  termsOfService: https://ai.silverbackmarketing.com/training-data-policy.txt
externalDocs:
  description: AI Readiness Kit — full guide, FAQ, and MCP setup
  url: https://ai.silverbackmarketing.com/guide
servers:
  - url: https://ai.silverbackmarketing.com
    description: Production (hosted, no auth)
tags:
  - name: mcp
    description: Model Context Protocol JSON-RPC endpoint
paths:
  /api/mcp:
    post:
      tags: [mcp]
      operationId: mcpJsonRpc
      summary: MCP JSON-RPC 2.0 endpoint (Streamable HTTP transport)
      description: |
        Send any MCP JSON-RPC message. Supported methods include:

        | Method | Purpose |
        |--------|---------|
        | `initialize` | Handshake; returns protocol version, capabilities, and server info (`ai-readiness` v1.0.0) |
        | `tools/list` | List the 6 available tools with JSON Schemas |
        | `tools/call` | Invoke a tool by name with arguments |
        | `resources/list` | List the 2 bundled markdown resources |
        | `resources/read` | Read a resource by URI (`ai-readiness://skill`, `ai-readiness://file-specs`) |
        | `prompts/list` | List the 1 available prompt |
        | `prompts/get` | Get the `generate-ai-readiness` prompt with a `url` argument |

        ### Tools available via `tools/call`
        - `generate_ai_readiness_files` — args: `{ "url": string }` — returns the
          full research/classify/generate workflow for the connected agent to
          execute against the given domain.
        - `list_output_files` — no args — returns all output files in
          generation order with purposes.
        - `get_file_spec` — args: `{ "filename": string }` — returns the
          detailed specification for one output file (e.g. `llms.txt`,
          `.well-known/ai-plugin.json`).
        - `get_skill_instructions` — no args — returns the full skill workflow
          (research checklist, classification, generation order, quality rules).
        - `get_site_classification_guide` — no args — returns the site-type
          classification table (SaaS, education, e-commerce, healthcare, etc.).
        - `generate_rag_jsonl` — args: `{ "rag_index_json": string }` — converts
          rag-index.json content (a JSON array) to JSON Lines, one record per line.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
            examples:
              initialize:
                summary: MCP handshake
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: initialize
                  params:
                    protocolVersion: '2025-03-26'
                    capabilities: {}
                    clientInfo: { name: my-client, version: '1.0' }
              toolsList:
                summary: List all tools
                value: { jsonrpc: '2.0', id: 2, method: tools/list, params: {} }
              generateFiles:
                summary: Start file generation for a domain
                value:
                  jsonrpc: '2.0'
                  id: 3
                  method: tools/call
                  params:
                    name: generate_ai_readiness_files
                    arguments: { url: example.com }
              getFileSpec:
                summary: Get the spec for one output file
                value:
                  jsonrpc: '2.0'
                  id: 4
                  method: tools/call
                  params:
                    name: get_file_spec
                    arguments: { filename: llms.txt }
              generateRagJsonl:
                summary: Convert a rag-index.json array to JSONL
                value:
                  jsonrpc: '2.0'
                  id: 5
                  method: tools/call
                  params:
                    name: generate_rag_jsonl
                    arguments:
                      rag_index_json: '[{"url":"https://example.com/","title":"Home","topics":["example"]}]'
              readSkillResource:
                summary: Read the bundled skill instructions resource
                value:
                  jsonrpc: '2.0'
                  id: 6
                  method: resources/read
                  params: { uri: 'ai-readiness://skill' }
              getPrompt:
                summary: Get the generate-ai-readiness prompt
                value:
                  jsonrpc: '2.0'
                  id: 7
                  method: prompts/get
                  params:
                    name: generate-ai-readiness
                    arguments: { url: example.com }
      responses:
        '200':
          description: |
            JSON-RPC response, framed as Server-Sent Events. Each SSE `data:`
            line contains one complete JSON-RPC 2.0 response object
            (see `JsonRpcResponse`). Clients should set
            `Accept: application/json, text/event-stream`.
          content:
            text/event-stream:
              schema:
                type: string
                description: 'SSE stream; each event''s data line is a JSON-RPC response, e.g.: data: {"jsonrpc":"2.0","id":1,"result":{...}}'
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '400':
          description: Malformed JSON-RPC request.
        '405':
          description: Method not allowed — the endpoint only accepts POST.
        '429':
          description: Rate limit exceeded (extreme volume only).
      security: []   # No authentication required
components:
  schemas:
    JsonRpcRequest:
      type: object
      required: [jsonrpc, method]
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          description: Request identifier (omit for notifications).
          oneOf:
            - type: string
            - type: integer
        method:
          type: string
          enum:
            - initialize
            - notifications/initialized
            - tools/list
            - tools/call
            - resources/list
            - resources/read
            - prompts/list
            - prompts/get
            - ping
        params:
          type: object
          description: Method-specific parameters. For tools/call see ToolCallParams.
      examples:
        - jsonrpc: '2.0'
          id: 1
          method: tools/call
          params:
            name: list_output_files
            arguments: {}
    ToolCallParams:
      type: object
      required: [name]
      properties:
        name:
          type: string
          enum:
            - generate_ai_readiness_files
            - list_output_files
            - get_file_spec
            - get_skill_instructions
            - get_site_classification_guide
            - generate_rag_jsonl
        arguments:
          description: Tool-specific arguments (see per-tool schemas).
          oneOf:
            - $ref: '#/components/schemas/GenerateAiReadinessFilesArgs'
            - $ref: '#/components/schemas/EmptyArgs'
            - $ref: '#/components/schemas/GetFileSpecArgs'
            - $ref: '#/components/schemas/GenerateRagJsonlArgs'
    GenerateAiReadinessFilesArgs:
      type: object
      title: generate_ai_readiness_files arguments
      required: [url]
      additionalProperties: false
      properties:
        url:
          type: string
          description: Website URL or domain, e.g. shopify.com or https://example.com
    GetFileSpecArgs:
      type: object
      title: get_file_spec arguments
      required: [filename]
      additionalProperties: false
      properties:
        filename:
          type: string
          description: Output filename, e.g. llms.txt or .well-known/ai-plugin.json
          examples: [llms.txt, ai.txt, ai-entities.json, .well-known/ai-plugin.json]
    GenerateRagJsonlArgs:
      type: object
      title: generate_rag_jsonl arguments
      required: [rag_index_json]
      additionalProperties: false
      properties:
        rag_index_json:
          type: string
          description: String contents of rag-index.json (must be a JSON array).
    EmptyArgs:
      type: object
      title: No arguments (list_output_files, get_skill_instructions, get_site_classification_guide)
      additionalProperties: false
    JsonRpcResponse:
      type: object
      required: [jsonrpc]
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
            - type: string
            - type: integer
        result:
          type: object
          description: |
            Method result. For `initialize`: protocolVersion, capabilities
            (tools, resources, prompts — all with listChanged), and serverInfo
            ({ name: "ai-readiness", version: "1.0.0" }). For `tools/call`:
            { content: [{ type: "text", text: "..." }] }. For `resources/read`:
            { contents: [{ uri, mimeType, text }] }.
        error:
          type: object
          description: JSON-RPC error object (code, message, optional data).
          properties:
            code: { type: integer }
            message: { type: string }
            data: {}