/**
 * Static metadata for the MCP tools Blume exposes. Shared by the server (which
 * pairs each entry with a Zod input schema and handler) and the `.well-known`
 * discovery documents, so tool names and descriptions never drift between the
 * live server and its advertised capabilities.
 */

/** A read-only, non-mutating tool hint set (every Blume tool is read-only). */
const READ_ONLY = { openWorldHint: false, readOnlyHint: true } as const;

export interface McpToolMeta {
  annotations: { openWorldHint: boolean; readOnlyHint: boolean };
  description: string;
  name: string;
  title: string;
}

export const MCP_TOOLS: McpToolMeta[] = [
  {
    annotations: READ_ONLY,
    description:
      'Full-text search across the documentation. Returns matching pages with their title, route, content type, and a short excerpt; pass `contentTypes` to search only pages of certain types (e.g. `rfc`, `changelog`), `filters` to require facet values the site declares per type (e.g. `{"status": "enforced"}`), and `locale` to search one language. On a versioned site results default to the current docs — pass `version` to search an archived version (e.g. `"v1.0"`) or `"all"` for every version. Use this first to discover relevant pages, then `get_page` to read one in full.',
    name: "search_docs",
    title: "Search documentation",
  },
  {
    annotations: READ_ONLY,
    description:
      "Fetch a single documentation page as agent-optimized Markdown (frontmatter included, components downleveled to plain Markdown). Pass a route from `search_docs` or `list_pages`, e.g. `/guides/install`.",
    name: "get_page",
    title: "Get page Markdown",
  },
  {
    annotations: READ_ONLY,
    description:
      'List every documentation page with its route, title, description, content type, and any declared facet values; pass `contentTypes`, `filters`, and/or `locale` to narrow the list. On a versioned site the list defaults to the current docs — pass `version` for an archived version or `"all"`. Useful for enumerating the docs, discovering the types and facets in use, or finding a page when search is too narrow.',
    name: "list_pages",
    title: "List pages",
  },
  {
    annotations: READ_ONLY,
    description:
      "Return the documentation navigation tree (header tabs and the sidebar hierarchy), reflecting how the docs are organized for readers. Pass `locale` for a language's tree and, on a versioned site, `version` for an archived snapshot's tree.",
    name: "get_navigation",
    title: "Get navigation",
  },
];