@mingdaocloud/hap-mcp

HAP (Hyper Application Platform) is an APaaS platform launched by Mingdao (https://www.mingdao.com) that helps you rapidly build enterprise-grade applications with no coding. This is the MCP (Model Context Protocol) server by HAP for seamless AI integration.

🚀 Quick Start with MCP Client (e.g. cursor)

1. Configure cursor MCP Settings (Need Node.js 18+)

Add the following configuration to your cursor settings:

Option A: Standard Configuration (SaaS Version) Create or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "hap-mcp": {
      "command": "npx",
      "args": ["-y", "@mingdaocloud/hap-mcp"],
      "env": {
        "APPKEY": "your_APPKEY_here",
        "SIGN": "your_signature_here"
      }
    }
  }
}

Option B: Private Deployment Configuration For private deployment environments only. Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "hap-mcp": {
      "command": "npx",
      "args": ["-y", "@mingdaocloud/hap-mcp"],
      "env": {
        "APPKEY": "your_APPKEY_here",
        "SIGN": "your_signature_here",
        "HOST": "https://www.nocoly.com"
      }
    }
  }
}

Note: The HOST parameter is only required for private deployment environments. Replace https://www.nocoly.com with your actual private deployment server URL.

2. Start Using in cursor

After configuration, true on the hap-mcp tool and you'll have access to all HAP API tools directly in your AI conversations!

📋 Alternative Installation Methods

# Run directly with npx
npx @mingdaocloud/hap-mcp

🔭 What's Included

HAP provides:

• Production-ready MCP server with both stdio and HTTP transport options
• Complete HAP API integration - Full access to HAP Application APIs
• Pre-built tools for common AI integration tasks
• Extensible architecture for custom tools, resources, and prompts
• TypeScript support with full type safety
• Easy deployment and configuration

✨ Features

• FastMCP Framework: Built on the robust FastMCP framework
• Dual Transport Support: Run over stdio or HTTP for maximum flexibility
• HAP API Tools: Complete set of tools for HAP application operations
• TypeScript: Full TypeScript support for enterprise-grade development
• Production Ready: Optimized for production deployments
• Extensible: Easy to extend with custom functionality

🔧 HAP API Tools

hap-mcp includes a complete set of tools for interacting with the HAP application:

Available Tools (33 Tools)

High-Level Tools (5 Tools - 新增!)

• create_full_time_entry: 🌟 一鍵創建完整工時記錄 - 自動查詢、創建任務單和工時單並建立關聯
• list_development_items: 列出所有可用的開發單
• list_members: 列出所有可用的成員列表
• find_member: 根據名稱查找成員信息 (建議在創建工時前先使用此工具確認)

💡 推薦工作流程:

1. 先使用 find_member 確認成員信息
2. 再使用 create_full_time_entry 創建完整工時記錄
3. 這樣可以避免創建錯誤的記錄

Core Worksheet Operations (9 Tools)

• add_worksheet_record: Add new records to worksheets
• delete_worksheet_record: Delete records from worksheets
• update_worksheet_record: Update existing records
• get_worksheet_fields: Get worksheet field information
• list_worksheet_records: List records with filtering and pagination
• list_worksheets: List all worksheets in application
• get_worksheet_pivot_data: Get pivot table data with aggregation
• create_worksheet: Create new worksheets with controls
• get_worksheet_record_detail: Get detailed information of specific records

Batch Operations (2 Tools)

• add_worksheet_records_batch: Bulk create multiple records
• update_worksheet_records_batch: Bulk update multiple records

Advanced Features (5 Tools)

• get_app_info: Get application information including groups, worksheets, and custom pages
• get_related_worksheet_records: Get records from linked worksheets
• get_worksheet_record_share_link: Generate sharing links for records
• get_worksheet_record_count: Get total record count in worksheets
• get_worksheet_record_logs: Get operation history for records

Role Management (7 Tools)

• get_roles: List application roles
• create_role: Create new roles with permissions
• delete_role: Delete roles
• add_role_members: Add users to roles
• remove_role_members: Remove users from roles
• get_role_detail: Get detailed role information
• exit_app: Kick someone off from application

Option Set Management (4 Tools)

• create_option_set: Create new option sets
• get_option_set: Get option set information
• update_option_set: Update existing option sets
• delete_option_set: Delete option sets

Utility Tools (1 Tools)

• get_area_info: Get geographical area information

Quick Example

{
  "tool": "list_worksheet_records",
  "parameters": {
    "worksheetId": "worksheet_id",
    "pageSize": 50
  }
}

🚀 Getting Started

After creating your project:

 claude mcp add-json hap-mcp '{"command":"npx","args":["-y","@keerhuang/hap-mcp"],"env":{"APPKEY":"${apiKey}","SIGN":"%{sign}","HOST":"https://hap.athena.com.tw"}}'

Note: The default scripts in package.json use Bun as the runtime (e.g., bun run src/index.ts). If you prefer to use a different package manager or runtime, you can modify these scripts in your package.json file to use Node.js or another runtime of your choice.

📖 Detailed Usage

Transport Methods

The MCP server supports two transport methods:

1. stdio Transport (Command Line Mode):

   • Runs on your local machine
   • Managed automatically by MCP Client (e.g. cursor)
   • Communicates directly via stdout
   • Only accessible by you locally
   • Ideal for personal development and tools

2. SSE Transport (HTTP Web Mode):

   • Can run locally or remotely
   • Managed and run by you
   • Communicates over the network
   • Can be shared across machines
   • Ideal for team collaboration and shared tools

Running the Server Locally

stdio Transport (CLI Mode)

Start the server in stdio mode for CLI tools:

# Start the stdio server
npm start
# or with other package managers
yarn start
pnpm start
bun start

# Start the server in development mode with auto-reload
npm run dev
# or
yarn dev
pnpm dev
bun dev

HTTP Transport (Web Mode)

Start the server in HTTP mode for web applications:

# Start the HTTP server
npm run start:http
# or
yarn start:http
pnpm start:http
bun start:http

# Start the HTTP server in development mode with auto-reload
npm run dev:http
# or
yarn dev:http
pnpm dev:http
bun dev:http

By default, the HTTP server runs on port 3001. You can change this by setting the PORT environment variable:

# Start the HTTP server on a custom port
PORT=8080 npm run start:http

Connecting to the Server

Connecting from Cursor

To connect to your MCP server from Cursor:

1. Open Cursor and go to Settings (gear icon in the bottom left)
2. Click on "Features" in the left sidebar
3. Scroll down to "MCP Servers" section
4. Click "Add new MCP server"
5. Enter the following details:
   • Server name: my-mcp-server (or any name you prefer)
   • For stdio mode:
     • Type: command
     • Command: The path to your server executable, e.g., npm start
   • For SSE mode:
     • Type: url
     • URL: http://localhost:3001/sse
6. Click "Save"

Using mcp.json with Cursor

For a more portable configuration, create an .cursor/mcp.json file in your project's root directory:

Standard Configuration (SaaS Version):

{
  "mcpServers": {
    "hap-mcp": {
      "command": "npx",
      "args": ["-y", "@mingdaocloud/hap-mcp"],
      "env": {
        "APPKEY": "your_APPKEY_here",
        "SIGN": "your_signature_here"
      }
    },
    "my-mcp-sse": {
      "url": "http://localhost:3001/sse"
    }
  }
}

Private Deployment Configuration:

{
  "mcpServers": {
    "hap-mcp": {
      "command": "npx",
      "args": ["-y", "@mingdaocloud/hap-mcp"],
      "env": {
        "APPKEY": "your_APPKEY_here",
        "SIGN": "your_signature_here",
        "HOST": "https://www.nocoly.com"
      }
    },
    "my-mcp-sse": {
      "url": "http://localhost:3001/sse"
    }
  }
}

You can also create a global configuration at ~/.cursor/mcp.json to make your MCP servers available in all your Cursor workspaces.

Environment Variables:

• APPKEY (required): Your Mingdao application key
• SIGN (required): Your Mingdao signature
• HOST (optional): Custom host URL for private deployment only (e.g., https://www.nocoly.com). If provided, API calls will use host/api instead of https://api.mingdao.com

Note:

• The command type entries run the server in stdio mode
• The url type entry connects to the HTTP server using SSE transport
• You can provide environment variables using the env field
• When connecting via SSE with FastMCP, use the full URL including the /sse path: http://localhost:3001/sse

Testing Your Server with CLI Tools

FastMCP provides built-in tools for testing your server:

# Test with mcp-cli
npx fastmcp dev server.js

# Inspect with MCP Inspector
npx fastmcp inspect server.ts

Using Environment Variables

You can customize the server using environment variables:

# Required Mingdao API credentials
export APPKEY="your_APPKEY_here"
export SIGN="your_signature_here"

# Optional custom host (for private deployment only)
export HOST="https://www.nocoly.com"

# Server configuration
# Change the HTTP port (default is 3001)
PORT=8080 npm run start:http

# Change the host binding (default is 0.0.0.0)
HOST=127.0.0.1 npm run start:http

🛠️ Adding Custom Tools and Resources

When adding custom tools, resources, or prompts to your FastMCP server:

Tools

server.addTool({
  name: "hello_world",
  description: "A simple hello world tool",
  parameters: z.object({
    name: z.string().describe("Name to greet")
  }),
  execute: async (params) => {
    return `Hello, ${params.name}!`;
  }
});

Resources

server.addResourceTemplate({
  uriTemplate: "example://{id}",
  name: "Example Resource",
  mimeType: "text/plain",
  arguments: [
    {
      name: "id",
      description: "Resource ID",
      required: true,
    },
  ],
  async load({ id }) {
    return {
      text: `This is an example resource with ID: ${id}`
    };
  }
});

Prompts

server.addPrompt({
  name: "greeting",
  description: "A simple greeting prompt",
  arguments: [
    {
      name: "name",
      description: "Name to greet",
      required: true,
    },
  ],
  load: async ({ name }) => {
    return `Hello, ${name}! How can I help you today?`;
  }
});

📚 Documentation

For more information about FastMCP, visit FastMCP GitHub Repository.

For more information about the Model Context Protocol, visit the MCP Documentation.

❓ 常見問題 (FAQ)

Q: 通過 API 創建的記錄無法編輯？

A: 這是 API 的限制。通過 API 創建的記錄，其擁有者(owner)會被設置為"未指定"。建議：

• 重要的記錄建議在 HAP 界面上手動創建
• 或者使用 API 創建後，由用戶在界面上補充編輯

詳細說明請參考 FAQ 文檔

Q: 成員字段應該傳什麼值？

A: 成員字段(Option-Member, type=26)應該傳遞：

• 單個成員: 直接傳 accountId 字符串
• 多個成員: 傳 ["accountId1", "accountId2"] 格式的 JSON 字符串
• ❌ 不要傳成員姓名或完整的 JSON 對象

詳細說明請參考 字段類型指南

Q: 如何找到用戶的 accountId？

A: 可以通過以下方式獲取:

1. 查看已有記錄中的成員字段（使用 get_worksheet_record_detail 並設置 getSystemControl: true）
2. 在 caid/uaid/ownerid 字段中查找 accountId

Q: 過濾條件(filters)中的 filterType 和 dateRange 怎麼用？

A: 詳細說明請參考工具描述中的 FilterTypeEnum 和 DateRangeEnum 參考表。 常用示例：

• 查詢今天的記錄: filterType: 17, dateRange: 1
• 按成員篩選: filterType: 24, values: ["accountId"]
• 模糊查詢文本: filterType: 1, value: "關鍵詞"

更多問題請查看 完整 FAQ 文檔

🌟 工時記錄優化功能

本項目專門針對工時記錄場景進行了優化,提供了一套完整的解決方案:

新增功能

1. 高級工具

• create_full_time_entry: 一鍵創建完整工時記錄

  • 自動查找開發單和成員
  • 自動創建任務單並綁定開發單
  • 自動創建工時單並關聯任務單
  • 智能錯誤處理和建議

• list_development_items: 列出所有可用的開發單

2. MCP 資源

• hap://guide/time-entry: 工時記錄完整情境指南
• hap://prompt/create-time-entry: AI 專用的詳細操作 Prompt

3. 輔助模組

• time-entry-helper.ts: 封裝好的輔助函數庫

使用範例

用戶: "可以幫我開任務單在開發單「星愷的工時」裡面,名稱叫做「修復登入bug」,然後在任務單底下開一個2小時的工時單,記得擁有者要填黃星愷"

AI 使用工具:

create_full_time_entry({
  developmentItemName: "星愷的工時",
  taskTitle: "修復登入bug",
  memberName: "黃星愷",
  hours: 2
})

效果對比:

• 優化前: 需要 6 個步驟,多次 API 調用,容易出錯
• 優化後: 1 個步驟即可完成,自動處理所有細節

詳細說明請參閱 工時記錄使用指南

📚 更多文檔

• 工時記錄使用指南 - 🌟 工時記錄完整教程
• 工時記錄情境指南 - 詳細的層級關係和數據格式說明
• 字段類型完整指南 - 詳細的字段格式說明
• 常見問題 FAQ - 常見問題和解決方案
• 工時管理示例 - 實戰代碼示例
• API 常量和輔助函數 - 常用常量定義

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.