@vielzeug/codex 2.3.2 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @vielzeug/codex
 
-MCP server for Vielzeug package metadata, documentation, public source, REPL examples, and Refine component data.
+> MCP server exposing all Vielzeug docs to AI clients
 
 ## Install and run
 
@@ -11,71 +11,25 @@ npx -y @vielzeug/codex --port=3100
 
 Stdio is default. HTTP uses Streamable HTTP on `127.0.0.1`; health endpoint: `http://127.0.0.1:3100/health`.
 
-`mcp-setup.json` ships a machine-readable generic stdio/HTTP setup manifest:
-
-```json
-{
-  "command": "npx",
-  "args": ["-y", "@vielzeug/codex"]
-}
-```
-
-## Local development
-
-Node 22+ and root workspace setup required:
-
-```sh
-pnpm setup
-cd packages/codex
-pnpm test:unit
-pnpm test:integration
-pnpm dev
-```
-
-`pnpm dev` regenerates an atomic chunked snapshot whenever docs or package inputs change. Use `--debug` to log tool timings and expected failures.
-
-## Programmatic API
+## Quick Start
 
 ```ts
-import { SnapshotCatalog, createMcpServer, loadSnapshot } from '@vielzeug/codex';
-import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { SnapshotCatalog, StdioServerTransport, createMcpServer, loadSnapshot } from '@vielzeug/codex';
 
 const snapshot = loadSnapshot();
 const catalog = new SnapshotCatalog(snapshot);
 await createMcpServer(catalog, { version: snapshot.manifest.version }).connect(new StdioServerTransport());
 ```
 
-## Tools
-
-<!-- TOOLS:GENERIC:START -->
-| Tool | Input | Description |
-| --- | --- | --- |
-| `list-packages` | — | List every Vielzeug package. |
-| `get-package` | `packageSlug` | Read metadata for one package. |
-| `get-docs` | `packageSlug`, `page?` | Read one documentation page as Markdown. |
-| `get-source` | `packageSlug` | Read bundled public source for one package. |
-| `list-examples` | `packageSlug` | List runnable REPL examples for one package. |
-| `get-example` | `exampleId`, `packageSlug` | Read one runnable REPL example. |
-| `search-packages` | `query` | Search package metadata, docs, examples, and source. |
-| `get-type-signature` | `slug`, `symbol` | Read one exported TypeScript declaration. |
-<!-- TOOLS:GENERIC:END -->
-
-<!-- TOOLS:REFINE:START -->
-| Tool | Input | Description |
-| --- | --- | --- |
-| `refine-list-components` | — | List bundled Refine web components. |
-| `refine-get-component` | `tagName` | Read one Refine component declaration. |
-| `refine-generate-template` | `scenario?`, `tagName` | Generate a minimal Refine component HTML template. |
-| `refine-get-tokens` | `filter?` | List bundled Refine CSS custom properties. |
-| `refine-validate-usage` | `html`, `tagName` | Validate unknown attributes in one Refine component HTML fragment. |
-<!-- TOOLS:REFINE:END -->
-
-## Snapshot layout
+## Documentation
 
-Published `data/` contains one static snapshot: `manifest.json`, lightweight `catalog.json` and `search.json`, optional `refine.json`, and lazy package chunks under `packages/`. Local `pnpm dev` snapshots live under ignored `.dev/` and use `current.json` to select an immutable generation. Pass `--snapshot=<directory>` to load either form.
+- [Overview](https://vielzeug.dev/codex/)
+- [Usage Guide](https://vielzeug.dev/codex/usage)
+- [API Reference](https://vielzeug.dev/codex/api)
+- [Examples](https://vielzeug.dev/codex/examples)
+- [MCP Tools](https://vielzeug.dev/codex/tools)
+- [Migration Guide](https://vielzeug.dev/codex/migration)
 
-## Documentation
+## License
 
-- https://vielzeug.dev/codex/
-- https://vielzeug.dev/codex/usage
-- https://vielzeug.dev/codex/api
+MIT © [Helmuth Saatkamp](https://github.com/helmuthdu) — part of the [Vielzeug](https://github.com/helmuthdu/vielzeug) monorepo.

package/dist/_log.d.ts

@@ -0,0 +1,2 @@
+/** Single stderr I/O path for all runtime output in src/. Mockable in tests. */
+export declare function log(message: string): void;

package/dist/advanced.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@vielzeug/codex/advanced` — snapshot parser internals.
+ *
+ * The main entry (`@vielzeug/codex`) keeps the supported catalog, loader, and server
+ * contracts. These pure validation parsers and raw snapshot types
+ * are the smaller, less stable contract used by generators and integration tests —
+ * import them explicitly from this subpath when you need to parse individual snapshot
+ * chunks rather than loading a whole validated snapshot.
+ */
+export { CodexError } from './errors.js';
+export { type LoadedSnapshot, loadSnapshotDirectory, parseCatalog, parseContent, parseManifest, parsePointer, parseRefine, parseSearch, validateSnapshot, } from './snapshot.js';
+export { type CatalogFile, DOC_PAGES, type SearchRecord, SNAPSHOT_SCHEMA_VERSION, type SnapshotPointer, } from './types.js';

package/dist/advanced.js

@@ -0,0 +1,13 @@
+/**
+ * `@vielzeug/codex/advanced` — snapshot parser internals.
+ *
+ * The main entry (`@vielzeug/codex`) keeps the supported catalog, loader, and server
+ * contracts. These pure validation parsers and raw snapshot types
+ * are the smaller, less stable contract used by generators and integration tests —
+ * import them explicitly from this subpath when you need to parse individual snapshot
+ * chunks rather than loading a whole validated snapshot.
+ */
+export { CodexError } from './errors.js';
+export { loadSnapshotDirectory, parseCatalog, parseContent, parseManifest, parsePointer, parseRefine, parseSearch, validateSnapshot, } from './snapshot.js';
+export { DOC_PAGES, SNAPSHOT_SCHEMA_VERSION, } from './types.js';
+//# sourceMappingURL=advanced.js.map

package/dist/advanced.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced.js","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAEL,qBAAqB,EACrB,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACX,WAAW,EACX,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,SAAS,EAET,uBAAuB,GAExB,MAAM,YAAY,CAAC"}

package/dist/catalog.d.ts

@@ -0,0 +1,41 @@
+import { CodexError } from './errors.js';
+import { type LoadedSnapshot } from './snapshot.js';
+import type { DocPage, Example, PackageContent, PackageMeta } from './types.js';
+export type CatalogErrorCode = 'INVALID_ARG' | 'NOT_FOUND' | 'UNAVAILABLE';
+export declare class CatalogError extends CodexError {
+    readonly code: CatalogErrorCode;
+    constructor(code: CatalogErrorCode, message: string);
+}
+export interface SearchHit {
+    matchedExamples?: string[];
+    matchedIn: Array<'docs' | 'examples' | 'exports' | 'keywords' | 'metadata' | 'related' | 'source'>;
+    matchedPages?: DocPage[];
+    name: string;
+    slug: string;
+}
+export interface Catalog {
+    getContent(slug: string): PackageContent;
+    getDocs(slug: string, page: DocPage): string;
+    getExample(slug: string, exampleId: string): Example;
+    getPackage(slug: string): PackageMeta;
+    getSource(slug: string): string;
+    getTypeSignature(slug: string, symbol: string): string;
+    listExamples(slug: string): Array<Pick<Example, 'id' | 'name'>>;
+    listPackages(): PackageMeta[];
+    search(query: string): SearchHit[];
+}
+export declare class SnapshotCatalog implements Catalog {
+    private readonly bySlug;
+    private readonly contentCache;
+    private readonly snapshot;
+    constructor(snapshot: LoadedSnapshot);
+    getPackage(slug: string): PackageMeta;
+    getContent(slug: string): PackageContent;
+    listPackages(): PackageMeta[];
+    getDocs(slug: string, page: DocPage): string;
+    getSource(slug: string): string;
+    listExamples(slug: string): Array<Pick<Example, 'id' | 'name'>>;
+    getExample(slug: string, exampleId: string): Example;
+    getTypeSignature(slug: string, symbol: string): string;
+    search(query: string): SearchHit[];
+}

package/dist/catalog.js

@@ -64,13 +64,11 @@ function searchRecord(record, query) {
 }
 export class SnapshotCatalog {
     bySlug;
-    componentsByTag;
     contentCache = new Map();
     snapshot;
     constructor(snapshot) {
         this.snapshot = snapshot;
         this.bySlug = new Map(snapshot.catalog.packages.map((pkg) => [pkg.slug, pkg]));
-        this.componentsByTag = new Map(snapshot.refineComponents.flatMap((component) => component.tagName ? [[component.tagName, component]] : []));
     }
     getPackage(slug) {
         const pkg = this.bySlug.get(slug);
@@ -133,17 +131,5 @@ export class SnapshotCatalog {
             .sort((left, right) => left.tier - right.tier || left.hit.slug.localeCompare(right.hit.slug))
             .map((result) => result.hit);
     }
-    listComponents() {
-        if (this.snapshot.refineComponents.length === 0)
-            throw new CatalogError('UNAVAILABLE', 'Refine component metadata is unavailable in this snapshot.');
-        return this.snapshot.refineComponents;
-    }
-    getComponent(tagName) {
-        this.listComponents();
-        const component = this.componentsByTag.get(tagName);
-        if (!component)
-            throw new CatalogError('NOT_FOUND', `Component "${tagName}" not found.`);
-        return component;
-    }
 }
 //# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: readonly string[]): Promise<number>;

package/dist/cli.js

@@ -5,11 +5,12 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parseArgs } from 'node:util';
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import { log } from './_log.js';
-import { SnapshotCatalog } from './catalog.js';
 import { startHttpHost } from './http.js';
 import { resolvePort } from './port.js';
+import { SnapshotRefineCatalog } from './refine-catalog.js';
 import { createMcpServer } from './server.js';
 import { loadSnapshot } from './snapshot.js';
+import { registerRefineTools } from './tools/refine.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 function usage() {
     log([
@@ -41,16 +42,28 @@ export async function main(argv = process.argv.slice(2)) {
             strict: true,
         }));
         const snapshot = loadSnapshot(values.snapshot);
-        const catalog = new SnapshotCatalog(snapshot);
+        const catalog = new SnapshotRefineCatalog(snapshot);
         const port = resolvePort(values.port);
+        const configure = (server) => registerRefineTools(server, catalog, values.debug);
         if (port === null) {
-            await createMcpServer(catalog, { debug: values.debug, version: snapshot.manifest.version }).connect(new StdioServerTransport());
+            const server = createMcpServer(catalog, { debug: values.debug, version: snapshot.manifest.version });
+            configure(server);
+            await server.connect(new StdioServerTransport());
             return 0;
         }
-        const host = await startHttpHost({ catalog, debug: values.debug, port, version: snapshot.manifest.version });
+        const host = await startHttpHost({
+            catalog,
+            configureServer: configure,
+            debug: values.debug,
+            port,
+            version: snapshot.manifest.version,
+        });
         const shutdown = () => {
             void host.dispose().then(() => {
                 process.exitCode = 0;
+            }, (error) => {
+                log(`error: failed to shut down HTTP host: ${error instanceof Error ? error.message : String(error)}`);
+                process.exitCode = 1;
             });
         };
         process.once('SIGINT', shutdown);

package/dist/cli.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,4 @@
+/** Base class for all codex errors. Use `instanceof CodexError` to catch any codex-originated error. */
+export declare class CodexError extends Error {
+    constructor(message: string, opts?: ErrorOptions);
+}

package/dist/http.d.ts

@@ -0,0 +1,21 @@
+import { type Server } from '@modelcontextprotocol/server';
+import type { Catalog } from './catalog.js';
+export interface HttpHost {
+    readonly disposalSignal: AbortSignal;
+    dispose(): Promise<void>;
+    readonly disposed: boolean;
+    readonly host: string;
+    readonly port: number;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export interface HttpHostOptions {
+    catalog: Catalog;
+    /** Optional hook invoked after generic tools are registered (e.g. to register Refine tools). */
+    configureServer?: (server: Server) => void;
+    debug?: boolean;
+    host?: '127.0.0.1' | '::1';
+    port: number;
+    version: string;
+}
+/** Streamable HTTP host owns every transport and only listens on loopback addresses. */
+export declare function startHttpHost(options: HttpHostOptions): Promise<HttpHost>;

package/dist/http.js

@@ -1,8 +1,9 @@
 import { createServer } from 'node:http';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
-import { createMcpHandler } from '@modelcontextprotocol/server';
+import { createMcpHandler, hostHeaderValidationResponse, localhostAllowedHostnames, localhostAllowedOrigins, originValidationResponse, } from '@modelcontextprotocol/server';
 import { log } from './_log.js';
+import { CodexError } from './errors.js';
 import { createMcpServer } from './server.js';
 function close(server) {
     return new Promise((resolve, reject) => {
@@ -27,7 +28,8 @@ function toWebRequest(request) {
             headers.set(key, value);
     }
     const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
-    return new Request(`http://${request.headers.host ?? 'localhost'}${request.url}`, {
+    const path = request.url?.startsWith('/') ? request.url : '/';
+    return new Request(`http://localhost${path}`, {
         ...(hasBody && { body: Readable.toWeb(request), duplex: 'half' }),
         headers,
         method: request.method,
@@ -47,24 +49,41 @@ async function sendWebResponse(webResponse, response) {
 /** Streamable HTTP host owns every transport and only listens on loopback addresses. */
 export async function startHttpHost(options) {
     const host = options.host ?? '127.0.0.1';
+    if (host !== '127.0.0.1' && host !== '::1') {
+        throw new CodexError('HTTP host must be a loopback address (127.0.0.1 or ::1).');
+    }
     // Stateless by default (SEP-2575): a fresh server instance per request, matching the
     // spec's "any request can land on any instance" design — codex's tools carry no
     // per-connection state, so a persistent instance buys nothing beyond a small, negligible
     // (13-tool catalog) reconstruction cost per request.
-    const factory = () => createMcpServer(options.catalog, { debug: options.debug, version: options.version });
-    // `createMcpHandler()`'s factory only runs lazily, on the first real request — call it once
-    // eagerly here so a broken catalog/registration setup fails `startHttpHost()` itself, before
-    // the port opens, matching the old eager `mcpServer.connect()` fail-fast guarantee.
-    factory();
+    const factory = () => {
+        const server = createMcpServer(options.catalog, { debug: options.debug, version: options.version });
+        options.configureServer?.(server);
+        return server;
+    };
+    // `createMcpHandler()` creates and configures one fresh server per MCP request.
     const handler = createMcpHandler(factory);
+    const allowedHosts = localhostAllowedHostnames();
+    const allowedOrigins = localhostAllowedOrigins();
     const httpServer = createServer((request, response) => {
+        const webRequest = toWebRequest(request);
+        const rejected = hostHeaderValidationResponse(webRequest, allowedHosts) ?? originValidationResponse(webRequest, allowedOrigins);
+        if (rejected) {
+            request.resume();
+            void sendWebResponse(rejected, response).catch((error) => {
+                if (!response.writableEnded)
+                    response.end();
+                log(`HTTP validation response error: ${error instanceof Error ? error.message : String(error)}`);
+            });
+            return;
+        }
         if (request.method === 'GET' && request.url === '/health') {
             response.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
             response.end(JSON.stringify({ status: 'ok', version: options.version }));
             return;
         }
         handler
-            .fetch(toWebRequest(request))
+            .fetch(webRequest)
             .then((webResponse) => sendWebResponse(webResponse, response))
             .catch((error) => {
             if (!response.headersSent) {
@@ -76,19 +95,39 @@ export async function startHttpHost(options) {
             log(`HTTP MCP error: ${error instanceof Error ? error.message : String(error)}`);
         });
     });
+    const disposal = new AbortController();
     let listening = false;
     let disposed = false;
-    const dispose = async () => {
+    let disposing;
+    const dispose = () => {
         if (disposed)
-            return;
-        disposed = true;
-        try {
-            if (listening)
-                await close(httpServer);
-        }
-        finally {
-            await handler.close();
-        }
+            return Promise.resolve();
+        if (disposing)
+            return disposing;
+        disposing = (async () => {
+            const errors = [];
+            try {
+                if (listening)
+                    await close(httpServer);
+                listening = false;
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            try {
+                await handler.close();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            if (errors.length > 0)
+                throw new AggregateError(errors, 'Failed to dispose Codex HTTP host');
+            disposed = true;
+            disposal.abort();
+        })().finally(() => {
+            disposing = undefined;
+        });
+        return disposing;
     };
     try {
         await new Promise((resolve, reject) => {
@@ -107,6 +146,17 @@ export async function startHttpHost(options) {
     const address = httpServer.address();
     const port = address && typeof address === 'object' ? address.port : options.port;
     log(`codex MCP HTTP host listening on http://${host}:${port}/`);
-    return { dispose, host, port, [Symbol.asyncDispose]: dispose };
+    return {
+        get disposalSignal() {
+            return disposal.signal;
+        },
+        dispose,
+        get disposed() {
+            return disposed;
+        },
+        host,
+        port,
+        [Symbol.asyncDispose]: dispose,
+    };
 }
 //# sourceMappingURL=http.js.map

package/dist/http.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@vielzeug/codex` — supported public contract.
+ *
+ * Exposes the generic catalog, snapshot loader, errors, and server hosts. Snapshot
+ * parser internals live behind `@vielzeug/codex/advanced`; Refine catalog types and
+ * tools live behind `@vielzeug/codex/refine`.
+ */
+export { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+export { type Catalog, CatalogError, type SearchHit, SnapshotCatalog } from './catalog.js';
+export { CodexError } from './errors.js';
+export { type HttpHost, type HttpHostOptions, startHttpHost } from './http.js';
+export { createMcpServer } from './server.js';
+export { type LoadedSnapshot, loadSnapshot } from './snapshot.js';
+export type { DocPage, Example, PackageContent, PackageMeta, SnapshotManifest, } from './types.js';

package/dist/index.js

@@ -1,7 +1,14 @@
+/**
+ * `@vielzeug/codex` — supported public contract.
+ *
+ * Exposes the generic catalog, snapshot loader, errors, and server hosts. Snapshot
+ * parser internals live behind `@vielzeug/codex/advanced`; Refine catalog types and
+ * tools live behind `@vielzeug/codex/refine`.
+ */
+export { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 export { CatalogError, SnapshotCatalog } from './catalog.js';
 export { CodexError } from './errors.js';
 export { startHttpHost } from './http.js';
 export { createMcpServer } from './server.js';
-export { loadSnapshot, parseCatalog, parseContent, parseManifest, parsePointer, parseSearch, validateSnapshot, } from './snapshot.js';
-export { DOC_PAGES, SNAPSHOT_SCHEMA_VERSION, } from './types.js';
+export { loadSnapshot } from './snapshot.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,YAAY,EAAkB,eAAe,EAAE,MAAM,cAAc,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAuC,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAQL,SAAS,EAKT,uBAAuB,GAGxB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAgB,YAAY,EAAkB,eAAe,EAAE,MAAM,cAAc,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAuC,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAuB,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/port.d.ts

@@ -0,0 +1,2 @@
+/** Parses and validates a --port CLI argument. Returns the port number or null if omitted. */
+export declare function resolvePort(raw: string | undefined): number | null;

package/dist/refine-catalog.d.ts

@@ -0,0 +1,14 @@
+import { type Catalog, SnapshotCatalog } from './catalog.js';
+import type { LoadedSnapshot } from './snapshot.js';
+import type { CemDeclaration } from './types.js';
+export interface RefineCatalog extends Catalog {
+    getComponent(tagName: string): CemDeclaration;
+    listComponents(): CemDeclaration[];
+}
+export declare class SnapshotRefineCatalog extends SnapshotCatalog implements RefineCatalog {
+    private readonly components;
+    private readonly componentsByTag;
+    constructor(snapshot: LoadedSnapshot);
+    listComponents(): CemDeclaration[];
+    getComponent(tagName: string): CemDeclaration;
+}

package/dist/refine-catalog.js

@@ -0,0 +1,24 @@
+import { CatalogError, SnapshotCatalog } from './catalog.js';
+export class SnapshotRefineCatalog extends SnapshotCatalog {
+    components;
+    componentsByTag;
+    constructor(snapshot) {
+        super(snapshot);
+        this.components = snapshot.refineComponents;
+        this.componentsByTag = new Map(this.components.flatMap((component) => (component.tagName ? [[component.tagName, component]] : [])));
+    }
+    listComponents() {
+        if (this.components.length === 0) {
+            throw new CatalogError('UNAVAILABLE', 'Refine component metadata is unavailable in this snapshot.');
+        }
+        return [...this.components];
+    }
+    getComponent(tagName) {
+        this.listComponents();
+        const component = this.componentsByTag.get(tagName);
+        if (!component)
+            throw new CatalogError('NOT_FOUND', `Component "${tagName}" not found.`);
+        return component;
+    }
+}
+//# sourceMappingURL=refine-catalog.js.map

package/dist/refine-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refine-catalog.js","sourceRoot":"","sources":["../src/refine-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAS3E,MAAM,OAAO,qBAAsB,SAAQ,eAAe;IACvC,UAAU,CAAmB;IAC7B,eAAe,CAA8B;IAE9D,YAAY,QAAwB;QAClC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChB,IAAI,CAAC,UAAU,GAAG,QAAQ,CAAC,gBAAgB,CAAC;QAC5C,IAAI,CAAC,eAAe,GAAG,IAAI,GAAG,CAC5B,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,SAAS,CAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAC7G,CAAC;IACJ,CAAC;IAED,cAAc;QACZ,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,YAAY,CAAC,aAAa,EAAE,4DAA4D,CAAC,CAAC;QACtG,CAAC;QAED,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;IAED,YAAY,CAAC,OAAe;QAC1B,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAEpD,IAAI,CAAC,SAAS;YAAE,MAAM,IAAI,YAAY,CAAC,WAAW,EAAE,cAAc,OAAO,cAAc,CAAC,CAAC;QACzF,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}

package/dist/refine.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@vielzeug/codex/refine` — opt-in Refine component tools.
+ *
+ * The main entry (`@vielzeug/codex`) registers only generic, product-agnostic package
+ * tools. Refine-specific tools (`refine-*`) live here behind a subpath so the core
+ * documentation server stays reusable without Refine. Call `registerRefineTools()` on
+ * a server created by `createMcpServer()` to upgrade it to the full Refine-augmented
+ * tool surface.
+ */
+export { type RefineCatalog, SnapshotRefineCatalog } from './refine-catalog.js';
+export { refineTools, registerRefineTools } from './tools/refine.js';
+export type { CemAttribute, CemCssPart, CemCssProperty, CemDeclaration, CemEvent, CemMember, CemSlot, } from './types.js';

package/dist/refine.js

@@ -0,0 +1,12 @@
+/**
+ * `@vielzeug/codex/refine` — opt-in Refine component tools.
+ *
+ * The main entry (`@vielzeug/codex`) registers only generic, product-agnostic package
+ * tools. Refine-specific tools (`refine-*`) live here behind a subpath so the core
+ * documentation server stays reusable without Refine. Call `registerRefineTools()` on
+ * a server created by `createMcpServer()` to upgrade it to the full Refine-augmented
+ * tool surface.
+ */
+export { SnapshotRefineCatalog } from './refine-catalog.js';
+export { refineTools, registerRefineTools } from './tools/refine.js';
+//# sourceMappingURL=refine.js.map

package/dist/refine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refine.js","sourceRoot":"","sources":["../src/refine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAsB,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,11 @@
+import { Server } from '@modelcontextprotocol/server';
+import type { Catalog } from './catalog.js';
+/**
+ * Creates an MCP server with the generic package tools registered. Refine-specific
+ * tools are opt-in via `@vielzeug/codex/refine`'s `registerRefineTools()` — the main
+ * library entry stays product-agnostic.
+ */
+export declare function createMcpServer(catalog: Catalog, options: {
+    debug?: boolean;
+    version: string;
+}): Server;