@lichtblick/docs-mcp 0.0.0 → 0.1.0

package/dist/api/extension-api.js

@@ -0,0 +1,137 @@
+// SPDX-FileCopyrightText: Copyright (C) 2023-2026 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)<lichtblick@bmwgroup.com>
+// SPDX-License-Identifier: MPL-2.0
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { basename, dirname, join, resolve } from "node:path";
+import ts from "typescript";
+const KINDS = new Map([
+    [ts.SyntaxKind.InterfaceDeclaration, "interface"],
+    [ts.SyntaxKind.TypeAliasDeclaration, "type"],
+    [ts.SyntaxKind.FunctionDeclaration, "function"],
+    [ts.SyntaxKind.ClassDeclaration, "class"],
+    [ts.SyntaxKind.EnumDeclaration, "enum"],
+    [ts.SyntaxKind.VariableStatement, "const"],
+]);
+/** Reads the public API of `@lichtblick/suite` from the TypeScript sources it ships. */
+export class ExtensionApi {
+    #packageDir;
+    #loaded;
+    constructor(packageDir = resolveSuitePackageDir()) {
+        this.#packageDir = packageDir;
+    }
+    async load() {
+        if (!this.#loaded) {
+            this.#loaded = loadSuiteApi(this.#packageDir);
+            this.#loaded.catch(() => (this.#loaded = undefined));
+        }
+        return await this.#loaded;
+    }
+    async get(name) {
+        const { symbols } = await this.load();
+        const lower = name.toLowerCase();
+        return (symbols.get(name) ??
+            [...symbols.values()].find((symbol) => symbol.name.toLowerCase() === lower));
+    }
+    async suggest(query, max = 15) {
+        const { symbols } = await this.load();
+        const lower = query.toLowerCase();
+        return [...symbols.keys()]
+            .filter((name) => name.toLowerCase().includes(lower))
+            .slice(0, max);
+    }
+}
+export function resolveSuitePackageDir() {
+    return dirname(createRequire(import.meta.url).resolve("@lichtblick/suite/package.json"));
+}
+export async function loadSuiteApi(packageDir) {
+    const { version } = JSON.parse(await readFile(join(packageDir, "package.json"), "utf8"));
+    const srcDir = join(packageDir, "src");
+    const modules = new Map();
+    const parse = async (file) => {
+        let parsed = modules.get(file);
+        if (!parsed) {
+            parsed = readFile(file, "utf8").then((text) => parseModule(file, text));
+            modules.set(file, parsed);
+        }
+        return await parsed;
+    };
+    const entry = await parse(join(srcDir, "index.ts"));
+    const symbols = new Map(entry.declarations);
+    const reExported = await Promise.all(entry.reExports.map(async ({ name, exportedAs, from }) => {
+        const symbol = (await parse(resolve(srcDir, `${from}.ts`))).declarations.get(name);
+        return symbol && { ...symbol, name: exportedAs };
+    }));
+    for (const symbol of reExported) {
+        if (symbol) {
+            symbols.set(symbol.name, symbol);
+        }
+    }
+    return { version, symbols };
+}
+export function parseModule(fileName, text) {
+    const sourceFile = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true);
+    const declarations = new Map();
+    const reExports = [];
+    for (const statement of sourceFile.statements) {
+        if (ts.isExportDeclaration(statement)) {
+            const { exportClause, moduleSpecifier } = statement;
+            if (exportClause &&
+                ts.isNamedExports(exportClause) &&
+                moduleSpecifier &&
+                ts.isStringLiteral(moduleSpecifier)) {
+                for (const element of exportClause.elements) {
+                    reExports.push({
+                        name: (element.propertyName ?? element.name).text,
+                        exportedAs: element.name.text,
+                        from: moduleSpecifier.text,
+                    });
+                }
+            }
+            continue;
+        }
+        const kind = KINDS.get(statement.kind);
+        if (!kind || !isExported(statement)) {
+            continue;
+        }
+        const source = [
+            attachedComments(sourceFile, statement),
+            statement.getText(sourceFile),
+        ]
+            .filter(Boolean)
+            .join("\n");
+        for (const name of declaredNames(statement)) {
+            declarations.set(name, { name, kind, file: basename(fileName), source });
+        }
+    }
+    return { declarations, reExports };
+}
+function isExported(statement) {
+    return (ts.canHaveModifiers(statement) &&
+        (ts
+            .getModifiers(statement)
+            ?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ??
+            false));
+}
+function declaredNames(statement) {
+    if (ts.isVariableStatement(statement)) {
+        return statement.declarationList.declarations.flatMap((declaration) => ts.isIdentifier(declaration.name) ? [declaration.name.text] : []);
+    }
+    const { name } = statement;
+    return name && ts.isIdentifier(name) ? [name.text] : [];
+}
+// Leading comments separated from the declaration by a blank line (e.g. license headers) are not attached.
+function attachedComments(sourceFile, node) {
+    const text = sourceFile.text;
+    const ranges = ts.getLeadingCommentRanges(text, node.getFullStart()) ?? [];
+    const attached = [];
+    let next = node.getStart(sourceFile);
+    for (const range of ranges.toReversed()) {
+        if (text.slice(range.end, next).split("\n").length > 2) {
+            break;
+        }
+        attached.unshift(text.slice(range.pos, range.end));
+        next = range.pos;
+    }
+    return attached.join("\n");
+}
+//# sourceMappingURL=extension-api.js.map

package/dist/check.js

@@ -0,0 +1,26 @@
+// SPDX-FileCopyrightText: Copyright (C) 2023-2026 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)<lichtblick@bmwgroup.com>
+// SPDX-License-Identifier: MPL-2.0
+import { createDocSource } from "./docs/source.js";
+import { DocsStore } from "./docs/store.js";
+import { errorMessage } from "./logging.js";
+/** Verifies that every page listed in llms.txt resolves to its .md page; returns the process exit code. */
+export async function runCheck(config, print = (line) => process.stderr.write(`${line}\n`)) {
+    const source = config.docsSource;
+    try {
+        const { pages, failures } = await new DocsStore(createDocSource(source), config.siteUrl).verify();
+        if (pages === 0) {
+            print(`FAIL: llms.txt from ${source} lists no pages`);
+            return 1;
+        }
+        for (const { path, reason } of failures) {
+            print(`FAIL ${path}: ${reason}`);
+        }
+        print(`${pages - failures.length}/${pages} pages resolved (source: ${source})`);
+        return failures.length === 0 ? 0 : 1;
+    }
+    catch (error) {
+        print(`FAIL: could not read llms.txt from ${source}: ${errorMessage(error)}`);
+        return 1;
+    }
+}
+//# sourceMappingURL=check.js.map

package/dist/config.js

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: Copyright (C) 2023-2026 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)<lichtblick@bmwgroup.com>
+// SPDX-License-Identifier: MPL-2.0
+import { withTrailingSlash } from "./docs/source.js";
+const DEFAULT_SITE_URL = "https://lichtblick-suite.github.io/docs/";
+export function loadConfig(env = process.env) {
+    const siteUrl = new URL(withTrailingSlash(env.LICHTBLICK_DOCS_SITE_URL ?? DEFAULT_SITE_URL));
+    return {
+        siteUrl,
+        docsSource: env.LICHTBLICK_DOCS_SOURCE ?? siteUrl.href,
+        log: env.LICHTBLICK_DOCS_LOG?.trim().toLowerCase() !== "off",
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/docs/llms-txt.js

@@ -0,0 +1,64 @@
+// SPDX-FileCopyrightText: Copyright (C) 2023-2026 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)<lichtblick@bmwgroup.com>
+// SPDX-License-Identifier: MPL-2.0
+const LINK_LINE = /^- \[(?<title>[^\]]+)\]\((?<url>[^)\s]+)\)(?<rest>.*)$/;
+export function parseLlmsTxt(text, siteUrl) {
+    const entries = [];
+    let section = "";
+    for (const rawLine of text.split("\n")) {
+        const line = rawLine.trim();
+        if (line.startsWith("## ")) {
+            section = line.slice(3).trim();
+            continue;
+        }
+        const groups = LINK_LINE.exec(line)?.groups;
+        if (!groups?.title || !groups.url) {
+            continue;
+        }
+        const path = toPagePath(groups.url, siteUrl);
+        if (!path) {
+            continue;
+        }
+        entries.push({
+            path,
+            title: groups.title,
+            url: new URL(path, siteUrl).href,
+            description: groups.rest?.startsWith(":") === true
+                ? cleanDescription(groups.rest.slice(1))
+                : "",
+            section,
+        });
+    }
+    return entries;
+}
+/** Returns the page path for URLs under `siteUrl`, or undefined for external links. */
+export function toPagePath(url, siteUrl) {
+    let parsed;
+    try {
+        parsed = new URL(url, siteUrl);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.origin !== siteUrl.origin ||
+        !parsed.pathname.startsWith(siteUrl.pathname)) {
+        return undefined;
+    }
+    return (trimSlashes(parsed.pathname.slice(siteUrl.pathname.length)) || undefined);
+}
+export function trimSlashes(value) {
+    let start = 0;
+    let end = value.length;
+    while (start < end && value[start] === "/") {
+        start++;
+    }
+    while (end > start && value[end - 1] === "/") {
+        end--;
+    }
+    return value.slice(start, end);
+}
+// docusaurus-plugin-llms falls back to the first body line, which is sometimes an admonition or HTML tag.
+function cleanDescription(description) {
+    const trimmed = description.trim();
+    return trimmed.startsWith("<") || trimmed.startsWith(":::") ? "" : trimmed;
+}
+//# sourceMappingURL=llms-txt.js.map

package/dist/docs/markdown.js

@@ -0,0 +1,42 @@
+// SPDX-FileCopyrightText: Copyright (C) 2023-2026 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)<lichtblick@bmwgroup.com>
+// SPDX-License-Identifier: MPL-2.0
+const FENCE = /^\s*(```|~~~)/;
+const HEADING = /^#{2,3} (.*)$/;
+/** Splits a page into its intro plus one section per `##`/`###` heading. */
+export function splitSections(markdown) {
+    const sections = [];
+    let heading = "";
+    let lines = [];
+    let inFence = false;
+    const flush = () => {
+        const text = lines.join("\n").trim();
+        if (text) {
+            sections.push({ heading, anchor: slugify(heading), text });
+        }
+    };
+    for (const line of markdown.split("\n")) {
+        if (FENCE.test(line)) {
+            inFence = !inFence;
+        }
+        const nextHeading = inFence ? undefined : HEADING.exec(line)?.[1]?.trim();
+        if (nextHeading) {
+            flush();
+            heading = nextHeading;
+            lines = [];
+        }
+        else {
+            lines.push(line);
+        }
+    }
+    flush();
+    return sections;
+}
+/** Approximates the Docusaurus heading id so search hits can link to the section. */
+export function slugify(heading) {
+    return heading
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s-]/gu, "")
+        .trim()
+        .replace(/\s+/g, "-");
+}
+//# sourceMappingURL=markdown.js.map

package/dist/docs/source.js

@@ -0,0 +1,44 @@
+// SPDX-FileCopyrightText: Copyright (C) 2023-2026 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)<lichtblick@bmwgroup.com>
+// SPDX-License-Identifier: MPL-2.0
+import { readFile } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+const FETCH_TIMEOUT_MS = 10_000;
+export function withTrailingSlash(value) {
+    return value.endsWith("/") ? value : `${value}/`;
+}
+/** `location` is either an http(s) URL or a local Docusaurus build directory. */
+export function createDocSource(location) {
+    return /^https?:\/\//i.test(location)
+        ? httpSource(new URL(withTrailingSlash(location)))
+        : fileSource(resolve(location));
+}
+function httpSource(base) {
+    return {
+        async read(relativePath) {
+            const url = new URL(relativePath, base);
+            if (url.origin !== base.origin ||
+                !url.pathname.startsWith(base.pathname)) {
+                throw new Error(`Path escapes the docs source: ${relativePath}`);
+            }
+            const response = await fetch(url, {
+                signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            });
+            if (!response.ok) {
+                throw new Error(`GET ${url.href} failed with HTTP ${response.status}`);
+            }
+            return await response.text();
+        },
+    };
+}
+function fileSource(root) {
+    return {
+        async read(relativePath) {
+            const file = resolve(root, relativePath);
+            if (!file.startsWith(root + sep)) {
+                throw new Error(`Path escapes the docs source: ${relativePath}`);
+            }
+            return await readFile(file, "utf8");
+        },
+    };
+}
+//# sourceMappingURL=source.js.map

package/dist/docs/store.js

@@ -0,0 +1,169 @@
+// SPDX-FileCopyrightText: Copyright (C) 2023-2026 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)<lichtblick@bmwgroup.com>
+// SPDX-License-Identifier: MPL-2.0
+import MiniSearch from "minisearch";
+import { errorMessage, silentLogger } from "../logging.js";
+import { parseLlmsTxt, toPagePath, trimSlashes, } from "./llms-txt.js";
+import { splitSections } from "./markdown.js";
+const SNIPPET_LENGTH = 280;
+export class DocsStore {
+    #source;
+    #siteUrl;
+    #logger;
+    #entries;
+    #index;
+    #markdown = new Map();
+    constructor(source, siteUrl, logger = silentLogger) {
+        this.#source = source;
+        this.#siteUrl = siteUrl;
+        this.#logger = logger;
+    }
+    async list(section) {
+        const entries = [...(await this.#loadEntries()).values()];
+        return section
+            ? entries.filter((entry) => entry.section.toLowerCase() === section.toLowerCase())
+            : entries;
+    }
+    /** Accepts a page path, a path with `.md`/anchor, or a full page URL. */
+    async fetch(pathOrUrl) {
+        const entry = (await this.#loadEntries()).get(this.#normalizePath(pathOrUrl));
+        return (entry && { ...entry, markdown: await this.#loadMarkdown(entry.path) });
+    }
+    async search(query, limit) {
+        const { search, sections } = await this.#loadIndex();
+        return search
+            .search(query)
+            .slice(0, limit)
+            .flatMap((result) => {
+            const section = sections.get(result.id);
+            if (!section) {
+                return [];
+            }
+            const pageUrl = new URL(section.path, this.#siteUrl).href;
+            return [
+                {
+                    path: section.path,
+                    title: section.title,
+                    heading: section.heading,
+                    url: section.anchor ? `${pageUrl}#${section.anchor}` : pageUrl,
+                    snippet: snippet(section.text, result.terms),
+                    score: result.score,
+                },
+            ];
+        });
+    }
+    /** Starts building the search index in the background so the first docs_search is fast. */
+    warmUp() {
+        this.#loadIndex().catch((error) => {
+            this.#logger("error", {
+                message: "failed to build the docs index",
+                error: errorMessage(error),
+            });
+        });
+    }
+    /** Fetches every page listed in llms.txt and reports the ones that cannot be loaded. */
+    async verify() {
+        const { loaded, failures } = await this.#loadAllPages();
+        return { pages: loaded.length + failures.length, failures };
+    }
+    #normalizePath(pathOrUrl) {
+        if (/^https?:\/\//i.test(pathOrUrl)) {
+            return toPagePath(pathOrUrl, this.#siteUrl) ?? "";
+        }
+        const withoutAnchor = pathOrUrl.split("#")[0] ?? "";
+        return trimSlashes(withoutAnchor.endsWith(".md")
+            ? withoutAnchor.slice(0, -3)
+            : withoutAnchor);
+    }
+    async #loadEntries() {
+        if (!this.#entries) {
+            this.#entries = this.#source
+                .read("llms.txt")
+                .then((text) => new Map(parseLlmsTxt(text, this.#siteUrl).map((entry) => [
+                entry.path,
+                entry,
+            ])));
+            this.#entries.catch(() => (this.#entries = undefined));
+        }
+        return await this.#entries;
+    }
+    async #loadMarkdown(path) {
+        let markdown = this.#markdown.get(path);
+        if (!markdown) {
+            markdown = this.#source.read(`${path}.md`);
+            this.#markdown.set(path, markdown);
+            markdown.catch(() => this.#markdown.delete(path));
+        }
+        return await markdown;
+    }
+    async #loadIndex() {
+        if (!this.#index) {
+            this.#index = this.#buildIndex();
+            this.#index.catch(() => (this.#index = undefined));
+        }
+        return await this.#index;
+    }
+    async #loadAllPages() {
+        const entries = [...(await this.#loadEntries()).values()];
+        const results = await Promise.all(entries.map(async (entry) => {
+            try {
+                return { entry, markdown: await this.#loadMarkdown(entry.path) };
+            }
+            catch (error) {
+                return { entry, error: errorMessage(error) };
+            }
+        }));
+        const pages = { loaded: [], failures: [] };
+        for (const { entry, markdown, error } of results) {
+            if (markdown != undefined) {
+                pages.loaded.push({ entry, markdown });
+            }
+            else {
+                pages.failures.push({ path: entry.path, reason: error });
+            }
+        }
+        return pages;
+    }
+    async #buildIndex() {
+        const start = performance.now();
+        const { loaded, failures } = await this.#loadAllPages();
+        const sections = new Map();
+        for (const { entry, markdown } of loaded) {
+            splitSections(markdown).forEach((section, i) => {
+                const id = `${entry.path}::${i}`;
+                sections.set(id, {
+                    id,
+                    path: entry.path,
+                    title: entry.title,
+                    ...section,
+                });
+            });
+        }
+        const search = new MiniSearch({
+            fields: ["title", "heading", "text"],
+            searchOptions: {
+                boost: { title: 3, heading: 2 },
+                prefix: true,
+                fuzzy: 0.2,
+            },
+        });
+        search.addAll([...sections.values()]);
+        this.#logger("docs_index", {
+            pages: loaded.length,
+            sections: sections.size,
+            durationMs: Math.round(performance.now() - start),
+            skipped: failures.map(({ path, reason }) => `${path} (${reason})`),
+        });
+        return { search, sections };
+    }
+}
+function snippet(text, terms) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    const lower = flat.toLowerCase();
+    const firstHit = Math.min(...terms
+        .map((term) => lower.indexOf(term.toLowerCase()))
+        .filter((index) => index >= 0));
+    const start = Number.isFinite(firstHit) ? Math.max(0, firstHit - 80) : 0;
+    const end = Math.min(flat.length, start + SNIPPET_LENGTH);
+    return `${start > 0 ? "…" : ""}${flat.slice(start, end)}${end < flat.length ? "…" : ""}`;
+}
+//# sourceMappingURL=store.js.map

package/dist/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (C) 2023-2026 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)<lichtblick@bmwgroup.com>
+// SPDX-License-Identifier: MPL-2.0
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ExtensionApi } from "./api/extension-api.js";
+import { runCheck } from "./check.js";
+import { loadConfig } from "./config.js";
+import { createDocSource } from "./docs/source.js";
+import { DocsStore } from "./docs/store.js";
+import { createLogger, errorMessage, silentLogger } from "./logging.js";
+import { createServer, SERVER_VERSION } from "./server.js";
+const config = loadConfig();
+if (process.argv[2] === "check") {
+    process.exitCode = await runCheck(config);
+}
+else {
+    const logger = config.log ? createLogger() : silentLogger;
+    try {
+        const docs = new DocsStore(createDocSource(config.docsSource), config.siteUrl, logger);
+        const server = createServer({
+            docs,
+            api: new ExtensionApi(),
+            logger,
+        });
+        await server.connect(new StdioServerTransport());
+        logger("ready", { version: SERVER_VERSION, docsSource: config.docsSource });
+        docs.warmUp();
+    }
+    catch (error) {
+        // Fatal errors are reported even when logging is disabled.
+        createLogger()("error", {
+            message: "failed to start lichtblick-docs-mcp",
+            error: errorMessage(error),
+        });
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/logging.js

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: Copyright (C) 2023-2026 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)<lichtblick@bmwgroup.com>
+// SPDX-License-Identifier: MPL-2.0
+export const silentLogger = () => { };
+/** Writes one JSON object per line, to stderr by default: stdout carries the MCP protocol. */
+export function createLogger(write = (line) => void process.stderr.write(`${line}\n`)) {
+    return (event, fields) => {
+        write(JSON.stringify({ ts: new Date().toISOString(), event, ...fields }));
+    };
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=logging.js.map