@dnb/eufemia
Version:
DNB Eufemia Design System UI Library
58 lines (57 loc) • 2.23 kB
TypeScript
/**
* 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>;