Instruction file imported from microsoft/atlas-design (.github/instructions/mcp.instructions.md). Copyright stays with the author.

Atlas MCP Server - Copilot Instructions

applyTo: "mcp/**"

This is the @microsoft/atlas-mcp package, a Model Context Protocol (MCP) server that exposes Atlas Design System resources — components, page-level patterns, atomic classes, design tokens, and code examples — to AI agents. Its primary job is to serve canonical HTML snippets so agents can build Atlas web pages; class-name and token data is supporting metadata.

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     # Loads the pre-bundled data/atlas-data.json at runtime
├── 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 Model Context Protocol SDK
• zod - Schema validation for tool inputs
• front-matter - Parse markdown frontmatter

Data pipeline

At build time, scripts/build-data.js bundles these sources into data/atlas-data.json. At runtime, the server reads only that bundle (see src/data/loader.ts):

• site/src/components/*.md - Component HTML examples
• site/src/patterns/*.md - Page-level pattern HTML examples
• site/src/atomics/*.md - Atomic utility HTML examples
• css/dist/class-names.json - Class names with color/size metadata (supporting)
• css/dist/tokens.json - Design tokens (supporting)

data/atlas-data.json is a generated artifact, not source: it is git-ignored (mcp/.gitignore), regenerated by npm run build:data, shipped in the npm package via package.json files, and rebuilt in CI and on prepublishOnly.

Only HTML code fences become examples (html, abut-html, html-no-indent, html-no-example), all normalized to html; CSS/SCSS fences are excluded. Each example keeps the nearest preceding doc heading as its title, so agents can request a snippet by intent. The goal is building HTML pages — not authoring CSS or suggesting class names.

Available Tools

1. get_composition_guide - How to assemble a page (layout → atomic containers → large components → small elements)
2. get_code_examples - Get canonical HTML snippets (component, pattern, or atomic) to build pages
3. list_components - List all components
4. list_patterns - List page-level patterns (multi-component HTML compositions)
5. list_atomics - List atomic classes by category
6. get_component - Get component details and HTML examples
7. search_classes - (Supporting) Search CSS classes by name or pattern
8. get_class_details - (Supporting) Get class color/size metadata

Available Resources

• atlas://composition - How to compose a page (layout → atomics → large → small)
• atlas://components - Component catalog
• atlas://patterns - Page-level patterns (HTML compositions)
• atlas://atomics - Atomic classes by category
• atlas://tokens - Design tokens

Coding Guidelines

1. Validate inputs with Zod - Define every tool input with a Zod schema.
2. Cache loaded data - Class names, tokens, and docs are cached in memory after first load.
3. Return JSON content - Return each tool result as JSON in the text field of an MCP content block.
4. Handle errors gracefully - Return helpful error messages instead of throwing.

When Making Changes

1. Run npm run build to verify compilation.
2. Test the server with the MCP Inspector or direct JSON-RPC calls.
3. Ensure data paths resolve from the compiled dist/ directory — this is the easiest thing to break.
4. Update README.md when adding or changing tools or resources.