blume 0.0.0 → 0.1.1

package/src/ai/mcp/server.ts

@@ -0,0 +1,225 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { buildOramaIndex, queryOramaIndex } from "../../search/orama-index.ts";
+import type { OramaDoc } from "../../search/orama-index.ts";
+import type { McpData } from "./data.ts";
+import { MCP_TOOLS } from "./tools.ts";
+
+/**
+ * The low-level SDK `Server` is used (rather than the high-level `McpServer`)
+ * because the latter's `registerTool` is generic over the caller's Zod version;
+ * Blume pins Zod 3 while the SDK resolves Zod 4, so their types don't unify.
+ * Hand-written JSON Schema and the SDK's own request schemas avoid that entirely.
+ */
+
+/** Default and maximum number of hits returned by `search_docs`. */
+const DEFAULT_SEARCH_LIMIT = 8;
+const MAX_SEARCH_LIMIT = 20;
+/** Excerpt length when a page has no description. */
+const EXCERPT_LENGTH = 200;
+
+const CORS_HEADERS: Record<string, string> = {
+  "Access-Control-Allow-Headers":
+    "Content-Type, Mcp-Session-Id, Mcp-Protocol-Version",
+  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Expose-Headers": "Mcp-Session-Id",
+};
+
+/** JSON Schema for each tool's input, keyed by tool name. */
+const INPUT_SCHEMAS: Record<string, Record<string, unknown>> = {
+  get_navigation: { properties: {}, type: "object" },
+  get_page: {
+    properties: {
+      route: {
+        description: "The page route, e.g. `/guides/install`.",
+        type: "string",
+      },
+    },
+    required: ["route"],
+    type: "object",
+  },
+  list_pages: { properties: {}, type: "object" },
+  search_docs: {
+    properties: {
+      limit: {
+        description: `Maximum hits to return (default ${DEFAULT_SEARCH_LIMIT}).`,
+        maximum: MAX_SEARCH_LIMIT,
+        minimum: 1,
+        type: "integer",
+      },
+      query: { description: "The search query.", type: "string" },
+    },
+    required: ["query"],
+    type: "object",
+  },
+};
+
+/** The `tools/list` payload, derived from shared metadata + input schemas. */
+const TOOL_DEFINITIONS = MCP_TOOLS.map((tool) => ({
+  annotations: tool.annotations,
+  description: tool.description,
+  inputSchema: INPUT_SCHEMAS[tool.name],
+  name: tool.name,
+  title: tool.title,
+}));
+
+const asString = (value: unknown): string =>
+  typeof value === "string" ? value : "";
+
+const asLimit = (value: unknown): number => {
+  const num = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(num)) {
+    return DEFAULT_SEARCH_LIMIT;
+  }
+  return Math.min(Math.max(Math.trunc(num), 1), MAX_SEARCH_LIMIT);
+};
+
+/** Normalize a user-supplied route to a `pages` key (`/`, `/a/b`, no suffix). */
+const normalizeRoute = (input: string): string => {
+  const noTrailing = input.trim().replace(/\/+$/u, "");
+  const noSuffix = noTrailing.replace(/\.mdx?$/u, "");
+  const withSlash = noSuffix.startsWith("/") ? noSuffix : `/${noSuffix}`;
+  return withSlash === "" ? "/" : withSlash;
+};
+
+/** Build the absolute (or root-relative) URL for a route. */
+const urlFor = (route: string, site: string | null): string =>
+  site ? new URL(route, site).href : route;
+
+const text = (value: string, isError = false) => ({
+  content: [{ text: value, type: "text" as const }],
+  ...(isError ? { isError: true } : {}),
+});
+
+/** Construct a fresh MCP server with Blume's read-only docs tools registered. */
+const buildServer = (
+  data: McpData,
+  index: () => Promise<Awaited<ReturnType<typeof buildOramaIndex>>>
+): Server => {
+  const server = new Server(
+    { name: data.name, version: data.version },
+    {
+      capabilities: { tools: {} },
+      ...(data.instructions ? { instructions: data.instructions } : {}),
+    }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, () => ({
+    tools: TOOL_DEFINITIONS,
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { arguments: args = {}, name } = request.params;
+
+    if (name === "search_docs") {
+      const db = await index();
+      const hits = await queryOramaIndex(
+        db,
+        asString(args.query),
+        asLimit(args.limit)
+      );
+      const results = hits.map((doc: OramaDoc) => ({
+        excerpt:
+          doc.description || `${doc.content.slice(0, EXCERPT_LENGTH)}…`.trim(),
+        title: doc.title,
+        url: urlFor(doc.route, data.site),
+      }));
+      return text(JSON.stringify(results, null, 2));
+    }
+
+    if (name === "get_page") {
+      const key = normalizeRoute(asString(args.route));
+      const markdown = data.pages[key];
+      if (markdown === undefined) {
+        return text(
+          `No page found at "${key}". Use list_pages or search_docs to find valid routes.`,
+          true
+        );
+      }
+      return text(markdown);
+    }
+
+    if (name === "list_pages") {
+      return text(
+        JSON.stringify(
+          data.routes.map((route) => ({
+            contentType: route.contentType,
+            description: route.description,
+            lastModified: route.lastModified,
+            route: route.route,
+            title: route.title,
+            url: urlFor(route.route, data.site),
+          })),
+          null,
+          2
+        )
+      );
+    }
+
+    if (name === "get_navigation") {
+      return text(JSON.stringify(data.navigation, null, 2));
+    }
+
+    return text(`Unknown tool: ${name}`, true);
+  });
+
+  return server;
+};
+
+/**
+ * Build a stateless Streamable-HTTP MCP request handler from a data snapshot.
+ *
+ * The Orama index is built once and reused; a fresh `Server` and transport are
+ * created per request (required by the SDK's stateless mode, which skips session
+ * tracking). `enableJsonResponse` makes each call a plain request/response — no
+ * SSE — which suits read-only docs tools and runs on any adapter (Node, Vercel,
+ * Netlify, Cloudflare). CORS is added so browser-based connectors (e.g.
+ * claude.ai) can reach the endpoint.
+ */
+export const createMcpFetchHandler = (
+  data: McpData
+): ((request: Request) => Promise<Response>) => {
+  let dbPromise: Promise<Awaited<ReturnType<typeof buildOramaIndex>>> | null =
+    null;
+  const index = () => {
+    dbPromise ??= buildOramaIndex(data.documents);
+    return dbPromise;
+  };
+
+  return async (request: Request): Promise<Response> => {
+    if (request.method === "OPTIONS") {
+      return new Response(null, { headers: CORS_HEADERS, status: 204 });
+    }
+    if (request.method === "GET") {
+      // No server-initiated streams are needed for read-only tools.
+      return new Response("Method Not Allowed", {
+        headers: { ...CORS_HEADERS, Allow: "POST, OPTIONS" },
+        status: 405,
+      });
+    }
+
+    const server = buildServer(data, index);
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      enableJsonResponse: true,
+      sessionIdGenerator: undefined,
+    });
+    await server.connect(transport);
+    const response = await transport.handleRequest(request);
+
+    const headers = new Headers(response.headers);
+    for (const [key, value] of Object.entries(CORS_HEADERS)) {
+      headers.set(key, value);
+    }
+    return new Response(response.body, {
+      headers,
+      status: response.status,
+      statusText: response.statusText,
+    });
+  };
+};

package/src/ai/mcp/tools.ts

@@ -0,0 +1,47 @@
+/**
+ * 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, and a short excerpt. 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 its original Markdown source (frontmatter included). 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, and content type. Useful for enumerating the docs 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.",
+    name: "get_navigation",
+    title: "Get navigation",
+  },
+];

package/src/astro/examples.ts

@@ -0,0 +1,104 @@
+import { readFile } from "node:fs/promises";
+
+import { join, relative } from "pathe";
+import { glob } from "tinyglobby";
+
+import type { IslandClientMode } from "./islands.ts";
+import { readClientMode } from "./islands.ts";
+
+/** Framework an example is authored in, inferred from its extension. */
+export type ExampleFramework = "astro" | "react" | "svelte" | "vue";
+
+/** A discovered `examples/` file, ready to wrap (live) and show (source). */
+export interface ExampleSpec {
+  /** Hydration directive for a framework example; `undefined` for `.astro`. */
+  client?: IslandClientMode;
+  /** Absolute path to the example source file. */
+  file: string;
+  /** Framework, or `astro` for a server-rendered (static) example. */
+  framework: ExampleFramework;
+  /** Shiki language for the source pane — the file extension. */
+  lang: string;
+  /** MDX-facing key: the path under `examples/`, sans extension, `/`-joined. */
+  path: string;
+  /** Raw source text shown in the code tab. */
+  source: string;
+}
+
+export interface ExampleDiscovery {
+  examples: ExampleSpec[];
+  warnings: string[];
+}
+
+/** Example extensions mapped to the framework that renders them. */
+const FRAMEWORK_BY_EXT: Record<string, ExampleFramework> = {
+  astro: "astro",
+  jsx: "react",
+  svelte: "svelte",
+  tsx: "react",
+  vue: "vue",
+};
+
+// Captures the extension so we can strip it from the path key and pick the
+// framework. Kept in sync with the glob below.
+const EXAMPLE_FILE = /\.(?<ext>astro|jsx|svelte|tsx|vue)$/u;
+
+/**
+ * Discover preview examples under `<root>/examples`. Every `.astro`/`.tsx`/
+ * `.jsx`/`.vue`/`.svelte` file becomes addressable by `<Component path="...">`,
+ * where the path is the file's location under `examples/` without its extension
+ * (e.g. `forms/login.tsx` → `forms/login`). Discovery is path-based (a glob),
+ * so no example code is executed. Framework examples carry a hydration mode
+ * (default `client:visible`, overridable via `export const client`); `.astro`
+ * examples render statically with no client directive.
+ */
+export const discoverExamples = async (
+  root: string
+): Promise<ExampleDiscovery> => {
+  const dir = join(root, "examples");
+  const matches = await glob(["**/*.{astro,jsx,svelte,tsx,vue}"], {
+    absolute: true,
+    cwd: dir,
+    onlyFiles: true,
+  });
+  const files = matches.toSorted();
+  const sources = await Promise.all(
+    files.map((file) => readFile(file, "utf-8"))
+  );
+
+  const examples: ExampleSpec[] = [];
+  const warnings: string[] = [];
+  const seen = new Map<string, string>();
+
+  for (const [index, file] of files.entries()) {
+    const ext = file.match(EXAMPLE_FILE)?.groups?.ext;
+    const framework = ext ? FRAMEWORK_BY_EXT[ext] : undefined;
+    if (!(ext && framework)) {
+      continue;
+    }
+    // Strip the trailing `.<ext>` to form the `<Component path>` key.
+    const path = relative(dir, file).slice(0, -(ext.length + 1));
+    const existing = seen.get(path);
+    if (existing) {
+      warnings.push(
+        `Two examples both resolve to "${path}" ("${existing}" and "${file}"); ignoring the second. Give them distinct paths.`
+      );
+      continue;
+    }
+    seen.set(path, file);
+    const source = sources[index] ?? "";
+    examples.push({
+      client:
+        framework === "astro"
+          ? undefined
+          : readClientMode(source, file, warnings),
+      file,
+      framework,
+      lang: ext,
+      path,
+      source,
+    });
+  }
+
+  return { examples, warnings };
+};