blume 1.5.3 → 1.6.1

package/src/ai/markdown.ts

@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises";
 import { rewriteRelativeImages } from "../core/content-assets.ts";
 import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
-import { readEntryText } from "../core/sources/read.ts";
+import { readExpandedEntryText } from "../core/sources/read.ts";
 import type { RouteManifestEntry } from "../core/types.ts";
 import {
   downlevelComponents,
@@ -65,7 +65,7 @@ export const buildRawMarkdown = async (
   const readRoute = async (route: RouteManifestEntry): Promise<string> => {
     const page = pageById.get(route.id);
     if (page) {
-      return await readEntryText(project, page);
+      return await readExpandedEntryText(project, page);
     }
     return route.sourcePath ? await readFile(route.sourcePath, "utf-8") : "";
   };

package/src/ai/mcp/discovery.ts

@@ -103,7 +103,10 @@ const HTTP_URL = /^https?:\/\//u;
  */
 export interface McpServerCard {
   $schema: string;
-  capabilities: { tools: { listChanged: boolean } };
+  capabilities: {
+    resources: { listChanged: boolean; subscribe: boolean };
+    tools: { listChanged: boolean };
+  };
   description: string;
   name: string;
   /** Absolute endpoints only — present when a `site` is configured. */
@@ -122,7 +125,12 @@ export const buildMcpServerCard = (input: McpDiscoveryInput): McpServerCard => {
   const url = serverUrl(input);
   const card: McpServerCard = {
     $schema: SERVER_CARD_SCHEMA,
-    capabilities: { tools: { listChanged: false } },
+    // Resources mirror the page list (one `text/markdown` resource per page);
+    // a rebuilt site replaces the server wholesale, so nothing changes live.
+    capabilities: {
+      resources: { listChanged: false, subscribe: false },
+      tools: { listChanged: false },
+    },
     description: truncate(
       `Model Context Protocol server for the ${input.name} documentation.`
     ),

package/src/ai/mcp/server.ts

@@ -3,7 +3,10 @@ import type { ServerOptions } from "@modelcontextprotocol/sdk/server/index.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import {
   CallToolRequestSchema,
+  ListResourcesRequestSchema,
   ListToolsRequestSchema,
+  McpError,
+  ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 
@@ -33,6 +36,12 @@ const DEFAULT_SEARCH_LIMIT = 8;
 const MAX_SEARCH_LIMIT = 20;
 /** Excerpt length when a page has no description. */
 const EXCERPT_LENGTH = 200;
+/** Every page resource is the page's agent Markdown. */
+const RESOURCE_MIME_TYPE = "text/markdown";
+/** The MCP spec's JSON-RPC code for an unknown resource URI. */
+const RESOURCE_NOT_FOUND = -32_002;
+/** URI scheme for page resources when no `deployment.site` is configured. */
+const LOCAL_RESOURCE_SCHEME = "blume:";
 
 const CORS_HEADERS = {
   "Access-Control-Allow-Headers":
@@ -191,6 +200,15 @@ interface SearchHitPayload {
   version?: string;
 }
 
+/** One `resources/list` entry: a page served as `text/markdown`. */
+interface PageResource {
+  description?: string;
+  mimeType: string;
+  name: string;
+  title: string;
+  uri: string;
+}
+
 /** One `list_pages` entry; `version` only appears on versioned sites. */
 interface PageListingPayload {
   contentType: string;
@@ -288,6 +306,26 @@ const urlFor = (route: string, data: McpData): string => {
   return data.site ? absoluteUrl(data.site, path) : path;
 };
 
+/**
+ * A page's resource URI. Resource URIs must be absolute, so this is the page's
+ * served URL when a site is configured (the same URL `search_docs` and
+ * `list_pages` emit, so an agent can hand either back to `resources/read`),
+ * and a `blume:` URI carrying the based route otherwise.
+ */
+const resourceUri = (route: string, data: McpData): string =>
+  data.site
+    ? urlFor(route, data)
+    : `${LOCAL_RESOURCE_SCHEME}${withBasePath(data.base, route)}`;
+
+/** The `pages` key a resource URI (either form, or a bare route) names. */
+const resourceRoute = (uri: string, data: McpData): string =>
+  normalizeRoute(
+    uri.startsWith(LOCAL_RESOURCE_SCHEME)
+      ? uri.slice(LOCAL_RESOURCE_SCHEME.length)
+      : uri,
+    data
+  );
+
 /** A hit's excerpt: its description, else the head of its content with an
  * ellipsis only when something was actually cut off. */
 const excerptFor = (doc: OramaDoc): string => {
@@ -331,9 +369,10 @@ export const buildServer = (
   data: McpData,
   index: OramaIndexProvider
 ): Server => {
+  const capabilities = { resources: {}, tools: {} };
   const serverOptions: ServerOptions = data.instructions
-    ? { capabilities: { tools: {} }, instructions: data.instructions }
-    : { capabilities: { tools: {} } };
+    ? { capabilities, instructions: data.instructions }
+    : { capabilities };
   const server = new Server(
     { name: data.name, version: data.version },
     serverOptions
@@ -343,6 +382,39 @@ export const buildServer = (
     tools: TOOL_DEFINITIONS,
   }));
 
+  // Every page doubles as a resource, so a client that attaches context by
+  // URI (rather than calling tools) can browse and read the docs too. The
+  // list is the same route set `list_pages` returns; reading one serves the
+  // same agent Markdown `get_page` does.
+  server.setRequestHandler(ListResourcesRequestSchema, () => ({
+    resources: data.routes.map((route) => {
+      const resource: PageResource = {
+        mimeType: RESOURCE_MIME_TYPE,
+        name: route.title,
+        title: route.title,
+        uri: resourceUri(route.route, data),
+      };
+      if (route.description) {
+        resource.description = route.description;
+      }
+      return resource;
+    }),
+  }));
+
+  server.setRequestHandler(ReadResourceRequestSchema, (request) => {
+    const { uri } = request.params;
+    const markdown = data.pages[resourceRoute(uri, data)];
+    if (markdown === undefined) {
+      throw new McpError(
+        RESOURCE_NOT_FOUND,
+        `No page found at "${uri}". Use resources/list or list_pages to find valid URIs.`
+      );
+    }
+    return {
+      contents: [{ mimeType: RESOURCE_MIME_TYPE, text: markdown, uri }],
+    };
+  });
+
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { arguments: args = {}, name } = request.params;
 

package/src/astro/examples.ts

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 
 import pMap from "p-map";
-import { join, relative } from "pathe";
+import { isAbsolute, join, relative } from "pathe";
 import { glob } from "tinyglobby";
 
 import type { ExampleLookup } from "../core/types.ts";
@@ -28,6 +28,11 @@ export interface ExampleSpec {
 }
 
 export interface ExampleDiscovery {
+  /**
+   * Absolute directory the examples were discovered under: the configured
+   * `examples.source` (or a glob's static prefix) resolved against the root.
+   */
+  dir: string;
   examples: ExampleSpec[];
   warnings: string[];
 }
@@ -56,6 +61,28 @@ const DEFAULT_EXAMPLE_GLOB = "**/*.{astro,jsx,svelte,tsx,vue}";
 /** Ceiling on concurrent example-file reads; unbounded fan-out risks EMFILE. */
 const READ_CONCURRENCY = 16;
 
+/**
+ * Files the preview-frame Tailwind entry scans for utility classes, appended
+ * to each directory from `exampleScanRoots`.
+ */
+export const EXAMPLE_SCAN_GLOB = "**/*.{astro,jsx,svelte,ts,tsx,vue}";
+
+/**
+ * Directories the `<Component />` preview sheet scans for utility classes:
+ * the project root, plus the examples directory when it lives outside the
+ * root (a sibling workspace package, say). Tailwind's `@source` is a file
+ * glob, not an import graph, so an out-of-root examples directory would
+ * otherwise contribute no utilities and previews would render half-styled.
+ */
+export const exampleScanRoots = (
+  root: string,
+  examplesDir: string
+): string[] => {
+  const path = relative(root, examplesDir);
+  const outside = path.startsWith("..") || isAbsolute(path);
+  return outside ? [root, examplesDir] : [root];
+};
+
 // Glob magic that turns `examples` from a plain directory into a pattern. `()`,
 // `@`, and `+` are excluded so literal path segments (npm scopes, parens) keep
 // resolving as directories; the extglob leads `*?!` still trigger here.
@@ -153,7 +180,7 @@ export const discoverExamples = async (
     collectExample(file, sources[index] ?? "");
   }
 
-  return { examples, warnings };
+  return { dir, examples, warnings };
 };
 
 /**