HAP MCP 自动化配置技能

本技能帮助用户在 9 种 AI 工具中自动化配置 HAP MCP 服务器，并验证连通性。

🎯 技能触发场景

当用户说以下任何内容时，立即使用本技能：

"配置这个 MCP"
"添加 MCP 服务器"
"帮我配置 HAP MCP"
"设置 MCP 连接"
提供了包含 hap-mcp- 的配置信息
提供了包含 HAP-Appkey 和 HAP-Sign 的 URL

关于 HAP MCP

HAP 提供两种不同类型的 MCP，作用和使用场景完全不同：

🔷 类型 1: HAP API 文档 MCP

作用: 让 AI 读懂 HAP 接口文档（只读，不执行操作）

配置格式（官方固定）:

{
  "mcpServers": {
    "应用 API - API 文档": {
      "command": "npx",
      "args": ["-y", "apifox-mcp-server@latest", "--site-id=5442569"]
    }
  }
}

适用场景:

📖 查询 HAP API 文档
🛠️ 学习接口结构和参数
📝 生成 API 调用代码

🔶 类型 2: HAP 应用执行 MCP

作用: 让 AI 执行 HAP 应用接口（可操作真实数据）

配置格式（应用专属）:

{
  "mcpServers": {
    "hap-mcp-应用名": {
      "url": "https://api.mingdao.com/mcp?HAP-Appkey=xxx&HAP-Sign=xxx",
      "type": "streamable"
    }
  }
}

⚠️ 重要: HAP MCP 的 "type": "streamable" 配置取决于 IDE 平台：

需要指定: Cursor, TRAE, GitHub Copilot, Antigravity, OpenCode, Windsurf 等
不需要指定: Claude Code（命令行自动处理）
建议: 如果不确定，建议添加 "type": "streamable"，兼容性更好

适用场景:

🔍 查询应用真实数据
✏️ 创建/修改/删除记录
📊 数据统计和分析
🔄 执行工作流

🤖 AI 执行步骤（自动化配置）

当用户提供 MCP 配置时，AI 必须按以下步骤自动化完成配置：

Step 1: 识别当前 AI 工具平台

首先确定用户当前使用的是哪个 AI 工具（从以下 9 个平台中识别）：

Claude Code - Anthropic 官方 CLI
TRAE - 标准化 .trae/ 目录
Cursor - 最流行的 AI 编辑器
GitHub Copilot - GitHub 官方工具
Google Antigravity - Google 实验工具
OpenCode - 开源 AI 工具
Windsurf - Codeium 出品
Gemini CLI - Google Gemini 命令行
Codex - OpenAI 编程助手

识别方法:

如果用户明确提到工具名称，使用该工具
否则，询问用户："您当前使用的是哪个 AI 工具？（Claude Code / Cursor / TRAE / 其他）"

Step 2: 解析 MCP 配置信息

从用户提供的配置中提取：

服务器名称: 如 hap-mcp-客户管理
URL: 包含 HAP-Appkey 和 HAP-Sign 的完整 URL
MCP 类型: 根据配置格式判断是 API 文档 MCP 还是应用执行 MCP

重要: 如果服务器名称包含中文，需要为 Codex 平台生成英文名称：

原始名称: hap-mcp-客户管理 → 保留（用于其他平台）
英文名称: hap-mcp-customer-management → 用于 Codex
转换规则: 将中文部分翻译成英文拼音或英文单词，保持 kebab-case 格式

Step 3: 根据平台自动化配置

根据识别到的平台，执行对应的配置步骤：

🔧 Claude Code

配置方式: 命令行

# 添加 HTTP MCP 服务器
claude mcp add <server-name> --url "<server-url>"

# 示例
claude mcp add hap-mcp-客户管理 --url "https://api.mingdao.com/mcp?HAP-Appkey=xxx&HAP-Sign=xxx"

验证命令:

claude mcp list

🔧 Cursor

MCP 配置文件: .cursor/mcp.json（项目级，推荐）或 ~/.cursor/mcp.json（全局） Skills 安装位置: ~/.cursor/skills/ 或 ~/.cursor/skills-cursor/

自动化步骤:

检查并创建 .cursor 目录（如果不存在）
读取现有配置文件（如果存在）- 重要：保留所有已有配置
增量添加或更新 MCP 配置：
- 如果 MCP 名称不存在 → 新增
- 如果 MCP 名称已存在 → 更新（覆盖）
- 其他 MCP → 保留（不删除）
保存到 .cursor/mcp.json
启用 MCP 服务器（配置后自动生效，无需重启）

配置格式:

{
  "mcpServers": {
    // 保留用户已有的 MCP 配置
    "existing-mcp-server": {
      "url": "https://example.com/mcp"
    },
    // 新增 HAP MCP 配置（必须指定 type: streamable）
    "hap-mcp-应用名": {
      "url": "https://api.mingdao.com/mcp?HAP-Appkey=xxx&HAP-Sign=xxx",
      "type": "streamable"
    }
  }
}

⚠️ 关键原则:

✅ 增量更新: 名称不存在则新增，已存在则更新，其他保留
❌ 禁止覆盖: 不要清空或删除用户已有的 MCP 服务器
✅ streamable 类型: 根据平台决定是否需要（建议添加以提高兼容性）
✅ 启用并验证: 配置后立即启用并验证连通性（无需重启）

注意: "type": "streamable" 是否需要取决于 IDE 平台，建议添加以提高兼容性

🔧 TRAE

配置文件: .trae/mcp.json（项目级）或 ~/.trae/mcp.json（全局）

自动化步骤:

检查并创建 .trae 目录
读取或创建 mcp.json
添加 MCP 配置（格式同 Cursor）
保存文件

🔧 GitHub Copilot

配置文件: ~/.copilot/mcp-config.json

自动化步骤:

检查并创建 ~/.copilot 目录
读取或创建 mcp-config.json 文件
添加 MCP 配置
保存文件

配置格式: 同 Cursor

⚠️ 注意: GitHub Copilot 使用 mcp-config.json 而不是 mcp.json

🔧 Google Antigravity

配置文件: ~/.gemini/antigravity/mcp_config.json

自动化步骤:

检查并创建目录 ~/.gemini/antigravity/
读取或创建 mcp_config.json 文件
在 mcpServers 部分添加配置
保存文件

配置格式: 同 Cursor

⚠️ 注意: Antigravity 使用 mcp_config.json 而不是 config.json

🔧 OpenCode

配置文件: ~/.config/opencode/opencode.json

自动化步骤:

检查并创建目录 ~/.config/opencode/
读取或创建 opencode.json 文件
在 mcp 部分添加配置
保存文件

配置格式: 同 Cursor

⚠️ 注意: OpenCode 使用 opencode.json 而不是 mcp.json

🔧 Windsurf

配置文件: ~/.codeium/windsurf/mcp_config.json

自动化步骤:

检查并创建目录 ~/.codeium/windsurf/
读取或创建 mcp_config.json 文件
添加 MCP 配置
保存文件

配置格式: 同 Cursor

⚠️ 注意: Windsurf 使用 mcp_config.json 而不是 mcp.json

🔧 Gemini CLI

配置文件: settings.json（位置由 Gemini CLI 管理）

配置方式: 命令行或配置文件

命令行方式:

gemini mcp add <server-name> --url "<server-url>"

配置文件方式:

使用 /mcp 命令打开配置文件
在 mcpServers 中添加配置

⚠️ 注意: Gemini CLI 使用 settings.json，具体路径由工具管理

参考文档: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md

🔧 OpenAI Codex

配置文件: ~/.codex/config.toml

⚠️ 重要限制: Codex 的 TOML 格式不支持中文 key 名称

自动化步骤:

中文名称转换: 如果服务器名称包含中文，转换为英文
- 示例: hap-mcp-客户管理 → hap-mcp-customer-management
- 规则: 中文翻译成英文单词或拼音，使用 kebab-case 格式
读取现有 config.toml
添加 MCP 服务器配置（使用英文名称）
保存文件

配置格式 (TOML):

# ✅ 正确 - 使用英文名称
[mcp_servers."hap-mcp-customer-management"]
url = "https://api.mingdao.com/mcp?HAP-Appkey=xxx&HAP-Sign=xxx"

# ❌ 错误 - 中文名称不支持
# [mcp_servers."hap-mcp-客户管理"]
# url = "https://api.mingdao.com/mcp?HAP-Appkey=xxx&HAP-Sign=xxx"

名称转换示例:

hap-mcp-客户管理 → hap-mcp-customer-management
hap-mcp-订单系统 → hap-mcp-order-system
hap-mcp-人力资源 → hap-mcp-hr 或 hap-mcp-human-resources
hap-mcp-财务管理 → hap-mcp-finance-management

Step 4: 启用并验证 MCP 连通性

重要: 配置完成后，必须立即启用 MCP 服务器并验证是否可以正常连接。

4.1 启用 MCP 服务器

配置后自动生效，无需重启工具：

配置文件保存后，MCP 服务器会自动加载
可以立即开始使用 MCP 工具

注意: 如果 MCP 未自动启用，可能需要手动刷新或重新加载配置

4.2 验证连通性

验证方法:

调用 MCP 工具：get_app_info（获取应用信息）
检查返回结果：
- ✅ 成功：返回应用信息（应用名称、工作表列表等）
- ❌ 失败：返回错误信息（鉴权失败、网络错误等）

验证示例:

// 调用 MCP 工具验证连通性
const result = await mcpClient.call('get_app_info');

if (result.success) {
  console.log('✅ MCP 连接成功！');
  console.log('应用名称：', result.appName);
  console.log('工作表数量：', result.worksheets.length);
} else {
  console.error('❌ MCP 连接失败：', result.error);
}

4.3 连接失败诊断

如果 MCP 连接失败，按以下步骤诊断：

诊断清单:

检查配置文件:
- 配置文件路径是否正确
- JSON/TOML 格式是否正确
- "type": "streamable" 是否已添加（HAP MCP 必需）
检查鉴权信息:
- HAP-Appkey 和 HAP-Sign 是否正确
- URL 是否完整且格式正确
检查应用状态:
- 应用是否已启用 MCP 功能
- 应用是否可以正常访问
检查网络连接: 确认可以访问 api.mingdao.com 或 www.nocoly.com
检查 MCP 服务器状态:
- MCP 服务器是否已启用
- 是否需要手动刷新配置

常见错误及解决方案:

错误类型	可能原因	解决方案
鉴权失败	Appkey/Sign 错误	重新从 HAP 获取正确的鉴权信息
连接超时	网络问题	检查网络连接，尝试访问 api.mingdao.com
MCP 未找到	配置未生效	检查配置文件路径和格式，手动刷新配置
配置格式错误	JSON/TOML 语法错误	检查并修正配置文件格式
缺少 streamable	未指定 type	添加 `"type": "streamable"` 到配置中
中文 key 错误	Codex 使用了中文名称	将服务器名称转换为英文

提供给用户的诊断步骤:

❌ MCP 连接失败，请按以下步骤排查：

1. 检查配置文件
   → 位置: [配置文件路径]
   → 格式: [JSON/TOML]
   → 打开文件检查是否有语法错误
   → 确认已添加 "type": "streamable"（HAP MCP 必需）

2. 检查鉴权信息
   → HAP-Appkey: [显示前5位]...
   → HAP-Sign: [显示前5位]...
   → 如果不确定，请重新从 HAP 应用获取

3. 验证 URL 格式
   → 确认 URL 完整且无多余空格
   → 格式: https://api.mingdao.com/mcp?HAP-Appkey=xxx&HAP-Sign=xxx
   → 或: https://www.nocoly.com/mcp?HAP-Appkey=xxx&HAP-Sign=xxx

4. 测试网络连接
   → 在浏览器访问: https://api.mingdao.com
   → 确认网络可以访问明道云 API

5. 检查应用设置
   → 登录 HAP 应用
   → 确认 MCP 功能已启用
   → 检查 API 权限设置

6. 手动刷新配置
   → 如果配置未自动生效，尝试手动刷新
   → 或重启 AI 工具使配置重新加载

如果以上步骤都无法解决，请提供完整错误信息以便进一步诊断。

Step 5: 向用户报告结果

配置完成后，向用户报告：

成功时:

✅ MCP 配置成功！

📋 配置信息：
- 平台：Cursor
- 服务器名称：hap-mcp-客户管理
- 配置文件：.cursor/mcp.json
- 已保留其他 MCP 配置

✅ 连通性验证通过：
- 应用名称：客户管理系统
- 工作表数量：5 个

💡 下一步：
- MCP 已启用并可正常使用
- 现在可以使用 MCP 工具操作数据了

失败时:

❌ MCP 配置已保存，但连通性验证失败

📋 配置信息：
- 平台：Cursor
- 配置文件：.cursor/mcp.json
- 已保留其他 MCP 配置

❌ 连接错误：
- 错误类型：鉴权失败
- 错误信息：Invalid HAP-Appkey or HAP-Sign

🔧 诊断步骤：

1️⃣ 检查配置文件
   → 打开文件: .cursor/mcp.json
   → 检查 JSON 格式是否正确
   → 确认已添加 "type": "streamable"
   → 确认 URL 完整且无多余空格

2️⃣ 检查鉴权信息
   → HAP-Appkey: abc12... (前5位)
   → HAP-Sign: xyz78... (前5位)
   → 如果不确定，请从 HAP 应用重新获取

3️⃣ 验证 URL 格式
   → 格式: https://api.mingdao.com/mcp?HAP-Appkey=xxx&HAP-Sign=xxx
   → 或: https://www.nocoly.com/mcp?HAP-Appkey=xxx&HAP-Sign=xxx

4️⃣ 测试网络
   → 在浏览器访问: https://api.mingdao.com
   → 确认网络可以连接明道云

5️⃣ 检查应用设置
   → 登录 HAP 应用后台
   → 确认 MCP 功能已启用
   → 检查 API 访问权限

6️⃣ 手动刷新配置
   → 如果配置未自动生效，尝试手动刷新
   → 或重启 AI 工具使配置重新加载

📞 需要帮助？
- 提供完整错误信息以便进一步诊断
- 或访问 HAP 帮助中心查看 MCP 配置文档

📋 MCP 配置文件和 Skills 安装位置速查表

MCP 配置文件位置

平台	项目级配置	全局配置	格式	Skills 位置
Claude Code	-	命令行配置	命令	`~/.claude/skills/`
Cursor	`.cursor/mcp.json`	`~/.cursor/mcp.json`	JSON	`~/.cursor/skills/` 或 `~/.cursor/skills-cursor/`
TRAE	`.trae/mcp.json`	`~/.trae/mcp.json`	JSON	`~/.trae/skills/`
GitHub Copilot	-	`~/.copilot/mcp-config.json`	JSON	`~/.copilot/skills/`
Antigravity	-	`~/.gemini/antigravity/mcp_config.json`	JSON	`~/.gemini/antigravity/skills/`
OpenCode	-	`~/.config/opencode/opencode.json`	JSON	`~/.config/opencode/skills/`
Windsurf	-	`~/.codeium/windsurf/mcp_config.json`	JSON	`~/.codeium/windsurf/skills/`
Gemini CLI	-	`settings.json` (工具管理)	JSON	工具管理
Codex	-	`~/.codex/config.toml`	TOML	`~/.codex/skills/`

重要说明

MCP 配置策略:

支持项目级配置的平台（Cursor, TRAE）：优先使用项目级
其他平台：使用全局配置
streamable 类型: 根据平台决定是否需要，建议添加以提高兼容性

Skills 安装:

Skills 通常安装在对应工具的 skills/ 目录下
Cursor 可能有 skills/ 或 skills-cursor/ 两个目录
安装 skills 后需要重启工具使其生效

配置后必须操作:

✅ 保存配置文件
✅ 启用 MCP 服务器（配置后自动生效，无需重启）
✅ 立即验证连通性（调用 get_app_info 测试）
✅ 如果失败，提供详细诊断步骤给用户

⚠️ 重要注意事项

配置时必须做到

✅ 自动化执行: 直接帮用户配置，不要只告诉步骤
✅ 平台识别: 准确识别用户使用的工具
✅ streamable 类型: 根据平台决定是否需要（建议添加以提高兼容性）
✅ 中文转换: Codex 平台必须将中文服务器名称转换为英文
✅ 增量更新: 名称不存在则新增，已存在则更新，其他保留
✅ 格式检查: 确保 JSON/TOML 格式正确
✅ 启用配置: 配置后立即启用（无需重启）
✅ 验证连通: 配置后立即验证 MCP 是否可用
✅ 失败诊断: 连接失败时提供详细诊断步骤和解决方案
✅ 错误处理: 如果配置或验证失败，提供清晰的错误信息

配置时不要做

❌ 不要覆盖配置: 禁止清空或删除用户已有的 MCP 服务器（致命错误！）
❌ 增量更新原则: 名称不存在则新增，已存在则更新，其他必须保留
❌ streamable 类型: 根据平台决定是否需要，建议添加以提高兼容性
❌ 不要只告诉用户如何配置，要直接执行
❌ 不要跳过连通性验证步骤
❌ 不要在验证失败时直接放弃，要提供诊断步骤
❌ 不要在 Codex 中使用中文服务器名称（必须转换为英文）
❌ 不要使用错误的配置格式（根据平台使用正确的 type）

配置优先级

项目级配置 - 如果平台支持（Cursor, TRAE）
全局配置 - 其他平台或用户明确要求

安全提示

🔐 提醒用户保护 HAP-Appkey 和 HAP-Sign
🔐 不要将配置文件提交到 Git（建议添加到 .gitignore）
🔐 定期检查和更新鉴权信息

📚 配置示例

示例 1: Cursor 项目级配置

用户提供:

{"hap-mcp-客户管理":{"url":"https://api.mingdao.com/mcp?HAP-Appkey=abc123&HAP-Sign=xyz789"}}

AI 执行:

创建 .cursor 目录（如果不存在）
读取现有 .cursor/mcp.json 并保留所有已有配置
增量添加新的 HAP MCP 配置:

{
  "mcpServers": {
    // 保留所有已有的 MCP 配置
    "existing-server-1": { "url": "..." },
    "existing-server-2": { "url": "..." },
    // 新增 HAP MCP（必须指定 type: streamable）
    "hap-mcp-客户管理": {
      "url": "https://api.mingdao.com/mcp?HAP-Appkey=abc123&HAP-Sign=xyz789",
      "type": "streamable"
    }
  }
}

保存文件
启用 MCP 服务器（配置后自动生效，无需重启）
立即验证连通性（调用 get_app_info 测试）
如果失败，提供详细的诊断步骤
报告结果给用户

示例 2: Claude Code 命令行配置

用户提供: 同上

AI 执行:

claude mcp add hap-mcp-客户管理 --url "https://api.mingdao.com/mcp?HAP-Appkey=abc123&HAP-Sign=xyz789"

验证:

claude mcp list

示例 3: Codex TOML 配置（中文名称转换）

用户提供:

{"hap-mcp-客户管理":{"url":"https://api.mingdao.com/mcp?HAP-Appkey=abc123&HAP-Sign=xyz789"}}

AI 执行:

识别服务器名称包含中文: hap-mcp-客户管理
转换为英文名称: hap-mcp-customer-management
编辑 ~/.codex/config.toml:

[mcp_servers."hap-mcp-customer-management"]
url = "https://api.mingdao.com/mcp?HAP-Appkey=abc123&HAP-Sign=xyz789"

向用户说明名称转换:

✅ MCP 配置成功！

📋 配置信息：
- 平台：Codex
- 原始名称：hap-mcp-客户管理
- 转换后名称：hap-mcp-customer-management（Codex 不支持中文 key）
- 配置文件：~/.codex/config.toml

💡 说明：Codex 的 TOML 格式不支持中文 key 名称，已自动转换为英文。

🎯 总结

本技能的核心价值：

自动化 - 用户只需提供配置，AI 自动完成所有步骤
全平台支持 - 支持 9 种主流 AI 工具
增量更新 - 只添加新配置，保留用户所有已有 MCP
启用验证 - 配置后启用并验证连通性，确保可用
失败诊断 - 连接失败时提供详细诊断和解决方案
错误处理 - 清晰的错误信息和用户指导

关键原则:

✅ 增量更新：名称不存在则新增，已存在则更新，其他保留
✅ 配置后立即启用并验证（无需重启）
✅ 失败时提供诊断步骤，不直接放弃
✅ Codex 平台自动转换中文名称
✅ "type": "streamable" 根据平台决定，建议添加以提高兼容性

记住: 用户说"配置 MCP"时，不要问"需要我帮您配置吗？"，而是立即执行配置流程！

hap-mcp-usage

HAP MCP 自动化配置技能

🎯 技能触发场景

关于 HAP MCP

🔷 类型 1: HAP API 文档 MCP

🔶 类型 2: HAP 应用执行 MCP

🤖 AI 执行步骤（自动化配置）

Step 1: 识别当前 AI 工具平台

Step 2: 解析 MCP 配置信息

Step 3: 根据平台自动化配置

🔧 Claude Code

🔧 Cursor

🔧 TRAE

🔧 GitHub Copilot

🔧 Google Antigravity

🔧 OpenCode

🔧 Windsurf

🔧 Gemini CLI

🔧 OpenAI Codex

Step 4: 启用并验证 MCP 连通性

4.1 启用 MCP 服务器

4.2 验证连通性

4.3 连接失败诊断

Step 5: 向用户报告结果

📋 MCP 配置文件和 Skills 安装位置速查表

MCP 配置文件位置

重要说明

⚠️ 重要注意事项

配置时必须做到

配置时不要做

配置优先级

安全提示

📚 配置示例

示例 1: Cursor 项目级配置

示例 2: Claude Code 命令行配置

示例 3: Codex TOML 配置（中文名称转换）

🎯 总结