openapi: 3.1.0
info:
  title: MCP Server Quality Corpus
  version: 0.2.0
  description: Hosted dataset-backed x402 API for MCP server freshness, installability, security, incident advisories, and tool-handshake quality.
servers:
  - url: https://mcp-server-quality-corpus.mtree.workers.dev
paths:
  /healthz:
    get:
      operationId: healthz
      responses:
        '200': { description: OK }
  /dataset/health:
    get:
      operationId: datasetHealth
      responses:
        '200': { description: Hosted dataset freshness and coverage }
  /v1/mcp/server_quality_report:
    post:
      operationId: mcpServerQualityReport
      summary: MCP server quality report
      description: Paid x402 endpoint. Returns freshness, installability, security, handshake, risk flags, tools, evidence, and recommendations for one MCP server.
      x-x402-price-usd: 0.15
      x402:
        price: "$0.15"
        network: base
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                query: { type: string, description: Name, registry id, repo URL, package URL, or category to match. }
                repo_url: { type: string }
                package_url: { type: string }
      responses:
        '200': { description: Quality report }
        '402': { description: x402 payment required }
  /v1/mcp/compare_candidates:
    post:
      operationId: mcpCompareCandidates
      summary: Compare MCP server candidates
      description: Paid x402 endpoint. Ranks candidate MCP servers using hosted quality, freshness, installability, security, and handshake signals.
      x-x402-price-usd: 0.25
      x402:
        price: "$0.25"
        network: base
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                candidates:
                  type: array
                  items: { type: string }
                query: { type: string }
                category: { type: string }
                limit: { type: integer, minimum: 1, maximum: 25 }
      responses:
        '200': { description: Ranked candidates }
        '402': { description: x402 payment required }
  /v1/mcp/incident_watch:
    post:
      operationId: mcpIncidentWatch
      summary: MCP incident watch
      description: Paid x402 endpoint. Returns current MCP incident/security advisories and controls matched to a server, category, or deployment plan. Response includes dataset_fresh_at and provenance.
      x-x402-price-usd: 0.20
      x402:
        price: "$0.20"
        network: base
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                query: { type: string }
                server: { type: string }
                category: { type: string }
                deployment: { type: string }
                limit: { type: integer, minimum: 1, maximum: 12 }
      responses:
        '200': { description: Incident advisory report }
        '402': { description: x402 payment required }
  /mcp:
    get:
      operationId: mcpToolsListGet
      responses:
        '200': { description: MCP tools list }
    post:
      operationId: mcpJsonRpc
      responses:
        '200': { description: MCP JSON-RPC response }

x-money-tree-buyer-readiness:
  quote_before_signing: "Read the unpaid 402 quote before signing or before paying; compare payTo, amount, network, asset, and resource."
  rail_readiness:
    network: "eip155:8453"
    asset: "USDC on Base"
  payment_proof_policy:
    require_payment_response: true
    receipt_fields: [transaction, network, asset, amount, payer, payTo]
  funding_handoff: "If the buyer lacks Base USDC or the settlement asset, stop before signing and hand off to funding; retry only with the same request after funding."
  revenue_metric_policy: "External paid calls are settled revenue; self-funded/internal-credit calls are protocol proof only."
  decision_json_shape:
    required_keys: [verdict, recommendation, warnings, confidence, metadata, evidence, action, stop_conditions, fallbacks, attribution]
