@vielzeug/codex 1.0.2

package/README.md

@@ -0,0 +1,142 @@
+# @vielzeug/codex
+
+> MCP server for the Vielzeug ecosystem. Run over stdio or HTTP to expose package metadata, docs, source entrypoints, runnable REPL examples, and Refine component metadata.
+
+[![npm version](https://img.shields.io/npm/v/@vielzeug/codex)](https://www.npmjs.com/package/@vielzeug/codex) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+<details>
+<summary>Quick Reference</summary>
+
+**Package:** `@vielzeug/codex` &nbsp;·&nbsp; **Category:** AI Tooling
+
+**Key exports:** `createServer`, `createServerFromDisk`, `loadData`, `packageMeta`, `validateBundledData`, `startHttpServer`
+
+**When to use:** You want AI clients to query Vielzeug docs and package metadata through a compact MCP tool set.
+
+**Related:** [@vielzeug/refine](https://vielzeug.dev/refine/) · [@vielzeug/spell](https://vielzeug.dev/spell/)
+
+</details>
+
+`@vielzeug/codex` ships with bundled snapshot data, so it runs without a local Vielzeug checkout.
+
+## Installation
+
+```sh
+pnpm add @vielzeug/codex
+npm install @vielzeug/codex
+yarn add @vielzeug/codex
+```
+
+## Quick Start
+
+Run over stdio (default):
+
+```sh
+npx -y @vielzeug/codex
+```
+
+Run over HTTP:
+
+```sh
+npx -y @vielzeug/codex --port 3100
+```
+
+CLI helpers:
+
+```sh
+npx -y @vielzeug/codex --help
+npx -y @vielzeug/codex --version
+```
+
+## Tools
+
+Two tiers: generic tools work for every bundled package; `refine-*` tools expose
+[@vielzeug/refine](https://vielzeug.dev/refine/)'s structured component metadata (Custom
+Elements Manifest data generated from refine's real build output, never hand-duplicated).
+There's no ore/spell/sandbox-specific tooling — `get-docs`, `get-source`, and
+`get-type-signature` already cover those packages accurately; see
+[docs/ore/api.md](https://vielzeug.dev/ore/api), [docs/spell/api.md](https://vielzeug.dev/spell/api),
+and [docs/sandbox/api.md](https://vielzeug.dev/sandbox/api).
+
+These tables are generated from the tool registry (`pnpm gen:tool-docs`) — never hand-edit them.
+
+<!-- TOOLS:GENERIC:START -->
+| Tool | Input | Description |
+| --- | --- | --- |
+| `list-packages` | — | List all vielzeug packages with metadata (version, description, category, keywords, exports, availableDocPages, exampleIds, hasSource). |
+| `get-package` | `packageSlug` | Get metadata for a single vielzeug package by slug. |
+| `get-docs` | `packageSlug`, `page?` | Read a documentation page for a vielzeug package. |
+| `get-source` | `packageSlug` | Read the full src/index.ts source of a vielzeug package. |
+| `list-examples` | `packageSlug` | List runnable REPL code examples for a vielzeug package. |
+| `get-example` | `exampleId`, `packageSlug` | Read the full runnable source code of a single REPL example for a vielzeug package. |
+| `search-packages` | `query` | Search vielzeug packages by keyword across name, description, category, keywords, exports, related, docs, REPL examples, and source. |
+| `get-type-signature` | `slug`, `symbol` | Look up the exported TypeScript declaration for a named symbol from a @vielzeug package's bundled src/index.ts (extracted and indexed at build time, not parsed per-request). |
+<!-- TOOLS:GENERIC:END -->
+
+<!-- TOOLS:REFINE:START -->
+| Tool | Input | Description |
+| --- | --- | --- |
+| `refine-list-components` | — | List all @vielzeug/refine web component tags from bundled Custom Elements Manifest (CEM) metadata. |
+| `refine-get-component` | `tagName` | Get the full Custom Elements Manifest (CEM) declaration for a single @vielzeug/refine component by its HTML tag name (e.g. "ore-button"). |
+| `refine-generate-template` | `scenario?`, `tagName` | Generate a ready-to-use HTML template for a @vielzeug/refine component. |
+| `refine-get-tokens` | `filter?` | List all CSS custom properties (design tokens) exposed by @vielzeug/refine components. |
+| `refine-validate-usage` | `html`, `tagName` | Validate AI-generated HTML against a @vielzeug/refine component spec. |
+<!-- TOOLS:REFINE:END -->
+
+### Error results
+
+A failed tool call returns `isError: true` with a single text content block containing
+`{"code": "...", "message": "..."}` — `code` is one of `INVALID_ARG` (bad or missing argument),
+`NOT_FOUND` (unknown slug/tag/symbol/example), or `UNAVAILABLE` (data not bundled, e.g. refine
+CEM metadata when refine wasn't built). Branch on `code` instead of matching `message` text.
+
+## HTTP mode
+
+- MCP endpoint: `http://localhost:<port>/`
+- Health check: `http://localhost:<port>/health`
+- No authentication and permissive CORS (`Access-Control-Allow-Origin: *`) — any origin reachable from the machine running the server can call every tool. All bundled tools are read-only and side-effect-free (no filesystem writes, no shell/network access beyond serving pre-bundled data), so this is a deliberate trade-off for local developer tooling (editor extensions, browser-based MCP inspectors) rather than a public-facing deployment mode. Do not expose `--port` beyond `localhost` or a trusted network.
+
+## Debugging
+
+Environment variables for local development (not needed for normal use):
+
+| Variable | Effect |
+| --- | --- |
+| `CODEX_DEBUG=1` | Logs every tool call (name, args, timing, and errors) to stderr. |
+| `CODEX_PORT=<port>` | Port used by `pnpm dev` (default `3001`). |
+| `CODEX_FORCE_REGEN=1` | Skips the incremental cache in `prepare:data` — full regeneration. |
+
+Local dev loop: `pnpm dev` generates bundled data once, then runs the CLI directly against
+`src/` (via `node --watch`, no build step) alongside a `docs/` watcher that regenerates data on
+change.
+
+## Programmatic API
+
+`createServerFromDisk()` is the simplest entry point — one call, no arguments:
+
+```ts
+import { createServerFromDisk } from '@vielzeug/codex';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+await createServerFromDisk().connect(new StdioServerTransport());
+```
+
+For explicit control over data loading:
+
+```ts
+import { createServer, loadData } from '@vielzeug/codex';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+await createServer(loadData()).connect(new StdioServerTransport());
+```
+
+## Documentation
+
+- [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)
+
+## License
+
+MIT © [Helmuth Saatkamp](https://github.com/helmuthdu) — part of the [Vielzeug](https://github.com/helmuthdu/vielzeug) monorepo.

package/data/.cache.json

@@ -0,0 +1,33 @@
+{
+  "arsenal": "8d744515bdf784877f30519c9ae6553aaee4527fd41de781e3c300266b8c3ad8",
+  "clockwork": "d5722fda4cf1d710c7423ac08999b5d9180220c27dc1a580a14966c8d7b61720",
+  "codex": "e672b7dd118bc5717ddec287e06e98dcda9716ff5903d2059db689db7602f005",
+  "coins": "e3d8a9a8d154479acd959257ea16fc27f9460ae478ffa7c655f7c10b49811605",
+  "conduit": "bdffd7e5f5bdfc396188a4187ef50fb1c2a8178237defcae33be1102b99aee4f",
+  "courier": "f42b96c8986b5e000dbc19fae4418b6a4f6c5e66c05dbf07bfbdc51cb0fdf0b7",
+  "dnd": "d6eaab0839b16b63920d10ac9d3a67ad27d591e0179ecf1291ac3f58748e156b",
+  "familiar": "7d54a60b5e34208482e0e95ada2fd1f8152226a069681bc728c79dc46ebe6362",
+  "flux": "2227e3a16de24dec5207b3ee4a636de2ea6914151269e56e2eba144060560367",
+  "forge": "090181512d99f943ef128725aab1c91e9393d8ce6b11f67fe6a410dd66f99237",
+  "herald": "a9a5eec4d6114fb518cda744a736021176f678fdbdec4d405046b7bd87f53714",
+  "keymap": "1c0eaaf07ca7f595b3830ea1c680ef6b5168daf546fd2a16be8cdf3ec8e963b3",
+  "ledger": "bba4fe645ad1d53c7d120c00e8c8ac26a82db2ceecb2c7783962aa26b815eee4",
+  "lingua": "c4872b073d8c4138bee1105e66e6c523a4d96577e4f15924d238906ae9051513",
+  "orbit": "70717ad52896bb74c38f3bf6ce44f043902dba950560d4a33c7ebe8b42275444",
+  "ore": "a30e04a0dcab65d79e1242164a39a47528b38e7322986f4f36dd567085006d1c",
+  "prism": "49c08d330b5a7be5a3a414a04df98ee8a8404bdd01ef219f7a0b14f23c919dd0",
+  "pulse": "8e4ab0a8e0240f020113b1e16489b7bd41836ec2d3649ca5ef85ab7998684d9d",
+  "refine": "cac1a1b23996571e6a7ae0d596d3b9bd7e791e51287b31c416d3393bb473d2f0",
+  "ripple": "830be4d0bf3de92cece1027db2ed7f7909c0cb6d0aeeb6f61d99c0d71e40fea1",
+  "rune": "3d94e2b88cf53e5b3a36cd24ceec069ae4bfc841c46d16f065ae8d0383ad142b",
+  "sandbox": "9ac8209df9ed55a9618fbae89a1aa8e5a7d36356e21392519a764c1be1a997c4",
+  "scout": "58e41ad009901fc01884258bf0eba03fbf62c73cc75990a6a99c8a4f6072952e",
+  "scroll": "4ce4da017e28d76e415a2cb4bacfcf6d4b4481b75956590b7f5a913914415052",
+  "sourcerer": "3b968bfd165a2f27251fd5b0870b1edcdc8f06734ef766366c3db06c60aa12f0",
+  "spell": "7a7582f895fd201f0d672e46a93f27ede384b70aa6bf0eac31899dc62cfd7303",
+  "tempo": "dbdce8f6bac7450b57ac2a0d28e448cb0b2e5824766ba095234269eda98c081b",
+  "vault": "7868c26064dfd04fa0101fff3a42ea28543bb6d3faf086718e965335e6f672db",
+  "ward": "3e423ba720c0ef8550db5a52b96dcfb52866e176d3762f609069753cabeb48a6",
+  "wayfinder": "dd0fb194b09c777034c2967489e5f3548979828f99ddc78d39e616f892f8b22d",
+  "__generator__": "939356241d6d5cc293ed640916bbed11456d819cd8d17c4967381355dadf1272"
+}