@commercetools/nimbus-mcp 0.1.0 → 2.10.0

package/README.md

@@ -46,11 +46,14 @@ npx @commercetools/nimbus-mcp
 
 ## Available Tools
 
-| Tool              | Description                                             |
-| ----------------- | ------------------------------------------------------- |
-| `list_components` | Returns names and descriptions of all Nimbus components |
-
-More tools are being added. See `src/tools/` for the full list.
+| Tool                 | Description                                                                            |
+| -------------------- | -------------------------------------------------------------------------------------- |
+| `list_components`    | Returns names and descriptions of all Nimbus components and patterns                   |
+| `get_component`      | Returns detailed info about a component or pattern (metadata, props, recipe, docs)     |
+| `search_docs`        | Full-text search across all Nimbus documentation pages                                 |
+| `search_icons`       | Fuzzy-search Nimbus icons by name or keyword                                           |
+| `get_tokens`         | Returns design tokens — list categories, browse by category, or reverse-lookup a value |
+| `migrate_from_uikit` | Returns migration mappings from UI Kit components to Nimbus equivalents                |
 
 ## Development
 
@@ -68,9 +71,15 @@ pnpm install
 pnpm --filter @commercetools/nimbus-mcp build
 ```
 
-### Running from source (no build needed)
+### Running from source
+
+Requires a prebuild to copy docs data, generate the icon catalog, and generate
+token data first:
 
 ```bash
+pnpm --filter @commercetools/nimbus-mcp prebuild
+pnpm --filter @commercetools/nimbus-mcp catalog:icons
+pnpm --filter @commercetools/nimbus-mcp build:tokens
 pnpm --filter @commercetools/nimbus-mcp dev
 ```
 
@@ -131,14 +140,54 @@ export function registerMyTool(server: McpServer): void {
 
 That's it — no other files need changing.
 
-## Data Availability
+## Data & Build Pipeline
+
+The MCP server reads generated docs data (route manifest, search index, types,
+and per-component route JSON) from `data/docs/` inside the package directory.
+
+### How data gets into `data/docs/`
+
+The package has a **prebuild** step, an **icon catalog** step, and a **token
+flattener** step that run automatically before `tsup`:
+
+```
+pnpm build  →  pnpm prebuild  →  build-icon-catalog.ts  →  build-token-data.ts  →  tsup
+                    │                       │                        │
+                    ▼                       ▼                        ▼
+            scripts/prebuild.mjs    scripts/build-icon-catalog.ts   src/processors/build-token-data.ts
+                    │                       │                        │
+                    ▼                       ▼                        ▼
+            scripts/copy-docs-data.mjs   data/icons.json          data/tokens.json
+                    │
+    copies apps/docs/src/data/ → data/docs/
+```
 
-The server has two runtime modes:
+The prebuild orchestrator (`scripts/prebuild.mjs`) runs an array of steps in
+order. Currently the only step is `copy-docs-data`, which copies
+`route-manifest.json`, `search-index.json`, `routes/`, and `types/` from the
+docs app into `data/docs/`. New prebuild steps can be added to the array.
+
+After prebuild, `build-icon-catalog.ts` scans `packages/nimbus-icons/src/` and
+generates `data/icons.json` — a searchable catalog of all icon names,
+categories, import paths, and normalized keywords. This can also be run
+standalone via `pnpm --filter @commercetools/nimbus-mcp catalog:icons`.
+
+Then, `build-token-data.ts` reads the raw tokens and writes a flattened
+`data/tokens.json` with all tokens, a by-category index, and a reverse-lookup
+map. This can also be run standalone via
+`pnpm --filter @commercetools/nimbus-mcp build:tokens`.
+
+The `data/` directory is gitignored — it is always regenerated at build time.
+
+### Build order (CI and local)
+
+```
+tokens → packages (excl. mcp) → docs-data → mcp (prebuild + tsup)
+```
 
-- **Monorepo mode** (detected automatically): reads live data from
-  `apps/docs/src/data/`. Run `pnpm build:docs` first to generate these files.
-- **Standalone mode** (npm package): reads from a bundled `data/` directory
-  shipped with the package.
+The root `build:docs-data` script runs only the docs data generation (not the
+full Vite app build), keeping CI fast. The full `pnpm build` runs the complete
+docs build which also produces the data files.
 
-Tools that depend on docs data will return a graceful error message if data
-files are not present.
+Tools that depend on docs data return a graceful error message if data files are
+not present.