HIG Doctor

HIG Doctor MCP 服务

供开发者将 HIG Doctor 接入编码 Agent 的活跃 MCP 服务。 它以结构化工具的形式提供 HIG 技能库和源代码审计功能。

构建后可在 Node 20+ 下运行，也可直接从源代码通过 Bun 运行。支持 Claude Desktop、Cursor、Windsurf 和 Claude Code。传输方式：stdio（默认）和可流式 HTTP（--http）。

安装并启动

npx hig-mcp

预期结果：该进程会启动一个 MCP stdio 服务，并公布以下六种工具。已发布的软件包包含技能库。

工具

工具	用途
hig_list_skills	列出可用技能及其描述和参考主题。首先调用此工具以了解技能库内容。
hig_lookup	获取 HIG 参考 Markdown。提供技能名称（例如 hig-foundations），或技能名称加主题（例如 skill=hig-foundations, topic=color）。
hig_search	在所有参考主题中进行 BM25 全文搜索。使用自然语言提问（例如“最小触控目标尺寸”），即可获取带摘要片段的相关主题排名。
hig_audit	对项目目录运行 HIG 合规性审计。返回严重性统计、按类别划分的明细、Markdown 报告、配置／基线状态，以及可选的 fail_on 门槛。
hig_audit_file	审计单个文件——编写或编辑代码后的快速迭代环节。返回每项发现及其规则 ID、严重性、行号、修复指南和 HIG 引用。
hig_explain_finding	解释一项发现：提供完整的规则元数据，以及引用的 Apple HIG 参考内容摘录。传入审计结果中的 ruleId。

每种工具都会返回 structuredContent（已解析的 JSON）以及对应的文本内容，因此 Agent 可以直接使用结构化数据。内容来自 Apple 的 HIG，快照日期为 2025-02-02；Apple 的实时人机界面指南仍是权威版本。

从代码仓库检出目录运行

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 配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

对于本地检出目录，可将 command／args 指向 Bun 源文件（bun /abs/path/packages/mcp/src/index.ts）或构建后的 Node 产物（node /abs/path/packages/mcp/dist/index.js）。

可流式 HTTP 传输

对于远程或多客户端环境，通过 HTTP 而非 stdio 启动服务：

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

每个请求都会以无状态方式处理，因此可安全地并发使用。

Cursor／Windsurf／Claude Code

这些编辑器都通过各自的 mcpServers 配置支持 MCP stdio 协议。将 command／args 指向 npx hig-mcp，或指向本地检出目录中的 Bun／Node 入口点。

技能目录解析

服务按以下顺序解析技能库：

1. $HIG_SKILLS_DIR — 显式覆盖（指向较新的本地副本）
2. <module-dir>/skills — 与构建产物一同打包（npm 发行包）
3. Monorepo 开发目录结构 — 从源文件所在位置使用 ../../../skills
4. $PWD/skills — 当前工作目录

已发布的 npm 软件包会将技能库打包到 dist/skills，因此只有在需要覆盖时才需设置 $HIG_SKILLS_DIR。

输入验证

Slug 参数（skill、topic）会先根据 kebab-case 允许列表（/^[a-z0-9-]+$/）进行验证，然后才用于构造文件系统路径。hig_audit.directory 和 hig_audit_file.file 必须是绝对路径。无效输入会在访问文件系统之前抛出错误。

限制和支持范围

审计工具提供静态审查依据；它们无法证明符合 HIG、具备可访问性或达到设计质量。HTTP 模式不提供身份验证或 TLS，因此应将其置于适当的本地或可信传输边界之后。请参阅项目指南、基准测试和安全策略。

许可证

此软件包采用 MIT 许可证。hig_lookup/hig_search 读取的 Apple HIG 参考内容版权归 Apple Inc. 所有 — 完整署名信息请参阅仓库根目录的 THIRD_PARTY_NOTICES.md。