Hap Mcp

@mingdaocloud/hap-mcp

HAP（Hyper Application Platform，超应用平台）是明道（https://www.mingdao.com）推出的 APaaS 平台，可帮助你无需编码，快速构建企业级应用。 这是 HAP 提供的 MCP（Model Context Protocol）服务，可实现与 AI 的无缝集成。

🚀 使用 MCP 客户端快速开始（例如 cursor）

1. 配置 cursor MCP 设置（需要 Node.js 18+）

将以下配置添加到 cursor 设置中：

选项 A：标准配置（SaaS 版本） 创建或编辑 ~/.cursor/mcp.json：

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

选项 B：私有部署配置 仅适用于私有部署环境。在项目根目录中创建 .cursor/mcp.json：

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

注意：HOST 参数仅适用于私有部署环境。请将 https://www.nocoly.com 替换为实际的私有部署服务 URL。

2. 在 cursor 中开始使用

配置完成后，启用 hap-mcp 工具，即可在 AI 对话中直接使用所有 HAP API 工具！

📋 其他安装方式

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

🔭 包含内容

HAP 提供：

• 生产就绪的 MCP 服务，支持 stdio 和 HTTP 两种传输方式
• 完整的 HAP API 集成 - 全面访问 HAP 应用 API
• 为常见 AI 集成任务预先构建的工具
• 可扩展的架构，支持自定义工具、资源和提示词
• 支持 TypeScript，并提供完整的类型安全保障
• 部署和配置简单

✨ 功能特性

• FastMCP 框架：基于强大的 FastMCP 框架构建
• 双传输支持：支持通过 stdio 或 HTTP 运行，灵活性更高
• HAP API 工具：提供用于 HAP 应用操作的完整工具集
• TypeScript：全面支持 TypeScript，满足企业级开发需求
• 生产就绪：针对生产部署进行了优化
• 可扩展：轻松扩展自定义功能

🔧 HAP API 工具

hap-mcp 包含一套完整的工具，可用于与 HAP 应用交互：

可用工具（28 个工具）

核心工作表操作（9 个工具）

• add_worksheet_record：向工作表添加新记录
• delete_worksheet_record：删除工作表中的记录
• update_worksheet_record：更新现有记录
• get_worksheet_fields：获取工作表字段信息
• list_worksheet_records：通过筛选和分页列出记录
• list_worksheets：列出应用中的所有工作表
• get_worksheet_pivot_data：获取带聚合数据的透视表数据
• create_worksheet：创建包含控件的新工作表
• get_worksheet_record_detail：获取特定记录的详细信息

批量操作（2 个工具）

• add_worksheet_records_batch：批量创建多条记录
• update_worksheet_records_batch：批量更新多条记录

高级功能（5 个工具）

• get_app_info：获取应用信息，包括分组、工作表和自定义页面
• get_related_worksheet_records：获取关联工作表中的记录
• get_worksheet_record_share_link：生成记录分享链接
• get_worksheet_record_count：获取工作表中的记录总数
• get_worksheet_record_logs：获取记录的操作历史

角色管理（7 个工具）

• get_roles：列出应用角色
• create_role：创建具有权限的新角色
• delete_role：删除角色
• add_role_members：将用户添加到角色
• remove_role_members：从角色中移除用户
• get_role_detail：获取角色详细信息
• exit_app：将某人从应用中移除

选项集管理（4 个工具）

• create_option_set：创建新的选项集
• get_option_set：获取选项集信息
• update_option_set：更新现有选项集
• delete_option_set：删除选项集

实用工具（1 个工具）

• get_area_info：获取地区信息

快速示例

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

🚀 开始使用

创建项目后：

1. 使用你偏好的包管理器安装依赖：

   # Using npm
   npm install
   
   # Using yarn
   yarn
   
   # Using pnpm
   pnpm install
   
   # Using bun
   bun install
   

2. 启动服务：

   # Start the stdio server
   npm start
   
   # Or start the HTTP server
   npm run start:http
   

3. 如需在开发时启用自动重新加载：

   # Development mode with stdio
   npm run dev
   
   # Development mode with HTTP
   npm run dev:http
   

注意：package.json 中的默认脚本使用 Bun 作为运行时（例如，bun run src/index.ts）。如果你更喜欢使用其他包管理器或运行时，可以修改 package.json 文件中的这些脚本，以使用 Node.js 或其他你选择的运行时。

📖 详细用法

传输方式

MCP 服务支持两种传输方式：

1. stdio 传输（命令行模式）：

   • 在你的本地计算机上运行
   • 由 MCP 客户端（例如 cursor）自动管理
   • 通过 stdout 直接通信
   • 仅供你在本地访问
   • 适用于个人开发和工具

2. SSE 传输（HTTP Web 模式）：

   • 可在本地或远程运行
   • 由你管理和运行
   • 通过网络通信
   • 可在多台计算机之间共享
   • 适用于团队协作和共享工具

在本地运行服务

stdio 传输（CLI 模式）

以 stdio 模式启动服务，供 CLI 工具使用：

# 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 传输（Web 模式）

以 HTTP 模式启动服务，供 Web 应用使用：

# 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

默认情况下，HTTP 服务运行在端口 3001。你可以通过设置 PORT 环境变量来更改端口：

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

连接到服务

从 Cursor 连接

要从 Cursor 连接到 MCP 服务：

1. 打开 Cursor，并进入 Settings（左下角的齿轮图标）
2. 点击左侧栏中的 "Features"
3. 向下滚动到 "MCP Servers" 部分
4. 点击 "Add new MCP server"
5. 输入以下信息：
   • 服务名称：my-mcp-server（或任何你喜欢的名称）
   • 对于 stdio 模式：
     • 类型：command
     • 命令：服务可执行文件的路径，例如 npm start
   • 对于 SSE 模式：
     • 类型：url
     • URL：http://localhost:3001/sse
6. 点击 "Save"

在 Cursor 中使用 mcp.json

如需使用更便于移植的配置，请在项目根目录中创建 .cursor/mcp.json 文件：

标准配置（SaaS 版本）：

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

私有部署配置：

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

你也可以在 ~/.cursor/mcp.json 创建全局配置，以便在所有 Cursor 工作区中使用 MCP 服务。

环境变量：

• APPKEY（必填）：你的明道应用密钥
• SIGN（必填）：你的明道签名
• HOST（可选）：仅用于私有部署的自定义主机 URL（例如，https://www.nocoly.com）。如果提供，API 调用将使用 host/api，而不是 https://api.mingdao.com

注意：

• command 类型的条目会以 stdio 模式运行服务
• url 类型的条目会通过 SSE 传输连接到 HTTP 服务
• 你可以使用 env 字段提供环境变量
• 使用 FastMCP 通过 SSE 连接时，请使用包含 /sse 路径的完整 URL：http://localhost:3001/sse

使用 CLI 工具测试服务

FastMCP 提供了用于测试服务的内置工具：

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

# Inspect with MCP Inspector
npx fastmcp inspect server.ts

使用环境变量

你可以使用环境变量自定义服务：

# 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

🛠️ 添加自定义工具和资源

向 FastMCP 服务添加自定义工具、资源或提示词时：

工具

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}!`;
  }
});

资源

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}`
    };
  }
});

提示词

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?`;
  }
});

📚 文档

如需了解 FastMCP 的更多信息，请访问 FastMCP GitHub 仓库。

如需了解模型上下文协议的更多信息，请访问 MCP 文档。

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。