aurum-mcp

Talk to the Aurum Design System from your LLM client. Components · tokens · icons · Figma node IDs · changelog — all queryable from Claude Code, Cursor, Copilot CLI, Gemini, and Claude Desktop.

aurum-mcp is a Model Context Protocol server that surfaces the Aurum design system catalogue to LLMs. It reads a bundled JSON manifest (auto-synced from changejarapp.github.io/aurum-android) and exposes 9 tools the LLM can call to answer questions like:

• "Show me how to use AurumChip."
• "What colour token do we have for negative-feedback text?"
• "What's the Figma node for AurumTopAppBar?"
• "Give me the icon for a back arrow."
• "What changed in the most recent release?"

Install (one paste, every client)

Pick your client below, paste the snippet into the matching config file, restart the client.

Claude Code (.mcp.json in your project root, or ~/.claude.json)

{
  "mcpServers": {
    "aurum": {
      "command": "npx",
      "args": ["-y", "github:atri-jar/aurum-mcp#latest-stable"]
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "aurum": {
      "command": "npx",
      "args": ["-y", "github:atri-jar/aurum-mcp#latest-stable"]
    }
  }
}

Copilot CLI (~/.copilot/mcp.json)

{
  "mcpServers": {
    "aurum": {
      "command": "npx",
      "args": ["-y", "github:atri-jar/aurum-mcp#latest-stable"]
    }
  }
}

Gemini CLI (~/.gemini/settings.json under mcpServers)

{
  "mcpServers": {
    "aurum": {
      "command": "npx",
      "args": ["-y", "github:atri-jar/aurum-mcp#latest-stable"]
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

Same shape — drop the snippet above into mcpServers. Restart the app.

That's it. No npm registry, no ~/.npmrc, no PAT, no environment variables. Public Git, public npx.

Versioning

The default snippet uses #latest-stable — a CI-managed Git tag that always points at the newest stable release. Behaves like npm's @latest dist-tag: you get auto-updates on each fresh npx cache miss (~10 min to a few hours, depending on your client's cache).

For reproducibility — automated scripts, audited setups — pin to an explicit tag:

"args": ["-y", "github:atri-jar/aurum-mcp#v0.1.0"]

Every version of aurum-mcp ships the manifest from the matching Aurum library version (@aurum-mcp:0.1.6 ⇄ aurum:0.1.6). Call get_aurum_version from your LLM client to see exactly what you're talking to.

Tools

See docs/tools.md for full input schemas and example responses.

Why npx-from-Git, not npm?

We considered three distribution channels (public npm, GitHub Packages, npx-from-Git) and chose the third because for a team-internal tool optimising for simplicity, full ownership, and zero new infrastructure:

• Zero new accounts to govern. No npm org, no NPM_TOKEN rotation, no 2FA recovery, no 72-hour publish-permanence anxiety. The repo IS the artefact, end-to-end.
• Branch-based testing for free. Want to try a feature branch? Just change the snippet to #feat/branch-name — done. With npm you'd publish a pre-release tag that lives in the registry forever.
• Same auth users already have. This repo is public; team members have GitHub access; nothing new to configure.
• Marginal install delay. First-spawn is ~5–10 s of clone + build vs. ~2–5 s for npm. Cached spawns are identical.

Trade-offs we accept: less polished version-pinning UX (Git tags vs. semver ranges) and no public-npm discoverability. The full reasoning lives in docs/architecture.md.

Local development

git clone https://github.com/atri-jar/aurum-mcp.git
cd aurum-mcp
pnpm install
pnpm dev          # run the server via tsx + stdio
pnpm inspect      # spawn the official MCP Inspector UI
pnpm build        # tsc → dist/
pnpm smoke        # end-to-end tools/list + tools/call test

The server reads data/manifest.json (committed). To pull the latest manifest from the live Aurum gallery and update the bundled copy:

make manifest-fetch

CI does this automatically (see .github/workflows/sync-manifest.yml).

Architecture in one paragraph

The Aurum design system lives in Changejarapp/aurum-android (private) and ships a public gallery at changejarapp.github.io/aurum-android. Its tooling/gallery/generate.py script aggregates components, tokens, icons, Code Connect mappings, and the changelog from a single set of parsers. We added a --emit-manifest flag that produces a structured JSON projection of the same data — the contract is tooling/manifest/schema.json in aurum-android. This MCP server is the JSON's read-side: it loads the manifest at boot, indexes it, and serves the 9 tools above. One source of truth, two render targets (HTML for humans, JSON for agents). When aurum-ios ships, its manifest plugs in as a sibling source — the MCP code is platform- agnostic.

Full pipeline diagram: docs/architecture.md.

Contributing

Issues and PRs welcome. See docs/contributing.md for the workflow (manifest sync, drift-check, release process). Code style: TypeScript strict, Prettier defaults; no business logic in markdown formatters.

License

MIT — see LICENSE.