hap-mcp-usage

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

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "hap-mcp-usage" with this command: npx skills add garfield-bb/hap-skills-collection/garfield-bb-hap-skills-collection-hap-mcp-usage

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&#x26;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&#x26;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&#x26;HAP-Sign=xxx"

❌ 错误 - 中文名称不支持

[mcp_servers."hap-mcp-客户管理"]

url = "https://api.mingdao.com/mcp?HAP-Appkey=xxx&#x26;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&#x26;HAP-Sign=xxx → 或: https://www.nocoly.com/mcp?HAP-Appkey=xxx&#x26;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&#x26;HAP-Sign=xxx → 或: https://www.nocoly.com/mcp?HAP-Appkey=xxx&#x26;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&#x26;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&#x26;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&#x26;HAP-Sign=xyz789"

验证:

claude mcp list

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

用户提供:

{"hap-mcp-客户管理":{"url":"https://api.mingdao.com/mcp?HAP-Appkey=abc123&#x26;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&#x26;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"时，不要问"需要我帮您配置吗？"，而是立即执行配置流程！

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

General

hap-view-plugin

No summary provided by upstream source.

Repository SourceNeeds Review
-13
garfield-bb
General

hap-v3-api

No summary provided by upstream source.

Repository SourceNeeds Review
-13
garfield-bb
General

hap-skills-updater

No summary provided by upstream source.

Repository SourceNeeds Review
-13
garfield-bb