@besaitech/ng-design-system-mcp 0.0.5

package/README.md

@@ -0,0 +1,97 @@
+# @besaitech/ng-design-system-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that exposes the **`@besaitech/ng-design-system`**
+Angular component library documentation to AI coding tools (Claude Code, Cursor, Windsurf…).
+
+It lets the assistant look up real selectors, inputs, enum values, outputs (including
+two-way `model()` change-events), exported types, content-projection slots, design tokens,
+registered icon names, copyable examples, and the Tailwind-v4 setup — then **validate** the
+code it generates — so it stops guessing the API.
+
+The documentation is **generated from the library source at build time** and bundled into this
+package as `data/docs.json`, version-stamped to the library release it describes. It never
+drifts and never calls the network.
+
+## Install
+
+Published to the public npm registry, same as the library it documents:
+
+```bash
+npm install -g @besaitech/ng-design-system-mcp
+```
+
+No scope mapping, no `.npmrc` and no token needed.
+
+## Register the server
+
+### Claude Code
+
+```sh
+claude mcp add saitech-design-system -- npx -y @besaitech/ng-design-system-mcp
+```
+
+### `.mcp.json` (committed in a consuming repo)
+
+```json
+{
+  "mcpServers": {
+    "saitech-design-system": {
+      "command": "npx",
+      "args": ["-y", "@besaitech/ng-design-system-mcp@0.0.5"]
+    }
+  }
+}
+```
+
+> **Pin the same version as your installed `@besaitech/ng-design-system`** so the docs match the
+> code you ship. The `sds://meta` resource and `sds_get_setup` echo the bundled
+> `libraryVersion` so the agent can confirm what it is coding against.
+
+### Cursor / Windsurf
+
+Use the identical stdio command in the tool's MCP config (`command: npx`, `args: ["-y", "@besaitech/ng-design-system-mcp"]`).
+
+## What it provides
+
+**Tools**
+
+| tool | purpose |
+| --- | --- |
+| `sds_list_components` | discover the catalogue (filter by `kind` / `group`) |
+| `sds_get_component` | full API for one component (fuzzy: class name, selector, or bare name) |
+| `sds_get_examples` | curated, copyable snippets grouped by section |
+| `sds_search` | keyword search across names, descriptions, inputs, types, examples |
+| `sds_validate_usage` | lint generated markup (selectors, inputs, enums, required, icons, CVA `[value]`) |
+| `sds_validate_icon` | check an `<sds-icon name>` against the registry (+ suggestions) |
+| `sds_get_token` | design tokens with Tailwind utility + CSS variable |
+| `sds_get_setup` | install + Tailwind-v4 checklist (the #1 "renders unstyled" fix) |
+
+**Resources** — `sds://docs.json`, `sds://meta`, `sds://component/{selectorOrClass}`,
+`sds://components/{selector}.md`, `sds://llms.txt`.
+
+**Prompts** — `sds_generate_component_usage`, `sds_scaffold_form`, `sds_build_data_table`.
+
+## Contributor mode (inside the monorepo)
+
+To serve docs from a live working tree (re-extracts from source on startup, no rebuild):
+
+```sh
+node packages/mcp-server/dist/index.js --source /path/to/saitech-design-system
+```
+
+`--data <path>` serves a specific `docs.json`. `--http` is reserved for a future shared
+instance (currently falls back to stdio).
+
+## How it is built & released
+
+From the workspace root:
+
+```sh
+npm run docs:index     # regenerate data/docs.json (+ docs/ by-products) from source
+npm run build:mcp      # docs:index, then tsc -> dist/
+npm run release:mcp    # bump, build, publish to npm
+npm run release:all    # release the library, then this server (lockstep)
+```
+
+`prebuild:lib` regenerates the index before every `ng build saitech-design-system`, and CI
+(`npm run check:docs`) fails if the committed index drifts from source.