{
  "openapi": "3.0.3",
  "info": {
    "title": "Blackthorn Cycles — MCP tools API",
    "description": "A bicycle-workshop demo showing a website assistant grounded in the shop's own published work list and plan terms, booking a repair as a structured record through an in-chat form card rather than asking for one detail at a time, serving the work list and the job book over its own MCP server, registering its page actions over WebMCP, and reading back a signed-in customer's own jobs through the identity hand-off.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://helpscout.demo.busymate.ai"
    }
  ],
  "paths": {
    "/mcp": {
      "post": {
        "operationId": "mcpJsonRpcCall",
        "summary": "Invoke this demo's MCP tools over JSON-RPC 2.0",
        "description": "Every tool below is called the same way: POST a JSON-RPC 2.0 envelope with `method: \"tools/call\"` and `params: {name, arguments}`, where `name` is one of list_services, list_plans, search_knowledge, get_ticket, my_tickets, open_ticket, highlight_service, open_desk_form and `arguments` matches that tool's `<name>Args` schema under `components.schemas`. `method: \"tools/list\"` returns the live catalogue; `method: \"initialize\"` starts the session.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "enum": [
                      "2.0"
                    ]
                  },
                  "id": {
                    "description": "Request id, echoed on the response."
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "initialize",
                      "tools/list",
                      "tools/call",
                      "resources/list",
                      "resources/read"
                    ]
                  },
                  "params": {
                    "type": "object",
                    "description": "For tools/call: { name: <tool name>, arguments: <that tool's Args schema> }."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response: {jsonrpc, id, result} or {jsonrpc, id, error}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "list_servicesArgs": {
        "description": "The full Blackthorn Cycles catalogue — every service on offer, with its code, what it covers, which plan it belongs to and how long it takes.",
        "type": "object",
        "properties": {},
        "additionalProperties": false
      },
      "list_plansArgs": {
        "description": "Blackthorn Cycles's plans and what each one costs, including which services each tier covers and who it suits.",
        "type": "object",
        "properties": {},
        "additionalProperties": false
      },
      "search_knowledgeArgs": {
        "description": "Search everything Blackthorn Cycles publishes — the services, the plan detail and the answers on its FAQ — by keyword. Use this before answering from memory.",
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "A keyword or short phrase, e.g. a service name, a price question or a policy."
          }
        },
        "required": [
          "query"
        ],
        "additionalProperties": false
      },
      "get_ticketArgs": {
        "description": "Look up one ticket at Blackthorn Cycles by its ticket number together with the email it was raised under. Both are needed — a ticket number alone never returns anything.",
        "type": "object",
        "properties": {
          "reference": {
            "type": "string",
            "description": "The ticket number."
          },
          "email": {
            "type": "string",
            "description": "The email address it belongs to."
          }
        },
        "required": [
          "reference",
          "email"
        ],
        "additionalProperties": false
      },
      "my_ticketsArgs": {
        "description": "Every ticket belonging to the SIGNED-IN visitor at Blackthorn Cycles, with its current state and what happens next. Only ever call this for the person actually signed in — never for an address somebody types.",
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "The signed-in visitor's own email address, taken from their identity — never asked for in the chat."
          }
        },
        "required": [
          "email"
        ],
        "additionalProperties": false
      },
      "open_ticketArgs": {
        "description": "Do NOT ask the person for these fields one at a time — calling this with whatever is already known IS how the form opens. Open a ticket at Blackthorn Cycles, and report back what was recorded.",
        "type": "object",
        "properties": {
          "subject": {
            "type": "string",
            "description": "Which service it concerns — a code from list_services. Leave blank if unknown; the form lets the person pick."
          },
          "summary": {
            "type": "string",
            "description": "One line of detail in the person's own words."
          },
          "urgency": {
            "type": "string",
            "description": "How soon it matters, or the slot they want."
          },
          "name": {
            "type": "string",
            "description": "Who it is for."
          },
          "email": {
            "type": "string",
            "description": "The email the confirmation goes to."
          }
        },
        "additionalProperties": false
      },
      "highlight_serviceArgs": {
        "description": "Scroll Blackthorn Cycles's catalogue to one entry and highlight it on the page the visitor is reading. Runs in the page; it changes what is on screen, not any record.",
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "The catalogue code to bring into view, from list_services."
          }
        },
        "required": [
          "code"
        ],
        "additionalProperties": false
      },
      "open_desk_formArgs": {
        "description": "Open Blackthorn Cycles's open a ticket form already on this page, with any known details filled in. Runs in the page — it opens a form, it does not submit one.",
        "type": "object",
        "properties": {
          "subject": {
            "type": "string",
            "description": "The catalogue code to preselect."
          },
          "summary": {
            "type": "string",
            "description": "Text to put in the detail field."
          }
        },
        "additionalProperties": false
      }
    }
  }
}