# yFiles Quick Start Setup

Follow these steps in order to set up yFiles developer tools and MCP server integration.

---

## Prerequisites

Check that Node.js (version 22 or higher) and npm are installed by running:

```bash
node --version
npm --version
```

**If either command fails, stop immediately and provide a helpful error message explaining that Node.js 22+ and npm are required. Provide guidance on how to install them from https://nodejs.org/**

**If Node.js version is lower than 22, stop immediately and provide a helpful error message explaining that Node.js 22 or higher is required, and provide guidance on how to upgrade from https://nodejs.org/**

---

## Step 1: Authenticate with yFiles Dev Suite

Run the login command:

```bash
npx -y yfiles-dev-suite login
```

This will open a browser for authentication. Wait for the process to complete.

**If the login fails or the user doesn't complete authentication, stop immediately and provide a helpful error message explaining what went wrong.**

---

## Step 2: Download yFiles Package

Run the download command:

```bash
npx -y yfiles-dev-suite download-yfiles
```

This downloads the yFiles for HTML package required for development.

**If this command fails, stop immediately and provide a helpful error message.**

---

## Step 3: Install yFiles Skills

Run the install command:

```bash
npx -y yfiles-dev-suite install-skills
```

This installs yFiles-specific skills for your AI coding assistant.

**If this command fails, stop immediately and provide a helpful error message.**

---

## Step 4: Install yFiles MCP Server

The yFiles MCP server provides API documentation and code generation tools. Follow these substeps:

### 4.1 Detect the AI harness

Probe these paths in order; the first that exists identifies your harness:

| Harness        | Probe path                                                              |
|----------------|-------------------------------------------------------------------------|
| OpenCode       | `~/.config/opencode/opencode.json`                                      |
| Cursor         | `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)           |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
| VS Code        | `.vscode/mcp.json` (project)                                            |
| Claude Code    | `~/.claude.json`                                                        |

**If no path is found, ask the user which harness they are using.**

### 4.2 Add MCP server configuration

Based on the detected harness, add the appropriate configuration:

#### OpenCode

**Config file:** `~/.config/opencode/opencode.json`

Add this block under `"mcp"`:

```json
"yfiles-api": {
  "type": "local",
  "command": ["npx", "--yes", "yfiles-dev-suite@latest", "mcp"],
  "enabled": true
}
```

**Restart instruction:** Restart OpenCode to load the new MCP server.

---

#### Cursor

**Config file:** `.cursor/mcp.json` (project-local) or `~/.cursor/mcp.json` (global)

Use the project-local file if it exists; otherwise use the global file. Create the file if neither exists.

Add this block under `"mcpServers"`:

```json
"yfiles-api": {
  "command": "npx",
  "args": ["--yes", "yfiles-dev-suite@latest", "mcp"]
}
```

If the file does not exist yet, create it with this full structure:

```json
{
  "mcpServers": {
    "yfiles-api": {
      "command": "npx",
      "args": ["--yes", "yfiles-dev-suite@latest", "mcp"]
    }
  }
}
```

**Restart instruction:** Restart Cursor, or reload the window via Command Palette → "Reload Window".

---

#### Claude Desktop

**Config file:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)

Add this block under `"mcpServers"`:

```json
"yfiles-api": {
  "command": "npx",
  "args": ["--yes", "yfiles-dev-suite@latest", "mcp"]
}
```

If the file does not exist yet, create it with this full structure:

```json
{
  "mcpServers": {
    "yfiles-api": {
      "command": "npx",
      "args": ["--yes", "yfiles-dev-suite@latest", "mcp"]
    }
  }
}
```

**Restart instruction:** Quit and relaunch Claude Desktop.

---

#### VS Code

**Config file:** `.vscode/mcp.json` (project-local, requires VS Code 1.99+)

Add this block under `"servers"`:

```json
"yfiles-api": {
  "type": "stdio",
  "command": "npx",
  "args": ["--yes", "yfiles-dev-suite@latest", "mcp"]
}
```

If the file does not exist yet, create it with this full structure:

```json
{
  "servers": {
    "yfiles-api": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "yfiles-dev-suite@latest", "mcp"]
    }
  }
}
```

**Restart instruction:** Reload the VS Code window via Command Palette → "Developer: Reload Window".

---

#### Claude Code

**Config file:** `~/.claude.json` (user scope)

Add this block under `"mcpServers"`:

```json
"yfiles-api": {
  "type": "stdio",
  "command": "npx",
  "args": ["--yes", "yfiles-dev-suite@latest", "mcp"]
}
```

Alternatively, you can add the server via CLI:

```bash
claude mcp add --transport stdio --scope user yfiles-api -- npx --yes yfiles-dev-suite@latest mcp
```

**Restart instruction:** Start a new Claude Code session to load the server.

---

## Step 5: Restart Required

After completing the above steps, display this message to the user:

```
✓ yFiles Dev Suite authenticated
✓ yFiles skills installed  
✓ yFiles MCP server configured

To complete the setup, please restart your AI coding assistant session.

After restarting, manually invoke the "yfiles-quick-start" skill to create your first yFiles visualization app.
```

**Stop execution here. Do not proceed further until the user has restarted and manually invoked the yfiles-quick-start skill.**