Agent tooling

MiHCM ships agent tooling in two layers:

1. Maintainer tooling for agents working inside this repository.
2. External developer tooling for agents building product screens from the published packages, hosted MCP endpoint, docs, and examples.

Use skills for process. Use MCP for live facts.

This page is the source of truth for hosted MCP setup, downloadable .skill files, client-specific install steps, one-click links, setup verification, and installer security. External developer onboarding links here instead of repeating agent setup instructions.

What ships

Maintainer skill — .claude/skills/mihcm-design-system/

The maintainer skill is the repository playbook. It points agents to the universal-component contract, token rules, AI-UI safety rules, wiki protocol, and verification loop.

External skill pack — skills/

These skills are safe to share with community or partner developers:

@mihcm/mcp — src/packages/mcp/

The MCP package is the live tool layer. It exposes component search, component details, examples, pattern lookup, token lookup, descriptor validation, semantics/accessibility review, frontend snippet review, client/server boundary checks, contract checks, and recent wiki log lookup.

Together, the skills and MCP answer the two questions agents need before touching the design system:

1. What is the rule for this kind of work?
2. What does the repo currently contain?

Build the MCP server

Run from the monorepo workspace:

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

The built server entry is:

src/packages/mcp/dist/index.js

Rebuild after changing src/packages/mcp/src/**.

Use the hosted MCP

The docs site also exposes the same tools as a remote Streamable HTTP endpoint:

https://designsystem.mihcm.com/mcp

Remote clients can register it as an HTTP MCP server:

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

The hosted endpoint is stateless and JSON-response only. It is meant for component metadata, token lookup, descriptor validation, contract checks, and recent design-system log entries. Source-code output is disabled on the hosted route even if a client asks for includeSource.

Install MCP and skills

Use the hosted MCP and the matching skill files together. MCP gives the agent current design-system facts; skills tell the agent how to apply those facts safely.

Skill install guide

For most users, download the .skill file for the workflow they need. Install mihcm-design-system first; add the other skills only when the task matches.

Use .skill archives when the client supports bundled skill imports. Use raw SKILL.md files when the client expects a directory with SKILL.md. The skill pack manifest remains available for automation and internal tooling, but users should start with the buttons above.

Claude Code

1. Install MCP:

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

2. Download the needed skill archive or raw skill folder from /downloads/skills/.
3. Place each skill in the Claude Code skills directory used by your workspace or user profile.
4. Keep mihcm-design-system installed by default. Add mihcm-frontend-build for project setup, mihcm-component-review for audits, and mihcm-brand for logo or marketing work.
5. Verify with claude mcp list, then ask Claude Code to call mihcm_get_agent_setup({ "client": "claude-code" }).

Codex

1. Install MCP:

codex mcp add mihcm --url https://designsystem.mihcm.com/mcp

2. Or download mihcm-codex-config.toml and merge it into the Codex MCP config.
3. Install raw skill folders or .skill archives into the Codex skills directory for the current workspace or user profile.
4. Verify with codex mcp list and codex mcp get mihcm --json.
5. Run an agent check by asking Codex to call mihcm_search_components before writing UI, mihcm_review_semantics_accessibility for semantic/a11y review, and mihcm_review_frontend_snippet before final output.

Cursor

1. Use the Cursor MCP one-click link above or download mihcm-cursor-mcp.json.
2. Add mihcm-cursor.mdc under .cursor/rules/ in the project.
3. Use the rule for project-wide MiHCM component, token, MCP, AI-UI, and brand constraints.
4. Verify in Cursor Settings -> MCP that mihcm is enabled and tools are visible.

VS Code

1. Use the VS Code MCP one-click link above, run code --add-mcp, or download mihcm-vscode-mcp.json.
2. Add mihcm-vscode.instructions.md to your workspace instructions.
3. Use the same instruction file for VS Code Insiders.
4. Verify through the Command Palette: MCP: List Servers, then start mihcm and confirm tools appear in Copilot agent mode.

Using the skills

Every skill expects the same safety rule: MiHCM components, MiHCM icons, standard Tailwind utilities, and MiHCM semantic token classes are allowed; hardcoded design values and local primitive forks are not. Every UI task must also pass semantic and accessibility review: real headings and paragraphs, Link for navigation, Button for side effects, labelled fields, image alt text, icon-only labels, keyboard focus, contrast, reduced motion, and 44px touch targets.

Every skill also expects agents to use the approved underlying library through the MiHCM wrapper before adding a dependency:

Verify setup

After installation, run these checks:

1. MCP server is registered as mihcm.
2. mihcm_get_agent_setup returns the client you installed.
3. mihcm_search_components returns component results.
4. mihcm_list_tokens returns semantic token names.
5. mihcm_review_semantics_accessibility returns findings for invalid JSX and passes valid representative JSX.
6. The agent can explain the approved library path for forms, calendars, data grids, command palettes, charts, drag/drop, uploads, and rich text.
7. The relevant skill triggers when you ask for MiHCM UI, project setup, component review, or brand/logo work.
8. The agent can explain that hosted MCP is read-only and source-disabled.

If token tools work but component search returns an empty list, the client is reaching the MCP server but the hosted deployment is missing the generated component registry fallback. Redeploy the docs site with the latest @mihcm/mcp build so src/packages/mcp/src/generated-component-registry.ts is included.

For generated install guidance, call:

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

Security rules for installers:

• Review the MCP URL and config before accepting a one-click install.
• Do not place package tokens, PATs, bearer tokens, or .npmrc contents in a downloaded skill file.
• Prefer workspace/team config only when every collaborator should use the same server.
• Keep hosted MCP read-only. Use local stdio only for maintainers who need source-oriented metadata.

Wire local MCP into Claude

The repository Claude settings register a local stdio server named mihcm:

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

Restart Claude after the first build. The local server reads the checked-out repository and may return source-oriented metadata.

Share with external developers

External developers do not need repository access to use the design system facts:

1. Register the hosted MCP endpoint.
2. Install the external skill pack from skills/.
3. Add mihcm-brand when the work includes logos, brand pages, marketing layouts, documents, or presentations.
4. Use the external onboarding guide at /getting-started/external-developers for registry, package, framework, and import setup.
5. Use package access from /getting-started/registry-access.

The hosted endpoint is intentionally narrower than local stdio. It returns design-system metadata, docs snippets, tokens, and validation results, but source-code output is disabled.

Daily workflows

Before adding a component

Search first with mihcm_search_components. If something close exists, extend or compose it before creating a new primitive.

Before editing a component

Inspect it with mihcm_get_component. That returns source paths, wiki coverage, story coverage, AI-UI schema hints, and parsed variant or size options where available.

Before rendering model output

Validate the descriptor with mihcm_validate_descriptor. It uses the same Zod schema as @mihcm/ai-ui, so the MCP check and renderer share one source of truth.

Before building in a consumer app

Use mihcm_list_components, mihcm_get_component_examples, and mihcm_search_patterns to pick existing primitives and compositions before writing JSX.

Before finalizing consumer JSX

Use mihcm_review_frontend_snippet. It combines import checks, token checks, local primitive checks, native control warnings, and Next.js client/server boundary heuristics.

Before claiming a primitive is done

Run mihcm_check_contract. It audits the §7 requirements: source, platform variant, Storybook story, AI-UI schema/allowlist, docs page, and index coverage.

Tool reference

MiHCM-only enforcement

MCP review is advisory unless the consumer project wires it into local checks. For a strict Next.js project:

1. Install @mihcm/mcp as a dev dependency.
2. Add mihcm-design-system-check app components src to CI.
3. Block non-MiHCM UI imports in ESLint.
4. Protect main so the checker must pass.

Full guide: MiHCM-only Next.js enforcement.

Verification loop

Agent-assisted changes still use the normal repo gate from src/:

pnpm build
pnpm typecheck
pnpm lint
pnpm test

Update the wiki after source changes: docs/index.md, docs/log.md, MEMORY.md, and tasks/gotchas.md when a new lesson should be remembered.

Versioning

@mihcm/mcp is publishable through public npm. The current package is installed without consumer registry tokens.

Use a changeset for any user-facing MCP change:

cd src
pnpm changeset

Choose @mihcm/mcp. New tools or request/response changes are minor before 1.0; same-contract bug fixes are patch. Changesets generates src/packages/mcp/CHANGELOG.md in the Version Packages PR.

Security boundary

The MCP server must stay deterministic and repo-bounded, whether it runs locally or on Vercel:

• It reads known repo files only.
• It never evaluates model output.
• It never imports a model-supplied component path.
• It never logs secrets or user prompts.
• Descriptor validation stays anchored to the schema-only componentDescriptorSchema export.

The hosted route also rejects unsupported methods, caps request body size, validates host/origin headers, and can require Authorization: Bearer <token> when MIHCM_MCP_BEARER_TOKEN is configured in Vercel.

Full operational guides:

• MCP setup
• Remote MCP for developers