@nysds/mcp-server 1.20.1 → 1.21.1

package/data/tokens/tokens.css

@@ -1,5 +1,5 @@
 /*!
- * New York State Design System v1.20.1
+ * New York State Design System v1.21.1
  * Description: A design system for New York State's digital products.
  * Repository: https://github.com/its-hcd/nysds
  * License: MIT

package/dist/lib/framework-snippets.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Framework snippet generation
+ *
+ * Turns a component's canonical HTML examples into React and Angular
+ * snippets using `@nysds/codegen`'s `transformExample` — the same
+ * transformer the docs site and Storybook autodocs use, so an AI assistant
+ * asking the MCP server sees exactly the same code a developer sees on
+ * designsystem.ny.gov.
+ */
+import { type CEMExample, type CEMFormControl } from "./cem-parser.js";
+export type FrameworkFilter = "html" | "react" | "angular";
+export interface FrameworkSnippet {
+    code: string;
+    imports: string[];
+    warnings: string[];
+    unsupported: boolean;
+}
+export interface ExampleWithSnippets {
+    title: string;
+    html: string;
+    react: FrameworkSnippet;
+    angular: FrameworkSnippet;
+}
+/**
+ * Builds React and Angular snippets for every HTML example on a component.
+ *
+ * When `framework` names one target explicitly, that framework's snippet
+ * uses its most idiomatic forms binding for a form-control component —
+ * React's controlled pattern (`value` + `onNys*`), Angular's
+ * `formControlName` (Reactive Forms). The unrequested framework, and every
+ * snippet when `framework` is `"html"` (the default), stays a plain
+ * attribute-for-attribute conversion so the default response isn't
+ * surprising.
+ */
+export declare function buildExampleSnippets(examples: CEMExample[] | undefined, framework: FrameworkFilter, formControl: CEMFormControl | undefined): ExampleWithSnippets[];
+//# sourceMappingURL=framework-snippets.d.ts.map

package/dist/lib/framework-snippets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-snippets.d.ts","sourceRoot":"","sources":["../../src/lib/framework-snippets.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,EAAU,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE/E,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,gBAAgB,CAAC;IACxB,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAgBD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,UAAU,EAAE,GAAG,SAAS,EAClC,SAAS,EAAE,eAAe,EAC1B,WAAW,EAAE,cAAc,GAAG,SAAS,GACtC,mBAAmB,EAAE,CA+BvB"}

package/dist/lib/framework-snippets.js

@@ -0,0 +1,55 @@
+/**
+ * Framework snippet generation
+ *
+ * Turns a component's canonical HTML examples into React and Angular
+ * snippets using `@nysds/codegen`'s `transformExample` — the same
+ * transformer the docs site and Storybook autodocs use, so an AI assistant
+ * asking the MCP server sees exactly the same code a developer sees on
+ * designsystem.ny.gov.
+ */
+import { transformExample, } from "@nysds/codegen";
+import { getCEM } from "./cem-parser.js";
+function toSnippet(result) {
+    return {
+        code: result.code,
+        imports: result.imports,
+        warnings: result.warnings,
+        unsupported: result.unsupported,
+    };
+}
+/**
+ * Builds React and Angular snippets for every HTML example on a component.
+ *
+ * When `framework` names one target explicitly, that framework's snippet
+ * uses its most idiomatic forms binding for a form-control component —
+ * React's controlled pattern (`value` + `onNys*`), Angular's
+ * `formControlName` (Reactive Forms). The unrequested framework, and every
+ * snippet when `framework` is `"html"` (the default), stays a plain
+ * attribute-for-attribute conversion so the default response isn't
+ * surprising.
+ */
+export function buildExampleSnippets(examples, framework, formControl) {
+    if (!examples || examples.length === 0)
+        return [];
+    const manifest = getCEM();
+    const reactFormsMode = framework === "react" && formControl ? "template" : "none";
+    const angularFormsMode = framework === "angular" && formControl ? "reactive" : "none";
+    return examples
+        .filter((example) => !example.lang || example.lang === "html")
+        .map((example) => ({
+        title: example.title,
+        html: example.code,
+        react: toSnippet(transformExample({
+            html: example.code,
+            framework: "react",
+            manifest,
+            formsMode: reactFormsMode,
+        })),
+        angular: toSnippet(transformExample({
+            html: example.code,
+            framework: "angular",
+            manifest,
+            formsMode: angularFormsMode,
+        })),
+    }));
+}

package/dist/lib/framework-usage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Framework usage notes
+ *
+ * Short, framework-specific guidance attached to `get_component` responses
+ * when the caller asks for `framework: "react"` or `"angular"` — the import
+ * line, the event-prop naming rule, and (when the component is a form
+ * control) how it binds into that framework's forms. Naming follows the
+ * rules in `.claude/plans/framework-support/README.md` section 4.1, reused
+ * here via `@nysds/codegen` rather than re-derived.
+ */
+import type { CEMFormControl } from "./cem-parser.js";
+export interface FrameworkUsageNotes {
+    package: string;
+    import: string;
+    events: string;
+    forms?: string;
+}
+export declare function buildReactUsageNotes(tagName: string, className: string, formControl: CEMFormControl | undefined): FrameworkUsageNotes;
+export declare function buildAngularUsageNotes(tagName: string, className: string, formControl: CEMFormControl | undefined): FrameworkUsageNotes;
+//# sourceMappingURL=framework-usage.d.ts.map

package/dist/lib/framework-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-usage.d.ts","sourceRoot":"","sources":["../../src/lib/framework-usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAQD,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,cAAc,GAAG,SAAS,GACtC,mBAAmB,CAqBrB;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,cAAc,GAAG,SAAS,GACtC,mBAAmB,CAmBrB"}

package/dist/lib/framework-usage.js

@@ -0,0 +1,50 @@
+/**
+ * Framework usage notes
+ *
+ * Short, framework-specific guidance attached to `get_component` responses
+ * when the caller asks for `framework: "react"` or `"angular"` — the import
+ * line, the event-prop naming rule, and (when the component is a form
+ * control) how it binds into that framework's forms. Naming follows the
+ * rules in `.claude/plans/framework-support/README.md` section 4.1, reused
+ * here via `@nysds/codegen` rather than re-derived.
+ */
+import { eventToAngularOutput, eventToReactProp, tagToSubpath, } from "@nysds/codegen";
+const FORM_CONTROL_LABEL = {
+    value: "value",
+    checked: "checked state",
+    files: "selected files",
+};
+export function buildReactUsageNotes(tagName, className, formControl) {
+    const subpath = tagToSubpath(tagName);
+    const changeProp = formControl
+        ? eventToReactProp(formControl.changeEvent)
+        : undefined;
+    const inputProp = formControl?.inputEvent !== undefined
+        ? eventToReactProp(formControl.inputEvent)
+        : undefined;
+    return {
+        package: "@nysds/react",
+        import: `import { ${className} } from "@nysds/react/${subpath}";`,
+        events: "Events map to onNys* props (nys-change -> onNysChange). The handler receives the typed CustomEvent, so e.detail autocompletes.",
+        forms: formControl
+            ? `Form control (${formControl.kind}). For a controlled component, bind ${formControl.kind} and update state from ${changeProp}${inputProp ? ` (or ${inputProp} for every keystroke)` : ""}; re-rendering with the same ${FORM_CONTROL_LABEL[formControl.kind]} snaps the element back to your state. See get_guide({ topic: "installation", framework: "react" }) for React Hook Form and uncontrolled-form patterns.`
+            : undefined,
+    };
+}
+export function buildAngularUsageNotes(tagName, className, formControl) {
+    const subpath = tagToSubpath(tagName);
+    const angularClass = `${className}Component`;
+    const changeOutput = formControl
+        ? eventToAngularOutput(formControl.changeEvent)
+        : undefined;
+    return {
+        package: "@nysds/angular",
+        import: `import { ${angularClass} } from "@nysds/angular/${subpath}";`,
+        events: `Events map to camelCase outputs (nys-change -> (nysChange)); event.detail is typed.${changeOutput
+            ? ` This component's change output is (${changeOutput}).`
+            : ""}`,
+        forms: formControl
+            ? 'Implements ControlValueAccessor: works with [(ngModel)], formControlName (Reactive Forms), and Signal Forms [formField] with no CUSTOM_ELEMENTS_SCHEMA. Add the nysControlErrors directive to let Angular own validation display instead of the component\'s own errorMessage/showError. See get_guide({ topic: "installation", framework: "angular" }).'
+            : undefined,
+    };
+}

package/dist/lib/frameworks-data.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Framework package index
+ *
+ * Reads `data/frameworks.json`, written by `scripts/sync-guides.mjs` from
+ * `packages/react/package.json` and `packages/angular/package.json`. Gives
+ * tools and resources the published package name and version without
+ * hand-maintaining either.
+ */
+export interface FrameworkPackageInfo {
+    packageName: string;
+    version: string;
+}
+export interface FrameworksIndex {
+    react: FrameworkPackageInfo;
+    angular: FrameworkPackageInfo;
+}
+export declare function getFrameworksIndex(): FrameworksIndex;
+//# sourceMappingURL=frameworks-data.d.ts.map

package/dist/lib/frameworks-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frameworks-data.d.ts","sourceRoot":"","sources":["../../src/lib/frameworks-data.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,oBAAoB,CAAC;IAC5B,OAAO,EAAE,oBAAoB,CAAC;CAC/B;AAiBD,wBAAgB,kBAAkB,IAAI,eAAe,CAcpD"}

package/dist/lib/frameworks-data.js

@@ -0,0 +1,39 @@
+/**
+ * Framework package index
+ *
+ * Reads `data/frameworks.json`, written by `scripts/sync-guides.mjs` from
+ * `packages/react/package.json` and `packages/angular/package.json`. Gives
+ * tools and resources the published package name and version without
+ * hand-maintaining either.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let cached = null;
+function getFrameworksDataPath() {
+    const candidates = [
+        resolve(__dirname, "../../data/frameworks.json"),
+        resolve(process.cwd(), "data/frameworks.json"),
+    ];
+    for (const path of candidates) {
+        if (existsSync(path))
+            return path;
+    }
+    throw new Error(`data/frameworks.json not found. Searched paths:\n${candidates.join("\n")}`);
+}
+export function getFrameworksIndex() {
+    if (cached)
+        return cached;
+    try {
+        cached = JSON.parse(readFileSync(getFrameworksDataPath(), "utf-8"));
+    }
+    catch (error) {
+        console.error("Warning: Could not load data/frameworks.json:", error);
+        cached = {
+            react: { packageName: "@nysds/react", version: "unknown" },
+            angular: { packageName: "@nysds/angular", version: "unknown" },
+        };
+    }
+    return cached;
+}

package/dist/resources/frameworks.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Framework Resources
+ *
+ * MCP resources for NYSDS framework packages (@nysds/react, @nysds/angular).
+ *
+ * Resources:
+ * - nysds://frameworks - Index of framework packages with version and guide URI
+ * - nysds://frameworks/react - @nysds/react guide (synced from its README)
+ * - nysds://frameworks/angular - @nysds/angular guide (synced from its README)
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerFrameworkResources(server: McpServer): void;
+//# sourceMappingURL=frameworks.d.ts.map

package/dist/resources/frameworks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frameworks.d.ts","sourceRoot":"","sources":["../../src/resources/frameworks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAezE,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA8ElE"}

package/dist/resources/frameworks.js

@@ -0,0 +1,83 @@
+/**
+ * Framework Resources
+ *
+ * MCP resources for NYSDS framework packages (@nysds/react, @nysds/angular).
+ *
+ * Resources:
+ * - nysds://frameworks - Index of framework packages with version and guide URI
+ * - nysds://frameworks/react - @nysds/react guide (synced from its README)
+ * - nysds://frameworks/angular - @nysds/angular guide (synced from its README)
+ */
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getFrameworksIndex } from "../lib/frameworks-data.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const GUIDES_DIR = join(__dirname, "../../data/guides/frameworks");
+function loadFrameworkGuide(framework) {
+    try {
+        return readFileSync(join(GUIDES_DIR, `${framework}.md`), "utf-8");
+    }
+    catch {
+        return `Framework guide not found: ${framework}. Run "npm run sync:guides -w @nysds/mcp-server".`;
+    }
+}
+export function registerFrameworkResources(server) {
+    // nysds://frameworks - Index of framework packages
+    server.resource("frameworks", "nysds://frameworks", {
+        description: "Index of NYSDS framework packages (@nysds/react, @nysds/angular) with their published version and guide resource URI",
+        mimeType: "application/json",
+    }, async () => {
+        const index = getFrameworksIndex();
+        const list = [
+            {
+                id: "react",
+                packageName: index.react.packageName,
+                version: index.react.version,
+                guideUri: "nysds://frameworks/react",
+            },
+            {
+                id: "angular",
+                packageName: index.angular.packageName,
+                version: index.angular.version,
+                guideUri: "nysds://frameworks/angular",
+            },
+        ];
+        return {
+            contents: [
+                {
+                    uri: "nysds://frameworks",
+                    mimeType: "application/json",
+                    text: JSON.stringify(list, null, 2),
+                },
+            ],
+        };
+    });
+    // nysds://frameworks/react - @nysds/react guide
+    server.resource("frameworks-react", "nysds://frameworks/react", {
+        description: "@nysds/react install, usage, forms, SSR, and troubleshooting guide",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "nysds://frameworks/react",
+                mimeType: "text/markdown",
+                text: loadFrameworkGuide("react"),
+            },
+        ],
+    }));
+    // nysds://frameworks/angular - @nysds/angular guide
+    server.resource("frameworks-angular", "nysds://frameworks/angular", {
+        description: "@nysds/angular install, usage, forms, SSR, and troubleshooting guide",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "nysds://frameworks/angular",
+                mimeType: "text/markdown",
+                text: loadFrameworkGuide("angular"),
+            },
+        ],
+    }));
+}

package/dist/tools/utility-tools.d.ts

@@ -2,7 +2,55 @@
  * Utility Tools
  *
  * MCP tools for NYSDS utility classes.
+ *
+ * The class lists this tool returns are RENDERED from the scale constants
+ * below. Those constants mirror the Sass sources that actually generate the
+ * stylesheet:
+ *
+ *   - packages/styles/src/utilities/_config.scss     ($spacing, $opacity-values,
+ *                                                     $zindex-values, $display-values,
+ *                                                     $breakpoints, $flex-columns)
+ *   - packages/styles/src/utilities/_layout-grid.scss ($responsive-gap-suffixes)
+ *   - packages/styles/src/core/typography.scss        ($body-sizes, $ui-sizes,
+ *                                                     $ui-underline-styles, $display-sizes)
+ *
+ * Do not hand-write a class name into the markdown. Add it to a scale and let
+ * the renderer emit it, so a name can never appear here without a scale entry
+ * behind it.
+ *
+ * `npm run verify:utility-docs` compiles the stylesheet and asserts that every
+ * class this tool names exists in it. Run it after touching any scale.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+declare const UTILITY_DOCS: {
+    grid: string;
+    flex: string;
+    spacing: string;
+    display: string;
+    opacity: string;
+    zindex: string;
+    typography: string;
+    responsive: string;
+    componentSpacing: string;
+};
+/**
+ * Classes the reference deliberately names in order to say they do NOT exist.
+ *
+ * These are the names people reach for out of habit from other frameworks.
+ * Saying so explicitly is more useful than silence, but it means the docs
+ * mention class names the stylesheet does not define, which would otherwise
+ * trip the verifier.
+ *
+ * `verify-utility-docs.mjs` asserts each of these is genuinely absent, so if
+ * NYSDS ever adds one, the stale warning fails the check instead of quietly
+ * misinforming people.
+ */
+declare const KNOWN_ABSENT: readonly string[];
+/**
+ * Exported so `src/scripts/verify-utility-docs.mjs` can assert that every class
+ * named in this reference exists in the compiled stylesheet — and that every
+ * class named in KNOWN_ABSENT still does not.
+ */
+export { UTILITY_DOCS, KNOWN_ABSENT };
 export declare function registerUtilityTools(server: McpServer): void;
 //# sourceMappingURL=utility-tools.d.ts.map

package/dist/tools/utility-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utility-tools.d.ts","sourceRoot":"","sources":["../../src/tools/utility-tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAmPzE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA8D5D"}
+{"version":3,"file":"utility-tools.d.ts","sourceRoot":"","sources":["../../src/tools/utility-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAiLzE,QAAA,MAAM,YAAY;;;;;;;;;;CAyOjB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,QAAA,MAAM,YAAY,EAAE,SAAS,MAAM,EAUlC,CAAC;AAEF;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;AAEtC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA8D5D"}