Hap Mcp

@mingdaocloud/hap-mcp

HAP（Hyper Application Platform）は、Mingdao（https://www.mingdao.com）が提供する APaaS プラットフォームです。コーディング不要で、エンタープライズ向けアプリケーションをすばやく構築できます。 これは、AI とシームレスに連携するための、HAP の MCP（Model Context Protocol）サーバーです。

🚀 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 には以下が含まれます。

• stdio と HTTP の両方のトランスポートに対応した、本番環境対応の MCP サーバー
• 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 サーバーは、次の 2 種類のトランスポート方式に対応しています。

1. stdio トランスポート（コマンドラインモード）：

   • ローカルマシン上で実行します
   • MCP クライアント（例：cursor）が自動的に管理します
   • stdout を介して直接通信します
   • ローカルでのみアクセスできます
   • 個人での開発やツールの利用に最適です

2. SSE トランスポート（HTTP ウェブモード）：

   • ローカルまたはリモートで実行できます
   • ユーザーが管理および実行します
   • ネットワーク経由で通信します
   • 複数のマシン間で共有できます
   • チームでの共同作業や共有ツールに最適です

サーバーをローカルで実行する

stdio トランスポート（CLI モード）

CLI ツール向けに、stdio モードでサーバーを起動します。

# 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 トランスポート（ウェブモード）

ウェブアプリケーション向けに、HTTP モードでサーバーを起動します。

# 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（必須）：Mingdao アプリケーションキー
• SIGN（必須）：Mingdao 署名
• HOST（任意）：プライベートデプロイ専用のカスタムホスト URL（例：https://www.nocoly.com）。指定すると、API 呼び出しでは https://api.mingdao.com の代わりに host/api が使用されます

注：

• 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 リポジトリをご覧ください。

Model Context Protocol の詳細については、MCP ドキュメントをご覧ください。

📄 ライセンス

このプロジェクトは MIT ライセンスのもとでライセンスされています。詳細については、LICENSE ファイルをご覧ください。