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
Expected result: the process starts an MCP stdio server and advertises the six
tools below. The published package includes the skills corpus.
| 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
bun src/index.ts
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:
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:
$HIG_SKILLS_DIR — explicit override (point at a newer local copy)<module-dir>/skills — bundled alongside the built artifact (the npm distribution)- Monorepo dev layout —
../../../skills from the source file
$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.
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.