@nysds/mcp-server 1.16.0-alpha4 → 1.16.0-alpha5

package/README.md

@@ -3,40 +3,24 @@
 MCP (Model Context Protocol) server for the New York State Design System. Exposes NYSDS components, design tokens, and documentation to AI assistants.
 
 > [!WARNING]
-> This MCP server is a work-in-progress and the current results are incomplete or inaccurate. The server is functional, but the quality of the output depends on the robustness of the underlying documentation, which requires some updating. Our team is in the process of migrating design tokens to the [DTCG 2025.10 format](https://www.designtokens.org/tr/2025.10/format/) (will be @nysds/tokens) and enhancing component JSDoc with patterns, accessibility guidance, and usage rules based on guidance from ["Effective Writing for AI" by Benny Powers](https://bennypowers.dev/cem/docs/mcp/writing-descriptions/). AI results should improve significantly as tokens and improved documentation rolls out.
+> This MCP server is a work-in-progress and the current tool results are being refined. The server is functional, but the quality of the output depends on the robustness of the underlying documentation, and we're enhancing component JSDoc with patterns, accessibility guidance, and usage rules based on guidance from ["Effective Writing for AI" by Benny Powers](https://bennypowers.dev/cem/docs/mcp/writing-descriptions/).
 
 ## Installation
 
-> [!CAUTION]
-> This package is not yet published to npm. You must clone the repository and build locally until it is.
-
-Once it's cloned, run this command from the `/packages/mcp-server` directory:
-
 ```bash
-# Clone the repository
-git clone https://github.com/ITS-HCD/nysds nysds-mcp
-cd nysds-mcp
-
-# Switch to the MCP feature branch
-git checkout feature/mcp-server
-
-# Install dependencies (from repo root)
-npm install
+npx -y @nysds/mcp-server
+```
 
-# Build the MCP server
-npm run build --workspace=packages/mcp-server
+Or install globally:
 
-# Explore the MCP server with the MCP inspector
-cd packages
-npx @modelcontextprotocol/inspector node dist/index.js
+```bash
+npm install -g @nysds/mcp-server
+nysds-mcp
 ```
 
 ## Connecting to the MCP Server
 
-Once the MCP server is set up and built, your AI code assistant can automatically connect and communicate with it. You only need to set up the configuration. Each assistant has its own configuration format, but they all follow the same pattern: tell the assistant how to start the server (via `npx`), and it will automatically connect and use the available tools.
-
-> [!NOTE]
-> The "args" in these examples will change after the package is published to npm.
+Once the MCP server is installed, your AI code assistant can automatically connect and communicate with it. You only need to set up the configuration. Each assistant has its own configuration format, but they all follow the same pattern: tell the assistant how to start the server (via `npx`), and it will automatically connect and use the available tools.
 
 ### GitHub Copilot
 
@@ -46,8 +30,8 @@ MCP support in GitHub Copilot is available in VS Code. Add to your VS Code setti
 {
   "servers": {
     "nysds": {
-      "command": "node",
-      "args": ["/absolute/path/to/nysds-mcp/packages/mcp-server/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "@nysds/mcp-server"]
     }
   }
 }
@@ -66,8 +50,8 @@ Add to your Claude Desktop configuration:
 {
   "mcpServers": {
     "nysds": {
-      "command": "node",
-      "args": ["/absolute/path/to/nysds-mcp/packages/mcp-server/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "@nysds/mcp-server"]
     }
   }
 }
@@ -81,8 +65,8 @@ Add to your project's `.mcp.json`:
 {
   "mcpServers": {
     "nysds": {
-      "command": "node",
-      "args": ["/absolute/path/to/nysds-mcp/packages/mcp-server/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "@nysds/mcp-server"]
     }
   }
 }
@@ -98,8 +82,8 @@ Add to your Cursor MCP settings (`.cursor/mcp.json`):
 {
   "mcpServers": {
     "nysds": {
-      "command": "node",
-      "args": ["/absolute/path/to/nysds-mcp/packages/mcp-server/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "@nysds/mcp-server"]
     }
   }
 }
@@ -107,23 +91,29 @@ Add to your Cursor MCP settings (`.cursor/mcp.json`):
 
 ## Available Tools
 
-### P0 (Core)
+### Components
+
+| Tool | Description |
+|------|-------------|
+| `find_components` | Search for components by name/description, or list all (omit query) |
+| `get_component` | Full documentation for a specific component. Use `includeExamples: true` for code examples. |
+| `validate_component_api` | Validate that attributes/properties are valid for a component |
+
+### Design Tokens
 
 | Tool | Description |
 |------|-------------|
-| `list_components` | List all NYSDS components with summaries |
-| `get_component_docs` | Full documentation for a specific component |
-| `find_components` | Search components by name/description |
-| `get_design_tokens` | Get token values by category |
-| `get_usage_guide` | Installation and usage patterns |
+| `get_tokens` | Get tokens, categories, or agency themes. Filter by category or layer. |
+| `find_tokens` | Search tokens by CSS variable name, value, or description |
+| `get_token_info` | Detailed info for a specific token with optional context validation |
+| `get_token_graph` | Token dependency graph showing references and usage |
 
-### P1 (Extended)
+### Styles & Guides
 
 | Tool | Description |
 |------|-------------|
-| `validate_component_api` | Validate prop/attribute usage |
-| `setup_framework` | Framework-specific setup guides |
-| `find_tokens` | Search tokens by name/value |
+| `get_utility_classes` | Grid, flexbox, spacing, display, and typography utility classes |
+| `get_guide` | Guides for installation, forms, styles, fonts, page structure, or framework setup (angular, react, dotnet, drupal, vanilla). Angular, React, .NET, and Drupal guides are currently untested. |
 
 ## Available Resources
 
@@ -131,7 +121,13 @@ Add to your Cursor MCP settings (`.cursor/mcp.json`):
 |-----|-------------|
 | `nysds://components` | Component overview list |
 | `nysds://component/{tag}` | Individual component docs |
-| `nysds://tokens` | All design tokens |
+| `nysds://tokens` | All design tokens with CSS variables and descriptions |
+| `nysds://tokens/css` | Raw tokens.css file content |
+| `nysds://tokens/graph` | Token dependency graph with stats |
+| `nysds://tokens/color` | Color tokens only |
+| `nysds://tokens/font` | Typography tokens |
+| `nysds://tokens/space` | Spacing tokens |
+| `nysds://tokens/size` | Size tokens |
 | `nysds://installation` | Installation guide |
 
 ## Prompts
@@ -162,7 +158,7 @@ Once configured, you can ask your AI assistant questions like:
 **Framework integration:**
 - "How do I set up NYSDS components in my Angular project?"
 - "Show me how to use nys-button in React"
-- "What's the recommended way to integrate NYSDS with Vue?"
+- "How do I integrate NYSDS with Drupal?"
 
 **Code review:**
 - "Is this the correct way to use the nys-select component?"

package/data/guides/fonts.md

@@ -0,0 +1,77 @@
+# NYSDS Font Setup Guide
+
+## Overview
+
+NYSDS uses proprietary fonts that are licensed for New York State government use. These fonts are distributed through a private repository.
+
+## Obtaining Fonts
+
+The NYSDS font package is available through a private npm registry. Contact the NYSDS team for access:
+
+1. Request access to the private font repository
+2. Configure your npm to use the private registry
+3. Install the font package
+
+## Manual Installation
+
+If you have the font files:
+
+1. Place font files in your project (e.g., `/assets/fonts/`)
+2. Include the font CSS in your stylesheet
+3. The fonts will be loaded automatically when using NYSDS styles
+
+### Directory Structure
+```
+/assets/fonts/
+├── proxima-nova/
+│   ├── proxima-nova-regular.woff2
+│   ├── proxima-nova-medium.woff2
+│   ├── proxima-nova-semibold.woff2
+│   └── proxima-nova-bold.woff2
+└── d-din/
+    ├── d-din-regular.woff2
+    └── d-din-bold.woff2
+```
+
+## Font Tokens
+
+NYSDS provides the following font family tokens:
+
+| Token | Description | Usage |
+|-------|-------------|-------|
+| `--nys-font-body` | Body text font | Paragraphs, general content |
+| `--nys-font-heading` | Heading font | h1-h6 elements |
+| `--nys-font-ui` | UI font | Buttons, labels, form elements |
+| `--nys-font-display` | Display font | Large headlines, hero text |
+| `--nys-font-brand` | Brand font | Brand-specific usage |
+| `--nys-font-alt` | Alternative font | Secondary content |
+
+### Usage Example
+```css
+.custom-heading {
+  font-family: var(--nys-font-heading);
+  font-weight: 600;
+}
+```
+
+## Font Preloading
+
+For optimal performance, preload critical fonts in your HTML head:
+
+```html
+<link rel="preload" href="/assets/fonts/proxima-nova/proxima-nova-regular.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="preload" href="/assets/fonts/proxima-nova/proxima-nova-semibold.woff2" as="font" type="font/woff2" crossorigin>
+```
+
+## Fallback Fonts
+
+NYSDS includes system font fallbacks. If custom fonts are unavailable, the design system will gracefully degrade to:
+
+- **Sans-serif:** -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial
+- **Monospace:** "SF Mono", Consolas, "Liberation Mono", Menlo, monospace
+
+## Getting Access
+
+To request access to the NYSDS font package, contact the NYSDS team through:
+- The NYS Digital Services team
+- Your agency's designated NYSDS contact

package/data/guides/form-validation.md

@@ -0,0 +1,169 @@
+# NYSDS Form Validation Guide
+
+## Overview
+
+NYSDS form components include built-in validation support using the `showError` and `errorMessage` properties. All form components integrate with ElementInternals for native form validation.
+
+## Error Display Properties
+
+All NYSDS form components support these validation properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `showError` | boolean | When true, displays the error state |
+| `errorMessage` | string | The error message to display |
+| `required` | boolean | Marks the field as required |
+
+## Error Summary Pattern
+
+Display an error summary at the top of forms with links to each field:
+
+```html
+<nys-alert type="danger" heading="Please correct the following errors">
+  <ul>
+    <li><a href="#email-field">Email address is required</a></li>
+    <li><a href="#phone-field">Phone number format is invalid</a></li>
+  </ul>
+</nys-alert>
+```
+
+This pattern:
+- Appears at the top of the form after submission attempt
+- Lists all errors with anchor links to the fields
+- Helps users quickly navigate to problem areas
+- Is essential for accessibility (screen reader users)
+
+## Inline Error Pattern
+
+Display errors directly on the form fields:
+
+```html
+<nys-textinput
+  id="email-field"
+  label="Email"
+  required
+  showError
+  errorMessage="Please enter a valid email address"
+></nys-textinput>
+
+<nys-select
+  id="state-field"
+  label="State"
+  required
+  showError
+  errorMessage="Please select a state"
+></nys-select>
+
+<nys-radiogroup
+  id="preference-field"
+  label="Contact Preference"
+  showError
+  errorMessage="Please select a contact preference"
+>
+  <nys-radiobutton label="Email" value="email"></nys-radiobutton>
+  <nys-radiobutton label="Phone" value="phone"></nys-radiobutton>
+</nys-radiogroup>
+```
+
+## Complete Form Example
+
+```html
+<form id="contact-form" novalidate>
+  <!-- Error summary (hidden initially, shown on validation failure) -->
+  <nys-alert id="error-summary" type="danger" heading="Please correct the following errors" hidden>
+    <ul id="error-list"></ul>
+  </nys-alert>
+
+  <nys-textinput
+    id="name-field"
+    label="Full Name"
+    required
+    class="nys-margin-b-300"
+  ></nys-textinput>
+
+  <nys-textinput
+    id="email-field"
+    label="Email Address"
+    type="email"
+    required
+    class="nys-margin-b-300"
+  ></nys-textinput>
+
+  <nys-textarea
+    id="message-field"
+    label="Message"
+    required
+    class="nys-margin-b-400"
+  ></nys-textarea>
+
+  <nys-button type="submit" label="Submit"></nys-button>
+</form>
+```
+
+## JavaScript Validation Example
+
+```javascript
+const form = document.getElementById('contact-form');
+const errorSummary = document.getElementById('error-summary');
+const errorList = document.getElementById('error-list');
+
+form.addEventListener('submit', (e) => {
+  e.preventDefault();
+
+  const errors = [];
+
+  // Validate each field
+  const nameField = document.getElementById('name-field');
+  if (!nameField.value) {
+    nameField.showError = true;
+    nameField.errorMessage = 'Full name is required';
+    errors.push({ id: 'name-field', message: 'Full name is required' });
+  } else {
+    nameField.showError = false;
+  }
+
+  const emailField = document.getElementById('email-field');
+  if (!emailField.value) {
+    emailField.showError = true;
+    emailField.errorMessage = 'Email address is required';
+    errors.push({ id: 'email-field', message: 'Email address is required' });
+  } else if (!isValidEmail(emailField.value)) {
+    emailField.showError = true;
+    emailField.errorMessage = 'Please enter a valid email address';
+    errors.push({ id: 'email-field', message: 'Please enter a valid email address' });
+  } else {
+    emailField.showError = false;
+  }
+
+  // Show/hide error summary
+  if (errors.length > 0) {
+    errorList.innerHTML = errors
+      .map(err => `<li><a href="#${err.id}">${err.message}</a></li>`)
+      .join('');
+    errorSummary.hidden = false;
+    errorSummary.scrollIntoView({ behavior: 'smooth' });
+  } else {
+    errorSummary.hidden = true;
+    form.submit();
+  }
+});
+```
+
+## Form Components with Validation Support
+
+The following NYSDS components support `showError` and `errorMessage`:
+
+- `nys-textinput` - Text input fields
+- `nys-textarea` - Multi-line text areas
+- `nys-select` - Dropdown selects
+- `nys-radiogroup` - Radio button groups
+- `nys-checkbox` - Checkboxes
+- `nys-checkboxgroup` - Checkbox groups
+- `nys-date` - Date pickers
+
+## Accessibility Considerations
+
+1. **Error summary links**: Include anchor links to fields for keyboard navigation
+2. **Focus management**: Move focus to error summary or first error field on validation failure
+3. **ARIA attributes**: NYSDS components automatically set `aria-invalid` and `aria-describedby`
+4. **Clear error messages**: Use specific, actionable error text

package/data/guides/frameworks/angular.md

@@ -0,0 +1,71 @@
+# NYSDS with Angular
+
+> **Note:** Angular integration is currently untested. The guidance below is based on standard web component usage patterns and may require adjustments.
+
+## Installation
+
+```bash
+npm install @nysds/components @nysds/styles
+```
+
+## Load styles
+
+Add the NYSDS stylesheet to `angular.json`:
+
+```json
+{
+  "projects": {
+    "your-app": {
+      "architect": {
+        "build": {
+          "options": {
+            "styles": [
+              "node_modules/@nysds/styles/dist/nysds-full.min.css",
+              "src/styles.css"
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Use `nysds-full.min.css` for new projects (includes reset, typography, and utilities) or `nysds.min.css` for existing projects (CSS variables only).
+
+## Configuration
+
+Add `CUSTOM_ELEMENTS_SCHEMA` to your module so Angular allows custom element tags:
+
+```typescript
+import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
+
+@NgModule({
+  schemas: [CUSTOM_ELEMENTS_SCHEMA]
+})
+export class AppModule {}
+```
+
+For standalone components:
+
+```typescript
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+
+@Component({
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `<nys-button label="Click me"></nys-button>`
+})
+export class MyComponent {}
+```
+
+## Usage
+
+Import components in the component or module where they're used:
+
+```typescript
+import '@nysds/nys-button';
+```
+
+```html
+<nys-button label="Click me"></nys-button>
+```

package/data/guides/frameworks/dotnet.md

@@ -0,0 +1,42 @@
+# NYSDS with .NET / Blazor
+
+> **Note:** .NET / Blazor integration is currently untested. The guidance below is based on standard web component usage patterns and may require adjustments.
+
+## Installation
+
+Add the NYSDS scripts and styles to your layout file (e.g., `_Layout.cshtml` or `App.razor`).
+
+Install via npm:
+
+```bash
+npm install @nysds/components @nysds/styles
+```
+
+Then reference in your layout:
+
+```html
+<head>
+  <!-- New project: includes reset, typography, and utility classes -->
+  <link rel="stylesheet" href="node_modules/@nysds/styles/dist/nysds-full.min.css" />
+
+  <!-- Existing project: CSS variables only -->
+  <!-- <link rel="stylesheet" href="node_modules/@nysds/styles/dist/nysds.min.css" /> -->
+
+  <script type="module" src="node_modules/@nysds/components/dist/nysds.es.js"></script>
+</head>
+```
+
+## Usage in Razor
+
+```razor
+<nys-button label="Click me"></nys-button>
+<nys-alert type="info">This is an informational message.</nys-alert>
+```
+
+## Usage in Blazor
+
+Blazor treats unknown elements as custom elements by default. No additional configuration is needed:
+
+```razor
+<nys-button label="Submit" variant="filled"></nys-button>
+```

package/data/guides/frameworks/drupal.md

@@ -0,0 +1,39 @@
+# NYSDS with Drupal
+
+> **Note:** Drupal integration is currently untested. The guidance below is based on standard web component usage patterns and may require adjustments.
+
+## Installation
+
+Install the packages:
+
+```bash
+npm install @nysds/components @nysds/styles
+```
+
+Add the NYSDS styles and scripts to your theme's `*.libraries.yml`:
+
+```yaml
+nysds:
+  css:
+    theme:
+      # New project: includes reset, typography, and utility classes
+      /node_modules/@nysds/styles/dist/nysds-full.min.css: { minified: true }
+      # Existing project: CSS variables only
+      # /node_modules/@nysds/styles/dist/nysds.min.css: { minified: true }
+  js:
+    /node_modules/@nysds/components/dist/nysds.es.js: { attributes: { type: module } }
+```
+
+Then attach the library in your theme's `.info.yml`:
+
+```yaml
+libraries:
+  - mytheme/nysds
+```
+
+## Usage in Twig
+
+```twig
+<nys-button label="{{ 'Click me'|t }}"></nys-button>
+<nys-alert type="info">{{ 'This is an alert.'|t }}</nys-alert>
+```

package/data/guides/frameworks/react.md

@@ -0,0 +1,45 @@
+# NYSDS with React
+
+> **Note:** React integration is currently untested. The guidance below is based on standard web component usage patterns and may require adjustments.
+
+## Installation
+
+```bash
+npm install @nysds/components @nysds/styles
+```
+
+## Load styles
+
+Import the NYSDS stylesheet in your app entry point (e.g., `index.tsx` or `App.tsx`):
+
+```tsx
+// New project: includes reset, typography, and utility classes
+import '@nysds/styles/dist/nysds-full.min.css';
+
+// Existing project: CSS variables only (styles components, nothing else)
+// import '@nysds/styles/dist/nysds.min.css';
+```
+
+## Usage
+
+Import components and use them in JSX:
+
+```tsx
+import '@nysds/nys-button';
+import '@nysds/nys-alert';
+
+function App() {
+  return (
+    <div>
+      <nys-button label="Click me"></nys-button>
+      <nys-alert type="info">This is an alert.</nys-alert>
+    </div>
+  );
+}
+```
+
+## Notes on web components in React
+
+- String attributes work normally: `<nys-button label="Click me" />`
+- For event listeners, use `ref` and `addEventListener` — React's synthetic event system doesn't forward to custom elements
+- Boolean attributes should be set explicitly: `<nys-button disabled={true} />`

package/data/guides/frameworks/vanilla.md

@@ -0,0 +1,45 @@
+# NYSDS with Vanilla JavaScript
+
+## Installation
+
+```bash
+npm install @nysds/components @nysds/styles
+```
+
+## Load styles
+
+Choose the right stylesheet for your project:
+
+```html
+<!-- New project: includes reset, typography, and utility classes -->
+<link rel="stylesheet" href="node_modules/@nysds/styles/dist/nysds-full.min.css" />
+
+<!-- Existing project: CSS variables only (styles components, nothing else) -->
+<link rel="stylesheet" href="node_modules/@nysds/styles/dist/nysds.min.css" />
+```
+
+## Usage
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <link rel="stylesheet" href="node_modules/@nysds/styles/dist/nysds-full.min.css" />
+  <script type="module">
+    import '@nysds/components';
+  </script>
+</head>
+<body>
+  <nys-button label="Click me"></nys-button>
+</body>
+</html>
+```
+
+You can also import individual components to reduce bundle size:
+
+```html
+<script type="module">
+  import '@nysds/nys-button';
+  import '@nysds/nys-alert';
+</script>
+```