@mihcm/mcp

Model Context Protocol server for the MiHCM Design System. It exposes live component, token, AI-UI, and wiki facts to MCP-aware agents so they can work against the current repo instead of guessing from stale context.

What it pairs with

This package is the live-data half of the agent workflow:

• Skill: .claude/skills/mihcm-design-system/ teaches the workflow, rules, and verification gates.
• MCP: @mihcm/mcp exposes typed tools that read current repo source, docs, tokens, and schemas.

Together: skill = playbook, MCP = current senses.

Current release

Current published version: 0.5.9.

This release is published on public npm and tracks @mihcm/[email protected] / @mihcm/[email protected]. The component registry stays current with the rebuilt sonner-backed Toast API (Toaster + toast) and the polished MainSidebar (variant + colorScheme + mobile hamburger surface), so hosted MCP tools return up-to-date primitive metadata for agents.

Recent additions and fixes

• Added 60/30/10 color-balance guidance to token output and snippet review so agents can distinguish dominant, supporting, and emphasis roles without hardcoded colors.
• Added approved-library guidance so agents keep forms on TanStack Form, date/time UI on DayPicker v10 through Calendar/DatePicker, data grids on TanStack Table/Virtual, command palettes on cmdk, drag/drop on dnd-kit/react-dropzone, charts on the documented chart primitives, and rich text on RichTextEditor.
• Added mihcm_review_semantics_accessibility and wired the same checks into combined snippet review so agents must check headings, paragraphs, Link/Button semantics, labelled fields, image alt text, icon-only labels, focus, contrast, and touch targets.
• Added a generated, source-safe component registry fallback so hosted MCP component tools keep returning primitives when deployment bundling omits repo source/wiki folders.
• Added mihcm_get_agent_setup so agents can retrieve client-specific MCP install commands, one-click links where supported, and skill download guidance.
• Added hosted Streamable HTTP support through the docs site /mcp route.
• Added frontend enforcement tools for MiHCM-only UI usage, token audits, client/server boundary checks, and snippet review.
• Added package version and changeset lookup tools so agents can reason about current release state.
• Added AI-UI validation and security rule tools for schema-first generated interfaces.
• Added component matrix and examples tools so agents can check docs, Storybook, native, and AI-UI coverage before inventing new components.
• Hardened hosted mode as read-only with bearer-token support, origin/host checks, request caps, and remote source-output restrictions.

Build

Run from the monorepo workspace root:

cd src
pnpm install
pnpm -F @mihcm/mcp build

Register

The repo already includes this in .claude/settings.json:

{
  "mcpServers": {
    "mihcm": {
      "type": "stdio",
      "command": "node",
      "args": ["./src/packages/mcp/dist/index.js"]
    }
  }
}

Other MCP clients can use the same stdio command from repo root.

Hosted endpoint

The docs site hosts the same tools over stateless Streamable HTTP:

https://designsystem.mihcm.com/mcp

Register it from a remote-capable MCP client:

claude mcp add --transport http mihcm https://designsystem.mihcm.com/mcp

The hosted endpoint is read-only, JSON-response only, and designed for short component/token/schema lookups. Source-code output is disabled remotely. Set MIHCM_MCP_BEARER_TOKEN on the Vercel project to require bearer auth.

Hosted component tools use live repo files when available. If the deployment bundle does not include those files, the MCP falls back to src/generated-component-registry.ts, which is generated before package builds. Regenerate it with:

cd src
pnpm -F @mihcm/mcp prebuild

Client install helpers

The MCP server exposes its own installation guide:

{
  "tool": "mihcm_get_agent_setup",
  "input": { "client": "all" }
}

Supported clients:

| Client | Supported install surface | |---|---| | Claude Code | claude mcp add --transport http mihcm https://designsystem.mihcm.com/mcp and JSON config download. | | Codex | codex mcp add mihcm --url https://designsystem.mihcm.com/mcp and TOML config download. | | Cursor | cursor://anysphere.cursor-deeplink/mcp/install?... one-click link plus JSON config/rule downloads. | | VS Code | vscode:mcp/install?..., code --add-mcp ..., and .vscode/mcp.json download. | | VS Code Insiders | vscode-insiders:mcp/install?... and code-insiders --add-mcp .... |

Public skill and config downloads live under the docs site:

• /downloads/skills/mihcm-design-system/SKILL.md
• /downloads/skills/mihcm-frontend-build/SKILL.md
• /downloads/skills/mihcm-component-review/SKILL.md
• /downloads/skills/mihcm-brand/SKILL.md
• /downloads/skills/*.skill
• /downloads/skills/mihcm-skill-pack.json
• /downloads/mcp/mihcm-cursor-mcp.json
• /downloads/mcp/mihcm-vscode-mcp.json
• /downloads/mcp/mihcm-claude-code.mcp.json
• /downloads/mcp/mihcm-codex-config.toml

Tools

| Tool | Purpose | |---|---| | mihcm_search_components | Fuzzy search across primitives in @mihcm/ui; returns artifact presence. | | mihcm_get_component | Paths, artifact presence, parsed variants/sizes, wiki preview, optional source. | | mihcm_list_components | Filter the primitive catalog by platform and artifact coverage. | | mihcm_get_component_examples | Return docs paths, usage guidance, examples preview, and live example exports. | | mihcm_search_patterns | Find recommended app patterns such as admin shells, settings forms, dashboards, and permission editors. | | mihcm_get_component_matrix | Return web/native/story/wiki/AI-UI coverage for each primitive. | | mihcm_list_tokens | Semantic tokens by kind: color, spacing, radius, typography, motion, or all. | | mihcm_validate_descriptor | Run the live @mihcm/ai-ui Zod schema against a candidate descriptor. | | mihcm_validate_component_usage | Check JSX/TSX for non-MiHCM imports, local primitive forks, hardcoded values, local CSS styling layers, inline styles, and native controls. | | mihcm_audit_tokens | Check JSX/TSX for raw colours, arbitrary Tailwind values, local CSS styling layers, and inline styles. Standard Tailwind classes and MiHCM token classes are allowed. | | mihcm_check_client_server_boundary | Check whether a Next.js snippet requires a Client Component wrapper. | | mihcm_review_semantics_accessibility | Check JSX/TSX for semantic HTML and accessibility rules before final UI output. | | mihcm_review_frontend_snippet | Run the combined MiHCM frontend review and return score, findings, and required actions. | | mihcm_get_agent_setup | Return client-specific MCP setup, install links where officially supported, config downloads, and skill install guidance. | | mihcm_get_installation_guide | Return setup guidance for Next.js, Vite React, React Native, theme, AI-UI, and MCP enforcement. | | mihcm_get_versions | Return current workspace package versions. | | mihcm_get_changesets | Return pending changeset previews. | | mihcm_get_security_rules | Return MCP and design-system security rules. | | mihcm_check_contract | Audit a primitive against the universal-component contract. | | mihcm_recent_log | Return recent docs/log.md entries. |

Recommended agent workflow

1. Call mihcm_search_components before writing UI.
2. Call mihcm_get_component or mihcm_get_component_examples for the chosen primitive.
3. Call mihcm_list_tokens before adding color, spacing, type, radius, shadow, or motion classes.
4. Use 60/30/10 as a composition heuristic: dominant neutral surfaces, supporting brand-blue structure/actions, and restrained accent emphasis.
5. Use semantic HTML: Link for navigation, Button for actions, explicit button types in forms, visible labels for inputs, and Text.as for headings.
6. Use the approved MiHCM-backed library path when one exists: TanStack Form, TanStack Table/Virtual, DayPicker v10, cmdk, d3/Recharts, dnd-kit, react-dropzone, RichTextEditor, and Motion. Do not add React Hook Form, @hookform/resolvers, react-datepicker, or duplicate custom engines for those solved areas.
7. Call mihcm_review_semantics_accessibility before finalizing UI. Treat every error as blocking.
8. Call mihcm_validate_component_usage or mihcm_review_frontend_snippet before finalizing implementation.
9. Call mihcm_validate_descriptor before rendering any AI-generated component descriptor.

Local enforcement checker

Consumer projects can add this package as a dev dependency and run the deterministic checker in CI:

{
  "scripts": {
    "mihcm:check": "mihcm-design-system-check app components src"
  }
}

The checker shares rules with the MCP review tools. It allows standard Tailwind utility classes and MiHCM token classes, and it fails on non-MiHCM UI imports, local primitive imports, raw colours, arbitrary Tailwind values, local CSS styling layers, inline styles, and snippets that need a Client Component boundary.

Programmatic use

The package exports the underlying functions for tests and internal tools:

import {
  searchComponents,
  getComponent,
  listTokens,
  validateDescriptor,
  checkContract,
  validateComponentUsage,
  auditTokens,
  checkClientServerBoundary,
  reviewFrontendSnippet,
  recentLog,
} from '@mihcm/mcp/lib';
import { createMihcmMcpServer } from '@mihcm/mcp/server';

Example:

const result = validateDescriptor({
  descriptor: {
    component: 'Button',
    props: { children: 'Save', variant: 'default' },
  },
});

if (!result.valid) throw new Error('Descriptor rejected');

Security contract

• Never evaluate model output.
• Never import arbitrary component paths from a model.
• Never accept a model-supplied filesystem path.
• Never log prompts, .env, .npmrc, keys, PATs, or build secrets.
• Keep descriptor validation anchored to the schema-only componentDescriptorSchema export.
• Keep component lookup anchored to known repo directories.
• Keep hosted deployments read-only and reject arbitrary path, mutation, and secret-bearing tools.
• Keep source-code output disabled on hosted deployments.

Maintainer checklist

When adding or changing an MCP tool:

1. Keep request schemas strict and reject unknown unsafe input.
2. Keep hosted mode read-only.
3. Do not expose arbitrary filesystem reads, mutations, shell execution, or secrets.
4. Add tests for tool output and failure cases.
5. Update this README, docs-site Agent tooling, and relevant runbooks.
6. Add a changeset before publishing.

Versioning

This package is published through Changesets and the repo-level GitHub Actions publish workflow. Do not run pnpm release locally for production publishing; push the version commit to main and let CI publish to npm through trusted publishing/provenance.

Before publishing MCP changes:

1. Run pnpm -F @mihcm/mcp prebuild or a workspace build so src/generated-component-registry.ts is refreshed.
2. Run pnpm -F @mihcm/mcp test.
3. Confirm hosted-mode tools remain read-only and source-disabled.
4. Update public Agent tooling docs and this README.

This is a public npm package backed by a private source repo. Any user-facing tool or contract change requires a changeset:

cd src
pnpm changeset

Choose @mihcm/mcp. New tools or request/response changes are minor before 1.0; same-contract bug fixes are patch.

Current initial release: 0.1.0, generated by the Version Packages PR.

Full guide: docs/runbooks/mcp-setup.md.