@speakeasy-api/docs-mcp-core 0.1.0

package/dist/search.js

@@ -0,0 +1,166 @@
+import { decodeSearchCursor, encodeSearchCursor } from "./cursor.js";
+import { clampLimit, isChunkIdFormat, makeSnippet, matchesMetadataFilters, normalizeSearchText, tokenizeSearchText } from "./search-common.js";
+export class InMemorySearchEngine {
+    chunks;
+    byId;
+    byFile;
+    proximityWeight;
+    constructor(chunks, options = {}) {
+        this.chunks = [...chunks];
+        this.byId = new Map(chunks.map((chunk) => [chunk.chunk_id, chunk]));
+        this.byFile = new Map();
+        this.proximityWeight = options.proximityWeight ?? 1.25;
+        for (const chunk of chunks) {
+            const list = this.byFile.get(chunk.filepath) ?? [];
+            list.push(chunk);
+            this.byFile.set(chunk.filepath, list);
+        }
+        for (const list of this.byFile.values()) {
+            list.sort((a, b) => a.chunk_index - b.chunk_index);
+        }
+    }
+    async search(request) {
+        const query = request.query.trim();
+        if (!query) {
+            throw new Error("query is required");
+        }
+        const limit = clampLimit(request.limit);
+        const filters = request.filters ?? {};
+        const offset = request.cursor
+            ? decodeSearchCursor(request.cursor, { query, filters }).offset
+            : 0;
+        const taxonomyKeys = request.taxonomy_keys;
+        const proximityWeight = request.rrf_weights?.phrase ?? this.proximityWeight;
+        const scored = this.chunks
+            .filter((chunk) => matchesMetadataFilters(chunk.metadata, filters, taxonomyKeys))
+            .map((chunk) => ({ chunk, score: scoreChunk(chunk, query, proximityWeight) }))
+            .filter((entry) => entry.score > 0)
+            .sort((a, b) => b.score - a.score || a.chunk.chunk_id.localeCompare(b.chunk.chunk_id));
+        const paged = scored.slice(offset, offset + limit);
+        const hits = paged.map(({ chunk, score }) => toSearchHit(chunk, score, query));
+        const nextOffset = offset + paged.length;
+        const nextCursor = nextOffset < scored.length
+            ? encodeSearchCursor({ offset: nextOffset, limit }, { query, filters })
+            : null;
+        if (hits.length > 0) {
+            return {
+                hits,
+                next_cursor: nextCursor,
+                hint: null
+            };
+        }
+        return {
+            hits,
+            next_cursor: nextCursor,
+            hint: buildHint(this.chunks, query, filters)
+        };
+    }
+    async getDoc(request) {
+        if (!isChunkIdFormat(request.chunk_id)) {
+            throw new Error(`Chunk ID '${request.chunk_id}' has invalid format. Expected {filepath} or {filepath}#{heading-path}.`);
+        }
+        const context = Math.max(0, Math.min(5, request.context ?? 0));
+        const target = this.byId.get(request.chunk_id);
+        if (!target) {
+            throw new Error(`Chunk ID '${request.chunk_id}' not found. Use search_docs to discover valid chunk IDs.`);
+        }
+        const fileChunks = this.byFile.get(target.filepath);
+        if (!fileChunks) {
+            throw new Error(`Internal error: file '${target.filepath}' is missing from index`);
+        }
+        const indexInFile = fileChunks.findIndex((chunk) => chunk.chunk_id === target.chunk_id);
+        const start = Math.max(0, indexInFile - context);
+        const end = Math.min(fileChunks.length - 1, indexInFile + context);
+        const blocks = [];
+        for (let i = start; i <= end; i += 1) {
+            const chunk = fileChunks[i];
+            if (!chunk) {
+                continue;
+            }
+            const positionLabel = `Chunk ${i + 1} of ${fileChunks.length}`;
+            const contextOffset = i - indexInFile;
+            const role = contextOffset === 0
+                ? "Target"
+                : `Context: ${contextOffset > 0 ? `+${contextOffset}` : contextOffset}`;
+            blocks.push(`--- Chunk: ${chunk.chunk_id} (${positionLabel}) (${role}) ---\n${chunk.content}`);
+        }
+        return {
+            text: blocks.join("\n\n")
+        };
+    }
+}
+// Backwards-compatible alias while introducing the SearchEngine abstraction.
+export class DocsIndex extends InMemorySearchEngine {
+}
+function scoreChunk(chunk, query, proximityWeight) {
+    const queryNormalized = normalizeSearchText(query);
+    const tokens = tokenizeSearchText(queryNormalized);
+    if (tokens.length === 0) {
+        return 0;
+    }
+    const heading = normalizeSearchText(chunk.heading);
+    const content = normalizeSearchText(chunk.content_text);
+    let lexical = 0;
+    for (const token of tokens) {
+        lexical += countToken(content, token) + 3 * countToken(heading, token);
+    }
+    const phraseMatch = content.includes(queryNormalized) || heading.includes(queryNormalized);
+    const proximityBoost = phraseMatch ? proximityWeight : 0;
+    return lexical + proximityBoost;
+}
+function toSearchHit(chunk, score, query) {
+    return {
+        chunk_id: chunk.chunk_id,
+        heading: chunk.heading,
+        breadcrumb: chunk.breadcrumb,
+        snippet: makeSnippet(chunk.content_text, query),
+        filepath: chunk.filepath,
+        metadata: chunk.metadata,
+        score: Number(score.toFixed(6))
+    };
+}
+function buildHint(chunks, query, filters) {
+    const queryMatches = chunks.filter((chunk) => scoreChunk(chunk, query, 0) > 0);
+    if (queryMatches.length === 0) {
+        return {
+            message: "0 results found. No matches were found for this query in the indexed corpus.",
+            suggested_filters: {}
+        };
+    }
+    const suggestions = {};
+    for (const [key, activeValue] of Object.entries(filters)) {
+        const values = new Set();
+        for (const chunk of queryMatches) {
+            const candidate = chunk.metadata[key];
+            if (!candidate || candidate === activeValue) {
+                continue;
+            }
+            values.add(candidate);
+        }
+        if (values.size > 0) {
+            suggestions[key] = [...values].sort((a, b) => a.localeCompare(b));
+        }
+    }
+    const filterSummary = Object.entries(filters)
+        .map(([key, value]) => `${key}='${value}'`)
+        .join(", ");
+    return {
+        message: filterSummary
+            ? `0 results found for query '${query}' with filters ${filterSummary}.`
+            : `0 results found for query '${query}'.`,
+        suggested_filters: suggestions
+    };
+}
+function countToken(value, token) {
+    if (!token) {
+        return 0;
+    }
+    let count = 0;
+    let index = value.indexOf(token);
+    while (index >= 0) {
+        count += 1;
+        index = value.indexOf(token, index + token.length);
+    }
+    return count;
+}
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EACL,UAAU,EACV,eAAe,EACf,WAAW,EACX,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,oBAAoB,CAAC;AAa5B,MAAM,OAAO,oBAAoB;IACd,MAAM,CAAU;IAChB,IAAI,CAAqB;IACzB,MAAM,CAAuB;IAC7B,eAAe,CAAS;IAEzC,YAAY,MAAe,EAAE,UAA4B,EAAE;QACzD,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;QACpE,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,EAAmB,CAAC;QACzC,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,IAAI,CAAC;QAEvD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACjB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACxC,CAAC;QAED,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACxC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,OAAsB;QACjC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QACnC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QACvC,CAAC;QAED,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACxC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM;YAC3B,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM;YAC/D,CAAC,CAAC,CAAC,CAAC;QAEN,MAAM,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;QAC3C,MAAM,eAAe,GAAG,OAAO,CAAC,WAAW,EAAE,MAAM,IAAI,IAAI,CAAC,eAAe,CAAC;QAE5E,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM;aACvB,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,sBAAsB,CAAC,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;aAChF,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,eAAe,CAAC,EAAE,CAAC,CAAC;aAC7E,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;aAClC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;QAEzF,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC;QACnD,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;QAE/E,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QACzC,MAAM,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC,MAAM;YAC3C,CAAC,CAAC,kBAAkB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;YACvE,CAAC,CAAC,IAAI,CAAC;QAET,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,OAAO;gBACL,IAAI;gBACJ,WAAW,EAAE,UAAU;gBACvB,IAAI,EAAE,IAAI;aACX,CAAC;QACJ,CAAC;QAED,OAAO;YACL,IAAI;YACJ,WAAW,EAAE,UAAU;YACvB,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC;SAC7C,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,OAAsB;QACjC,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CACb,aAAa,OAAO,CAAC,QAAQ,yEAAyE,CACvG,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;QAC/D,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC/C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,aAAa,OAAO,CAAC,QAAQ,2DAA2D,CACzF,CAAC;QACJ,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACpD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,CAAC,QAAQ,yBAAyB,CAAC,CAAC;QACrF,CAAC;QAED,MAAM,WAAW,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,KAAK,MAAM,CAAC,QAAQ,CAAC,CAAC;QACxF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC;QACjD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC;QAEnE,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YACrC,MAAM,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;YAC5B,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,SAAS;YACX,CAAC;YACD,MAAM,aAAa,GAAG,SAAS,CAAC,GAAG,CAAC,OAAO,UAAU,CAAC,MAAM,EAAE,CAAC;YAC/D,MAAM,aAAa,GAAG,CAAC,GAAG,WAAW,CAAC;YACtC,MAAM,IAAI,GACR,aAAa,KAAK,CAAC;gBACjB,CAAC,CAAC,QAAQ;gBACV,CAAC,CAAC,YAAY,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,aAAa,EAAE,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;YAE5E,MAAM,CAAC,IAAI,CACT,cAAc,KAAK,CAAC,QAAQ,KAAK,aAAa,MAAM,IAAI,UAAU,KAAK,CAAC,OAAO,EAAE,CAClF,CAAC;QACJ,CAAC;QAED,OAAO;YACL,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;SAC1B,CAAC;IACJ,CAAC;CACF;AAED,6EAA6E;AAC7E,MAAM,OAAO,SAAU,SAAQ,oBAAoB;CAAG;AAEtD,SAAS,UAAU,CAAC,KAAY,EAAE,KAAa,EAAE,eAAuB;IACtE,MAAM,eAAe,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,kBAAkB,CAAC,eAAe,CAAC,CAAC;IACnD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACnD,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAExD,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,OAAO,IAAI,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;IAC3F,MAAM,cAAc,GAAG,WAAW,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAEzD,OAAO,OAAO,GAAG,cAAc,CAAC;AAClC,CAAC;AAED,SAAS,WAAW,CAAC,KAAY,EAAE,KAAa,EAAE,KAAa;IAC7D,OAAO;QACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,OAAO,EAAE,WAAW,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC;QAC/C,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;KAChC,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAChB,MAAe,EACf,KAAa,EACb,OAA+B;IAE/B,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/E,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO;YACL,OAAO,EAAE,8EAA8E;YACvF,iBAAiB,EAAE,EAAE;SACtB,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GAA6B,EAAE,CAAC;IACjD,KAAK,MAAM,CAAC,GAAG,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACzD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;QACjC,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;YACjC,MAAM,SAAS,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YACtC,IAAI,CAAC,SAAS,IAAI,SAAS,KAAK,WAAW,EAAE,CAAC;gBAC5C,SAAS;YACX,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACxB,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACpB,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;IAED,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;SAC1C,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,KAAK,GAAG,CAAC;SAC1C,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,OAAO;QACL,OAAO,EAAE,aAAa;YACpB,CAAC,CAAC,8BAA8B,KAAK,kBAAkB,aAAa,GAAG;YACvE,CAAC,CAAC,8BAA8B,KAAK,IAAI;QAC3C,iBAAiB,EAAE,WAAW;KAC/B,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,KAAa,EAAE,KAAa;IAC9C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACjC,OAAO,KAAK,IAAI,CAAC,EAAE,CAAC;QAClB,KAAK,IAAI,CAAC,CAAC;QACX,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,125 @@
+export interface Chunk {
+    chunk_id: string;
+    filepath: string;
+    heading: string;
+    heading_level: number;
+    content: string;
+    content_text: string;
+    breadcrumb: string;
+    chunk_index: number;
+    metadata: Record<string, string>;
+}
+export interface ChunkingStrategy {
+    chunk_by: "h1" | "h2" | "h3" | "file";
+    max_chunk_size?: number;
+    min_chunk_size?: number;
+}
+export interface ManifestOverride {
+    pattern: string;
+    strategy?: ChunkingStrategy;
+    metadata?: Record<string, string>;
+}
+export interface Manifest {
+    version: string;
+    strategy?: ChunkingStrategy;
+    metadata?: Record<string, string>;
+    overrides?: ManifestOverride[];
+}
+export interface RrfWeights {
+    vector?: number;
+    match?: number;
+    phrase?: number;
+}
+export interface SearchRequest {
+    query: string;
+    limit: number;
+    cursor?: string;
+    filters: Record<string, string>;
+    /** Available taxonomy keys from metadata, used for conditional auto-include */
+    taxonomy_keys?: string[];
+    /** Optional RRF weight overrides for this request */
+    rrf_weights?: RrfWeights;
+}
+export interface SearchHit {
+    chunk_id: string;
+    heading: string;
+    breadcrumb: string;
+    snippet: string;
+    filepath: string;
+    metadata: Record<string, string>;
+    score: number;
+}
+export interface SearchHint {
+    message: string;
+    suggested_filters: Record<string, string[]>;
+}
+export interface SearchResult {
+    hits: SearchHit[];
+    next_cursor: string | null;
+    hint: SearchHint | null;
+}
+export interface SearchEngine {
+    search(request: SearchRequest): Promise<SearchResult>;
+    getDoc(request: GetDocRequest): Promise<GetDocResult>;
+}
+export interface TaxonomyField {
+    description?: string;
+    values: string[];
+}
+export interface MetadataStats {
+    total_chunks: number;
+    total_files: number;
+    indexed_at: string;
+    source_commit?: string | null;
+}
+export interface EmbeddingMetadata {
+    provider: string;
+    model: string;
+    dimensions: number;
+}
+export interface CorpusMetadata {
+    metadata_version: string;
+    corpus_description: string;
+    taxonomy: Record<string, TaxonomyField>;
+    stats: MetadataStats;
+    embedding: EmbeddingMetadata | null;
+}
+export interface GetDocRequest {
+    chunk_id: string;
+    context?: number;
+}
+export interface GetDocResult {
+    text: string;
+}
+export interface BuildChunksInput {
+    filepath: string;
+    markdown: string;
+    strategy: ChunkingStrategy;
+    metadata?: Record<string, string>;
+}
+export interface ResolvedFileConfig {
+    strategy: ChunkingStrategy;
+    metadata: Record<string, string>;
+}
+export interface EmbeddingConfig {
+    provider: string;
+    model: string;
+    dimensions: number;
+    configFingerprint: string;
+}
+export interface EmbeddingProvider {
+    readonly name: string;
+    readonly model: string;
+    readonly dimensions: number;
+    readonly configFingerprint: string;
+    embed(texts: string[]): Promise<number[][]>;
+}
+export interface DocsIndexOptions {
+    proximityWeight?: number;
+    phraseSlop?: number;
+}
+export interface CursorPayload {
+    offset: number;
+    limit: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@speakeasy-api/docs-mcp-core",
+  "version": "0.1.0",
+  "description": "Core retrieval and indexing primitives for docs-mcp: markdown chunking, hybrid search, and LanceDB integration",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "author": "Speakeasy <info@speakeasy.com> (https://speakeasy.com)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/speakeasy-api/docs-mcp.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/speakeasy-api/docs-mcp",
+  "bugs": {
+    "url": "https://github.com/speakeasy-api/docs-mcp/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@lancedb/lancedb": "^0.26.2",
+    "apache-arrow": "^18.1.0",
+    "gray-matter": "^4.0.3",
+    "mdast-util-to-string": "^4.0.0",
+    "picomatch": "^4.0.2",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.0",
+    "remark-parse": "^11.0.0",
+    "semver": "^7.7.1",
+    "unified": "^11.0.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src test"
+  }
+}