@texuli/tools 0.0.0-stage → 0.1.0-next.0

package/dist/llms/format.js

@@ -0,0 +1,166 @@
+/** Stable path for a component doc: `components/<id>.md`. */
+export function componentDocPath(id) {
+    return `components/${id}.md`;
+}
+/** Link href for llms.txt (relative or absolute). */
+export function componentHref(id, baseUrl = '') {
+    const rel = componentDocPath(id);
+    if (!baseUrl)
+        return rel;
+    return `${baseUrl.replace(/\/$/, '')}/${rel}`;
+}
+function escapeMd(text) {
+    return text.replace(/\|/g, '\\|').replace(/\r\n/g, '\n');
+}
+function listBlock(title, items) {
+    if (items.length === 0)
+        return '';
+    const lines = items.map((item) => `- ${escapeMd(item)}`);
+    return `### ${title}\n\n${lines.join('\n')}\n`;
+}
+function propRow(prop) {
+    const req = prop.required ? 'yes' : 'no';
+    const kind = prop.kind === 'enum' && prop.enumValues?.length
+        ? `enum(${prop.enumValues.join(' | ')})`
+        : prop.kind;
+    const trust = prop.trust ? prop.trust : '—';
+    const def = prop.default === undefined ? '—' : `\`${JSON.stringify(prop.default)}\``.replace(/\|/g, '\\|');
+    const desc = prop.description ? escapeMd(prop.description) : '—';
+    return `| \`${prop.name}\` | ${kind} | ${req} | ${trust} | ${def} | ${desc} |`;
+}
+function exampleBlock(example) {
+    const props = JSON.stringify(example.props, null, 2);
+    const desc = example.description ? `\n\n${escapeMd(example.description)}` : '';
+    return `#### ${escapeMd(example.title)} (\`${example.id}\`)${desc}\n\n\`\`\`json\n${props}\n\`\`\`\n`;
+}
+/**
+ * Full Markdown page for one catalog entry (agent-facing).
+ * No HTML; plain Markdown only.
+ */
+export function formatComponentMarkdown(entry, options = {}) {
+    const emit = 'emit' in entry && Array.isArray(entry.emit)
+        ? entry.emit.join(', ')
+        : entry.agentEmittable
+            ? 'developer (agent-emittable)'
+            : 'not agent-emittable';
+    const group = 'group' in entry && typeof entry.group === 'string' ? entry.group : undefined;
+    const a11y = Array.isArray(entry.a11y) ? entry.a11y : entry.a11y ? [entry.a11y] : [];
+    const parts = [
+        `# ${escapeMd(entry.label)}\n`,
+        `> ${escapeMd(entry.summary)}\n`,
+        `- **id:** \`${entry.id}\``,
+        `- **package:** \`${entry.package}\``,
+        `- **tier:** \`${entry.tier}\``,
+        `- **agent emittable:** ${entry.agentEmittable === true ? 'yes' : 'no'}`,
+        `- **emit:** ${emit}`,
+    ];
+    if (group)
+        parts.push(`- **group:** \`${group}\``);
+    parts.push('');
+    parts.push(listBlock('Use when', entry.useWhen));
+    parts.push(listBlock("Don't use when", entry.dontUseWhen));
+    parts.push(listBlock('Accessibility', a11y));
+    if (entry.props.length > 0) {
+        parts.push('### Props\n');
+        parts.push('| Name | Kind | Required | Trust | Default | Description |');
+        parts.push('| --- | --- | --- | --- | --- | --- |');
+        for (const prop of entry.props)
+            parts.push(propRow(prop));
+        parts.push('');
+    }
+    if (entry.examples.length > 0) {
+        parts.push('### Examples\n');
+        for (const example of entry.examples)
+            parts.push(exampleBlock(example));
+    }
+    if (entry.related?.length) {
+        parts.push('### Related\n');
+        for (const id of entry.related) {
+            // A page under `components/` links its siblings directly; `llms-full.txt`
+            // sits at the root, beside `components/`.
+            const href = options.fromComponents && !options.baseUrl
+                ? `${id}.md`
+                : componentHref(id, options.baseUrl);
+            parts.push(`- [\`${id}\`](${href})`);
+        }
+        parts.push('');
+    }
+    parts.push('---\n', '_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._\n');
+    return parts.filter((p, i, arr) => !(p === '' && arr[i - 1] === '')).join('\n');
+}
+/** One llms.txt link line. */
+export function formatLlmsLink(entry, baseUrl = '') {
+    const href = componentHref(entry.id, baseUrl);
+    return `- [${entry.label}](${href}): ${entry.summary}`;
+}
+/**
+ * Compact `llms.txt` index (llmstxt.org-style).
+ * Sections: overview, agent-emittable (Tier U + developer), app chrome.
+ */
+export function formatLlmsTxt(entries, options = {}) {
+    const title = options.title ?? 'Texuli';
+    const summary = options.summary ??
+        'Texuli is a Svelte 5 component system with a closed agent catalog and a sink-free renderer.';
+    const baseUrl = options.baseUrl ?? '';
+    const split = options.splitTiers !== false;
+    const sorted = [...entries].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const emittable = sorted.filter((e) => e.agentEmittable === true);
+    const chrome = sorted.filter((e) => e.agentEmittable !== true);
+    const lines = [`# ${title}\n`, `> ${summary}\n`];
+    if (options.intro?.length) {
+        for (const para of options.intro)
+            lines.push(`${para}\n`);
+    }
+    lines.push('This file is generated from catalog manifests. Prefer component pages under `components/` for props and examples.\n');
+    if (split) {
+        lines.push('## Agent-emittable components\n');
+        lines.push('Ids agents may emit into a catalog tree (subject to tier rules). Untrusted model output is limited further by the catalog build tiers.\n');
+        if (emittable.length === 0)
+            lines.push('_None in this catalog._\n');
+        else
+            for (const entry of emittable)
+                lines.push(formatLlmsLink(entry, baseUrl));
+        lines.push('');
+        lines.push('## App and chrome components\n');
+        lines.push('Developer-authored UI. Not agent-emittable by default (overlays, forms, display chrome).\n');
+        if (chrome.length === 0)
+            lines.push('_None in this catalog._\n');
+        else
+            for (const entry of chrome)
+                lines.push(formatLlmsLink(entry, baseUrl));
+        lines.push('');
+    }
+    else {
+        lines.push('## Components\n');
+        for (const entry of sorted)
+            lines.push(formatLlmsLink(entry, baseUrl));
+        lines.push('');
+    }
+    lines.push('## Optional\n');
+    lines.push(`- [Full catalog docs](${baseUrl ? `${baseUrl.replace(/\/$/, '')}/` : ''}llms-full.txt)`);
+    lines.push('');
+    return `${lines
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim()}\n`;
+}
+/**
+ * `llms-full.txt`: every component Markdown page concatenated with clear separators.
+ */
+export function formatLlmsFullTxt(entries, options = {}) {
+    const title = options.title ?? 'Texuli';
+    const sorted = [...entries].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const parts = [
+        `# ${title} — full agent docs\n`,
+        `> Complete catalog documentation generated from manifests (${sorted.length} components).\n`,
+        '---\n',
+    ];
+    for (const entry of sorted) {
+        parts.push(formatComponentMarkdown(entry, { baseUrl: options.baseUrl }));
+        parts.push('\n---\n');
+    }
+    return `${parts
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim()}\n`;
+}

package/dist/llms/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@texuli/tools/llms` — generate `llms.txt`, `llms-full.txt` and per-component
+ * Markdown from Texuli catalog manifests (agent docs bundle).
+ */
+export { buildLlmsBundle } from './bundle.js';
+export { isMainModule, type LlmsCliArgs, parseLlmsArgs, runLlmsCli, } from './cli.js';
+export { componentDocPath, componentHref, formatComponentMarkdown, formatLlmsFullTxt, formatLlmsLink, formatLlmsTxt, } from './format.js';
+export type { LlmsBundle, LlmsBundleOptions, LlmsFile, LlmsWriteResult, } from './types.js';
+export { writeLlmsBundle } from './write.js';

package/dist/llms/index.js

@@ -0,0 +1,8 @@
+/**
+ * `@texuli/tools/llms` — generate `llms.txt`, `llms-full.txt` and per-component
+ * Markdown from Texuli catalog manifests (agent docs bundle).
+ */
+export { buildLlmsBundle } from "./bundle.js";
+export { isMainModule, parseLlmsArgs, runLlmsCli, } from "./cli.js";
+export { componentDocPath, componentHref, formatComponentMarkdown, formatLlmsFullTxt, formatLlmsLink, formatLlmsTxt, } from "./format.js";
+export { writeLlmsBundle } from "./write.js";

package/dist/llms/types.d.ts

@@ -0,0 +1,51 @@
+import type { Catalog, CatalogEntry } from '@texuli/catalog/build';
+import type { CatalogManifest } from '@texuli/catalog/manifest';
+/** One file in the agent docs bundle. */
+export interface LlmsFile {
+    /** Path relative to the output root, always POSIX (`llms.txt`, `components/card.md`). */
+    path: string;
+    /** UTF-8 text body (no BOM). */
+    body: string;
+}
+/** Options for building the llms.txt / agent-docs bundle from manifests. */
+export interface LlmsBundleOptions {
+    /**
+     * Built catalog (preferred) or a plain list of manifests.
+     * When manifests are passed, they are treated as developer-tier entries.
+     */
+    catalog?: Catalog;
+    manifests?: readonly CatalogManifest[];
+    /** Site / docs base URL for links (no trailing slash). Default empty (relative). */
+    baseUrl?: string;
+    /** Project title in llms.txt. Default `Texuli`. */
+    title?: string;
+    /** One-line project blurb. */
+    summary?: string;
+    /** Optional extra intro paragraphs under the title. */
+    intro?: readonly string[];
+    /**
+     * When true, only `agentEmittable` components appear in the untrusted
+     * section of llms.txt. Default true.
+     */
+    splitTiers?: boolean;
+}
+/** Full in-memory bundle. */
+export interface LlmsBundle {
+    /** Compact index (`llms.txt`). */
+    llmsTxt: string;
+    /** Full concatenated docs (`llms-full.txt`). */
+    llmsFullTxt: string;
+    /** Per-component Markdown files. */
+    components: readonly LlmsFile[];
+    /** Every file including the two roots, sorted by path. */
+    files: readonly LlmsFile[];
+    /** Entry count used to build the bundle. */
+    entryCount: number;
+}
+export type { Catalog, CatalogEntry, CatalogManifest };
+/** Write result when persisting the bundle. */
+export interface LlmsWriteResult {
+    outDir: string;
+    written: readonly string[];
+    dryRun: boolean;
+}

package/dist/llms/types.js

@@ -0,0 +1 @@
+export {};

package/dist/llms/write.d.ts

@@ -0,0 +1,14 @@
+import type { LlmsBundle, LlmsWriteResult } from './types.js';
+/**
+ * Write every file from a bundle under `outDir`.
+ *
+ * Containment (shared with `cli-add` via `../internal/paths.ts`):
+ * - `outDir` is resolved once
+ * - every bundle path is `path.resolve(outDir, file.path)`
+ * - paths that escape `outDir` (`escapesRoot`) are refused
+ * - `assertNoSymlinkOnPath` runs before each write so nothing is written
+ *   through a symlinked file or parent, including overwrite
+ */
+export declare function writeLlmsBundle(outDir: string, bundle: LlmsBundle, options?: {
+    dryRun?: boolean;
+}): Promise<LlmsWriteResult>;

package/dist/llms/write.js

@@ -0,0 +1,49 @@
+/// <reference types="node" />
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { assertNoSymlinkOnPath, escapesRoot } from "../internal/paths.js";
+/**
+ * Write every file from a bundle under `outDir`.
+ *
+ * Containment (shared with `cli-add` via `../internal/paths.ts`):
+ * - `outDir` is resolved once
+ * - every bundle path is `path.resolve(outDir, file.path)`
+ * - paths that escape `outDir` (`escapesRoot`) are refused
+ * - `assertNoSymlinkOnPath` runs before each write so nothing is written
+ *   through a symlinked file or parent, including overwrite
+ */
+export async function writeLlmsBundle(outDir, bundle, options = {}) {
+    const dryRun = options.dryRun === true;
+    const written = [];
+    const outResolved = resolve(outDir);
+    for (const file of bundle.files) {
+        if (file.path.includes('\0')) {
+            throw new Error(`Refusing unsafe bundle path: ${file.path}`);
+        }
+        if (isAbsolute(file.path) ||
+            /^[A-Za-z]:[\\/]/.test(file.path) ||
+            file.path.startsWith('\\\\')) {
+            throw new Error(`Refusing absolute bundle path: ${file.path}`);
+        }
+        const abs = resolve(outResolved, file.path);
+        if (escapesRoot(outResolved, abs)) {
+            throw new Error(`Refusing unsafe bundle path: ${file.path}`);
+        }
+        written.push(file.path);
+        if (dryRun)
+            continue;
+        // Before creating parents or writing: refuse symlink leaves and parents.
+        const before = assertNoSymlinkOnPath(abs, outResolved);
+        if (!before.ok) {
+            throw new Error(before.error);
+        }
+        await mkdir(dirname(abs), { recursive: true });
+        // Re-check after mkdir (parent may have been replaced / linked).
+        const after = assertNoSymlinkOnPath(abs, outResolved);
+        if (!after.ok) {
+            throw new Error(after.error);
+        }
+        await writeFile(abs, file.body, 'utf8');
+    }
+    return { outDir: outResolved, written, dryRun };
+}

package/dist/mcp/index.d.ts

@@ -0,0 +1,2 @@
+export { createTexuliMcpServer, MCP_PROTOCOL_VERSION } from './server.js';
+export { runMcpStdio } from './stdio.js';

package/dist/mcp/index.js

@@ -0,0 +1,2 @@
+export { createTexuliMcpServer, MCP_PROTOCOL_VERSION } from "./server.js";
+export { runMcpStdio } from "./stdio.js";

package/dist/mcp/server.d.ts

@@ -0,0 +1,20 @@
+type JsonObject = Record<string, unknown>;
+type JsonRpcId = string | number;
+type JsonRpcError = {
+    code: number;
+    message: string;
+    data?: unknown;
+};
+type JsonRpcResponse = {
+    jsonrpc: '2.0';
+    id: JsonRpcId | null;
+    result: JsonObject;
+} | {
+    jsonrpc: '2.0';
+    id: JsonRpcId | null;
+    error: JsonRpcError;
+};
+/** Create the request handler for a local, read-only MCP server. */
+export declare function createTexuliMcpServer(): (message: unknown) => Promise<JsonRpcResponse | undefined>;
+export declare const MCP_PROTOCOL_VERSION = "2025-11-25";
+export {};

package/dist/mcp/server.js

@@ -0,0 +1,326 @@
+import { buildCatalog } from '@texuli/catalog/build';
+import { discoverManifestGroups } from '@texuli/catalog/build/node';
+import { validateCatalogManifest, validateCatalogManifests } from '@texuli/catalog/manifest';
+import { getFullThemeLibraryMeta, listFullThemeLibrary, loadFullLibraryTheme, } from '@texuli/tokens/library-expand';
+const PROTOCOL_VERSION = '2025-11-25';
+const SERVER_VERSION = '0.0.0';
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 100;
+const SUPPORTED_PROTOCOL_VERSIONS = new Set([
+    '2024-11-05',
+    '2025-03-26',
+    '2025-06-18',
+    PROTOCOL_VERSION,
+]);
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function stringArg(args, name, required = false) {
+    const value = args[name];
+    if (value === undefined && !required)
+        return undefined;
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new TypeError(`"${name}" must be a non-empty string${required ? '' : ' when provided'}.`);
+    }
+    return value.trim();
+}
+function limitArg(args) {
+    const value = args.limit;
+    if (value === undefined)
+        return DEFAULT_LIMIT;
+    if (!Number.isInteger(value) || value < 1 || value > MAX_LIMIT) {
+        throw new TypeError(`"limit" must be an integer from 1 to ${MAX_LIMIT}.`);
+    }
+    return value;
+}
+function rejectUnknownArgs(args, allowed) {
+    const unknown = Object.keys(args).filter((key) => !allowed.includes(key));
+    if (unknown.length > 0) {
+        throw new TypeError(`Unknown argument${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}.`);
+    }
+}
+function textResult(value, isError = false) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(value) }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+const COMMON_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: false,
+};
+const TOOLS = [
+    {
+        name: 'catalog',
+        description: 'Search the built, content-addressed Texuli component catalog.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Text to match against component ids, labels and summaries.',
+                },
+                group: { type: 'string', description: 'Exact manifest group id.' },
+                tier: { type: 'string', enum: ['developer', 'untrusted'] },
+                limit: { type: 'integer', minimum: 1, maximum: MAX_LIMIT },
+            },
+            additionalProperties: false,
+        },
+        annotations: COMMON_ANNOTATIONS,
+    },
+    {
+        name: 'component',
+        description: 'Read one component manifest, including props, examples and allowed emit tiers.',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string', minLength: 1 } },
+            required: ['id'],
+            additionalProperties: false,
+        },
+        annotations: COMMON_ANNOTATIONS,
+    },
+    {
+        name: 'validate',
+        description: 'Validate one catalog manifest or a list of manifests without writing files.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                manifest: { type: 'object', description: 'One candidate manifest.' },
+                manifests: {
+                    type: 'array',
+                    items: { type: 'object' },
+                    description: 'A candidate manifest set.',
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: COMMON_ANNOTATIONS,
+    },
+    {
+        name: 'example',
+        description: 'Find manifest examples by component and/or example id, or search their titles.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                componentId: { type: 'string', minLength: 1 },
+                exampleId: { type: 'string', minLength: 1 },
+                query: { type: 'string' },
+                limit: { type: 'integer', minimum: 1, maximum: MAX_LIMIT },
+            },
+            additionalProperties: false,
+        },
+        annotations: COMMON_ANNOTATIONS,
+    },
+    {
+        name: 'theme',
+        description: 'Search theme metadata or read the full token definition for one theme id.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', minLength: 1 },
+                query: { type: 'string' },
+                category: { type: 'string' },
+                collection: { type: 'string' },
+                mood: { type: 'string' },
+                tag: { type: 'string' },
+                limit: { type: 'integer', minimum: 1, maximum: MAX_LIMIT },
+            },
+            additionalProperties: false,
+        },
+        annotations: COMMON_ANNOTATIONS,
+    },
+];
+function validId(id) {
+    return typeof id === 'string' || (typeof id === 'number' && Number.isFinite(id));
+}
+function response(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+function errorResponse(id, code, message) {
+    return { jsonrpc: '2.0', id, error: { code, message } };
+}
+/** Create the request handler for a local, read-only MCP server. */
+export function createTexuliMcpServer() {
+    let catalogPromise;
+    let initialized = false;
+    let initializeReceived = false;
+    const getCatalog = () => {
+        catalogPromise ??= discoverManifestGroups().then(buildCatalog);
+        return catalogPromise;
+    };
+    async function callTool(name, rawArgs) {
+        if (!isObject(rawArgs))
+            throw new TypeError('Tool arguments must be an object.');
+        const args = rawArgs;
+        if (name === 'catalog') {
+            rejectUnknownArgs(args, ['query', 'group', 'tier', 'limit']);
+            const query = stringArg(args, 'query')?.toLowerCase();
+            const group = stringArg(args, 'group');
+            const tier = stringArg(args, 'tier');
+            const limit = limitArg(args);
+            if (tier !== undefined && tier !== 'developer' && tier !== 'untrusted') {
+                throw new TypeError('"tier" must be "developer" or "untrusted".');
+            }
+            const built = await getCatalog();
+            const filtered = built.catalog.entries.filter((entry) => {
+                if (group && entry.group !== group)
+                    return false;
+                if (tier && !entry.emit.includes(tier))
+                    return false;
+                if (query && !`${entry.id} ${entry.label} ${entry.summary}`.toLowerCase().includes(query)) {
+                    return false;
+                }
+                return true;
+            });
+            return {
+                hash: built.hash,
+                fileName: built.fileName,
+                total: filtered.length,
+                entries: filtered
+                    .slice(0, limit)
+                    .map(({ id, package: packageName, label, summary, tier: componentTier, group: groupName, emit, }) => ({
+                    id,
+                    package: packageName,
+                    label,
+                    summary,
+                    tier: componentTier,
+                    group: groupName,
+                    emit,
+                })),
+                limit,
+            };
+        }
+        if (name === 'component') {
+            rejectUnknownArgs(args, ['id']);
+            const id = stringArg(args, 'id', true);
+            const entry = (await getCatalog()).catalog.entries.find((item) => item.id === id);
+            if (!entry)
+                throw new TypeError(`Unknown component "${id}". Search with the catalog tool first.`);
+            return { component: entry };
+        }
+        if (name === 'validate') {
+            rejectUnknownArgs(args, ['manifest', 'manifests']);
+            const hasManifest = Object.hasOwn(args, 'manifest');
+            const hasManifests = Object.hasOwn(args, 'manifests');
+            if (hasManifest === hasManifests) {
+                throw new TypeError('Provide exactly one of "manifest" or "manifests".');
+            }
+            if (hasManifest)
+                return validateCatalogManifest(args.manifest);
+            if (!Array.isArray(args.manifests))
+                throw new TypeError('"manifests" must be an array.');
+            return validateCatalogManifests(args.manifests);
+        }
+        if (name === 'example') {
+            rejectUnknownArgs(args, ['componentId', 'exampleId', 'query', 'limit']);
+            const componentId = stringArg(args, 'componentId');
+            const exampleId = stringArg(args, 'exampleId');
+            const query = stringArg(args, 'query')?.toLowerCase();
+            const limit = limitArg(args);
+            const entries = (await getCatalog()).catalog.entries;
+            const component = componentId ? entries.find((entry) => entry.id === componentId) : undefined;
+            if (componentId && !component) {
+                throw new TypeError(`Unknown component "${componentId}". Search with the catalog tool first.`);
+            }
+            const examples = (component ? [component] : entries).flatMap((entry) => entry.examples
+                .filter((example) => !exampleId || example.id === exampleId)
+                .filter((example) => !query ||
+                `${example.id} ${example.title} ${example.description ?? ''}`
+                    .toLowerCase()
+                    .includes(query))
+                .map((example) => ({ componentId: entry.id, package: entry.package, example })));
+            return { total: examples.length, examples: examples.slice(0, limit), limit };
+        }
+        if (name === 'theme') {
+            rejectUnknownArgs(args, ['id', 'query', 'category', 'collection', 'mood', 'tag', 'limit']);
+            const id = stringArg(args, 'id');
+            const limit = limitArg(args);
+            if (id) {
+                const themes = await getFullThemeLibraryMeta();
+                if (!themes.some((theme) => theme.id === id))
+                    throw new TypeError(`Unknown theme "${id}".`);
+                return { theme: await loadFullLibraryTheme(id) };
+            }
+            const query = stringArg(args, 'query')?.toLowerCase();
+            const collection = stringArg(args, 'collection');
+            const mood = stringArg(args, 'mood');
+            const matches = (await listFullThemeLibrary({
+                category: stringArg(args, 'category'),
+                tag: stringArg(args, 'tag'),
+            })).filter((theme) => {
+                if (collection && theme.collection !== collection)
+                    return false;
+                if (mood && !theme.mood.includes(mood))
+                    return false;
+                if (query &&
+                    !`${theme.id} ${theme.name} ${theme.description} ${theme.category} ${theme.tags.join(' ')}`
+                        .toLowerCase()
+                        .includes(query)) {
+                    return false;
+                }
+                return true;
+            });
+            return { total: matches.length, themes: matches.slice(0, limit), limit };
+        }
+        throw new Error(`Unknown tool: ${name}`);
+    }
+    return async (message) => {
+        if (!isObject(message) || message.jsonrpc !== '2.0' || typeof message.method !== 'string') {
+            const id = isObject(message) && validId(message.id) ? message.id : null;
+            return errorResponse(id, -32600, 'Invalid Request');
+        }
+        const hasId = Object.hasOwn(message, 'id');
+        const id = validId(message.id) ? message.id : null;
+        if (hasId && id === null)
+            return errorResponse(null, -32600, 'Invalid Request');
+        if (!hasId) {
+            if (message.method === 'notifications/initialized')
+                initialized = initializeReceived;
+            return undefined;
+        }
+        if (message.method === 'initialize') {
+            const params = message.params;
+            if (!isObject(params) || typeof params.protocolVersion !== 'string') {
+                return errorResponse(id, -32602, 'initialize requires params.protocolVersion.');
+            }
+            const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.has(params.protocolVersion)
+                ? params.protocolVersion
+                : PROTOCOL_VERSION;
+            initializeReceived = true;
+            initialized = false;
+            return response(id, {
+                protocolVersion,
+                capabilities: { tools: { listChanged: false } },
+                serverInfo: { name: 'texuli', version: SERVER_VERSION },
+                instructions: 'Read-only catalog, component, validation, example and theme tools. No files or network are modified.',
+            });
+        }
+        if (message.method === 'ping')
+            return response(id, {});
+        if (!initialized)
+            return errorResponse(id, -32002, 'Server not initialized.');
+        if (message.method === 'tools/list') {
+            return response(id, { tools: TOOLS });
+        }
+        if (message.method === 'tools/call') {
+            const params = message.params;
+            if (!isObject(params) || typeof params.name !== 'string') {
+                return errorResponse(id, -32602, 'tools/call requires params.name.');
+            }
+            const toolName = params.name;
+            const tool = TOOLS.find((item) => item.name === toolName);
+            if (!tool)
+                return errorResponse(id, -32602, `Unknown tool: ${toolName}`);
+            try {
+                const data = await callTool(tool.name, params.arguments ?? {});
+                return response(id, textResult(data));
+            }
+            catch (error) {
+                return response(id, textResult({ error: error instanceof Error ? error.message : 'Tool failed.' }, true));
+            }
+        }
+        return errorResponse(id, -32601, `Method not found: ${message.method}`);
+    };
+}
+export const MCP_PROTOCOL_VERSION = PROTOCOL_VERSION;

package/dist/mcp/stdio.d.ts

@@ -0,0 +1,3 @@
+import type { Readable, Writable } from 'node:stream';
+/** Run the MCP newline-delimited JSON-RPC transport over the supplied streams. */
+export declare function runMcpStdio(input?: Readable, output?: Writable): Promise<void>;