@usesource/mcp

MCP (Model Context Protocol) server exposing the canonical SOURCE registry to AI agents. Codemod-oriented: agents pivot between UI libraries through SOURCE without writing per-library mapping code.

What's the point

When an agent (Claude Code, Cursor, etc.) needs to translate a UI component or design token between libraries — say, migrate a shadcn codebase to MUI — the naïve approach is library-pair-specific mapping logic baked into the agent. That doesn't scale: N libraries means N×N pair-mappings, all stale the moment a library updates.

SOURCE is the canonical pivot. Every library has one adapter mapping to canonical IDs (@usesource/adapter-shadcn, @usesource/adapter-mui, …). This MCP server exposes lookup, search, fingerprint equivalence, and translate tools over those canonical IDs. Agents pivot through SOURCE. N adapters, not N×N.

Install / connect

npm install -g @usesource/mcp
# or use without install via npx

Add this to your MCP client config (Claude Code, Cursor, etc.):

{
  "mcpServers": {
    "source": {
      "command": "npx",
      "args": ["@usesource/mcp"]
    }
  }
}

The server speaks MCP over stdio. No flags needed; the agent spawns the binary.

Tools

Lookup (single canonical artifact)

| Tool | Returns | |---|---| | source_token_lookup | One Token by canonical ID | | source_property_lookup | One Property by canonical ID | | source_element_lookup | One Element by canonical ID |

Search (paginated, filterable)

| Tool | Filters | |---|---| | source_token_search | q, dimension, kind, limit, offset | | source_property_search | q, category, fingerprintHash, limit, offset | | source_element_search | q, capability, htmlTag, fingerprintHash, limit, offset |

Fingerprint equivalence

| Tool | Returns | |---|---| | source_by_fingerprint | All properties + elements with the given fingerprint hash |

This is the cross-library equivalence query. Two artifacts with the same fingerprint hash are behaviorally equivalent regardless of which library implemented them.

Translate (the codemod enabler)

| Tool | Returns | |---|---| | source_translate | Single library identifier → canonical pivot, optionally to another library | | source_codemod_plan | Full code block → list of identifier-level transformations to migrate from one library to another |

source_translate is for single-identifier Q&A. source_codemod_plan is for batch migration: pass a code block, get back every edit the agent should consider, plus an unmapped[] list for identifiers with no canonical equivalent.

// source_codemod_plan input
{
  "code": "import { Drawer, Snackbar } from '@mui/material';\n<Drawer />",
  "fromLibrary": "mui",
  "toLibrary": "shadcn",
  "minConfidence": 0.85
}

// Output
{
  "edits": [
    { "kind": "import-source", "original": "@mui/material", "suggested": "@/components/ui", "confidence": 1.0,  ... },
    { "kind": "import-named",  "original": "Drawer",        "suggested": "Sheet",            "confidence": 0.95, ... },
    { "kind": "import-named",  "original": "Snackbar",      "suggested": "Toast",            "confidence": 0.97, ... },
    { "kind": "jsx-tag",       "original": "Drawer",        "suggested": "Sheet",            "confidence": 0.95, ... }
  ],
  "unmapped": [],
  "summary": { "editCount": 4, "unmappedCount": 0, "uniqueIdentifiers": 3 }
}

The plan is suggestions, not source rewriting — the caller applies edits via their AST tool of choice (ts-morph, jscodeshift). v0.2 will add source_codemod_apply for direct AST application.

Introspection

| Tool | Returns | |---|---| | source_coverage | Snapshot version + counts + installed adapters | | source_snapshot_manifest | Full integrity manifest (hash, signature, key ID) | | source_adapters_list | All installed @usesource/adapter-* packs |

Adapters

This server discovers @usesource/adapter-* packages at install time. v0.1.0 ships with @usesource/adapter-shadcn baked in. Adding more libraries is a single npm install @usesource/adapter-mui away — the MCP tool surface auto-grows because adapters share the canonical pivot.

Authoring a new adapter is straightforward: provide a JSON pack of LibraryMapping entries (validated against the schema in @usesource/schema) plus minimal lookup helpers.

Use as a library

import { createMcpServer, TOOLS, callTool } from "@usesource/mcp";

// Direct tool dispatch (no MCP transport — useful for tests)
const result = await callTool("source_token_lookup", {
  id: "source.core.color.blue.500"
});

// Or wire to a custom transport
const server = createMcpServer({ version: "0.1.0" });
await server.connect(yourCustomTransport);

Roadmap

v0.2 will add:

• source_codemod_apply — programmatic AST application of a source_codemod_plan. Currently the plan is suggestion-only; you apply via your AST tool. v0.2 absorbs that step.
• AST-grade extraction in source_codemod_plan (currently regex).
• SSE transport for remote MCP usage.
• Streaming results for large search responses.

License

Apache-2.0. See LICENSE at the repository root.