@nysds/mcp-server 1.16.0-alpha5 → 1.16.0

package/README.md

@@ -5,22 +5,48 @@ MCP (Model Context Protocol) server for the New York State Design System. Expose
 > [!WARNING]
 > 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
 
-```bash
-npx -y @nysds/mcp-server
+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.
+
+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)
+
+### 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"]
 ```
 
-Or install globally:
+To go back to stable, just remove `@next`.
+
+> [!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.
+
+### Optional: Local Installation
+
+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 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.
+```bash
+npx -y @nysds/mcp-server
+```
+
+## 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
 
@@ -43,8 +69,8 @@ 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
 {
@@ -89,6 +115,23 @@ Add to your Cursor MCP settings (`.cursor/mcp.json`):
 }
 ```
 
+### 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
 
 ### Components
@@ -138,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"
-- "How do I integrate NYSDS with Drupal?"
+> 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/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@nysds/mcp-server",
-  "version": "1.16.0-alpha5",
+  "version": "1.16.0",
   "description": "MCP server for the New York State Design System. Exposes components, tokens, and documentation to AI assistants.",
   "type": "module",
   "bin": {
-    "nysds-mcp": "./dist/index.js"
+    "nysds-mcp": "dist/index.js"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,7 +22,7 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
-    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
+    "inspect": "npx -y @modelcontextprotocol/inspector node dist/index.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",