Salt MCP

An MCP server and Agent Skills for building applications with the Salt Design System — JP Morgan Chase's open-source React component library.

What it does

This project gives AI agents access to Salt DS knowledge so they can help you build Salt applications accurately, using the right components, props, patterns, and best practices — instead of guessing.

MCP Tools let agents look things up on the fly:

• Component APIs, props, and examples
• Usage guidelines and accessibility rules
• Design patterns (forms, navigation, search, etc.)
• Foundations (density, spacing, color, typography)

Agent Skills give agents step-by-step instructions for common tasks:

• Scaffolding a new Salt app
• Building page layouts
• Creating forms
• Implementing UI patterns
• Converting Figma designs to Salt code

Prerequisites

• Node.js (v18+)
• An MCP-compatible client or an agent that supports the Agent Skills standard (e.g. VS Code with GitHub Copilot, Claude Code, Cursor, Gemini CLI, Windsurf)
• A local clone of the Salt DS repository:

  git clone --depth 1 https://github.com/jpmorganchase/salt-ds.git ~/Code/salt-ds
  

Setup

# Clone this repo
git clone https://github.com/feesch/salt-mcp.git
cd salt-mcp

# Install dependencies
npm install

# Build
npm run build

Register the MCP server

The repo includes a .mcp.json file that Claude Code and some other clients auto-discover. For other clients, configure the server manually:

<details> <summary><strong>VS Code / GitHub Copilot</strong></summary>

Create or edit .vscode/mcp.json in your project:

{
  "servers": {
    "salt-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/salt-mcp/build/index.js"]
    }
  }
}

Replace /absolute/path/to/salt-mcp with the actual path where you cloned this repo. Then open Copilot Chat in Agent mode to use the tools.

</details>

<details> <summary><strong>Claude Code</strong></summary>

The .mcp.json file in the repo root is auto-discovered — no extra config needed. Alternatively, add to your project's .claude/settings.json:

{
  "mcpServers": {
    "salt-mcp": {
      "command": "node",
      "args": ["./build/index.js"]
    }
  }
}

</details>

<details> <summary><strong>Cursor / Windsurf / other MCP clients</strong></summary>

Add to your client's MCP configuration:

{
  "mcpServers": {
    "salt-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/salt-mcp/build/index.js"]
    }
  }
}

Refer to your client's documentation for the config file location.

</details>

Install the skills

Copy the skills/ directory into the location your agent expects:

• Claude Code: Copy into .claude/skills/ in your project or home directory
• Cursor: Copy into .cursor/skills/
• VS Code / GitHub Copilot: Skills are not yet natively supported — use the MCP tools directly, or paste skill content into your Copilot Chat prompt as instructions
• Other agents: See your agent's documentation for the skills directory

Skills follow the open Agent Skills standard and work with any compatible agent.

MCP Tools

Tool	Description
hello	Test that the server is running
list-components	List all Salt components (core, lab, or both)
get-component-props	Get the TypeScript props interface for a component
get-component-example	Get Storybook example code for a component
search-components	Search components by keyword
get-salt-docs	Get usage guidelines, accessibility rules, patterns, and foundations

Skills

Skills are portable instruction sets that guide agents through multi-step tasks. They follow the Agent Skills standard.

Skill	Description
salt-app	Scaffold a new React app with Salt DS (SaltProvider, theme, Vite)
salt-page	Build page layouts using Salt layout components
salt-form	Build forms following Salt's form pattern
salt-pattern	Build any of 20+ Salt UI patterns (search, navigation, wizard, etc.)
salt-figma	Convert a Figma design (screenshot or description) into Salt code

Keeping Salt DS up to date

The MCP tools read from your local Salt DS clone at runtime, so they automatically reflect any updates. Skills contain some static mapping tables but always instruct agents to verify via the tools.

To pull the latest Salt DS changes:

git -C ~/Code/salt-ds pull

No rebuild of salt-mcp is needed — the tools will return updated data immediately.

Development

npm run build        # Compile TypeScript
npm test             # Run unit tests (37 tests via Vitest)
npm run test:watch   # Run tests in watch mode

Project structure

salt-mcp/
  src/
    index.ts            # MCP server with tools
    helpers.ts          # Shared helpers and security functions
    helpers.test.ts     # Unit tests (Vitest)
  skills/               # Agent Skills (agentskills.io standard)
    salt-app/SKILL.md
    salt-page/SKILL.md
    salt-form/SKILL.md
    salt-pattern/SKILL.md
    salt-figma/SKILL.md
  .mcp.json             # Shareable MCP server config
  package.json
  tsconfig.json

References

• Salt Design System — official site
• Salt DS GitHub — source code
• Model Context Protocol — MCP specification
• Agent Skills — open standard for portable agent skills