@dnb/eufemia/mcp/docs-source.d.ts

DNB Eufemia Design System UI Library

/**
 * DocsSource is a tiny filesystem abstraction used by the MCP docs tools.
 *
 * The MCP server has two deployment targets:
 *
 * - Node.js (stdio + the local Express HTTP server) — uses
 *   `createNodeDocsSource(rootAbs)` which reads from disk via `node:fs`.
 *
 * - Cloudflare Workers — uses `createBundledDocsSource(bundle)` which is a
 *   pure in-memory implementation backed by a `path → content` map that the
 *   docs build step generates as `docs.bundle.json`.
 *
 * Keeping the surface small makes it trivial to add another backend (R2,
 * KV, S3, ...) later without touching the tool handlers.
 */
export type DocsEntryKind = 'file' | 'dir' | 'missing';
export type DocsEntry = {
    kind: DocsEntryKind;
};
export type DocsSource = {
    /**
     * Returns markdown/MDX file paths relative to the docs root, normalised to
     * forward slashes and **without** a leading slash. Order is implementation
     * defined.
     */
    listMarkdown(): Promise<string[]>;
    /**
     * Reads a single file given a path relative to the docs root.
     *
     * Returns `null` when the path does not exist or is not a regular file.
     * The path is normalised before lookup; a leading slash is allowed.
     */
    read(relPath: string): Promise<string | null>;
    /**
     * Returns whether `relPath` is a file, directory, or missing.
     */
    stat(relPath: string): Promise<DocsEntry>;
    /**
     * Lists the entries directly inside `relPath`. Returns an empty array if
     * `relPath` is missing or not a directory.
     */
    listDir(relPath: string, max?: number): Promise<string[]>;
    /**
     * Human-readable label for log lines (e.g. "node:/abs/path" or "bundle").
     */
    readonly label: string;
};
/**
 * Normalises a user-supplied path so it can safely be used as a key into the
 * docs source. Strips leading slashes, converts back-slashes, and rejects
 * paths that try to escape the docs root with `..`.
 */
export declare function normalizeDocsPath(input: unknown): string;
export declare function createBundledDocsSource(bundle: Record<string, string>, options?: {
    label?: string;
}): DocsSource;
export declare function createNodeDocsSource(rootAbs: string): Promise<DocsSource>;