@rio-cloud/uikit-mcp 1.0.0 → 1.1.0

package/README.md

@@ -3,12 +3,10 @@
 ## Overview
 
 - Model Context Protocol (MCP) server that exposes the captured RIO UI Kit documentation as Markdown resources plus a keyword search tool.
-- Ships with the full dataset under `data/`—no network calls or external services are required at runtime.
-- Captured UI Kit version: see `data/version.json` (written automatically by `npm run capture:all`)
+- Ships with the full dataset - no network calls or external services are required at runtime.
 - `search_docs` must always be used before `readResource`; listResources is a static inventory snapshot and not intended for guessing IDs.
 - `readResource` returns rich Markdown (sections, examples, code tabs, props tables) for the URI returned by `search_docs`.
 
-
 ## MCP Client Configuration
 
 Add the server to an MCP-aware client configuration (example for Codex CLI):
@@ -16,11 +14,9 @@ Add the server to an MCP-aware client configuration (example for Codex CLI):
 ```toml
 [mcp_servers.uikit]
 command = "npx"
-args = ["@rio-cloud/uikit-mcp"]
-startup_timeout_sec = 30
+args = ["-y", "@rio-cloud/uikit-mcp"]
 ```
 
-
 ## Available Resources & Tools
 
 - **Resource namespace:** `uikit-doc://<route>` (e.g. `uikit-doc://components/button`).
@@ -41,50 +37,89 @@ Add the short UI Kit usage snippet from `AGENTS.md` to your agent guidelines so
 - Best tech stack for the RIO UI Kit is a React application with TypeScript
 ```
 
-## Development Notes
-
-- Crawler scripts live in `crawler/` and stay out of the npm bundle.
-  - Download Chromium once: `npm run setup:crawler`.
-  - One-shot full run: `npm run crawl:full` (ensures Playwright Chromium, runs `crawl:navigation`, `capture:all -- --force --concurrency=5`, then `npm test`).
-  - Refresh navigation snapshot: `npm run crawl:navigation`.
-  - Capture all routes: `npm run capture:all` with optional flags:
-    - `--category=Components` (filter by top-level navigation label)
-    - `--section=Interaction` (filter by sidebar section title)
-    - `--match=button` (substring match across category/section/label/href)
-    - `--retries=3` (per-route retry count)
-    - `--concurrency=5` (parallel workers; 5 recommended for full crawl)
-    - `--force` (re-write artefacts even when hashes match existing files)
-  - Script writes JSON to `data/pages/**` and updates `data/version.json` with the detected UI Kit version. Full captures (no `--match`/`--section`) clean existing JSON artefacts per captured category before writing; partial captures rely on hash comparison to skip unchanged files.
-- `docs/navigation-inventory.json` records the latest navigation snapshot; `docs/content-schema.md` documents the capture format.
-- Run the lightweight regression suite with `npm test` to ensure doc loading, search, and Markdown rendering stay healthy.
-- Search synonyms and preferred resource IDs live in `docs/search-synonyms.json`; after crawls, keep this file in sync. `npm test` fails if any preferredDocIds are missing.
-
-### New crawl for a new UI Kit version
-- Shortcut: `npm run crawl:full` (runs setup if needed, navigation crawl, full capture with `--force --concurrency=5`, then tests).
-- `data/version.json` is written automatically; README points to this file so no manual version bump is needed.
-
-### Local Installation with git checkout
+---
+
+## Development
+
+> **Note:** The following sections are only relevant for contributors working on this repository.
+
+### Requirements
+
+- **Node 22+** (tsdown target)
+- Dev dependencies must be installed (tsx is required for the tsdown build hook and tests)
+
+### Setup
 
 ```bash
+git clone <repository>
+cd uikit-mcp
 npm install
-# global link for CLI availability
-npm link
+npm run build:server
 ```
 
-- CLI entrypoint: `uikit-mcp` 
-- (optional) smoke test: `node tools/demo-client.mjs`.
+### Available Scripts
 
-#### MCP Client Configuration (Local Checkout)
+| Script | Description |
+|--------|-------------|
+| `npm run build:server` | Build server + generate docs (via tsdown hook) |
+| `npm run mcp:server` | Build and start server locally |
+| `npm run crawl:full` | Run crawler and rebuild (full pipeline) |
+| `npm test` | Run tests (builds first via pretest) |
 
-Add the server to an MCP-aware client configuration (example for Codex CLI):
+### Architecture
 
-```toml
-# use globally linked CLI (npm link)
-[mcp_servers.uikit]
-command = "uikit-mcp"
-startup_timeout_sec = 30
+The server uses a **build-time compilation** approach for fast startup:
+
+1. **Build time** (`npm run build:server`):
+   - tsdown bundles `server/index.ts` → `dist/index.mjs`
+   - `build:done` hook generates pre-compiled docs:
+     - `data/pages/**/*.json` → `dist/docs/**/*.md`
+     - Creates `dist/doc-metadata.json` (metadata for search index)
+     - Copies `dist/search-synonyms.json` and `dist/version.json`
+
+2. **Runtime** (server start):
+   - Loads 2 JSON files
+   - Builds FlexSearch index
+   - Markdown files loaded on-demand (lazy loading)
+
+### Version Information
+
+| Context | Path | Description |
+|---------|------|-------------|
+| **Source** (Repository) | `data/version.json` | Written by crawler, source of truth |
+| **Published** (npm Package) | `dist/version.json` | Copied during build |
+
+### Crawler Scripts
+
+Crawler scripts live in `crawler/` and stay out of the npm bundle:
+
+- Download Chromium once: `npm run setup:crawler`
+- One-shot full run: `npm run crawl:full` (ensures Playwright Chromium, runs `crawl:navigation`, `capture:all -- --force --concurrency=5`, then `npm test`)
+- Refresh navigation snapshot: `npm run crawl:navigation`
+- Capture all routes: `npm run capture:all` with optional flags:
+  - `--category=Components` (filter by top-level navigation label)
+  - `--section=Interaction` (filter by sidebar section title)
+  - `--match=button` (substring match across category/section/label/href)
+  - `--retries=3` (per-route retry count)
+  - `--concurrency=5` (parallel workers; 5 recommended for full crawl)
+  - `--force` (re-write artefacts even when hashes match existing files)
+
+### Package Contents
+
+The published npm package contains only:
+
+```
+dist/
+├── index.mjs           # Server binary (with shebang)
+├── docs/**/*.md        # Pre-rendered Markdown files
+├── doc-metadata.json   # Metadata for search index
+├── search-synonyms.json
+└── version.json
+README.md
+LICENSE
 ```
 
+No `data/` or `crawler/` directories are included.
 
 ## License