Add @microsoft/atlas-mcp package - MCP server for AI agents

.changeset/brave-pens-teach.md

@@ -0,0 +1,5 @@
+---
+'@microsoft/atlas-mcp': minor
+---
+
+Add Atlas MCP Server - a Model Context Protocol server that exposes Atlas Design System resources to AI agents and copilots. Provides tools for searching CSS classes, listing components and atomics, and retrieving code examples from documentation.

.github/instructions/mcp.instructions.md

@@ -0,0 +1,76 @@
+# Atlas MCP Server - Copilot Instructions
+
+applyTo: "mcp/**"
+
+This is the `@microsoft/atlas-mcp` package, a Model Context Protocol server that exposes Atlas Design System resources to AI agents.
+
+## Package Overview
+
+- **Name**: `@microsoft/atlas-mcp`
+- **Type**: MCP Server (private package)
+- **Build Tool**: TypeScript compiler (tsc)
+- **Transport**: stdio (for integration with AI agents)
+
+## Project Structure
+
+```
+mcp/
+├── src/
+│   ├── index.ts          # Entry point with stdio transport
+│   ├── server.ts         # MCP server setup, tools, and resources
+│   └── data/
+│       └── loader.ts     # Data loading from css/dist and site/src
+├── dist/                 # Compiled JavaScript output
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Key Commands
+
+- `npm run build` - Compile TypeScript to JavaScript
+- `npm run dev` - Watch mode for development
+- `npm run start` - Run the MCP server
+
+## Dependencies
+
+- `@modelcontextprotocol/sdk` - Official MCP SDK
+- `zod` - Schema validation for tool inputs
+- `front-matter` - Parse markdown frontmatter
+
+## Data Sources
+
+The server reads from:
+- `css/dist/class-names.json` - All CSS class names with metadata
+- `css/dist/tokens.json` - Design tokens
+- `site/src/components/*.md` - Component documentation
+- `site/src/atomics/*.md` - Atomic class documentation
+
+## Available Tools
+
+1. **search_classes** - Search CSS classes by pattern
+2. **get_component** - Get component details and examples
+3. **get_code_examples** - Get HTML/CSS code snippets
+4. **list_components** - List all components
+5. **list_atomics** - List atomic classes by category
+6. **get_class_details** - Get class color/size metadata
+
+## Available Resources
+
+- `atlas://components` - Component catalog
+- `atlas://atomics` - Atomic classes by category
+- `atlas://tokens` - Design tokens
+
+## Coding Guidelines
+
+1. **Use Zod for schemas** - All tool inputs use Zod validation
+2. **Cache loaded data** - Data is cached in memory for performance
+3. **Return JSON content** - Tools return JSON in text content blocks
+4. **Handle errors gracefully** - Return helpful error messages
+
+## When Making Changes
+
+1. Run `npm run build` to verify compilation
+2. Test with MCP inspector or direct JSON-RPC calls
+3. Ensure data paths resolve correctly relative to dist/
+4. Update README.md if adding new tools or resources

.github/workflows/main.yml

@@ -50,6 +50,11 @@ jobs:
         run: |
           npm run build:css;
 
+      # Build MCP server
+      - name: Build MCP
+        run: |
+          npm run build -w @microsoft/atlas-mcp;
+
       # Run build for tokens and website
       - name: Build site
         run: |

README.md

@@ -68,6 +68,56 @@ Behaviors and elements beyond the scope of CSS are found in the `/js` folder.
 npm install --save @microsoft/atlas-js
 ```
 
+## Using Atlas with AI Agents
+
+The Atlas MCP Server exposes Atlas Design System resources to AI agents and copilots via the [Model Context Protocol](https://modelcontextprotocol.io/). This helps AI assistants discover and use Atlas CSS classes, components, and design tokens in your projects.
+
+### Install via npm
+
+```sh
+npm install -g @microsoft/atlas-mcp
+```
+
+### Configure with GitHub Copilot
+
+Add to your `.github/copilot-mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "atlas": {
+      "command": "npx",
+      "args": ["-y", "@microsoft/atlas-mcp"]
+    }
+  }
+}
+```
+
+### Configure with Claude Desktop
+
+Add to your Claude configuration:
+
+```json
+{
+  "mcpServers": {
+    "atlas": {
+      "command": "npx",
+      "args": ["-y", "@microsoft/atlas-mcp"]
+    }
+  }
+}
+```
+
+### Available Tools
+
+- **search_classes** - Search 1200+ CSS classes by name or pattern
+- **get_component** - Get component details with code examples
+- **list_components** - List all available components
+- **list_atomics** - List atomic utility classes by category
+- **get_code_examples** - Get HTML/CSS code snippets from documentation
+
+See `/mcp/README.md` for full documentation.
+
 ## Contributing
 
 While this project is open source, its primary purpose is to serve Microsoft web properties through a CSS-first implementation of a design system. We do appreciate contributions to our documentation (`/site` folder), our framework (`/css`), and its companion scripts (`/js`).

mcp/README.md

@@ -0,0 +1,147 @@
+# Atlas MCP Server
+
+A Model Context Protocol (MCP) server that exposes Atlas Design System resources to AI agents and copilots.
+
+## Overview
+
+This MCP server provides tools and resources for discovering and using Atlas CSS classes, components, and design tokens. It enables AI assistants to help developers use Atlas effectively in their projects.
+
+## Installation
+
+### Via npm (recommended for external users)
+
+```bash
+npm install -g @microsoft/atlas-mcp
+```
+
+Or run directly with npx (no installation required):
+
+```bash
+npx @microsoft/atlas-mcp
+```
+
+### From source (for contributors)
+
+From the repository root:
+
+```bash
+npm install
+npm run build -w @microsoft/atlas-mcp
+```
+
+## Configuration
+
+### GitHub Copilot CLI
+
+Add to your project's `.github/copilot-mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "atlas": {
+      "command": "npx",
+      "args": ["-y", "@microsoft/atlas-mcp"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+### `search_classes`
+Search Atlas CSS classes by name or pattern.
+
+**Parameters:**
+- `query` (string, required): Search query to match against class names
+- `category` (string, optional): Filter by "component" or "atomic"
+- `limit` (number, optional): Maximum results (default: 50, max: 100)
+
+**Example:** Search for button-related classes
+```
+search_classes({ query: "button", category: "component" })
+```
+
+### `get_component`
+Get detailed information about a specific Atlas component.
+
+**Parameters:**
+- `name` (string, required): Component name (e.g., "button", "card", "badge")
+
+**Example:** Get button component details
+```
+get_component({ name: "button" })
+```
+
+### `get_code_examples`
+Get HTML/CSS code examples for a component or atomic category.
+
+**Parameters:**
+- `name` (string, required): Component or atomic category name
+- `type` (string, optional): "component" or "atomic"
+
+**Example:** Get spacing examples
+```
+get_code_examples({ name: "spacing", type: "atomic" })
+```
+
+### `list_components`
+List all available Atlas components with descriptions.
+
+**Example:**
+```
+list_components({})
+```
+
+### `list_atomics`
+List Atlas atomic utility classes by category.
+
+**Parameters:**
+- `category` (string, optional): One of: spacing, color, display, flex, typography, border, background, position, size, other
+
+**Example:** List all spacing classes
+```
+list_atomics({ category: "spacing" })
+```
+
+### `get_class_details`
+Get detailed information about a specific CSS class including theme colors and size values.
+
+**Parameters:**
+- `className` (string, required): The CSS class name
+
+**Example:** Get details for color-primary
+```
+get_class_details({ className: "color-primary" })
+```
+
+## Available Resources
+
+### `atlas://components`
+Full catalog of Atlas components with metadata.
+
+### `atlas://atomics`
+All atomic utility classes organized by category (spacing, color, display, flex, typography, border, background, position, size).
+
+### `atlas://tokens`
+Design tokens including colors, spacing, typography, shadows, and more.
+
+## Development
+
+```bash
+# Build the MCP server
+npm run build -w @microsoft/atlas-mcp
+
+# Watch mode for development
+npm run dev -w @microsoft/atlas-mcp
+```
+
+## Prerequisites
+
+The MCP server requires built Atlas CSS artifacts. Ensure you've run:
+
+```bash
+npm run build:css
+npm run build:class-names
+```
+
+These commands generate `css/dist/class-names.json` and `css/dist/tokens.json` which the MCP server reads.