hap-mcp-usage

HAP MCP automated configuration skill

This skill helps users in 9 AI toolsautomatically configure the HAP MCP server, and verify connectivity.

🎯 Skill trigger scenarios

When the user says any of the following,immediately use this skill：

"Configure this MCP"
"Add MCP server"
"Help me configure HAP MCP"
"Set up MCP connection"
provided information containing hap-mcp- configuration information
provided information containing HAP-Appkey and HAP-Sign URL

About HAP MCP

HAP provides two different types of MCP,with completely different functions and use cases：

🔷 Type 1: HAP API documentation MCP

Function: lets AI read and understand HAP interface documentation (read-only, does not execute operations)

Configuration format(officially fixed):

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

Applicable scenarios:

📖 Query HAP API documentation
🛠️ Learn interface structure and parameters
📝 Generate API call code

🔶 Type 2: HAP app execution MCP

Function: lets AI execute HAP app interfaces (can operate on real data)

Configuration format(app-specific):

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

⚠️ Important: HAP MCP's "type": "streamable" configurationdepends on the IDE platform：

Needs to be specified: Cursor, TRAE, GitHub Copilot, Antigravity, OpenCode, Windsurf, etc.
Does not need to be specified: Claude Code (handled automatically by the command line)
Suggestion: If unsure, it is recommended to add "type": "streamable", for better compatibility

Applicable scenarios:

🔍 Query real app data
✏️ Create/modify/delete records
📊 Data statistics and analysis
🔄 Execute workflows

🤖 AI execution steps (automated configuration)

When the user provides an MCP configuration, the AI must complete the configuration automatically according to the following steps:

Step 1: Identify the current AI tool platform

First determine which AI tool the user is currently using (identify from the following 9 platforms):

Claude Code - Anthropic official CLI
TRAE - Standardized .trae/ directory
Cursor - The most popular AI editor
GitHub Copilot - GitHub official tool
Google Antigravity - Google experimental tool
OpenCode - Open-source AI tool
Windsurf - by Codeium
Gemini CLI - Google Gemini command line
Codex - OpenAI programming assistant

Identification method:

If the user explicitly mentions the tool name, use that tool
Otherwise, ask the user: "Which AI tool are you currently using? (Claude Code / Cursor / TRAE / other)"

Step 2: Parse the MCP configuration information

Extract from the configuration provided by the user:

Server name: such as hap-mcp-客户管理
URL: contains HAP-Appkey and HAP-Sign full URL
MCP Type: Based on the configuration format, determine whether it is API documentation MCP or application execution MCP

Important: If the server name contains Chinese, you need to generate an English name for the Codex platform:

Original name: hap-mcp-客户管理 → Keep (for other platforms)
English name: hap-mcp-customer-management → Used for Codex
Conversion rule: Translate the Chinese part into English pinyin or English words, keeping the kebab-case format

Step 3: Automate configuration based on the platform

Based on the identified platform, execute the corresponding configuration steps:

🔧 Claude Code

Configuration method: Command line

# 添加 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"

Verification command:

claude mcp list

🔧 Cursor

MCP configuration file: .cursor/mcp.json(project-level, recommended) or ~/.cursor/mcp.json(global) Skills installation location: ~/.cursor/skills/ or ~/.cursor/skills-cursor/

Automation steps:

Check and create the .cursor directory (if it does not exist)
Read the existing configuration file(if it exists) - Important: keep all existing configurations
Incrementally add or update MCP configuration:
- If the MCP name does not exist → add
- If the MCP name already exists → update (overwrite)
- Other MCPs → keep (do not delete)
Save to .cursor/mcp.json
Enable the MCP server(takes effect automatically after configuration, no restart required)

Configuration format:

{
  "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"
    }
  }
}

⚠️ Key principles:

✅ Incremental update: If the name does not exist, add it; if it already exists, update it; keep others
❌ Do not overwrite: Do not clear or delete the user's existing MCP servers
✅ streamable type: Whether it is needed depends on the platform (recommended to add to improve compatibility)
✅ Enable and verify: Enable immediately after configuration and verify connectivity (no restart required)

Note: "type": "streamable" Whether it is needed depends on the IDE platform; it is recommended to add it to improve compatibility

🔧 TRAE

Configuration file: .trae/mcp.json(project-level) or ~/.trae/mcp.json(global)

Automation steps:

Check and create the .trae directory
Read or create mcp.json
Add MCP configuration (format same as Cursor)
Save the file

🔧 GitHub Copilot

Configuration file: ~/.copilot/mcp-config.json

Automation steps:

Check and create the ~/.copilot directory
Read or create the mcp-config.json file
Add MCP configuration
Save the file

Configuration format: Same as Cursor

⚠️ Note: GitHub Copilot uses mcp-config.json instead of mcp.json

🔧 Google Antigravity

Configuration file: ~/.gemini/antigravity/mcp_config.json

Automation steps:

Check and create the directory ~/.gemini/antigravity/
Read or create the mcp_config.json file
In the mcpServers section, add configuration
Save the file

Configuration format: Same as Cursor

⚠️ Note: Antigravity uses mcp_config.json instead of config.json

🔧 OpenCode

Configuration file: ~/.config/opencode/opencode.json

Automation steps:

Check and create directory ~/.config/opencode/
Read or create opencode.json file
In mcp section add configuration
Save file

Configuration format: Same as Cursor

⚠️ Note: OpenCode uses opencode.json instead of mcp.json

🔧 Windsurf

Configuration file: ~/.codeium/windsurf/mcp_config.json

Automation steps:

Check and create directory ~/.codeium/windsurf/
Read or create mcp_config.json file
Add MCP configuration
Save file

Configuration format: Same as Cursor

⚠️ Note: Windsurf uses mcp_config.json instead of mcp.json

🔧 Gemini CLI

Configuration file: settings.json(location managed by Gemini CLI)

Configuration method: Command line or configuration file

Command line method:

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

Configuration file method:

Use /mcp command to open configuration file
In mcpServers add configuration

⚠️ Note: Gemini CLI uses settings.json, the specific path is managed by the tool

Reference documentation: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md

🔧 OpenAI Codex

Configuration file: ~/.codex/config.toml

⚠️ Important limitation: Codex's TOML formatdoes not support Chinese key names

Automation steps:

Chinese name conversion: If the server name contains Chinese, convert to English
- Example: hap-mcp-客户管理 → hap-mcp-customer-management
- Rule: Translate Chinese into English words or pinyin, use kebab-case format
Read existing config.toml
Add MCP server configuration (use English name)
Save file

Configuration format (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"

Name conversion example:

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

Step 4: Enable and verify MCP connectivity

Important: After configuration is complete, you mustimmediately enable the MCP server and verifywhether it can connect normally.

4.1 Enable MCP server

Takes effect automatically after configuration, no need to restart the tool:

After the configuration file is saved, the MCP server will load automatically
You can start using MCP tools immediately

Note: If MCP is not enabled automatically, you may need to manually refresh or reload the configuration

4.2 Verify connectivity

Verification method:

Call MCP tool:get_app_info(get application information)
Check the returned result:
- ✅ Success: Returns application information (application name, worksheet list, etc.)
- ❌ Failure: Returns error information (authentication failure, network error, etc.)

Verification example:

// 调用 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 Connection failure diagnosis

If the MCP connection fails, diagnose according to the following steps:

Diagnosis checklist:

Check configuration file:
- Whether the configuration file path is correct
- Whether the JSON/TOML format is correct
- "type": "streamable" Whether it has been added (required for HAP MCP)
Check authentication information:
- HAP-Appkey and HAP-Sign are correct
- Whether the URL is complete and correctly formatted
Check application status:
- Whether the MCP feature is enabled for the application
- Whether the application is accessible
Check network connection: Confirm that you can access api.mingdao.com or www.nocoly.com
Check MCP server status:
- Whether the MCP server is enabled
- Whether the configuration needs to be manually refreshed

Common errors and solutions:

Error type	Possible cause	Solution
Authentication failed	Incorrect Appkey/Sign	Retrieve the correct authentication information from HAP again
Connection timed out	Network issue	Check the network connection and try accessing api.mingdao.com
MCP not found	Configuration not taking effect	Check the configuration file path and format, and manually refresh the configuration
Configuration format error	JSON/TOML syntax error	Check and correct the configuration file format
Missing streamable	type not specified	Add `"type": "streamable"` to the configuration
Chinese key error	Codex used a Chinese name	Convert the server name to English

Diagnostic steps to provide to the user:

❌ 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: Report the results to the user

After configuration is complete, report to the user:

On success:

✅ MCP 配置成功！

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

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

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

On failure:

❌ 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 配置文档

📋 Quick reference table for MCP configuration files and Skills installation locations

MCP configuration file locations

Platform	Project-level configuration	Global configuration	Format	Skills location
Claude Code	-	Command-line configuration	Command	`~/.claude/skills/`
Cursor	`.cursor/mcp.json`	`~/.cursor/mcp.json`	JSON	`~/.cursor/skills/` or `~/.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` (tool management)	JSON	Tool management
Codex	-	`~/.codex/config.toml`	TOML	`~/.codex/skills/`

Important notes

MCP configuration strategy:

Platforms that support project-level configuration (Cursor, TRAE): Prefer project-level
Other platforms: Use global configuration
streamable type: Determined by platform requirements; recommended to add for better compatibility

Skills installation:

Skills are usually installed in the corresponding tool's skills/ directory
Cursor may have skills/ or skills-cursor/ two directories
After installing skills, the tool needs to be restarted for them to take effect

Required actions after configuration:

✅ Save the configuration file
✅ Enable the MCP server(Takes effect automatically after configuration, no restart required)
✅ Verify connectivity immediately(Call get_app_info to test)
✅ If it fails, provide detailed diagnostic steps to the user

⚠️ Important notes

Must be done during configuration

✅ Automated execution: Configure directly for the user, do not just tell them the steps
✅ Platform identification: Accurately identify the tool the user is using
✅ streamable type: Determine whether it is needed based on the platform (recommended to add for better compatibility)
✅ Chinese conversion: The Codex platform must convert Chinese server names to English
✅ Incremental update: If the name does not exist, add it; if it already exists, update it; keep everything else
✅ Format check: Ensure the JSON/TOML format is correct
✅ Enable configuration: Enable immediately after configuration (no restart required)
✅ Verify connectivity: After configuration,verify immediately whether the MCP is available
✅ Failure diagnosis: Provide detailed diagnostic steps and solutions when the connection fails
✅ Error handling: If configuration or verification fails, provide clear error information

Do not do during configuration

❌ Do not overwrite configuration: Do not clear or delete the user's existing MCP servers (fatal error!)
❌ Incremental update principle: If the name does not exist, add it; if it already exists, update it; everything else must be preserved
❌ streamable type: Determine whether it is needed based on the platform; it is recommended to add it for better compatibility
❌ Do not just tell the user how to configure it; execute directly
❌ Do not skip the connectivity verification step
❌ Do not give up directly when verification fails; provide diagnostic steps
❌ Do not use Chinese server names in Codex (they must be converted to English)
❌ Do not use the wrong configuration format (use the correct type according to the platform)

Configuration priority

Project-level configuration - If the platform supports it (Cursor, TRAE)
Global configuration - Other platforms or when the user explicitly requests it

Security tips

🔐 Remind the user to protect HAP-Appkey and HAP-Sign
🔐 Do not commit configuration files to Git (recommended to add to .gitignore）
🔐 Regularly check and update authentication information

📚 Configuration examples

Example 1: Cursor project-level configuration

User provides:

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

AI executes:

Create .cursor directory (if it does not exist)
Read the existing .cursor/mcp.json and preserve all existing configuration
Incrementally addthe new HAP MCP configuration:

{
  "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"
    }
  }
}

Save the file
Enable the MCP server(takes effect automatically after configuration, no restart required)
Verify connectivity immediately(call get_app_info to test)
If it fails, provide detailed diagnostic steps
Report the result to the user

Example 2: Claude Code command-line configuration

User provides: Same as above

AI executes:

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

Verification:

claude mcp list

Example 3: Codex TOML configuration (Chinese name conversion)

User provides:

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

AI executes:

Identify that the server name contains Chinese: hap-mcp-客户管理
Convert to English name: hap-mcp-customer-management
Edit ~/.codex/config.toml:

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

Explain name conversion to the user:

✅ MCP 配置成功！

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

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

🎯 Summary

Core value of this skill:

Automation - Users only need to provide configuration; AI automatically completes all steps
Full platform support - Supports 9 mainstream AI tools
Incremental updates - Only adds new configurations, preserving all existing user MCPs
Enable and verify - After configuration, enable and verify connectivity to ensure usability
Failure diagnosis - Provides detailed diagnosis and solutions when connection fails
Error handling - Clear error messages and user guidance

Key principles:

✅ Incremental updates: If the name does not exist, add it; if it already exists, update it; keep the rest
✅ After configurationenable and verify immediately(no restart required)
✅ Provide diagnostic steps on failure, do not give up directly
✅ Codex platform automatically converts Chinese names
✅ "type": "streamable" Determined by the platform; adding it is recommended to improve compatibility

Remember: When the user says "configure MCP", do not ask "Do you need me to help you configure it?", but immediately execute the configuration process!

About this skill

🎯 Skill trigger scenarios

About HAP MCP

🔷 Type 1: HAP API documentation MCP

🔶 Type 2: HAP app execution MCP

🤖 AI execution steps (automated configuration)

Step 1: Identify the current AI tool platform

Step 2: Parse the MCP configuration information

Step 3: Automate configuration based on the platform

🔧 Claude Code

🔧 Cursor

🔧 TRAE

🔧 GitHub Copilot

🔧 Google Antigravity

🔧 OpenCode

🔧 Windsurf

🔧 Gemini CLI

🔧 OpenAI Codex

Step 4: Enable and verify MCP connectivity

4.1 Enable MCP server

4.2 Verify connectivity

4.3 Connection failure diagnosis

Step 5: Report the results to the user

📋 Quick reference table for MCP configuration files and Skills installation locations

MCP configuration file locations

Important notes

⚠️ Important notes

Must be done during configuration

Do not do during configuration

Configuration priority

Security tips

📚 Configuration examples

Example 1: Cursor project-level configuration

Example 2: Claude Code command-line configuration

Example 3: Codex TOML configuration (Chinese name conversion)

🎯 Summary