Hudu MCP

🚀 HUDU MCP Server

このModel Context Protocol (MCP) サーバーは、技術ドキュメントと顧客情報管理のためにHUDUと統合されています。このサーバーにより、Large Language Models (LLMs) はHUDUのAPIとやり取りして、顧客アカウント情報、ナレッジベースの記事、資産などを取得することができます。

✨ 主な機能

• 会社/顧客管理：高度なフィルタリング機能を使って会社情報を取得します。
• ナレッジベースアクセス：強化されたフィルターで技術ドキュメントの記事を検索し、取得します。
• 資産管理：包括的な検索機能で資産情報にアクセスします。
• ユーザー管理：ユーザー情報と詳細を取得します。
• ネットワーク管理：ネットワーク構成と詳細にアクセスします。
• 手順管理：文書化された手順とワークフローを取得します。
• アクティビティログ：フィルタリング機能付きで詳細なアクティビティログにアクセスします。
• 資産レイアウト：資産レイアウトの定義とスキーマを取得します。
• フォルダ管理：組織的なフォルダ構造にアクセスします。
• パスワード管理：資格情報への安全なアクセスを提供します。
• 高度な検索：すべてのリソースタイプに対する強化されたフィルタリング機能。
• 安全な認証：HUDUとのAPIキーベースの認証。
• 型安全性：TypeScriptとZod検証を使用して構築されています。
• エラーハンドリング：包括的なエラーハンドリングとロギング。

📦 インストール

NPMから (推奨)

npm install -g hudu-mcp

ソースから

git clone https://github.com/jlbyh2o/hudu-mcp.git
cd hudu-mcp
npm install
npm run build

🔧 設定

サーバーには2つの環境変数が必要です。

• HUDU_API_KEY：あなたのHUDU APIキー (HUDUの管理画面の「Admin > API Keys」で確認できます)
• HUDU_BASE_URL：あなたのHUDUインスタンスのベースURL (ドメインのみ、/api/v1 は含めないでください)

環境変数の設定

1. サンプル環境ファイルをコピーします。

cp .env.example .env

2. .env ファイルを実際の値で編集します。

HUDU_API_KEY=your_actual_api_key_here
HUDU_BASE_URL=https://your-company.huducloud.com

重要: HUDU_BASE_URL にはドメインのみを含めてください (例: https://your-company.huducloud.com)。URLに /api/v1 を含めないでください。これはクライアントによって自動的に追加されます。

3. .env ファイルがバージョン管理にコミットされないようにしてください (すでに .gitignore に含まれています)。

💻 使用例

基本的な使用法

# 開発モード
npm run dev

# 本番モード
npm start

起動時の検証

MCPサーバーは起動時に /api_info エンドポイントを呼び出してAPI接続を自動的に検証します。これにより、以下のことが保証されます。

• あなたの HUDU_API_KEY が有効でアクティブであること。
• あなたの HUDU_BASE_URL が正しくアクセス可能であること。
• あなたのAPIキーに必要な権限があること。

検証に失敗した場合、問題を示す明確なエラーメッセージが表示されます。

• 401エラー：無効または期限切れのAPIキー。
• 403エラー：APIキーに十分な権限がない。
• 404/接続エラー：不正なベースURLまたはネットワーク問題。
• トークン制限超過：大きなレスポンスは自動的に切り捨てられる場合があります (以下の「レスポンスサイズ管理」を参照)。

この検証により、MCPツールを使用する前に構成問題を早期に発見することができます。

レスポンスサイズ管理

MCPサーバーは、トークン制限の問題を防ぐために大きなレスポンスを自動的に処理します。

• 自動切り捨て：約3MBを超えるレスポンスは自動的に切り捨てられます。
• 切り捨て指示：切り捨てられたレスポンスには _truncation_info が含まれ、詳細が表示されます。
• ページネーションの推奨：page と page_size パラメーターを使用して小さなチャンクを取得します。
• 配列制限：大きな配列は残りのアイテムに関する情報とともに切り捨てられます。
• テキストフィールド制限：長いテキストフィールド (>10KB) は "[truncated]" 指示とともに切り捨てられます。

大規模データセットのベストプラクティス

1. ページネーションを使用する：常に page_size パラメーター (最大100) を使用して結果を制限します。
2. 結果をフィルタリングする：検索とフィルターパラメーターを使用して結果を絞り込みます。
3. 増分クエリを使用する：大規模データセットの場合、複数の小さなクエリを実行します。
4. 切り捨てを監視する：レスポンスの _truncation_info を確認して、切り捨てられたデータを検出します。

ページネーションクエリの例：

{
  "page": 1,
  "page_size": 25,
  "search": "specific term"
}

利用可能なツール

MCPサーバーは、LLMとのやり取りのために以下のツールを提供します。

会社/顧客ツール

get_companies - 高度なフィルタリング機能を使って会社/顧客のリストを取得します。

• パラメーター：
  • name (オプション)：会社名でフィルタリングします。
  • phone_number (オプション)：電話番号でフィルタリングします。
  • website (オプション)：Webサイトでフィルタリングします。
  • city (オプション)：都市名でフィルタリングします。
  • id_number (オプション)：ID番号でフィルタリングします。
  • state (オプション)：州名でフィルタリングします。
  • slug (オプション)：URLスラッグでフィルタリングします。
  • search (オプション)：検索クエリを使用してフィルタリングします。
  • id_in_integration (オプション)：PSA/RMM/外部統合のID/識別子でフィルタリングします。
  • updated_at (オプション)：指定された範囲または正確な時間内に更新された会社をフィルタリングします。
  • page (オプション)：ページネーションのページ番号。
  • page_size (オプション)：ページあたりの結果数。

get_company_details - 特定の会社の詳細情報を取得します。

• パラメーター：
  • id (必須)：会社ID。

ナレッジベースツール

search_articles - 強化されたフィルタリング機能を使ってナレッジベースの記事を検索します。

• パラメーター：
  • search (オプション)：記事の検索クエリ。
  • company_id (オプション)：会社IDで記事をフィルタリングします。
  • name (オプション)：記事名でフィルタリングします。
  • slug (オプション)：URLスラッグでフィルタリングします。
  • draft (オプション)：trueに設定すると、下書き記事のみを表示します。
  • enable_sharing (オプション)：共有ステータスで記事をフィルタリングします。
  • updated_at (オプション)：指定された範囲または正確な時間内に更新された記事をフィルタリングします。
  • page (オプション)：ページネーションのページ番号。
  • page_size (オプション)：ページあたりの結果数。

get_article - 特定の記事の詳細内容を取得します。

• パラメーター：
  • id (必須)：記事ID。

資産管理ツール

get_assets - 高度なフィルタリングオプションを使って資産を取得します。

• パラメーター：
  • company_id (オプション)：資産をフィルタリングする会社ID。
  • asset_layout_id (オプション)：資産レイアウトIDでフィルタリングします。
  • id (オプション)：資産IDでフィルタリングします。
  • name (オプション)：資産名でフィルタリングします。
  • primary_serial (オプション)：主要なシリアル番号でフィルタリングします。
  • archived (オプション)：trueに設定すると、アーカイブされた資産のみを表示します。
  • slug (オプション)：URLスラッグでフィルタリングします。
  • search (オプション)：検索クエリを使用してフィルタリングします。
  • updated_at (オプション)：指定された範囲または正確な時間内に更新された資産をフィルタリングします。
  • page (オプション)：ページネーションのページ番号。
  • page_size (オプション)：ページあたりの結果数。

get_asset_passwords - 会社のパスワード資産 (資格情報) を取得します。

• パラメーター：
  • company_id (オプション)：パスワードをフィルタリングする会社ID。
  • name (オプション)：パスワード名でフィルタリングします。
  • page (オプション)：ページネーションのページ番号。
  • page_size (オプション)：ページあたりの結果数。

get_asset_layouts - 資産レイアウトの定義を取得します。

• パラメーター：
  • name (オプション)：レイアウト名でフィルタリングします。
  • page (オプション)：ページネーションのページ番号。
  • page_size (オプション)：ページあたりの結果数。

get_asset_layout - 特定の資産レイアウトの詳細情報を取得します。

• パラメーター：
  • id (必須)：資産レイアウトID。

注意: セキュリティ上の理由から、リストレスポンスではパスワードはマスクされます。個々のパスワードを取得するには、追加の実装が必要です。

ユーザー管理ツール

get_users - ユーザーのリストを取得します。

• パラメーター：
  • search (オプション)：検索クエリを使用してユーザーをフィルタリングします。
  • page (オプション)：ページネーションのページ番号。
  • page_size (オプション)：ページあたりの結果数。

get_user - 特定のユーザーの詳細情報を取得します。

• パラメーター：
  • id (必須)：ユーザーID。

ネットワーク管理ツール

get_networks - ネットワークのリストを取得します。

• パラメーター：
  • search (オプション)：検索クエリを使用してネットワークをフィルタリングします。
  • page (オプション)：ページネーションのページ番号。
  • page_size (オプション)：ページあたりの結果数。

get_network - 特定のネットワークの詳細情報を取得します。

• パラメーター：
  • id (必須)：ネットワークID。

手順管理ツール

get_procedures - 手順のリストを取得します。

• パラメーター：
  • search (オプション)：検索クエリを使用して手順をフィルタリングします。
  • page (オプション)：ページネーションのページ番号。
  • page_size (オプション)：ページあたりの結果数。

get_procedure - 特定の手順の詳細情報を取得します。

• パラメーター：
  • id (必須)：手順ID。

アクティビティログツール

get_activity_logs - 高度なフィルタリング機能を使ってアクティビティログを取得します。

• パラメーター：
  • user_id (オプション)：ユーザーIDでログをフィルタリングします。
  • user_email (オプション)：ユーザーのメールアドレスでログをフィルタリングします。
  • resource_id (オプション)：リソースIDでログをフィルタリングします。
  • resource_type (オプション)：リソースタイプでログをフィルタリングします。
  • action_message (オプション)：アクションメッセージでログをフィルタリングします。
  • start_date (オプション)：特定の開始日からのログをフィルタリングします。
  • search (オプション)：検索クエリを使用してログをフィルタリングします。
  • page (オプション)：ページネーションのページ番号。
  • page_size (オプション)：ページあたりの結果数。

フォルダ管理ツール

get_folders - フォルダのリストを取得します。

• パラメーター：
  • search (オプション)：検索クエリを使用してフォルダをフィルタリングします。
  • page (オプション)：ページネーションのページ番号。
  • page_size (オプション)：ページあたりの結果数。

get_folder - 特定のフォルダの詳細情報を取得します。

• パラメーター：
  • id (必須)：フォルダID。

Claude Desktopでの使用例

1. サーバーをClaude Desktopの設定に追加します。

{
  "mcpServers": {
    "hudu": {
      "command": "node",
      "args": ["/path/to/hudu-mcp/dist/index.js"],
      "env": {
        "HUDU_API_KEY": "your_api_key",
        "HUDU_BASE_URL": "https://your-hudu-instance.huducloud.com"
      }
    }
  }
}

2. Claude Desktopを再起動します。

3. これで、Claudeに以下のような問い合わせをすることができます。

会社管理:

• "Show me all companies in our HUDU instance"
• "Find companies in New York with phone numbers containing '555'"
• "Search for companies with website containing 'tech.com'"
• "Get company details for Acme Corp"

ナレッジベース:

• "Search for articles about 'network configuration'"
• "Find draft articles updated in the last week"
• "Show me shared articles for company ID 123"
• "Get the article with ID 456"

資産管理:

• "Show me all assets for company ID 789"
• "Find assets with serial number containing 'ABC123'"
• "Search for archived network equipment assets"
• "Get asset layout definitions for servers"

ユーザーとアクティビティ管理:

• "Show me all active users in the system"
• "Find activity logs for user john@company.com from last month"
• "Search for login activities in the past week"

ネットワークと手順:

• "List all documented network configurations"
• "Find procedures related to backup processes"
• "Show me folder structure for IT documentation"

📚 詳細ドキュメント

このMCPサーバーはHUDU API v1と統合されています。以下のエンドポイントがサポートされています。

• /api/v1/companies - 会社管理
• /api/v1/articles - ナレッジベースの記事
• /api/v1/assets - 資産管理
• /api/v1/asset_passwords - パスワード/資格情報管理
• /api/v1/asset_layouts - 資産レイアウトの定義
• /api/v1/activity_logs - アクティビティログ
• /api/v1/api_info - API情報

🔧 開発

プロジェクト構造

src/
├── index.ts              # メインのMCPサーバーエントリポイント
├── hudu-client.ts        # 型定義付きのHUDU APIクライアント
├── tools/
│   ├── index.ts          # ツールの登録とルーティング
│   ├── company-tools.ts  # 会社/顧客関連のツール
│   ├── article-tools.ts  # ナレッジベースの記事ツール
│   └── asset-tools.ts    # 資産管理ツール
└── .env.example          # 環境構成テンプレート

利用可能なスクリプト

• npm run build - TypeScriptプロジェクトをビルドします。
• npm run dev - ホットリロード付きで開発モードで実行します。
• npm run start - ビルドされたサーバーを実行します。
• npm run watch - 変更を監視して再ビルドします。
• npm run clean - distディレクトリをクリーンアップします。

新しいツールの追加

1. 適切なツールファイルでツールのスキーマとハンドラーを定義します。
2. tools/index.ts のルーティングロジックにツール名を追加します。
3. index.ts のツールリストを更新します。
4. 必要に応じて hudu-client.ts に対応するAPIメソッドを追加します。

🔒 セキュリティに関する考慮事項

• APIキーは環境変数を介して渡されます。
• リストレスポンスではパスワードはマスクされます。
• すべてのAPIリクエストには適切な認証ヘッダーが含まれています。
• Zodスキーマを使用した入力検証。
• 情報漏洩を防ぐための包括的なエラーハンドリング。

🐞 トラブルシューティング

一般的な問題

"Configuration validation failed"

• HUDU_API_KEY と HUDU_BASE_URL が環境に設定されていることを確認してください。
• APIキーが有効で適切な権限を持っていることを確認してください。

"HUDU API Error (401)"

• APIキーが正しいことを確認してください。
• APIキーが期限切れになっていないことを確認してください。
• あなたのHUDUユーザーがAPIアクセス権限を持っていることを確認してください。

"HUDU API Error (404)"

• HUDU_BASE_URLが正しいことを確認してください。
• HUDUインスタンスがアクセス可能であることを確認してください。

接続タイムアウト

• あなたのHUDUインスタンスへのネットワーク接続を確認してください。
• ファイアウォール設定がHTTPSアウトバウンド接続を許可していることを確認してください。

デバッグ

環境変数を設定してデバッグログを有効にします。

DEBUG=hudu-mcp:*

🤝 コントリビューション

HUDU MCP Serverへのコントリビューションを歓迎します！以下の手順で貢献することができます。

はじめるに

1. GitHubでリポジトリをフォークします。
2. あなたのフォークをクローンします。

git clone https://github.com/your-username/hudu-mcp.git
cd hudu-mcp

3. 依存関係をインストールします。

npm install

4. 機能ブランチを作成します。

git checkout -b feature/your-feature-name

開発ガイドライン

• 既存のコードスタイルに従ってください (Biomeによって強制されます)。
• 適切なエラーハンドリングを追加してください。
• 新機能のドキュメントを更新してください。
• あなたの変更を十分にテストしてください。
• リンターとフォーマッターを実行します。

npm run check:fix

変更の提出

1. 明確で説明的なメッセージで変更をコミットします。
2. あなたのフォークにプッシュします。

git push origin feature/your-feature-name

3. GitHubでプルリクエストを作成します。
4. あなたの変更とその目的を説明してください。
5. 関連する問題をリンクしてください。

行動規範

このプロジェクトに参加することで、すべてのコントリビューターに対して敬意と包括性のある環境を維持することに同意するものとします。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細については LICENSE ファイルを参照してください。

MITライセンスの要約

あなたは以下のことができます。

• ✅ このソフトウェアを任意の目的で使用することができます。
• ✅ ソフトウェアを変更し、配布することができます。
• ✅ 商用プロジェクトに含めることができます。
• ✅ ソフトウェアをサブライセンスすることができます。

要件:

• 📄 元の著作権表示を含めること。
• 📄 ライセンステキストを含めること。

ソフトウェアは「現状のまま」提供され、保証は一切ありません。

🆘 サポート

以下の問題に関しては、それぞれの方法で対応してください。

• HUDU API: HUDUのドキュメントを参照するか、HUDUサポートに問い合わせてください。
• MCPプロトコル: Model Context Protocolのドキュメントを参照してください。
• このサーバー: このリポジトリで問題を作成してください。