Parlance MCP Server

The single source of agreement between design and development.

Exposes Parlance design contracts and glossary as MCP tools for any AI coding assistant — including Claude Code, Cursor, VS Code Copilot, Windsurf, Cline, and more — so AI has full awareness of your design system contracts while generating code.

Installation

Published on npm — no clone or build required. Run it straight from the registry with npx:

npx @parlancelabs/mcp-server

Or install it globally:

npm install -g @parlancelabs/mcp-server

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | PARLANCE_API_KEY | Yes | — | Your Parlance API key | | PARLANCE_API_URL | No | https://api.parlancelabs.net | Parlance API base URL |

Configuration

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "parlance": {
      "command": "npx",
      "args": ["-y", "@parlancelabs/mcp-server"],
      "env": {
        "PARLANCE_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

Open Cursor Settings → MCP → Add Server:

{
  "mcpServers": {
    "parlance": {
      "command": "npx",
      "args": ["-y", "@parlancelabs/mcp-server"],
      "env": {
        "PARLANCE_API_KEY": "your-api-key"
      }
    }
  }
}

Or add to ~/.cursor/mcp.json.

VS Code Copilot / Windsurf / Cline

All three use the same .mcp.json format. Place the file in your project root or workspace settings directory:

{
  "mcpServers": {
    "parlance": {
      "command": "npx",
      "args": ["-y", "@parlancelabs/mcp-server"],
      "env": {
        "PARLANCE_API_KEY": "your-api-key"
      }
    }
  }
}

Tools Reference

Read Tools

list_projects

Returns all Parlance projects accessible with your API key.

Parameters: none

Example response:

[
  {
    "id": "proj_abc123",
    "name": "Design System 2.0",
    "description": "Core component library",
    "platforms": ["web", "ios"]
  }
]

get_contracts

Returns all component contracts for a project.

Parameters: | Name | Type | Description | |---|---|---| | projectId | string | Parlance project ID |

get_contract_detail

Returns the full specification for a single contract.

Parameters: | Name | Type | Description | |---|---|---| | projectId | string | Parlance project ID | | contractId | string | Contract ID |

get_glossary

Returns all design tokens / glossary terms for a project.

Parameters: | Name | Type | Description | |---|---|---| | projectId | string | Parlance project ID |

validate_component

Reads a local component file and validates it against the matching Parlance contract. Uses fuzzy name matching.

Parameters: | Name | Type | Description | |---|---|---| | projectId | string | Parlance project ID | | contractName | string | Contract name (fuzzy matched) | | filePath | string | Absolute path to component file |

Example response:

{
  "result": "fail",
  "contract": "Button",
  "violations": [
    { "type": "missing_state", "detail": "Interaction state \"disabled\" not detected" },
    { "type": "missing_a11y", "detail": "Accessibility pattern \"aria attributes\" not found" }
  ]
}

run_accessibility_audit

Runs a regex-based WCAG audit on a local component file. Checks 6 rules: img-alt, aria-click-role, aria-input-label, heading-order, keyboard-mouse-only, touch-target.

Parameters: | Name | Type | Description | |---|---|---| | filePath | string | Absolute path to component file |

Example response:

{
  "total": 2,
  "errors": 1,
  "warnings": 1,
  "issues": [
    {
      "rule": "img-alt",
      "severity": "error",
      "line": 12,
      "message": "<img> element is missing an alt attribute",
      "wcag_ref": "WCAG 1.1.1 Non-text Content (Level A)"
    }
  ]
}

Write Tools

create_contract

Creates a new component contract.

Parameters: | Name | Type | Description | |---|---|---| | projectId | string | Parlance project ID | | name | string | Contract name | | description | string | Contract description | | category | atom | molecule | organism | template | Component category | | status | proposed | agreed | divergent | Status (default: proposed) |

update_contract

Updates an existing contract. All fields except projectId and contractId are optional.

Parameters: | Name | Type | Description | |---|---|---| | projectId | string | Parlance project ID | | contractId | string | Contract ID | | name | string? | New name | | description | string? | New description | | category | enum? | New category | | status | enum? | New status |

delete_contract

Deletes a contract. Returns { deleted: true, contractId }.

Parameters: | Name | Type | Description | |---|---|---| | projectId | string | Parlance project ID | | contractId | string | Contract ID |

create_glossary_term

Creates a new design token / glossary term.

Parameters: | Name | Type | Description | |---|---|---| | projectId | string | Parlance project ID | | name | string | Token name | | raw_value | string | Token value | | category | string? | Token category |

update_glossary_term

Updates an existing glossary term.

Parameters: | Name | Type | Description | |---|---|---| | projectId | string | Parlance project ID | | termId | string | Term ID | | name | string? | New name | | raw_value | string? | New value | | category | string? | New category |

delete_glossary_term

Deletes a glossary term. Returns { deleted: true, termId }.

Parameters: | Name | Type | Description | |---|---|---| | projectId | string | Parlance project ID | | termId | string | Term ID |

Resources

| URI | Description | |---|---| | parlance://projects | All projects as JSON | | parlance://glossary/{projectId} | Glossary for a project as JSON |

Troubleshooting

Server won't start

• Ensure PARLANCE_API_KEY is set in the env block of .mcp.json
• Ensure args is ["-y", "@parlancelabs/mcp-server"] and that npx can reach npm
• Run npm run build if you haven't built yet

Tools return "Error: HTTP 401"

• Your API key is invalid or expired — check your Parlance account

Tools return "Error: HTTP 404"

• The project ID or contract ID doesn't exist — use list_projects and get_contracts to find valid IDs

Build fails

• Run npm install first, then npm run build
• Requires Node.js 18 or later

Development

npm run watch        # TypeScript watch mode
npm run inspector    # Open MCP inspector UI