@luna-oss/mcp

A Model Context Protocol (MCP) server for the Moon Design System, enabling LLMs and other MCP clients to interact with Moon component metadata, icon information, design tokens, source code, and accessibility heuristics.

This package can run over either the stdio transport (default) or the Streamable HTTP transport, and exposes tools, resources, and prompts.

Usage

Stdio (default)

npx @luna-oss/mcp

Streamable HTTP

npx @luna-oss/mcp --http --port 7777

Optional flags:

| Flag | Default | Description | |------------|---------------|---------------------------------------------------| | --http | false | Run with the Streamable HTTP transport. | | --port | 7777 | HTTP port. Ignored unless --http is set. | | --host | 127.0.0.1 | HTTP host. Ignored unless --http is set. |

When running over HTTP, the server exposes:

• POST /mcp — main JSON-RPC endpoint (initializes a session on first call).
• GET /mcp — server-to-client SSE notifications for an existing session.
• DELETE /mcp — terminates a session.

The session ID is exchanged via the mcp-session-id HTTP header, per the MCP Streamable HTTP spec.

Connecting AI Clients (stdio)

Cursor

Or manually update your Cursor MCP configuration file at ~/.cursor/mcp.json (create it if it doesn't exist):

{
  "mcpServers": {
    "moon": {
      "command": "npx",
      "args": ["@luna-oss/mcp"]
    }
  }
}

VSCode

Paste this in your browser:

vscode://mcp-server/add?config=%7B%22name%22%3A%22moon%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40luna-oss%2Fmcp%22%5D%7D

or manually update your VSCode MCP configuration file at .vscode/mcp.json (create it if it doesn't exist):

{
  "servers": {
    "moon": {
      "command": "npx",
      "args": ["@luna-oss/mcp"]
    }
  }
}

Capabilities

Tools

Component Tools

• get-moon-component-metadata — Returns metadata for a specific Moon component (or all components if no name is provided).
• list-moon-public-components — Get a list of all public @luna-oss/core and @luna-oss/core/next component names.
• get-moon-component-examples — Get React usage examples for Moon components.
• get-moon-component-accessibility — Get accessibility requirements and guidelines for a Moon component.
• get-moon-component-source — Returns the TypeScript/TSX source for a Moon component, with the public API surface (component declaration and props interface) always preserved. Accepts an optional maxTokens budget to truncate implementation details.

Icon Tool

• list-moon-icons — Get a list of all available Moon icons from the @luna-oss/icons package, with optional filtering and React usage examples.

Token Tool

• list-moon-tokens — Get a list of all available Moon design tokens from the @luna-oss/style package, with optional filtering and CSS usage examples.

Composition & A11y Tools

• compose — Compose a UI from a natural-language description. Returns a typed JSON tree of suggested @luna-oss/core components plus notes. Phase 1 uses a keyword-match heuristic; richer composition (live preview, validated trees) is planned for Phase 2.
• audit-accessibility — Run a quick static-heuristic accessibility audit on a JSX/HTML string. Reports missing button names, missing image alt text, and unlabeled inputs. Phase 1 is regex-only; a real Axe-in-headless-Chromium audit is planned for a future version.

Resources

The server registers three resource templates. Use resources/templates/list to discover them and resources/read to fetch a specific URI.

| URI template | MIME type | Description | |------------------------------------|---------------------|------------------------------------------------------------------------------| | moon://components/{name}/api | application/json | Component manifest JSON, sourced from @luna-oss/core's metadata.json. | | moon://components/{name}/mdx | text/markdown | MDX-style docs, read from dist/generated/code-examples/{name}.tsx if present. | | moon://tokens/{tier} | application/json | Design tokens at the given tier (core, semantic, or component). |

Prompts

The server registers three slash-command-style prompts. Use prompts/list to discover them and prompts/get to render one.

| Name | Arguments | Description | |-----------------------|-------------------------------------------------|--------------------------------------------------------------------------| | scaffold-component | name, category, description | Templated message to scaffold a new component built on @luna-oss/core. | | audit-a11y | componentName | Templated audit prompt that pairs with the accessibility tools. | | explain-tokens | tokenName | Templated prompt to explain a Moon design token. |