@nysds/mcp-server 1.16.0-alpha4 → 1.16.0

package/README.md

@@ -3,40 +3,50 @@
 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
+## Getting Started
 
-> [!CAUTION]
-> This package is not yet published to npm. You must clone the repository and build locally until it is.
+No installation is required. The MCP server runs on-demand via `npx` — your AI assistant downloads and starts it automatically when you add the configuration below. You just need [Node.js](https://nodejs.org/) (v18 or later) installed on your machine.
 
-Once it's cloned, run this command from the `/packages/mcp-server` directory:
+Jump to the configuration for your assistant:
+- [GitHub Copilot](#github-copilot)
+- [Claude Desktop](#claude-desktop)
+- [Claude Code](#claude-code)
+- [Cursor](#cursor)
+- [Gemini CLI](#gemini-cli)
 
-```bash
-# Clone the repository
-git clone https://github.com/ITS-HCD/nysds nysds-mcp
-cd nysds-mcp
+### Using the Next Channel
+
+To pull in the latest bleeding-edge changes before they hit the stable release, point to the `next` dist-tag by replacing `@nysds/mcp-server` with `@nysds/mcp-server@next` in any of the configurations below. For example:
+
+```json
+"args": ["-y", "@nysds/mcp-server@next"]
+```
 
-# Switch to the MCP feature branch
-git checkout feature/mcp-server
+To go back to stable, just remove `@next`.
 
-# Install dependencies (from repo root)
-npm install
+> [!NOTE]
+> Next releases may include breaking changes, incomplete features, or components not fully supported. They're useful for previewing upcoming work, but stick with the stable channel for production use.
 
-# Build the MCP server
-npm run build --workspace=packages/mcp-server
+### Optional: Local Installation
 
-# Explore the MCP server with the MCP inspector
-cd packages
-npx @modelcontextprotocol/inspector node dist/index.js
+If you prefer to install the server locally — for example, to use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) or to pin a specific version — you can install it globally:
+
+```bash
+npm install -g @nysds/mcp-server
+nysds-mcp
 ```
 
-## Connecting to the MCP Server
+Or run it directly without installing:
 
-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.
+```bash
+npx -y @nysds/mcp-server
+```
 
-> [!NOTE]
-> The "args" in these examples will change after the package is published to npm.
+## Connecting to Your AI Assistant
+
+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 handles the rest.
 
 ### GitHub Copilot
 
@@ -46,8 +56,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"]
     }
   }
 }
@@ -59,15 +69,15 @@ See the [Copilot MCP documentation](https://docs.github.com/en/copilot/using-git
 
 Add to your Claude Desktop configuration:
 
-- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
-- Windows: %APPDATA%\Claude\claude_desktop_config.json
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
   "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 +91,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,32 +108,55 @@ 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"]
     }
   }
 }
 ```
 
+### Gemini CLI
+
+Add to your Gemini CLI settings file (`~/.gemini/settings.json`) or your project's `.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "nysds": {
+      "command": "npx",
+      "args": ["-y", "@nysds/mcp-server"]
+    }
+  }
+}
+```
+
+See the [Gemini CLI documentation](https://github.com/google-gemini/gemini-cli) for the latest setup instructions.
+
 ## 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 +164,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
@@ -142,28 +181,40 @@ Add to your Cursor MCP settings (`.cursor/mcp.json`):
 
 ## Example Prompts
 
-Once configured, you can ask your AI assistant questions like:
+Once configured, you can ask your AI assistant to help you build real applications with the design system.
+
+**Building applications from requirements:**
+
+> Read the PDF from this folder and create a PRD for a multi-step front end application. Use the NYS Design System. Build with Vite and TypeScript. Break up the tasks into a step-by-step list. Before you start, ask any clarifying questions to do this task well.
+
+> Build out a newsletter signup form using the NYS Design System. Use existing DS components where possible. Where not, build new components using the same approach as existing components, and style with appropriate NYSDS design tokens and utility classes. Afterward, perform a gap analysis that documents everything not in the design system that was created.
+
+**Scaffolding and setup:**
+
+> Set up a new Vite project with TypeScript and install the NYS Design System. Configure it with the correct fonts, tokens, and page structure. Show me a working hello world page that follows the NYSDS page layout guide.
+
+> I have an existing .NET Razor Pages app. Walk me through integrating NYSDS components into it step by step.
+
+**Building pages and features:**
+
+> Build a search results page with a text input, filters using checkboxes and selects, and a results list. Use NYSDS components for all form elements and follow the grid system for layout.
+
+> Create an accessible multi-step wizard form for a permit application with validation on each step. Use NYSDS form components and show error states using the design system's error patterns.
+
+**Working with design tokens and theming:**
+
+> I'm building a page for the Department of Health. Show me how to apply their agency theme using NYSDS tokens, and build a dashboard header that uses the correct brand colors.
+
+> Show me all the spacing tokens available and explain the scale. Then refactor this layout to use NYSDS spacing tokens instead of hardcoded values.
+
+**Code review and validation:**
 
-**Discovering components:**
-- "What NYSDS components are available for forms?"
-- "Show me the documentation for the nys-button component"
-- "What properties does nys-alert support?"
+> Review this HTML page and identify everywhere I'm using NYSDS components incorrectly — wrong attributes, missing required properties, or deprecated patterns.
 
-**Building UI:**
-- "Create a contact form using NYSDS components with fields for name, email, and message"
-- "Build a page header with the global header component and navigation"
-- "Add form validation to this input using NYSDS error message components"
+> Check if I'm using the right token layers. I want to make sure my component-level styles reference the correct semantic tokens instead of raw values.
 
-**Working with tokens:**
-- "What color tokens are available in NYSDS?"
-- "Show me the spacing tokens I should use for consistent layouts"
-- "What's the correct token for the primary brand color?"
+**Exploring the system:**
 
-**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?"
+> What NYSDS components are available for forms? Show me the documentation for each one with code examples.
 
-**Code review:**
-- "Is this the correct way to use the nys-select component?"
-- "Check if I'm using valid attributes on this nys-checkbox"
+> Show me the token dependency graph for the primary color. I want to understand how the base, semantic, and component layers connect.

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>
+```