HIG Doctor MCP server

Active MCP server for developers connecting HIG Doctor to coding agents. It exposes the HIG skills corpus and source audit as structured tools.

Runs under Node 20+ (after build) or Bun (directly from source). Works with Claude Desktop, Cursor, Windsurf, and Claude Code. Transports: stdio (default) and streamable HTTP (--http).

Install and start

npx hig-mcp

Expected result: the process starts an MCP stdio server and advertises the six tools below. The published package includes the skills corpus.

Tools

Tool	Purpose
hig_list_skills	Enumerate available skills with descriptions and reference topics. Call first to discover the corpus.
hig_lookup	Fetch HIG reference markdown. Provide a skill name (e.g. hig-foundations) or skill + topic (e.g. skill=hig-foundations, topic=color).
hig_search	BM25 full-text search across every reference topic. Ask in natural language (e.g. "minimum touch target size") and get ranked topics with snippets.
hig_audit	Run the HIG compliance audit on a project directory. Returns severity counts, per-category breakdown, a markdown report, config/baseline status, and an optional fail_on gate.
hig_audit_file	Audit a single file — the fast inner loop after writing or editing code. Returns each finding with rule ID, severity, line, fix guidance, and HIG citation.
hig_explain_finding	Explain a finding: full rule metadata plus an excerpt of the cited Apple HIG reference. Pass a ruleId from an audit result.

Every tool returns structuredContent (parsed JSON) alongside the text mirror, so agents can consume structure directly. Content is from Apple's HIG, snapshot dated 2025-02-02; Apple's live Human Interface Guidelines remain canonical.

Run from a checkout

git clone https://github.com/raintree-technology/hig-doctor.git
cd hig-doctor/packages/mcp
bun install            # or: npm install
bun src/index.ts       # run directly (no build), or:
npm run build && node dist/index.js

Claude Desktop config

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hig-doctor": {
      "command": "npx",
      "args": ["-y", "hig-mcp"]
    }
  }
}

For a local checkout, point command/args at the Bun source (bun /abs/path/packages/mcp/src/index.ts) or the built Node artifact (node /abs/path/packages/mcp/dist/index.js).

Streamable HTTP transport

For remote or multi-client setups, start the server over HTTP instead of stdio:

hig-mcp --http 3845      # POST /mcp on the given port (default 3845)

Each request is handled statelessly, so concurrent clients are safe.

Cursor / Windsurf / Claude Code

All honor the MCP stdio protocol via each editor's mcpServers config. Point command/args at npx hig-mcp, or at the Bun/Node entry point of a local checkout.

Skills directory resolution

The server resolves the skills corpus in this order:

1. $HIG_SKILLS_DIR — explicit override (point at a newer local copy)
2. <module-dir>/skills — bundled alongside the built artifact (the npm distribution)
3. Monorepo dev layout — ../../../skills from the source file
4. $PWD/skills — current working directory

The published npm package bundles the corpus at dist/skills, so $HIG_SKILLS_DIR is only needed to override it.

Input validation

Slug arguments (skill, topic) are validated against a kebab-case allowlist (/^[a-z0-9-]+$/) before being used to construct filesystem paths. hig_audit.directory and hig_audit_file.file must be absolute paths. Invalid inputs throw before any filesystem access.

Limits and support boundary

The audit tools provide static review evidence; they do not prove HIG conformance, accessibility, or design quality. HTTP mode does not add authentication or TLS, so place it behind an appropriate local or trusted transport boundary. See the project guide, benchmark, and security policy.

License

MIT for this package. Apple HIG reference content read by hig_lookup/hig_search is © Apple Inc. — see the repository root THIRD_PARTY_NOTICES.md for the full attribution.