feat: allow markdown files titles for mcp resources

.changeset/legal-pots-nail.md

@@ -0,0 +1,7 @@
+---
+"@speakeasy-api/docs-mcp-server": minor
+"@speakeasy-api/docs-mcp-core": minor
+"@speakeasy-api/docs-mcp-cli": minor
+---
+
+Extract human-readable titles for MCP resources from markdown files. Titles are resolved using frontmatter `title` with a fallback to the first H1 heading. These titles appear in MCP resource listings, making it easier for agents to identify documents.

.gitignore

@@ -1,3 +1,6 @@
+.vscode/mcp.json
+.cursor/mcp.json
+.codex/config.toml
 node_modules/
 dist/
 .turbo/

package.json

@@ -33,9 +33,9 @@
     "prettier": "^3.8.1",
     "turbo": "^2.4.4",
     "typescript": "^5.9.3",
-    "vitest": "^3.0.9"
+    "vitest": "^4.0.17"
   },
   "engines": {
     "node": ">=22.0.0"
   }
-}
+}

packages/cli/src/index.ts

@@ -29,6 +29,7 @@ import {
   type EmbeddingMetadata,
   type ManifestTaxonomyFieldConfig,
   type IndexBuildStep,
+  type FileMeta,
   type Manifest,
   type PreviousIndexReader,
 } from "@speakeasy-api/docs-mcp-core";
@@ -306,6 +307,7 @@ program
 
       const chunks: Chunk[] = [];
       const newFileFingerprints: Record<string, string> = {};
+      const filesMeta: Record<string, FileMeta> = {};
       let chunkCacheHits = 0;
       for (let fi = 0; fi < files.length; fi++) {
         writeProgress(`Chunking [${fi + 1}/${files.length}]...`);
@@ -327,6 +329,10 @@ program
         const fingerprint = computeChunkFingerprint(markdown, resolved.strategy, resolved.metadata);
         newFileFingerprints[relative] = fingerprint;
 
+        if (resolved.title) {
+          filesMeta[relative] = { title: resolved.title };
+        }
+
         if (previousIndex?.fingerprints.get(relative) === fingerprint) {
           const cachedChunks = await previousIndex.getChunks(relative);
           chunks.push(...cachedChunks);
@@ -497,6 +503,7 @@ program
         embeddingMetadata,
         sourceCommit,
         taxonomyConfig,
+        filesMeta,
         Object.keys(toolDescriptions).length > 0 ? toolDescriptions : undefined,
         mcpServerInstructions,
       );
@@ -662,6 +669,7 @@ function buildMetadata(
   embedding: EmbeddingMetadata | null,
   sourceCommit: string | null,
   taxonomyConfig: Record<string, ManifestTaxonomyFieldConfig>,
+  filesMeta: Record<string, FileMeta>,
   toolDescriptions?: Record<string, string>,
   mcpServerInstructions?: string,
 ): {
@@ -685,6 +693,7 @@ function buildMetadata(
   embedding: EmbeddingMetadata | null;
   tool_descriptions?: Record<string, string>;
   mcpServerInstructions?: string;
+  files?: Record<string, FileMeta>;
 } {
   const taxonomyValues = new Map<string, Set<string>>();
   for (const chunk of chunks) {
@@ -727,6 +736,7 @@ function buildMetadata(
     embedding,
     ...(toolDescriptions ? { tool_descriptions: toolDescriptions } : {}),
     ...(mcpServerInstructions ? { mcpServerInstructions } : {}),
+    ...(filesMeta ? { files: filesMeta } : {}),
   };
 }
 

packages/core/src/manifest.ts

@@ -1,6 +1,7 @@
 import matter from "gray-matter";
 import picomatch from "picomatch";
 import { ManifestTaxonomyConfigSchema } from "./manifest-schema.js";
+import { extractFirstH1 } from "./parser.js";
 import type {
   ChunkingStrategy,
   Manifest,
@@ -147,6 +148,8 @@ export function resolveFileConfig(params: {
     }
   }
 
+  let title: string | undefined;
+
   if (params.markdown) {
     // HTML comment hints: applied after manifest but before frontmatter
     const htmlHint = parseHtmlChunkingHint(params.markdown);
@@ -167,11 +170,14 @@ export function resolveFileConfig(params: {
     if (frontmatterOverrides.strategy) {
       strategy = frontmatterOverrides.strategy;
     }
+
+    title = frontmatterOverrides.title ?? extractFirstH1(params.markdown);
   }
 
   return {
     strategy,
     metadata,
+    ...(title ? { title } : {}),
   };
 }
 
@@ -201,6 +207,7 @@ function toPosixPath(value: string): string {
 function parseFrontmatterOverrides(markdown: string): {
   strategy?: ChunkingStrategy;
   metadata?: Record<string, string>;
+  title?: string;
 } {
   const parsed = matter(markdown);
   if (!parsed.data || typeof parsed.data !== "object") {
@@ -229,16 +236,23 @@ function parseFrontmatterOverrides(markdown: string): {
     };
   }
 
+  const title =
+    typeof data.title === "string" && data.title.trim() ? data.title.trim() : undefined;
+
   const result: {
     strategy?: ChunkingStrategy;
     metadata?: Record<string, string>;
+    title?: string;
   } = {};
   if (strategy) {
     result.strategy = strategy;
   }
   if (metadata) {
     result.metadata = metadata;
   }
+  if (title) {
+    result.title = title;
+  }
   return result;
 }
 

packages/core/src/metadata.ts

@@ -2,6 +2,7 @@ import semver from "semver";
 import type {
   CorpusMetadata,
   EmbeddingMetadata,
+  FileMeta,
   TaxonomyField,
   TaxonomyValueProperties,
   ToolDescriptions,
@@ -58,13 +59,15 @@ export function normalizeMetadata(
   const embedding = normalizeEmbedding(metadata.embedding);
   const toolDescriptions = normalizeToolDescriptions(metadata.tool_descriptions);
   const mcpServerInstructions = normalizeInstructions(metadata.mcpServerInstructions);
+  const files = normalizeFiles(metadata.files);
 
   return {
     metadata_version: metadataVersion,
     corpus_description: corpusDescription,
     taxonomy,
     stats,
     embedding,
+    files,
     ...(toolDescriptions ? { tool_descriptions: toolDescriptions } : {}),
     ...(mcpServerInstructions ? { mcpServerInstructions } : {}),
   };
@@ -257,6 +260,44 @@ function normalizeInstructions(value: unknown): string | undefined {
   return asNonEmptyString(value, "mcpServerInstructions");
 }
 
+function normalizeFiles(value: unknown): Record<string, FileMeta> {
+  if (value === null || value === undefined) {
+    return {};
+  }
+
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("files must be an object");
+  }
+
+  const raw = value as Record<string, unknown>;
+  const result: Record<string, FileMeta> = {};
+  let hasAny = false;
+
+  for (const [filepath, entry] of Object.entries(raw)) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`files['${filepath}'] must be an object`);
+    }
+
+    const meta = entry as Record<string, unknown>;
+    const fileMeta: FileMeta = {};
+
+    if (meta.title !== undefined) {
+      if (typeof meta.title !== "string") {
+        throw new Error(`files['${filepath}'].title must be a string`);
+      }
+      const trimmed = meta.title.trim();
+      if (trimmed) {
+        fileMeta.title = trimmed;
+      }
+    }
+
+    result[filepath] = fileMeta;
+    hasAny = true;
+  }
+
+  return result;
+}
+
 function asTrimmedString(value: unknown): string {
   if (typeof value !== "string") {
     throw new Error("expected string");

packages/core/src/parser.ts

@@ -9,6 +9,7 @@ import remarkParse from "remark-parse";
 import remarkFrontmatter from "remark-frontmatter";
 import remarkGfm from "remark-gfm";
 import type { Root } from "mdast";
+import { toString } from "mdast-util-to-string";
 
 const processor = unified().use(remarkParse).use(remarkFrontmatter, ["yaml"]).use(remarkGfm);
 
@@ -18,3 +19,18 @@ const processor = unified().use(remarkParse).use(remarkFrontmatter, ["yaml"]).us
 export function parseMarkdown(content: string): Root {
   return processor.parse(content);
 }
+
+/**
+ * Extract the text content of the first H1 heading from a markdown string.
+ * Returns undefined if no H1 heading is found or it is empty.
+ */
+export function extractFirstH1(markdown: string): string | undefined {
+  const ast = processor.parse(markdown);
+  for (const node of ast.children) {
+    if (node.type === "heading" && node.depth === 1) {
+      const text = toString(node).trim();
+      return text || undefined;
+    }
+  }
+  return undefined;
+}

packages/core/src/types.ts

@@ -127,12 +127,17 @@ export interface ToolDescriptions {
   get_doc?: string;
 }
 
+export interface FileMeta {
+  title?: string;
+}
+
 export interface CorpusMetadata {
   metadata_version: string;
   corpus_description: string;
   taxonomy: Record<string, TaxonomyField>;
   stats: MetadataStats;
   embedding: EmbeddingMetadata | null;
+  files: Record<string, FileMeta>;
   tool_descriptions?: ToolDescriptions;
   mcpServerInstructions?: string;
 }
@@ -156,6 +161,7 @@ export interface BuildChunksInput {
 export interface ResolvedFileConfig {
   strategy: ChunkingStrategy;
   metadata: Record<string, string>;
+  title?: string;
 }
 
 export interface EmbeddingConfig {

packages/core/test/manifest.test.ts

@@ -305,6 +305,55 @@ describe("mergeTaxonomyConfigs", () => {
   });
 });
 
+describe("resolveFileConfig title resolution", () => {
+  it("prefers frontmatter title over H1 heading", () => {
+    const markdown = [
+      "---",
+      "title: Frontmatter Title",
+      "---",
+      "# H1 Title",
+      "Body text",
+    ].join("\n");
+
+    const resolved = resolveFileConfig({
+      relativeFilePath: "guide.md",
+      markdown,
+    });
+
+    expect(resolved.title).toBe("Frontmatter Title");
+  });
+
+  it("falls back to H1 heading when no frontmatter title", () => {
+    const markdown = ["# Getting Started", "", "Some content here."].join("\n");
+
+    const resolved = resolveFileConfig({
+      relativeFilePath: "guide.md",
+      markdown,
+    });
+
+    expect(resolved.title).toBe("Getting Started");
+  });
+
+  it("returns no title when neither frontmatter title nor H1 exist", () => {
+    const markdown = ["## Only H2", "", "Some content."].join("\n");
+
+    const resolved = resolveFileConfig({
+      relativeFilePath: "guide.md",
+      markdown,
+    });
+
+    expect(resolved.title).toBeUndefined();
+  });
+
+  it("returns no title when no markdown is provided", () => {
+    const resolved = resolveFileConfig({
+      relativeFilePath: "guide.md",
+    });
+
+    expect(resolved.title).toBeUndefined();
+  });
+});
+
 describe("parseManifest mcpServerInstructions", () => {
   it("parses mcpServerInstructions when present", () => {
     const manifest = parseManifest({

packages/core/test/parser.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { extractFirstH1 } from "../src/parser.js";
+
+describe("extractFirstH1", () => {
+  it("returns the text of the first H1 heading", () => {
+    expect(extractFirstH1("# Hello World\n\nSome content")).toBe("Hello World");
+  });
+
+  it("returns undefined when there is no H1", () => {
+    expect(extractFirstH1("## Second level\n\nSome content")).toBeUndefined();
+  });
+
+  it("skips YAML frontmatter and finds the H1", () => {
+    const md = ["---", "key: value", "---", "# My Title", "Body text"].join("\n");
+    expect(extractFirstH1(md)).toBe("My Title");
+  });
+
+  it("returns the first H1 when there are multiple", () => {
+    const md = ["# First", "Some text", "# Second"].join("\n");
+    expect(extractFirstH1(md)).toBe("First");
+  });
+
+  it("returns undefined for an empty H1", () => {
+    expect(extractFirstH1("#")).toBeUndefined();
+  });
+
+  it("returns undefined for empty input", () => {
+    expect(extractFirstH1("")).toBeUndefined();
+  });
+
+  it("handles inline formatting in H1", () => {
+    expect(extractFirstH1("# Hello **bold** world")).toBe("Hello bold world");
+  });
+});

packages/server/package.json

@@ -42,6 +42,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@speakeasy-api/docs-mcp-core": "workspace:*",
+    "change-case": "^5.4.4",
     "commander": "^13.1.0",
     "zod": "^4.3.6"
   }

packages/server/src/http.ts

@@ -130,6 +130,7 @@ function createMcpServer(
       resources: resources.map((r) => ({
         uri: r.uri,
         name: r.name,
+        title: r.title,
         description: r.description,
         mimeType: r.mimeType,
       })),