# CTT Design System MCP — Consumer Guide

This guide is for developers who want their AI coding assistant (GitHub Copilot, Cursor, Claude Desktop, Claude Code, or any MCP-compatible client) to understand and correctly emit `ctt-web-components` markup.

If you are contributing to the design system itself, see [`README.md`](./README.md) and [`QUICKSTART.md`](./QUICKSTART.md) instead.

---

## Prerequisites

- **Node.js ≥ 20** (the server is built for Node 20; older versions will fail to start).
- The `ctt-web-components` package installed in your project, or network access so `npx` can fetch it on demand.
- An MCP-capable client (see [Wiring per client](#wiring-per-client)).

---

## What you get

The server exposes four tools and two resources over stdio:

| Tool | What it does |
|---|---|
| `components_list` | Returns all components in the catalog. Optional filters: `category`, `target`. |
| `components_get` | Returns full documentation + target-aware imports and examples for one component. Takes `name` and optional `target` / `path`. |
| `components_search` | Relevance-ranked search by name, tag, description, properties, and usage notes. |
| `project_detect_environment` | Infers framework (React / Web Components / HTML) and language (TS / JS) from a file path. |

| Resource | URI |
|---|---|
| Full catalog | `components://catalog` |
| One component | `components://{name}` (e.g. `components://Button`) |

**Target-aware output.** Pass `path` (a real file in your project) or an explicit `target` and the server will tailor the example: typed React wrappers for `.tsx` projects, custom-element tags for plain HTML, and so on.

---

## Verification (before wiring a client)

Confirm the binary resolves and the server starts cleanly. Run from any directory where `ctt-web-components` is installed — or with network access, from anywhere:

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

Expected stderr:

```
Starting CTT Design System MCP Server...
CTT Design System MCP Server running on stdio
```

The process will block waiting for MCP traffic on stdin. Press Ctrl+C to exit.

### End-to-end protocol check (optional)

Pipe a minimal MCP handshake to confirm tool registration without wiring up a client:

```bash
(printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'; sleep 1) \
  | npx --package ctt-web-components ctt-mcp-server 2>/dev/null
```

You should see two JSON responses on stdout — the second lists all four tools (`components_list`, `components_get`, `components_search`, `project_detect_environment`). If you see nothing, the server crashed before responding; drop `2>/dev/null` to see the error.

---

## Wiring per client

Use one of the snippets below. Every client invokes the same command: `npx --package ctt-web-components ctt-mcp-server`. The `--package` flag is required because the package name (`ctt-web-components`) is different from the binary name (`ctt-mcp-server`) — plain `npx ctt-mcp-server` will fail.

### GitHub Copilot (VS Code)

Add to your user or workspace `settings.json`:

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

Reload the window after saving.

### Cursor

`Settings → MCP → Add MCP Server`, then paste:

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

### Claude Desktop

Edit `claude_desktop_config.json`:

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

Quit and reopen Claude Desktop.

### Claude Code

```bash
claude mcp add ctt-design-system -- npx --package ctt-web-components ctt-mcp-server
```

### Working inside this repository

If you have cloned the design system and want to point the client at your local build, swap the `command` to:

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

Run `npm --prefix mcp-server run build` first. See [`.vscode/settings.example.json`](../.vscode/settings.example.json).

---

## Is it working?

Paste these three prompts into your agent after wiring up the client. The agent should call the bracketed tool and you should see the bracketed shape in the response.

1. **"List all CTT Design System components."**
   → calls `components_list` → returns an array including at minimum `Button` (category `Actions`) and `InputText` (category `Form Inputs`).

2. **"Show me the CTT Button API for a React TypeScript file."**
   → calls `components_get` with `name: "Button"` and a React TS hint (either explicit `target: "react-ts"` or a `.tsx` path).
   → the example in the response uses `import { ButtonCtt } from 'ctt-web-components/react'`.

3. **"Find a CTT component for a text input with validation."**
   → calls `components_search` with a query like `"text input validation"` → returns `InputText` at the top.

If the agent answers these from general knowledge instead of calling a tool, the server isn't wired up — see [Troubleshooting](#troubleshooting).

---

## Troubleshooting

**`command not found: ctt-mcp-server` or `npx: could not resolve`**
Use the full `npx --package ctt-web-components ctt-mcp-server` form. The npm package is `ctt-web-components`; the binary inside it is `ctt-mcp-server`. Plain `npx ctt-mcp-server` won't work because no package by that name is published.

**Agent never calls a tool**
The MCP client likely didn't reload. Restart Claude Desktop / Cursor / VS Code after saving config. In VS Code, run `Developer: Reload Window` from the command palette.

**Agent replies "component not found" for a component you know exists**
Verify you are using the correct component name (e.g., `InputText` instead of `TextInput`). All 27 core components are available in the catalog. If you've just added a new component to the repo, remember to run `npm run generate` in the `mcp-server` directory.

**Server fails to start with "Component catalog not found"**
Only happens when running from source before building. For consumers using `npx`, the catalog ships inside the published package and this error indicates a broken install — try `npm cache clean --force && npx --package ctt-web-components ctt-mcp-server` again.

**Windows `${workspaceFolder}` issues when pointing at a local build**
On native Windows VS Code (not WSL), `${workspaceFolder}` expands with backslashes — e.g. `C:\Users\you\project\mcp-server\dist\index.js` — which Node will accept but which some MCP client parsers mis-escape inside JSON. Two reliable workarounds:
1. **Prefer the `npx --package` form.** It avoids workspace-path resolution entirely and works identically on Windows, macOS, Linux, and WSL.
2. **If you must point at a local build**, write the path manually with forward slashes (e.g. `"C:/Users/you/project/mcp-server/dist/index.js"`) or use a POSIX-style workspace variable if your client supports one.
WSL users: point the config at the WSL-side Node binary and a WSL-side path; mixing Windows-side Node with a WSL path will silently hang at startup.

**Node version mismatch**
The server is built for Node ≥ 20. Confirm with `node --version`. On nvm: `nvm use 20`.

---

## How the catalog is built

The catalog (`mcp-server/data/components.json`) is generated at publish time from the component source (`@property` decorators) and Storybook stories (`## Quando usar` / `## Quando não usar` sections). You don't need to do anything to refresh it — it's baked into each published version of `ctt-web-components`. Upgrading the package automatically updates your agent's knowledge.

---

## Reporting issues

Open an issue at [github.com/ctt/pt.dni.design-system](https://github.com/ctt/pt.dni.design-system/issues) with:

- Your MCP client + version.
- The exact prompt you used.
- The tool call the agent made (most clients show this in a "used tool" panel).
- The response you got vs. what you expected.

See also [`USAGE_STORY.md`](./USAGE_STORY.md) for a full end-to-end example building a form with the MCP-assisted workflow.