# CTT Design System MCP Server

MCP (Model Context Protocol) server that enables AI agents, especially GitHub Copilot, to understand and correctly use CTT Design System components.

## 🚀 Quick Start

**See [QUICKSTART.md](./QUICKSTART.md) for a 3-step setup guide.**

## 📦 What is this?

This MCP server provides AI coding assistants with structured documentation about CTT Design System components, including:

- **Component API**: Properties, types, defaults, and descriptions
- **Usage Guidance**: Real documentation and usage guidelines extracted from Storybook stories
- **Target-Aware Examples**: Framework-specific examples for React, Web Components, TypeScript, and plain HTML
- **Events**: Custom events dispatched by components
- **Best Practices**: When to use and when not to use each component
- **Accessibility**: Built-in a11y features

## 📦 Installation

### 1. Install dependencies

```bash
cd mcp-server
npm install
```

### 2. Generate component documentation

```bash
npm run generate
```

This extracts component information from source files and Storybook stories, creating a catalog in `data/components.json`.

### 3. Build the server

```bash
npm run build
```

## 🔧 Usage

### Development

```bash
npm run dev
```

### Production

```bash
npm start
```

### Running The Binary

Inside this repository, run the built server directly:

```bash
node mcp-server/dist/index.js
```

From npm via `npx`, use the published package name and binary name:

```bash
npx --package ctt-web-components ctt-mcp-server
```

## 🤖 Integrating with GitHub Copilot

For consumers of the published package, prefer `npx` with the package name `ctt-web-components`.

### Cursor

Add this MCP server in Cursor:

```json
{
  "name": "CTT Design System",
  "type": "command",
  "command": "npx --package ctt-web-components ctt-mcp-server"
}
```

### Claude Desktop

Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ctt": {
      "command": "npx",
      "args": ["--package", "ctt-web-components", "ctt-mcp-server"]
    }
  }
}
```

### GitHub Copilot

For installed users outside this repository, use an `npx`-based command.

```json
{
  "github.copilot.chat.agent.mcpServers": [
    {
      "name": "ctt-design-system",
      "command": "npx",
      "args": ["--package", "ctt-web-components", "ctt-mcp-server"]
    }
  ]
}
```

### GitHub Copilot In This Repository

If you are developing inside this repository, using the local built path is still useful.

### Option 1: VS Code Workspace Settings

Add to `.vscode/settings.json`:

```json
{
  "github.copilot.chat.agent.mcpServers": [
    {
      "name": "ctt-design-system",
      "command": "node",
      "args": ["${workspaceFolder}/mcp-server/dist/index.js"]
    }
  ]
}
```

### Option 2: Copilot Configuration

Create `.github/copilot/mcp.json`:

```json
{
  "servers": [
    {
      "name": "ctt-design-system",
      "command": "node",
      "args": ["${workspaceFolder}/mcp-server/dist/index.js"]
    }
  ]
}
```

## 🛠️ Available Tools

### `components_list`

List all available components.

**Parameters:**
- `category` (optional): Filter by category
- `target` (optional): preferred consumer target for usage hints in the results

**Example:**
```
List all CTT components
List components in "Form Inputs" category
List components for a React TypeScript app
```

### `components_get`

Get detailed documentation for a specific component.

**Parameters:**
- `name`: Component name (e.g., "Button", "InputText")
- `target` (optional): `react-ts` | `react-js` | `web-components-ts` | `web-components-js` | `html`
- `path` (optional): workspace file or directory path used to infer target when `target` is omitted

**Example:**
```
Get documentation for Button component
Show me the InputText component API
Get Button for env-tests/react-ts/src/App.tsx
```

### `components_search`

Search for components by functionality.

**Parameters:**
- `query`: Search query
- `target` (optional): preferred output target

**Example:**
```
Find a button component with icons
Search for text input with validation
Search for components for a React dashboard
```

### `project_detect_environment`

Detect whether a consumer project path should receive React wrappers, custom elements, TypeScript examples, or plain HTML.

**Parameters:**
- `path` (optional): file or directory path in the consumer app

**Example:**
```
Detect environment for env-tests/react-ts/src/App.tsx
```

## 📚 Resources

- `components://catalog` - Full component catalog
- `components://{name}` - Individual component documentation (e.g., `components://Button`)

## 📋 Example Interaction

**User asks Copilot:**
> "Add a primary button with an icon on the left"

**Copilot queries MCP:**
```
components_get({ name: "Button", path: "env-tests/react-ts/src/App.tsx" })
```

**MCP returns:**
```markdown
# Button (ctt-button)
**Category:** Actions
**Target:** react-ts

### Imports
```tsx
import { ButtonCtt } from 'ctt-web-components/react';
```

### Example
```tsx
<ButtonCtt variant="primary" label="Click me" />
```
```

**Copilot generates:**
```tsx
import { ButtonCtt } from 'ctt-web-components/react';

<ButtonCtt variant="primary" label="Submit Form" />
```

## 🧪 Testing Against Real Consumer Environments

The repository includes fixture consumers in [`env-tests/`](../env-tests/README.md):

- `env-tests/react-ts/` for React + TypeScript
- `env-tests/web-components-ts/` for custom elements + TypeScript
- `env-tests/html/` for plain HTML

Use them to validate that the MCP server returns the right integration mode:

```text
project_detect_environment({ "path": "env-tests/react-ts/src/App.tsx" })
components_get({ "name": "Button", "path": "env-tests/react-ts/src/App.tsx" })
components_get({ "name": "Button", "path": "env-tests/web-components-ts/src/main.ts" })
components_get({ "name": "Button", "path": "env-tests/html/index.html" })
```

Expected behavior:

- React fixture: import from `ctt-web-components/react`
- Web Components fixture: use `ctt-button` plus `ctt-web-components/register`
- HTML fixture: return direct HTML markup plus registration script

## 🏗️ Architecture

```
mcp-server/
├── src/
│   ├── index.ts              # Main entry point
│   ├── server.ts             # MCP server & tools
│   ├── parsers/
│   │   └── extractor.ts      # Component doc extractor
│   └── types/
│       └── component.ts      # Type definitions
├── scripts/
│   └── extract-components.js # Documentation generator
├── data/
│   └── components.json       # Generated catalog
└── package.json
```

## 🔄 Updating the Catalog

The MCP server automatically discovers all components in `src/components/` that have an associated Storybook story. 

To refresh the catalog after adding a new component or updating documentation:

1. Ensure the new component has a `.ts` source file and a `.stories.ts` file.
2. Run the generation script:
   ```bash
   npm run generate
   ```
3. Rebuild the server:
   ```bash
   npm run build
   ```

## 🎯 Current Components

The generated catalog currently includes all **27 components** of the CTT Design System.

The server is target-aware and automatically extracts properties, events, and usage guidelines directly from the source code and Storybook metadata.

## 📝 Component Catalog Schema

```typescript
interface ComponentDocumentation {
  name: string;              // Component class name
  tag: string;               // HTML custom element tag
  category: string;          // Component category
  description: string;       // Full description
  usage: string;             // Usage notes extracted from stories
  whenToUse?: string;        // Usage guidelines
  whenNotToUse?: string;     // Anti-patterns
  properties: Array<{        // Component props
    name: string;
    type: string;
    defaultValue?: string;
    description?: string;
    required?: boolean;
  }>;
  events: Array<{            // Custom events
    name: string;
    description?: string;
  }>;
  examples: Array<{          // Code examples
    name: string;
    code: string;
    language: string;
  }>;
  accessibility?: string;    // A11y features
}
```

## 🐛 Troubleshooting

### "Component catalog not found"
Run `npm run generate` to create the catalog.

### Copilot not recognizing MCP server
1. Check that the server builds successfully: `npm run build`
2. Verify the workspace path points to `mcp-server/dist/index.js`
3. If you want framework-aware output, pass a real app file path into `components_get` or `project_detect_environment`
4. `npx ctt-mcp-server` will 404 unless the binary is already installed locally; the npm package name is `ctt-web-components`
2. Verify the path in `.vscode/settings.json` is correct
3. Restart VS Code

### Component documentation missing
Ensure the component has:
- TypeScript source file with `@property` decorators
- Storybook stories with descriptions

## 📖 Usage Examples

**See [USAGE_STORY.md](./USAGE_STORY.md) for a complete real-world example of building a registration form.**

## 📄 License

MIT

## 🤝 Contributing

See main project CONTRIBUTING.md