@speakeasy-api/docs-mcp-core 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# @speakeasy-api/docs-mcp-core
+
+Core retrieval and indexing primitives for [Speakeasy Docs MCP](https://github.com/speakeasy-api/docs-mcp): markdown chunking, hybrid search, and LanceDB integration.
+
+**Beta.** Part of the [`docs-mcp`](https://github.com/speakeasy-api/docs-mcp) monorepo.
+
+## What This Package Does
+
+- AST-based markdown parsing and intelligent chunking (respects heading boundaries and code blocks)
+- Hybrid search combining full-text search with semantic vector search via Reciprocal Rank Fusion
+- LanceDB integration with memory-mapped IO for fast retrieval
+- Embedding generation and caching (OpenAI or deterministic hash)
+- Manifest resolution and metadata extraction from `.mcp-manifest.json` files
+
+## Installation
+
+```bash
+npm install @speakeasy-api/docs-mcp-core
+```
+
+## Usage
+
+This package is primarily consumed by [`@speakeasy-api/docs-mcp-server`](https://www.npmjs.com/package/@speakeasy-api/docs-mcp-server) and [`@speakeasy-api/docs-mcp-cli`](https://www.npmjs.com/package/@speakeasy-api/docs-mcp-cli). See the [monorepo README](https://github.com/speakeasy-api/docs-mcp) for end-to-end usage.
+
+## License
+
+[AGPL-3.0](https://github.com/speakeasy-api/docs-mcp/blob/main/LICENSE)

package/dist/chunking.d.ts

@@ -0,0 +1,3 @@
+import type { BuildChunksInput, Chunk } from "./types.js";
+export declare function buildChunks(input: BuildChunksInput): Chunk[];
+//# sourceMappingURL=chunking.d.ts.map

package/dist/chunking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunking.d.ts","sourceRoot":"","sources":["../src/chunking.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAoB,MAAM,YAAY,CAAC;AAqC5E,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,KAAK,EAAE,CAiC5D"}

package/dist/chunking.js

@@ -0,0 +1,332 @@
+import { toString } from "mdast-util-to-string";
+import { parseMarkdown } from "./parser.js";
+const CHUNK_LEVEL_MAP = {
+    h1: 1,
+    h2: 2,
+    h3: 3
+};
+// ─── Public API ──────────────────────────────────────────────────
+export function buildChunks(input) {
+    if (!input.filepath.trim()) {
+        throw new Error("filepath is required");
+    }
+    const ast = parseMarkdown(input.markdown);
+    if (input.strategy.chunk_by === "file") {
+        const contentNodes = ast.children.filter((n) => n.type !== "yaml");
+        const segments = applySizeRules([
+            {
+                kind: "file",
+                heading: "",
+                headingLevel: 0,
+                ancestorTexts: [],
+                ancestorSlugs: [],
+                slug: "",
+                nodes: contentNodes,
+                fullMarkdown: input.markdown,
+                part: 1
+            }
+        ], input.strategy);
+        return materializeChunks(input.filepath, segments, input.metadata ?? {});
+    }
+    const targetLevel = CHUNK_LEVEL_MAP[input.strategy.chunk_by];
+    const segments = splitByHeadingLevel(ast, input.markdown, targetLevel);
+    const adjusted = applySizeRules(segments, input.strategy);
+    return materializeChunks(input.filepath, adjusted, input.metadata ?? {});
+}
+// ─── Heading-based splitting ─────────────────────────────────────
+function splitByHeadingLevel(ast, markdown, targetLevel) {
+    const boundaries = [];
+    const stack = new Array(7).fill(undefined);
+    const slugCountsByParent = new Map();
+    // Filter out YAML frontmatter nodes for processing
+    const contentChildren = ast.children.filter((n) => n.type !== "yaml");
+    for (let childIdx = 0; childIdx < contentChildren.length; childIdx += 1) {
+        const node = contentChildren[childIdx];
+        if (node.type !== "heading") {
+            continue;
+        }
+        const heading = toString(node).trim() || "section";
+        const baseSlug = slugify(heading) || "section";
+        const parentSlugs = [];
+        for (let depth = 1; depth < node.depth; depth += 1) {
+            const current = stack[depth];
+            if (current) {
+                parentSlugs.push(current.slug);
+            }
+        }
+        const slug = dedupeSlug(parentSlugs, baseSlug, slugCountsByParent);
+        stack[node.depth] = { text: heading, slug };
+        for (let depth = node.depth + 1; depth < stack.length; depth += 1) {
+            stack[depth] = undefined;
+        }
+        if (node.depth !== targetLevel) {
+            continue;
+        }
+        const ancestorTexts = [];
+        const ancestorSlugs = [];
+        for (let depth = 1; depth < targetLevel; depth += 1) {
+            const current = stack[depth];
+            if (!current) {
+                continue;
+            }
+            ancestorTexts.push(current.text);
+            ancestorSlugs.push(current.slug);
+        }
+        boundaries.push({
+            childIndex: childIdx,
+            heading,
+            headingLevel: node.depth,
+            ancestorTexts,
+            ancestorSlugs,
+            slug
+        });
+    }
+    if (boundaries.length === 0) {
+        return [
+            {
+                kind: "preamble",
+                heading: "",
+                headingLevel: 0,
+                ancestorTexts: [],
+                ancestorSlugs: [],
+                slug: "_preamble",
+                nodes: contentChildren,
+                fullMarkdown: markdown,
+                part: 1
+            }
+        ];
+    }
+    const segments = [];
+    // Preamble: nodes before the first target-level heading
+    const preambleNodes = contentChildren.slice(0, boundaries[0].childIndex);
+    if (preambleNodes.length > 0) {
+        const preambleContent = rawMarkdown(preambleNodes, markdown);
+        if (preambleContent.trim()) {
+            segments.push({
+                kind: "preamble",
+                heading: "",
+                headingLevel: 0,
+                ancestorTexts: [],
+                ancestorSlugs: [],
+                slug: "_preamble",
+                nodes: preambleNodes,
+                fullMarkdown: markdown,
+                part: 1
+            });
+        }
+    }
+    for (let index = 0; index < boundaries.length; index += 1) {
+        const boundary = boundaries[index];
+        const next = boundaries[index + 1];
+        const startIdx = boundary.childIndex;
+        const endIdx = next ? next.childIndex : contentChildren.length;
+        const sectionNodes = contentChildren.slice(startIdx, endIdx);
+        const content = rawMarkdown(sectionNodes, markdown);
+        if (!content.trim()) {
+            continue;
+        }
+        segments.push({
+            kind: "heading",
+            heading: boundary.heading,
+            headingLevel: boundary.headingLevel,
+            ancestorTexts: boundary.ancestorTexts,
+            ancestorSlugs: boundary.ancestorSlugs,
+            slug: boundary.slug,
+            nodes: sectionNodes,
+            fullMarkdown: markdown,
+            part: 1
+        });
+    }
+    return segments.length > 0
+        ? segments
+        : [
+            {
+                kind: "preamble",
+                heading: "",
+                headingLevel: 0,
+                ancestorTexts: [],
+                ancestorSlugs: [],
+                slug: "_preamble",
+                nodes: contentChildren,
+                fullMarkdown: markdown,
+                part: 1
+            }
+        ];
+}
+// ─── Slug helpers ────────────────────────────────────────────────
+function dedupeSlug(ancestorSlugs, baseSlug, slugCountsByParent) {
+    const parentPath = ancestorSlugs.join("/") || "__root__";
+    const counterBySlug = slugCountsByParent.get(parentPath) ?? new Map();
+    slugCountsByParent.set(parentPath, counterBySlug);
+    const count = (counterBySlug.get(baseSlug) ?? 0) + 1;
+    counterBySlug.set(baseSlug, count);
+    return count === 1 ? baseSlug : `${baseSlug}-${count}`;
+}
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9 -]/g, "")
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+// ─── AST-safe size rules ─────────────────────────────────────────
+function applySizeRules(segments, strategy) {
+    const max = strategy.max_chunk_size;
+    const min = strategy.min_chunk_size;
+    // Phase 1: split oversized segments using AST node boundaries
+    const expanded = [];
+    for (const segment of segments) {
+        const contentLength = rawMarkdown(segment.nodes, segment.fullMarkdown).length;
+        if (!max || contentLength <= max) {
+            expanded.push(segment);
+            continue;
+        }
+        const nodeGroups = splitByNodeSize(segment.nodes, segment.fullMarkdown, max);
+        nodeGroups.forEach((groupNodes, partIndex) => {
+            expanded.push({
+                ...segment,
+                nodes: groupNodes,
+                part: partIndex + 1
+            });
+        });
+    }
+    // Phase 2: merge undersized segments into previous (Opus-style breadcrumb check)
+    if (!min || expanded.length <= 1) {
+        return expanded;
+    }
+    const merged = [];
+    for (const segment of expanded) {
+        const previous = merged[merged.length - 1];
+        const segmentContentLength = rawMarkdown(segment.nodes, segment.fullMarkdown).length;
+        if (previous &&
+            segmentContentLength < min &&
+            canMerge(previous, segment)) {
+            // Merge nodes together
+            previous.nodes = [...previous.nodes, ...segment.nodes];
+            continue;
+        }
+        merged.push({ ...segment, nodes: [...segment.nodes] });
+    }
+    return merged;
+}
+/**
+ * AST-safe max-size splitting (from Gemini approach).
+ *
+ * Iterates through AST nodes: if adding the next node would exceed the limit
+ * AND we already have accumulated nodes, flush current accumulation as a sub-chunk.
+ * Single nodes that exceed the limit on their own stay intact -- a large code
+ * block is never bisected.
+ */
+function splitByNodeSize(nodes, fullMarkdown, maxSize) {
+    const groups = [];
+    let current = [];
+    let currentSize = 0;
+    for (const node of nodes) {
+        const nodeSize = rawMarkdown([node], fullMarkdown).length;
+        if (current.length > 0 && currentSize + nodeSize > maxSize) {
+            groups.push(current);
+            current = [node];
+            currentSize = nodeSize;
+        }
+        else {
+            current.push(node);
+            currentSize += nodeSize;
+        }
+    }
+    if (current.length > 0) {
+        groups.push(current);
+    }
+    return groups;
+}
+/**
+ * Determine whether a small segment can be merged into the previous one.
+ *
+ * Only merges segments that originated from the same heading section
+ * (same slug, heading, heading level, and ancestor path). This prevents
+ * merging across heading boundaries while allowing sub-chunk parts
+ * (from max-size splitting) to be recombined.
+ */
+function canMerge(previous, current) {
+    if (previous.kind !== current.kind) {
+        return false;
+    }
+    if (previous.slug !== current.slug) {
+        return false;
+    }
+    if (previous.heading !== current.heading || previous.headingLevel !== current.headingLevel) {
+        return false;
+    }
+    return ancestorSlugsMatch(previous.ancestorSlugs, current.ancestorSlugs);
+}
+function ancestorSlugsMatch(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i += 1) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+// ─── Chunk materialization ───────────────────────────────────────
+function materializeChunks(filepath, segments, metadata) {
+    const chunks = [];
+    for (const [index, segment] of segments.entries()) {
+        const chunkId = computeChunkId(filepath, segment);
+        const breadcrumbParts = [filepath];
+        if (segment.ancestorTexts.length > 0) {
+            breadcrumbParts.push(...segment.ancestorTexts);
+        }
+        if (segment.heading) {
+            breadcrumbParts.push(segment.heading);
+        }
+        const content = rawMarkdown(segment.nodes, segment.fullMarkdown);
+        const contentText = segment.nodes.map((n) => toString(n)).join("\n\n");
+        chunks.push({
+            chunk_id: chunkId,
+            filepath,
+            heading: segment.heading,
+            heading_level: segment.headingLevel,
+            content,
+            content_text: contentText,
+            breadcrumb: breadcrumbParts.join(" > "),
+            chunk_index: index,
+            metadata: { ...metadata }
+        });
+    }
+    return chunks;
+}
+function computeChunkId(filepath, segment) {
+    if (segment.kind === "file") {
+        return segment.part === 1 ? filepath : `${filepath}#_part-${segment.part}`;
+    }
+    if (segment.kind === "preamble") {
+        return segment.part === 1
+            ? `${filepath}#_preamble`
+            : `${filepath}#_preamble-part-${segment.part}`;
+    }
+    const partSuffix = segment.part > 1 ? `-part-${segment.part}` : "";
+    const slug = `${segment.slug}${partSuffix}`;
+    const fullPath = [...segment.ancestorSlugs, slug].join("/");
+    return `${filepath}#${fullPath}`;
+}
+// ─── AST helpers ─────────────────────────────────────────────────
+/**
+ * Reconstruct raw markdown for a slice of AST nodes by extracting
+ * the original source range from the full content string.
+ * Falls back to mdast-util-to-string if position info is unavailable.
+ */
+function rawMarkdown(nodes, fullContent) {
+    if (nodes.length === 0)
+        return "";
+    const first = nodes[0];
+    const last = nodes[nodes.length - 1];
+    if (first.position?.start && last.position?.end) {
+        return fullContent.slice(first.position.start.offset, last.position.end.offset);
+    }
+    // Fallback
+    return nodes.map((n) => toString(n)).join("\n\n");
+}
+//# sourceMappingURL=chunking.js.map

package/dist/chunking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunking.js","sourceRoot":"","sources":["../src/chunking.ts"],"names":[],"mappings":"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"}

package/dist/cursor.d.ts

@@ -0,0 +1,12 @@
+import type { CursorPayload } from "./types.js";
+export declare function encodeCursor(payload: CursorPayload): string;
+export declare function decodeCursor(cursor: string): CursorPayload;
+export declare function encodeSearchCursor(payload: CursorPayload, context: {
+    query: string;
+    filters: Record<string, string>;
+}): string;
+export declare function decodeSearchCursor(cursor: string, context: {
+    query: string;
+    filters: Record<string, string>;
+}): CursorPayload;
+//# sourceMappingURL=cursor.d.ts.map

package/dist/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../src/cursor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAOhD,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAE3D;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAO1D;AAED,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC1D,MAAM,CAOR;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC1D,aAAa,CAef"}

package/dist/cursor.js

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+export function encodeCursor(payload) {
+    return encodePayload(payload);
+}
+export function decodeCursor(cursor) {
+    const payload = decodePayload(cursor);
+    if (!isCursorPayload(payload)) {
+        throw new Error("Invalid cursor: expected { offset:number, limit:number }");
+    }
+    return payload;
+}
+export function encodeSearchCursor(payload, context) {
+    const searchPayload = {
+        ...payload,
+        v: 1,
+        sig: computeSearchCursorSignature(context)
+    };
+    return encodePayload(searchPayload);
+}
+export function decodeSearchCursor(cursor, context) {
+    const payload = decodePayload(cursor);
+    if (!isSearchCursorPayload(payload)) {
+        throw new Error("Invalid cursor: expected a search cursor payload");
+    }
+    const expectedSignature = computeSearchCursorSignature(context);
+    if (payload.sig !== expectedSignature) {
+        throw new Error("Invalid cursor: does not match current query or filters");
+    }
+    return {
+        offset: payload.offset,
+        limit: payload.limit
+    };
+}
+function encodePayload(payload) {
+    const body = JSON.stringify(payload);
+    return Buffer.from(body, "utf8").toString("base64url");
+}
+function decodePayload(cursor) {
+    let decoded;
+    try {
+        decoded = Buffer.from(cursor, "base64url").toString("utf8");
+    }
+    catch {
+        throw new Error("Invalid cursor: not valid base64url");
+    }
+    let payload;
+    try {
+        payload = JSON.parse(decoded);
+    }
+    catch {
+        throw new Error("Invalid cursor: malformed JSON payload");
+    }
+    return payload;
+}
+function isCursorPayload(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const payload = value;
+    return (Number.isInteger(payload.offset) &&
+        Number.isInteger(payload.limit) &&
+        payload.offset >= 0 &&
+        payload.limit > 0);
+}
+function isSearchCursorPayload(value) {
+    if (!isCursorPayload(value)) {
+        return false;
+    }
+    const payload = value;
+    return payload.v === 1 && typeof payload.sig === "string" && payload.sig.length > 0;
+}
+function computeSearchCursorSignature(input) {
+    const query = input.query.trim();
+    const normalizedFilters = Object.entries(input.filters)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => [key, value]);
+    const serialized = JSON.stringify({
+        query,
+        filters: normalizedFilters
+    });
+    return createHash("sha1").update(serialized, "utf8").digest("base64url");
+}
+//# sourceMappingURL=cursor.js.map

package/dist/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../src/cursor.ts"],"names":[],"mappings":"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"}

package/dist/embedding-cache.d.ts

@@ -0,0 +1,46 @@
+import type { Chunk, EmbeddingConfig } from "./types.js";
+/**
+ * Bumped only if toEmbeddingInput() changes in a way that isn't captured
+ * by the input text itself (e.g., normalization, encoding).
+ */
+export declare const EMBEDDING_FORMAT_VERSION = "1";
+export interface CacheEntry {
+    fingerprint: string;
+    chunk_id: string;
+    vector: number[];
+}
+export interface EmbeddingCache {
+    entries: Map<string, CacheEntry>;
+}
+export interface EmbedIncrementalStats {
+    total: number;
+    hits: number;
+    misses: number;
+}
+/**
+ * Compute a fingerprint for a chunk that captures both the embedding model config
+ * and the exact text that would be sent to the model.
+ */
+export declare function computeFingerprint(chunk: Chunk, config: EmbeddingConfig): string;
+/**
+ * Load the embedding cache from disk.
+ * Returns null (with a warning to stderr) if the cache is missing, corrupt, or incompatible.
+ */
+export declare function loadCache(baseDir: string, currentConfig: EmbeddingConfig): Promise<EmbeddingCache | null>;
+/**
+ * Save the embedding cache to disk using the rotate-and-rename pattern
+ * for crash safety.
+ */
+export declare function saveCache(baseDir: string, cache: EmbeddingCache, config: EmbeddingConfig): Promise<void>;
+/**
+ * Embed chunks incrementally: reuse cached vectors for unchanged chunks,
+ * only call the provider for misses.
+ */
+export declare function embedChunksIncremental(chunks: Chunk[], provider: EmbeddingConfig & {
+    embed(texts: string[]): Promise<number[][]>;
+}, cache: EmbeddingCache | null): Promise<{
+    vectorsByChunkId: Map<string, number[]>;
+    updatedCache: EmbeddingCache;
+    stats: EmbedIncrementalStats;
+}>;
+//# sourceMappingURL=embedding-cache.d.ts.map

package/dist/embedding-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-cache.d.ts","sourceRoot":"","sources":["../src/embedding-cache.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAe5C,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,GAAG,MAAM,CAOhF;AAoBD;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,eAAe,GAC7B,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAiFhC;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,IAAI,CAAC,CA2Cf;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,KAAK,EAAE,EACf,QAAQ,EAAE,eAAe,GAAG;IAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;CAAE,EAC3E,KAAK,EAAE,cAAc,GAAG,IAAI,GAC3B,OAAO,CAAC;IACT,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACxC,YAAY,EAAE,cAAc,CAAC;IAC7B,KAAK,EAAE,qBAAqB,CAAC;CAC9B,CAAC,CA+DD"}