adobe / adobe/leonardo

Add @adobe/leonardo-mcp — runtime MCP server for color generation

Open
#269 1 comment 1 reaction 0 assignees View on GitHub
enhancement npm packages
Dominant language
JavaScript
Stars
2.1k
Forks
130
PR merge metrics
No merged PRs in 30d

Description

Part of #266 — Leonardo AI tooling initiative.

## Summary

Create a new monorepo package `packages/mcp/` published as `@adobe/leonardo-mcp`. This is an MCP (Model Context Protocol) server that wraps `@adobe/leonardo-contrast-colors` at runtime, so AI assistants can generate verified, executable color output rather than approximating from documentation.

Follows the same pattern as `@adobe/spectrum-design-data-mcp` and `@react-spectrum/mcp`.

## What makes this different from the Agent Skill

The Agent Skill teaches an AI _how_ to use the library. The MCP server _runs_ the library on the AI's behalf — producing real hex values, real contrast ratios, and real theme JSON that can be dropped directly into a project.

## Package structure

```
packages/mcp/
├── package.json # name: @adobe/leonardo-mcp, bin: src/cli.js
├── moon.yml # moon task definitions
└── src/
├── cli.js # #!/usr/bin/env node — npx entrypoint
├── server.js # MCP server using @modelcontextprotocol/sdk StdioServerTransport
└── tools/
├── generate-theme.js # Theme + contrastColors
├── check-contrast.js # contrast() wrapper with WCAG pass/fail
├── convert-color.js # convertColorValue() wrapper
└── create-palette.js # Color + createScale() wrapper
```

## Tools to expose

### `generate-theme`
Inputs: array of color definitions (name, colorKeys, ratios, colorspace), lightness, contrast multiplier, saturation, output format.
Output: `theme.contrastColors` JSON — ready to paste into a design token file.

### `check-contrast`
Inputs: foreground color, background color, optional contrast method (`wcag2` | `wcag3`).
Output: ratio value, WCAG 2 AA/AAA pass/fail, APCA Lc value if wcag3 selected.

### `convert-color`
Inputs: color value (any supported format), target format.
Output: converted color string.

### `create-palette`
Inputs: colorKeys, colorspace, number of steps.
Output: array of interpolated color values.

## Key technical decisions

- **Transport**: `StdioServerTransport` — works with `npx @adobe/leonardo-mcp`, no HTTP server required.
- **Runtime dependency**: `@adobe/leonardo-contrast-colors` as a workspace sibling (`workspace:*`), bundled at publish time.
- **Input validation**: `zod` schemas for each tool's inputs.
- **SDK**: `@modelcontextprotocol/sdk`

## Cursor integration

Add `.cursor/mcp.json` to the repo:

```json
{
"mcpServers": {
"leonardo": {
"command": "node",
"args": ["packages/mcp/src/cli.js"]
}
}
}
```

Published usage (post-release):

```json
{
"mcpServers": {
"leonardo": {
"command": "npx",
"args": ["@adobe/leonardo-mcp"]
}
}
}
```

## Moon integration

Add `mcp` to the workspace project list and add a `moon.yml` with `build` and `test` tasks matching the pattern in `packages/contrast-colors/moon.yml`.

## Acceptance criteria

- [ ] `packages/mcp/` exists as a valid monorepo package
- [ ] All four tools are implemented and input-validated with zod
- [ ] `npx @adobe/leonardo-mcp` starts the server without errors
- [ ] Each tool returns correct output when tested against known inputs (e.g., `#cacaca` background at lightness 97 with ratio 4.5 → expected hex)
- [ ] `.cursor/mcp.json` added to repo for local development
- [ ] `moon.yml` added with `build` and `test` tasks
- [ ] Package is added to changesets for release

Contributor guide

Open the contributing guide

Research direction

Start by comparing packages/mcp/ with the patterns in @adobe/spectrum-design-data-mcp, @react-spectrum/mcp, and packages/contrast-colors/moon.yml. Implement the listed files and four validated tools, then verify npx startup, known-input outputs, .cursor/mcp.json, Moon tasks, and the changeset acceptance criteria.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, node.js
Domain
build-system, release, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.