{
  "openapi": "3.1.0",
  "info": {
    "title": "Umesh Malik developer resources",
    "summary": "MCP JSON-RPC API and discovery files for umesh-malik.com",
    "description": "Public, unauthenticated surface for Umesh Malik's portfolio and technical blog. The live API is POST /mcp and POST /api/v1/mcp (Model Context Protocol, Streamable HTTP, JSON-RPC 2.0). There are no webhooks, no write endpoints, and no OAuth tokens to mint. URL-path versioning: the current REST prefix is https://umesh-malik.com/api/v1. The live MCP JSON-RPC endpoint is POST https://umesh-malik.com/mcp (also POST https://umesh-malik.com/api/v1/mcp). Breaking changes ship as /api/v2; v1 keeps working. Deprecated operations send RFC 8594 Sunset and RFC 9745 Deprecation headers at least 90 days before removal. No operation is deprecated today. Pin /api/v1 or send API-Version: 1. Human docs: https://umesh-malik.com/developers.",
    "version": "1.0.0",
    "contact": {
      "name": "Umesh Malik",
      "email": "ask@umesh-malik.com",
      "url": "https://umesh-malik.com"
    },
    "license": {
      "name": "Content license: see /terms",
      "url": "https://umesh-malik.com/terms"
    }
  },
  "x-deprecation-policy": {
    "strategy": "url-path",
    "current": "https://umesh-malik.com/api/v1",
    "header": "API-Version",
    "sunset": "RFC 8594 Sunset + RFC 9745 Deprecation, minimum 90 days",
    "deprecated": []
  },
  "x-rate-limit-policy": {
    "algorithm": "fixed-window",
    "limit": 120,
    "windowSeconds": 60,
    "headers": [
      "RateLimit",
      "RateLimit-Policy",
      "RateLimit-Limit",
      "RateLimit-Remaining",
      "RateLimit-Reset"
    ],
    "onExceeded": "HTTP 429 with Retry-After",
    "scope": "/mcp and /api/*"
  },
  "externalDocs": {
    "description": "Umesh Malik developer resources",
    "url": "https://umesh-malik.com/developers"
  },
  "servers": [
    {
      "url": "https://umesh-malik.com/api/v1",
      "description": "Umesh Malik REST API v1 (current). Pin this prefix."
    },
    {
      "url": "https://umesh-malik.com",
      "description": "Canonical origin. POST /mcp aliases POST /api/v1/mcp."
    }
  ],
  "tags": [
    {
      "name": "mcp",
      "description": "Live MCP JSON-RPC endpoint (Worker-metered)."
    },
    {
      "name": "v1",
      "description": "REST v1 catalog and versioned MCP alias."
    },
    {
      "name": "discovery",
      "description": "Prerendered machine-readable indexes."
    }
  ],
  "paths": {
    "/mcp": {
      "post": {
        "tags": [
          "mcp"
        ],
        "operationId": "mcpJsonRpc",
        "summary": "Call the Umesh Malik MCP server",
        "description": "JSON-RPC 2.0 over the MCP Streamable HTTP transport. Protocol 2025-06-18. Tools: search_posts, get_post, list_topics, get_profile. No session id is issued or required.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              },
              "examples": {
                "initialize": {
                  "summary": "initialize",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "initialize",
                    "params": {}
                  }
                },
                "toolsList": {
                  "summary": "tools/list",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "tools/list",
                    "params": {}
                  }
                },
                "searchPosts": {
                  "summary": "search_posts",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "tools/call",
                    "params": {
                      "name": "search_posts",
                      "arguments": {
                        "query": "mcp",
                        "limit": 5
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC result or JSON-RPC error object.",
            "headers": {
              "API-Version": {
                "description": "Major REST version currently serving this response.",
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              },
              "Deprecation": {
                "description": "RFC 9745. `?0` means this operation is not deprecated.",
                "schema": {
                  "type": "string",
                  "example": "?0"
                }
              },
              "Sunset": {
                "description": "RFC 8594 HTTP-date. Present only when an operation is scheduled for removal.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "IETF RateLimit header (limit, remaining, reset).",
                "schema": {
                  "type": "string",
                  "example": "limit=120, remaining=119, reset=1710000060"
                }
              },
              "RateLimit-Policy": {
                "description": "Quoted-window policy: 120 requests per 60 seconds.",
                "schema": {
                  "type": "string",
                  "example": "120;w=60"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait after HTTP 429.",
                "schema": {
                  "type": "integer"
                }
              },
              "Mcp-Protocol-Version": {
                "description": "MCP protocol version this server speaks.",
                "schema": {
                  "type": "string",
                  "example": "2025-06-18"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonRpcSuccess"
                    },
                    {
                      "$ref": "#/components/schemas/JsonRpcError"
                    }
                  ]
                }
              }
            }
          },
          "202": {
            "description": "Notification acknowledged (no JSON-RPC response body)."
          },
          "400": {
            "description": "HTTP-level parse failure (body is not JSON).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "jsonrpc",
                    "error"
                  ],
                  "properties": {
                    "jsonrpc": {
                      "type": "string",
                      "const": "2.0"
                    },
                    "id": {
                      "description": "JSON-RPC id from the request, or null for parse errors."
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "integer",
                          "description": "JSON-RPC error code."
                        },
                        "message": {
                          "type": "string"
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "hint": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Wrong HTTP method. POST only. RFC 9457 JSON body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Wait Retry-After seconds.",
            "headers": {
              "API-Version": {
                "description": "Major REST version currently serving this response.",
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              },
              "Deprecation": {
                "description": "RFC 9745. `?0` means this operation is not deprecated.",
                "schema": {
                  "type": "string",
                  "example": "?0"
                }
              },
              "Sunset": {
                "description": "RFC 8594 HTTP-date. Present only when an operation is scheduled for removal.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "IETF RateLimit header (limit, remaining, reset).",
                "schema": {
                  "type": "string",
                  "example": "limit=120, remaining=119, reset=1710000060"
                }
              },
              "RateLimit-Policy": {
                "description": "Quoted-window policy: 120 requests per 60 seconds.",
                "schema": {
                  "type": "string",
                  "example": "120;w=60"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait after HTTP 429.",
                "schema": {
                  "type": "integer"
                }
              },
              "Mcp-Protocol-Version": {
                "description": "MCP protocol version this server speaks.",
                "schema": {
                  "type": "string",
                  "example": "2025-06-18"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "mcp"
        ],
        "operationId": "mcpGetSseOrNotAllowed",
        "summary": "Open the Streamable HTTP SSE channel, or 405",
        "description": "GET with Accept: text/event-stream returns 200 and an empty SSE stream (no unsolicited notifications). Other Accept values return 405 with a JSON error envelope. JSON-RPC lives on POST.",
        "responses": {
          "200": {
            "description": "Empty SSE stream (comment frame).",
            "headers": {
              "API-Version": {
                "description": "Major REST version currently serving this response.",
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              },
              "Deprecation": {
                "description": "RFC 9745. `?0` means this operation is not deprecated.",
                "schema": {
                  "type": "string",
                  "example": "?0"
                }
              },
              "Sunset": {
                "description": "RFC 8594 HTTP-date. Present only when an operation is scheduled for removal.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "IETF RateLimit header (limit, remaining, reset).",
                "schema": {
                  "type": "string",
                  "example": "limit=120, remaining=119, reset=1710000060"
                }
              },
              "RateLimit-Policy": {
                "description": "Quoted-window policy: 120 requests per 60 seconds.",
                "schema": {
                  "type": "string",
                  "example": "120;w=60"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait after HTTP 429.",
                "schema": {
                  "type": "integer"
                }
              },
              "Mcp-Protocol-Version": {
                "description": "MCP protocol version this server speaks.",
                "schema": {
                  "type": "string",
                  "example": "2025-06-18"
                }
              }
            },
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "example": ": umesh-malik MCP Streamable HTTP\\n\\n"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "headers": {
              "Allow": {
                "schema": {
                  "type": "string",
                  "example": "GET, POST, OPTIONS"
                }
              },
              "API-Version": {
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "https://umesh-malik.com/developers#method-not-allowed",
                  "title": "Method Not Allowed",
                  "status": 405,
                  "detail": "GET without Accept: text/event-stream is not supported on /mcp. Send Accept: text/event-stream for the SSE channel, or POST a JSON-RPC body.",
                  "code": "method_not_allowed",
                  "message": "GET without Accept: text/event-stream is not supported on /mcp. Send Accept: text/event-stream for the SSE channel, or POST a JSON-RPC body.",
                  "hint": "POST a JSON-RPC body to https://umesh-malik.com/mcp or https://umesh-malik.com/api/v1/mcp, or read https://umesh-malik.com/openapi.json."
                }
              }
            }
          }
        }
      },
      "options": {
        "tags": [
          "mcp"
        ],
        "operationId": "mcpCorsPreflight",
        "summary": "CORS preflight",
        "responses": {
          "204": {
            "description": "No content."
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "tags": [
          "discovery"
        ],
        "operationId": "getOpenApi",
        "summary": "This OpenAPI document",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 specification.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenApiDocument"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "tags": [
          "discovery"
        ],
        "operationId": "getLlmsTxt",
        "summary": "LLM-readable site index",
        "responses": {
          "200": {
            "description": "Plain-text Markdown index.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/404.json": {
      "get": {
        "tags": [
          "discovery"
        ],
        "operationId": "getNotFoundEnvelope",
        "summary": "Example JSON 404 envelope",
        "description": "Canonical example of a JSON error body. Missing paths still return HTTP 404; this file is the documented envelope, served as 200 at /404.json so agents can read the schema without synthesizing a miss. Unknown /api/* paths return the same envelope as HTTP 404 with Content-Type application/problem+json.",
        "responses": {
          "200": {
            "description": "Error envelope example.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/api": {
      "get": {
        "tags": [
          "v1"
        ],
        "operationId": "getApiIndex",
        "summary": "REST version index",
        "description": "Lists current and historical REST prefixes. Pin /api/v1.",
        "responses": {
          "200": {
            "description": "Version index.",
            "headers": {
              "API-Version": {
                "description": "Major REST version currently serving this response.",
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              },
              "Deprecation": {
                "description": "RFC 9745. `?0` means this operation is not deprecated.",
                "schema": {
                  "type": "string",
                  "example": "?0"
                }
              },
              "Sunset": {
                "description": "RFC 8594 HTTP-date. Present only when an operation is scheduled for removal.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "IETF RateLimit header (limit, remaining, reset).",
                "schema": {
                  "type": "string",
                  "example": "limit=120, remaining=119, reset=1710000060"
                }
              },
              "RateLimit-Policy": {
                "description": "Quoted-window policy: 120 requests per 60 seconds.",
                "schema": {
                  "type": "string",
                  "example": "120;w=60"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait after HTTP 429.",
                "schema": {
                  "type": "integer"
                }
              },
              "Mcp-Protocol-Version": {
                "description": "MCP protocol version this server speaks.",
                "schema": {
                  "type": "string",
                  "example": "2025-06-18"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionIndex"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1": {
      "get": {
        "tags": [
          "v1"
        ],
        "operationId": "getApiV1Catalog",
        "summary": "Umesh Malik REST API v1 catalog",
        "description": "Current versioned prefix. Breaking changes ship as /api/v2. Deprecated operations send Sunset/Deprecation headers at least 90 days before removal; none are deprecated today.",
        "responses": {
          "200": {
            "description": "v1 catalog.",
            "headers": {
              "API-Version": {
                "description": "Major REST version currently serving this response.",
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              },
              "Deprecation": {
                "description": "RFC 9745. `?0` means this operation is not deprecated.",
                "schema": {
                  "type": "string",
                  "example": "?0"
                }
              },
              "Sunset": {
                "description": "RFC 8594 HTTP-date. Present only when an operation is scheduled for removal.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "IETF RateLimit header (limit, remaining, reset).",
                "schema": {
                  "type": "string",
                  "example": "limit=120, remaining=119, reset=1710000060"
                }
              },
              "RateLimit-Policy": {
                "description": "Quoted-window policy: 120 requests per 60 seconds.",
                "schema": {
                  "type": "string",
                  "example": "120;w=60"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait after HTTP 429.",
                "schema": {
                  "type": "integer"
                }
              },
              "Mcp-Protocol-Version": {
                "description": "MCP protocol version this server speaks.",
                "schema": {
                  "type": "string",
                  "example": "2025-06-18"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1Catalog"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/openapi.json": {
      "get": {
        "tags": [
          "v1"
        ],
        "operationId": "getOpenApiV1",
        "summary": "OpenAPI 3.1 at the versioned prefix",
        "responses": {
          "200": {
            "description": "Same document as /openapi.json.",
            "headers": {
              "API-Version": {
                "description": "Major REST version currently serving this response.",
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              },
              "Deprecation": {
                "description": "RFC 9745. `?0` means this operation is not deprecated.",
                "schema": {
                  "type": "string",
                  "example": "?0"
                }
              },
              "Sunset": {
                "description": "RFC 8594 HTTP-date. Present only when an operation is scheduled for removal.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "IETF RateLimit header (limit, remaining, reset).",
                "schema": {
                  "type": "string",
                  "example": "limit=120, remaining=119, reset=1710000060"
                }
              },
              "RateLimit-Policy": {
                "description": "Quoted-window policy: 120 requests per 60 seconds.",
                "schema": {
                  "type": "string",
                  "example": "120;w=60"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait after HTTP 429.",
                "schema": {
                  "type": "integer"
                }
              },
              "Mcp-Protocol-Version": {
                "description": "MCP protocol version this server speaks.",
                "schema": {
                  "type": "string",
                  "example": "2025-06-18"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenApiDocument"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/mcp": {
      "post": {
        "tags": [
          "v1",
          "mcp"
        ],
        "operationId": "mcpJsonRpcV1",
        "summary": "Versioned alias of POST /mcp",
        "description": "Same JSON-RPC handler as POST /mcp. Prefer this prefix when pinning a REST version.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC result or JSON-RPC error object.",
            "headers": {
              "API-Version": {
                "description": "Major REST version currently serving this response.",
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              },
              "Deprecation": {
                "description": "RFC 9745. `?0` means this operation is not deprecated.",
                "schema": {
                  "type": "string",
                  "example": "?0"
                }
              },
              "Sunset": {
                "description": "RFC 8594 HTTP-date. Present only when an operation is scheduled for removal.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "IETF RateLimit header (limit, remaining, reset).",
                "schema": {
                  "type": "string",
                  "example": "limit=120, remaining=119, reset=1710000060"
                }
              },
              "RateLimit-Policy": {
                "description": "Quoted-window policy: 120 requests per 60 seconds.",
                "schema": {
                  "type": "string",
                  "example": "120;w=60"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait after HTTP 429.",
                "schema": {
                  "type": "integer"
                }
              },
              "Mcp-Protocol-Version": {
                "description": "MCP protocol version this server speaks.",
                "schema": {
                  "type": "string",
                  "example": "2025-06-18"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonRpcSuccess"
                    },
                    {
                      "$ref": "#/components/schemas/JsonRpcError"
                    }
                  ]
                }
              }
            }
          },
          "405": {
            "description": "Wrong HTTP method.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Major REST version currently serving this response.",
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              },
              "Deprecation": {
                "description": "RFC 9745. `?0` means this operation is not deprecated.",
                "schema": {
                  "type": "string",
                  "example": "?0"
                }
              },
              "Sunset": {
                "description": "RFC 8594 HTTP-date. Present only when an operation is scheduled for removal.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "IETF RateLimit header (limit, remaining, reset).",
                "schema": {
                  "type": "string",
                  "example": "limit=120, remaining=119, reset=1710000060"
                }
              },
              "RateLimit-Policy": {
                "description": "Quoted-window policy: 120 requests per 60 seconds.",
                "schema": {
                  "type": "string",
                  "example": "120;w=60"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait after HTTP 429.",
                "schema": {
                  "type": "integer"
                }
              },
              "Mcp-Protocol-Version": {
                "description": "MCP protocol version this server speaks.",
                "schema": {
                  "type": "string",
                  "example": "2025-06-18"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "v1",
          "mcp"
        ],
        "operationId": "mcpV1GetSseOrNotAllowed",
        "summary": "SSE channel or 405 on /api/v1/mcp",
        "description": "Same GET contract as /mcp.",
        "responses": {
          "200": {
            "description": "Empty SSE stream.",
            "headers": {
              "API-Version": {
                "description": "Major REST version currently serving this response.",
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              },
              "Deprecation": {
                "description": "RFC 9745. `?0` means this operation is not deprecated.",
                "schema": {
                  "type": "string",
                  "example": "?0"
                }
              },
              "Sunset": {
                "description": "RFC 8594 HTTP-date. Present only when an operation is scheduled for removal.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "IETF RateLimit header (limit, remaining, reset).",
                "schema": {
                  "type": "string",
                  "example": "limit=120, remaining=119, reset=1710000060"
                }
              },
              "RateLimit-Policy": {
                "description": "Quoted-window policy: 120 requests per 60 seconds.",
                "schema": {
                  "type": "string",
                  "example": "120;w=60"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait after HTTP 429.",
                "schema": {
                  "type": "integer"
                }
              },
              "Mcp-Protocol-Version": {
                "description": "MCP protocol version this server speaks.",
                "schema": {
                  "type": "string",
                  "example": "2025-06-18"
                }
              }
            },
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Major REST version currently serving this response.",
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              },
              "Deprecation": {
                "description": "RFC 9745. `?0` means this operation is not deprecated.",
                "schema": {
                  "type": "string",
                  "example": "?0"
                }
              },
              "Sunset": {
                "description": "RFC 8594 HTTP-date. Present only when an operation is scheduled for removal.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "IETF RateLimit header (limit, remaining, reset).",
                "schema": {
                  "type": "string",
                  "example": "limit=120, remaining=119, reset=1710000060"
                }
              },
              "RateLimit-Policy": {
                "description": "Quoted-window policy: 120 requests per 60 seconds.",
                "schema": {
                  "type": "string",
                  "example": "120;w=60"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait after HTTP 429.",
                "schema": {
                  "type": "integer"
                }
              },
              "Mcp-Protocol-Version": {
                "description": "MCP protocol version this server speaks.",
                "schema": {
                  "type": "string",
                  "example": "2025-06-18"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "ApiVersion": {
        "name": "API-Version",
        "in": "header",
        "required": false,
        "description": "Major REST version. Current: 1. Pin /api/v1 in the URL; this header echoes the same major.",
        "schema": {
          "type": "string",
          "enum": [
            "1"
          ],
          "default": "1"
        }
      }
    },
    "schemas": {
      "ErrorEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "code",
          "message",
          "hint"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "Absolute URL of the error code documentation on /developers."
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599
          },
          "detail": {
            "type": "string",
            "description": "RFC 9457 problem detail. Same text as message."
          },
          "code": {
            "type": "string",
            "description": "Stable machine code (snake_case). Branch on this, not on the message."
          },
          "message": {
            "type": "string",
            "description": "Alias of detail for clients that look for message."
          },
          "hint": {
            "type": "string",
            "description": "Where to look next (docs URL, valid method, or discovery file)."
          },
          "instance": {
            "type": "string",
            "description": "RFC 9457 instance — the request path that failed, when known."
          }
        }
      },
      "JsonRpcError": {
        "type": "object",
        "required": [
          "jsonrpc",
          "error"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "description": "JSON-RPC id from the request, or null for parse errors."
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "integer",
                "description": "JSON-RPC error code."
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object",
                "properties": {
                  "hint": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "description": "Request id. Omit for notifications."
          },
          "method": {
            "type": "string",
            "enum": [
              "initialize",
              "ping",
              "tools/list",
              "tools/call",
              "notifications/initialized"
            ],
            "description": "MCP JSON-RPC method."
          },
          "params": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "JsonRpcSuccess": {
        "type": "object",
        "required": [
          "jsonrpc",
          "result"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {},
          "result": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "VersionIndex": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "current",
          "versions",
          "docs",
          "versioning"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "current": {
            "type": "string",
            "format": "uri"
          },
          "versions": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "current",
                    "deprecated"
                  ]
                },
                "href": {
                  "type": "string",
                  "format": "uri"
                },
                "openapi": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "docs": {
            "type": "string",
            "format": "uri"
          },
          "versioning": {
            "type": "string"
          }
        }
      },
      "V1Catalog": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "apiVersion",
          "prefix",
          "docs",
          "openapi",
          "mcp",
          "errors",
          "versioning"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "apiVersion": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "prefix": {
            "type": "string"
          },
          "docs": {
            "type": "string",
            "format": "uri"
          },
          "openapi": {
            "type": "string",
            "format": "uri"
          },
          "mcp": {
            "type": "string",
            "format": "uri"
          },
          "mcpAlias": {
            "type": "string",
            "format": "uri"
          },
          "cli": {
            "type": "string"
          },
          "rateLimit": {
            "type": "object",
            "properties": {
              "limit": {
                "type": "integer"
              },
              "windowSeconds": {
                "type": "integer"
              },
              "headers": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "errors": {
            "type": "object",
            "properties": {
              "mediaType": {
                "type": "string"
              },
              "example": {
                "type": "string",
                "format": "uri"
              },
              "fields": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "versioning": {
            "type": "object",
            "additionalProperties": true
          },
          "discovery": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "McpInitializeResult": {
        "type": "object",
        "required": [
          "protocolVersion",
          "capabilities",
          "serverInfo"
        ],
        "properties": {
          "protocolVersion": {
            "type": "string"
          },
          "capabilities": {
            "type": "object",
            "properties": {
              "tools": {
                "type": "object",
                "properties": {
                  "listChanged": {
                    "type": "boolean"
                  }
                }
              }
            }
          },
          "serverInfo": {
            "type": "object",
            "required": [
              "name",
              "version"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "version": {
                "type": "string"
              },
              "title": {
                "type": "string"
              }
            }
          },
          "instructions": {
            "type": "string"
          }
        }
      },
      "OpenApiDocument": {
        "type": "object",
        "required": [
          "openapi",
          "info",
          "paths"
        ],
        "properties": {
          "openapi": {
            "type": "string",
            "example": "3.1.0"
          },
          "info": {
            "type": "object",
            "required": [
              "title",
              "version"
            ],
            "properties": {
              "title": {
                "type": "string"
              },
              "version": {
                "type": "string"
              },
              "summary": {
                "type": "string"
              },
              "description": {
                "type": "string"
              }
            }
          },
          "jsonSchemaDialect": {
            "type": "string"
          },
          "servers": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "paths": {
            "type": "object"
          },
          "webhooks": {
            "type": "object"
          },
          "components": {
            "type": "object"
          },
          "security": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "externalDocs": {
            "type": "object"
          }
        }
      }
    }
  }
}