Mingdao Cloud HAP MCP automated configuration skill. Immediate trigger conditions: the user mentions "configure MCP", "add MCP", "MCP configuration", "MCP connection", "set MCP", provides a configuration containing "hap-mcp-", or provides a URL containing "HAP-Appkey" and "HAP-Sign". Supports automated configuration for nine AI tools and automatically verifies connectivity after configuration.
本技能帮助用户在 9 种 AI 工具中自动化配置 HAP MCP 服务器，并验证连通性。
当用户说以下任何内容时，立即使用本技能：
hap-mcp- 的配置信息HAP-Appkey 和 HAP-Sign 的 URLHAP 提供两种不同类型的 MCP，作用和使用场景完全不同：
作用: 让 AI 读懂 HAP 接口文档（只读，不执行操作）
配置格式（官方固定）:
{
"mcpServers": {
"应用 API - API 文档": {
"command": "npx",
"args": ["-y", "apifox-mcp-server@latest", "--site-id=5442569"]
}
}
}
适用场景:
作用: 让 AI 执行 HAP 应用接口（可操作真实数据）
配置格式（应用专属）:
{
"mcpServers": {
"hap-mcp-应用名": {
"url": "https://api.mingdao.com/mcp?HAP-Appkey=xxx&HAP-Sign=xxx",
"type": "streamable"
}
}
}
⚠️ 重要: HAP MCP 的 "type": "streamable" 配置取决于 IDE 平台：
"type": "streamable"，兼容性更好适用场景:
当用户提供 MCP 配置时，AI 必须按以下步骤自动化完成配置：
首先确定用户当前使用的是哪个 AI 工具（从以下 9 个平台中识别）：
.trae/ 目录识别方法:
从用户提供的配置中提取：
hap-mcp-客户管理HAP-Appkey 和 HAP-Sign 的完整 URL重要: 如果服务器名称包含中文，需要为 Codex 平台生成英文名称：
hap-mcp-客户管理 → 保留（用于其他平台）hap-mcp-customer-management → 用于 Codex根据识别到的平台，执行对应的配置步骤：
配置方式: 命令行
# 添加 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
MCP 配置文件: .cursor/mcp.json（项目级，推荐）或 ~/.cursor/mcp.json（全局）
Skills 安装位置: ~/.cursor/skills/ 或 ~/.cursor/skills-cursor/
自动化步骤:
.cursor 目录（如果不存在）.cursor/mcp.json配置格式:
{
"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"
}
}
}
⚠️ 关键原则:
注意: "type": "streamable" 是否需要取决于 IDE 平台，建议添加以提高兼容性
配置文件: .trae/mcp.json（项目级）或 ~/.trae/mcp.json（全局）
自动化步骤:
.trae 目录mcp.json配置文件: ~/.copilot/mcp-config.json
自动化步骤:
~/.copilot 目录mcp-config.json 文件配置格式: 同 Cursor
⚠️ 注意: GitHub Copilot 使用 mcp-config.json 而不是 mcp.json
配置文件: ~/.gemini/antigravity/mcp_config.json
自动化步骤:
~/.gemini/antigravity/mcp_config.json 文件mcpServers 部分添加配置配置格式: 同 Cursor
⚠️ 注意: Antigravity 使用 mcp_config.json 而不是 config.json
配置文件: ~/.config/opencode/opencode.json
自动化步骤:
~/.config/opencode/opencode.json 文件mcp 部分添加配置配置格式: 同 Cursor
⚠️ 注意: OpenCode 使用 opencode.json 而不是 mcp.json
配置文件: ~/.codeium/windsurf/mcp_config.json
自动化步骤:
~/.codeium/windsurf/mcp_config.json 文件配置格式: 同 Cursor
⚠️ 注意: Windsurf 使用 mcp_config.json 而不是 mcp.json
配置文件: 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
配置文件: ~/.codex/config.toml
⚠️ 重要限制: Codex 的 TOML 格式不支持中文 key 名称
自动化步骤:
hap-mcp-客户管理 → hap-mcp-customer-managementconfig.toml配置格式 (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-managementhap-mcp-订单系统 → hap-mcp-order-systemhap-mcp-人力资源 → hap-mcp-hr 或 hap-mcp-human-resourceshap-mcp-财务管理 → hap-mcp-finance-management重要: 配置完成后，必须立即启用 MCP 服务器并验证是否可以正常连接。
配置后自动生效，无需重启工具：
注意: 如果 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);
}
如果 MCP 连接失败，按以下步骤诊断：
诊断清单:
"type": "streamable" 是否已添加（HAP MCP 必需）HAP-Appkey 和 HAP-Sign 是否正确api.mingdao.com 或 www.nocoly.com常见错误及解决方案:
| 错误类型 | 可能原因 | 解决方案 |
|---------|---------|---------|
| 鉴权失败 | 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 工具使配置重新加载
如果以上步骤都无法解决，请提供完整错误信息以便进一步诊断。
配置完成后，向用户报告：
成功时:
✅ 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 配置文档
| 平台 | 项目级配置 | 全局配置 | 格式 | 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 配置策略:
Skills 安装:
skills/ 目录下skills/ 或 skills-cursor/ 两个目录配置后必须操作:
HAP-Appkey 和 HAP-Sign.gitignore）用户提供:
{"hap-mcp-客户管理":{"url":"https://api.mingdao.com/mcp?HAP-Appkey=abc123&HAP-Sign=xyz789"}}
AI 执行:
.cursor 目录（如果不存在）.cursor/mcp.json 并保留所有已有配置{
"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"
}
}
}
用户提供: 同上
AI 执行:
claude mcp add hap-mcp-客户管理 --url "https://api.mingdao.com/mcp?HAP-Appkey=abc123&HAP-Sign=xyz789"
验证:
claude mcp list
用户提供:
{"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 名称，已自动转换为英文。
本技能的核心价值：
关键原则:
"type": "streamable" 根据平台决定，建议添加以提高兼容性记住: 用户说"配置 MCP"时，不要问"需要我帮您配置吗？"，而是立即执行配置流程！
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer