Hudu

hudu-mcp

Hudu IT ドキュメントプラットフォーム向けの MCP（Model Context Protocol）サーバーです。MCP 互換クライアントを通じて、会社、アセット、記事、パスワード、Web サイトなどを管理するための 39 個のツールと 6 個のリソースを提供します。

特長

• 39 個の MCP ツールで、Hudu の主要なリソースをすべてカバー
• 6 個の MCP リソースで、データに直接アクセス
• 2 種類の認証モード：従来の HUDU_API_KEY による REST アクセス、または oauth — 新しい Hudu インスタンス独自のネイティブ MCP サーバーへの、薄型の認証済みプロキシ
• 2 種類のトランスポートに対応：stdio（デフォルト）と HTTP Streamable
• 遅延初期化 - SDK クライアントは最初のツール呼び出し時に作成されます
• 接続テストを内蔵
• MCP stdio トランスポートへのログ出力の混入を防ぐため、すべてのログを stderr に出力

ワンクリックデプロイ

重要

**クリックする前に：**このサーバーは、GitHub Packages npm レジストリでホストされている @wyre-technology/node-hudu に依存しています。GitHub Packages では匿名アクセスができません。パッケージが公開されていても、すべての npm install にトークンが必要です。クラウドビルダーは npm install を実行するため、トークンを渡す必要があります。渡さないと、ビルドは npm error 401 Unauthorized ... npm.pkg.github.com で失敗します。

1. read:packages スコープを持つ GitHub の Personal Access Token を作成します （classic token）。 公開パッケージを読み取るために wyre-technology org のメンバーである必要はなく、どの GitHub アカウントでもかまいません。
2. デプロイフローで求められたら、ビルド変数としてトークンを追加します。
   • DigitalOcean App Platform → Build Time スコープで、暗号化された環境変数 NODE_AUTH_TOKEN を設定し、PAT を指定します（Dockerfile は ARG NODE_AUTH_TOKEN を通じて読み取り、npm ci の認証に使用します）。
   • Cloudflare Workers → ビルド変数 NODE_AUTH_TOKEN を設定し、PAT を指定します （Workers → Settings → Build → Variables and Secrets）。

メモ

DigitalOcean のターゲットでは、Docker イメージ全体をビルドし、MCP サーバー全体を HTTP 経由で実行します。これは運用者に推奨される方法です。このリポジトリには wrangler.json／Workers のエントリーポイントが含まれていないため、セルフホスト可能なサーバーには DigitalOcean またはビルド済みコンテナイメージ（ghcr.io/wyre-ai/hudu-mcp）をお勧めします。

インストール

このプロジェクトは、GitHub Packages npm レジストリで公開されている @wyre-technology/node-hudu に依存しています。公開パッケージであってもトークンが必要です。 インストールする前に、npm の認証を一度行ってください。

git clone https://github.com/WYRE-AI/hudu-mcp.git
cd hudu-mcp

# Authenticate npm to GitHub Packages (token needs the read:packages scope)
export NODE_AUTH_TOKEN=$(gh auth token)   # or a PAT with read:packages

npm install
npm run build

リポジトリの .npmrc はすでに @wyre-technology スコープを GitHub Packages に向け、トークンを NODE_AUTH_TOKEN から読み取るよう設定されているため、これ以上の設定は不要です。

設定

変数	必須	デフォルト	説明
HUDU_BASE_URL	はい	-	Hudu インスタンスの URL（例：https://docs.example.com）
HUDU_API_KEY	いいえ	-	Hudu API キーです。設定すると api_key 認証モードが選択されます（下記参照）。省略すると、デフォルトで oauth モードになります。
HUDU_AUTH_MODE	いいえ	自動検出	api_key または oauth を明示的に指定します。下記の自動検出より優先されます。
MCP_TRANSPORT	いいえ	stdio	トランスポートの種類：stdio または http
AUTH_MODE	いいえ	env	env は環境変数から HUDU_* を読み取ります。gateway では各 /mcp リクエストに X-Hudu-Base-URL と X-Hudu-API-Key が必要で、これらの変数へのフォールバックは行いません。
CONDUIT_S2S_SECRET	HTTP では必須	-	サービス間共有シークレットです。空、または既知のプレースホルダー（changeme、secret、replace-me、your-s2s-secret、その他のサンプル値）の場合、HTTP はエラーをログに記録してゼロ以外の終了コードで終了します。openssl rand -hex 32 で生成してください。実際の値をコミットしないでください。この値がログに記録されることはありません。
MCP_ALLOW_INSECURE_DEV	いいえ	-	CONDUIT_S2S_SECRET がなくても HTTP を起動する場合に限り、ローカル開発用として 1 を設定します。プロセスは警告をログに記録し、X-Gateway-S2S を適用せず、127.0.0.1 のみでバインドします。ループバック以外の MCP_HTTP_HOST は無視され、その上書きがログに記録されます。既知のプレースホルダーシークレットが設定されている場合は、引き続き起動を拒否します。
MCP_HTTP_PORT	いいえ	8080	HTTP サーバーのポート（http トランスポート使用時）
MCP_HTTP_HOST	いいえ	127.0.0.1	実際の CONDUIT_S2S_SECRET が設定されている場合のバインドアドレス。コンテナーイメージでは 0.0.0.0 が設定されます。実際のシークレットがない場合、リスナーは 127.0.0.1 に強制されます。
MCP_SERVER_NAME	いいえ	hudu-mcp	MCP クライアントに報告されるサーバー名
MCP_SERVER_VERSION	いいえ	1.0.0	MCP クライアントに報告されるサーバーバージョン
LOG_LEVEL	いいえ	info	ログレベル：error、warn、info、debug
LOG_FORMAT	いいえ	simple	ログ形式：json または simple

認証モード

このサーバーは、2 つの方法のいずれかで Hudu と通信します。HUDU_AUTH_MODE でどちらを使うかを指定します。設定されていない場合は、HUDU_API_KEY が設定されているかどうかに基づいてモードが自動検出されます。

• api_key（HUDU_API_KEY が設定されている場合に自動選択）— 従来のモードです。このサーバーは @wyre-technology/node-hudu を介して Hudu の REST API を直接呼び出し、従来どおり 39 個すべてのツールを独自に実装します。既存のすべてのデプロイメントで使用されているモードであり、以下の内容による変更や影響は一切ありません。

• oauth（HUDU_API_KEY が設定されていない場合に自動選択）— 静的 API キーではなく、対話型 OAuth で保護された独自のネイティブ MCP サーバー（Hudu Admin -> External Apps -> MCP）を公開する、新しい Hudu インスタンス向けです。このモードでは、hudu-mcp はツールを再実装せず、認証済みの薄いプロキシとして動作します。MCP リクエストを {HUDU_BASE_URL}/mcp に直接転送して応答を中継するため、その Hudu インスタンスが公開するツールを自動的に利用できます。

  OAuth フロー（RFC 9728/8414 による検出、RFC 7591 の動的クライアント登録、PKCE の authorization_code、クライアントシークレットなし — パブリッククライアントです）は、トークンが必要なリクエストが初めて発生したときに実行されます。

  1. hudu-mcp は {HUDU_BASE_URL}/.well-known/oauth-protected-resource/mcp と {HUDU_BASE_URL}/.well-known/oauth-authorization-server から、インスタンスの OAuth メタデータを検出します。
  2. 動的クライアント登録を介して、自身をパブリック OAuth クライアントとして登録します（Hudu インスタンスごとに 1 回。発行された client_id はキャッシュされます）。
  3. 承認 URL を stderr に出力します。ブラウザーで開き、アクセスを承認してください。
  4. http://127.0.0.1:<ephemeral-port>/callback で一時的なローカルサーバーがリダイレクトを受け取り、コードをトークンと交換します。
  5. トークンは ~/.hudu-mcp/credentials-<hash-of-base-url>.json にキャッシュされ（ファイルモード 0600）、以降の実行時には透過的に更新されます。ブラウザーで再度の承認が求められるのは、リフレッシュトークン自体の有効期限が切れた場合、または取り消された場合のみです。

  このフローでは、hudu-mcp の実行マシン上の 127.0.0.1 にバインドされたコールバックサーバーにアクセスできるブラウザーが必要です。そのため、stdio（呼び出し元の MCP クライアントと常に同じマシン上）と、ブラウザーを使うマシンと同じマシン上で実行するセルフホストの http トランスポート（例：localhost:8080 でのローカルテスト）で動作します。一方、ブラウザーレベルのアクセス権がないリモートホスト（クラウド VM、コンテナーなど）にデプロイされた http トランスポートでは動作しません。ブラウザーからそのマシンのループバックインターフェイスにアクセスしてリダイレクトを完了できないため、初回の認証が停止します。これはゲートウェイモード（AUTH_MODE=gateway）とは無関係です。ゲートウェイモードは、リクエストごとにヘッダー経由で認証情報を注入するステートレスなマルチテナントプロキシであり、ブラウザーフローを実行する単一のユーザーは存在しません。HUDU_AUTH_MODE=oauth と AUTH_MODE=gateway を同時に設定すると、起動エラーになります。

  HTTP トランスポート（api_key と oauth の両方）には、CONDUIT_S2S_SECRET または MCP_ALLOW_INSECURE_DEV=1 も必要です。開発用フラグを設定すると、127.0.0.1 のみにバインドされます。HTTP 認証を参照してください。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

使用方法

Claude Desktop（stdio）

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "hudu": {
      "command": "node",
      "args": ["/path/to/hudu-mcp/dist/entry.js"],
      "env": {
        "HUDU_BASE_URL": "https://docs.example.com",
        "HUDU_API_KEY": "your-api-key"
      }
    }
  }
}

独自のネイティブ MCP サーバーを持つ新しい Hudu インスタンスの場合（認証モードを参照）、HUDU_API_KEY を省略し、HUDU_BASE_URL のみを設定してください。hudu-mcp の初回起動時に、ターミナルに承認 URL が出力されます。

{
  "mcpServers": {
    "hudu": {
      "command": "node",
      "args": ["/path/to/hudu-mcp/dist/entry.js"],
      "env": {
        "HUDU_BASE_URL": "https://docs.example.com"
      }
    }
  }
}

HTTP トランスポート

/health は認証されず、認証情報も読み取りません。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
HUDU_BASE_URL=https://docs.example.com \
HUDU_API_KEY=your-api-key \
MCP_TRANSPORT=http \
MCP_HTTP_PORT=8080 \
npm start

サービス間シークレットを使用しないローカル HTTP は、開発用途に限られます。127.0.0.1 にバインドされ、警告がログに記録されます。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

HTTP 認証

MCP_TRANSPORT=http かつ実際の CONDUIT_S2S_SECRET を設定している場合、すべての /mcp リクエストに X-Gateway-S2S を含める必要があります。チェックは src/mcp/s2s-verify.ts の verifyS2sHeader で行われます。ヘッダー値は t=<unix seconds>,v1=<hex> 形式で、16 進数部分は CONDUIT_S2S_SECRET をキーとして、文字列 t=<unix seconds> をそのまま HMAC-SHA256 でハッシュした値です（小文字の 16 進数 64 文字）。タイムスタンプはサーバーの時刻から 300 秒以内である必要があります。ヘッダーがないか無効な場合は、Hudu の認証情報を読み取る前に HTTP 401 が返されます。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-Hudu-Base-URL: $HUDU_BASE_URL" \
  -H "X-Hudu-API-Key: $HUDU_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

AUTH_MODE=gateway の場合、/mcp には X-Hudu-Base-URL と X-Hudu-API-Key も必要です。これらのヘッダーのみが、そのリクエストの認証情報の取得元となります。ヘッダーがない場合は HTTP 401 が返され、環境変数の HUDU_BASE_URL または HUDU_API_KEY にはフォールバックしません。

CONDUIT_S2S_SECRET が設定されていない場合、Compose は起動を拒否します。ゲートウェイサービスは AUTH_MODE=gateway を設定し、HUDU_BASE_URL または HUDU_API_KEY を注入せず、127.0.0.1:8080:8080 を公開します。

CONDUIT_S2S_SECRET=your-s2s-secret docker compose up

イメージはコンテナー内で 0.0.0.0 をリッスンし、実際のシークレットがない場合は引き続き起動を拒否します。ポートはループバックで公開してください。

docker run \
  -e CONDUIT_S2S_SECRET=your-s2s-secret \
  -e AUTH_MODE=gateway \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/hudu-mcp

ツール（39）

会社（8 個のツール）

ツール	説明
hudu_list_companies	任意のフィルターを指定して会社を一覧表示します
hudu_get_company	ID で会社を取得します
hudu_create_company	新しい会社を作成します
hudu_update_company	既存の会社を更新します
hudu_delete_company	会社を削除します
hudu_archive_company	会社をアーカイブします
hudu_unarchive_company	会社のアーカイブを解除します
hudu_test_connection	Hudu API への接続をテストします

資産（6 個のツール）

ツール	説明
hudu_list_assets	任意のフィルターを指定して資産を一覧表示します
hudu_get_asset	ID で資産を取得します
hudu_create_asset	新しい資産を作成します
hudu_update_asset	既存の資産を更新します
hudu_delete_asset	資産を削除します
hudu_archive_asset	資産をアーカイブします

資産レイアウト（4 個のツール）

ツール	説明
hudu_list_asset_layouts	資産レイアウトを一覧表示します
hudu_get_asset_layout	ID で資産レイアウトを取得します
hudu_create_asset_layout	新しい資産レイアウトを作成します
hudu_update_asset_layout	既存の資産レイアウトを更新します

資産パスワード（5 個のツール）

ツール	説明
hudu_list_asset_passwords	資産パスワードを一覧表示します
hudu_get_asset_password	ID で資産パスワードを取得します
hudu_create_asset_password	新しい資産パスワードを作成します
hudu_update_asset_password	既存の資産パスワードを更新します
hudu_delete_asset_password	資産パスワードを削除します

記事（6 個のツール）

ツール	説明
hudu_list_articles	ナレッジベースの記事を一覧表示します
hudu_get_article	ID で記事を取得します
hudu_create_article	新しい記事を作成します
hudu_update_article	既存の記事を更新します
hudu_delete_article	記事を削除します
hudu_archive_article	記事をアーカイブします

ウェブサイト（5 個のツール）

ツール	説明
hudu_list_websites	監視対象のウェブサイトを一覧表示します
hudu_get_website	ID でウェブサイトを取得します
hudu_create_website	新しいウェブサイトを作成します
hudu_update_website	既存のウェブサイトを更新します
hudu_delete_website	ウェブサイトを削除します

その他のリソース（5 個のツール）

ツール	説明
hudu_list_folders	フォルダーを一覧表示します
hudu_list_procedures	手順を一覧表示します
hudu_list_activity_logs	アクティビティログを一覧表示します
hudu_list_relations	関連項目を一覧表示します
hudu_list_magic_dash	Magic Dash 項目を一覧表示します

リソース

URI	説明
hudu://companies	すべての会社の一覧
hudu://companies/{id}	ID による会社の詳細
hudu://assets	すべての資産の一覧
hudu://assets/{id}	ID による資産の詳細
hudu://articles	すべての記事の一覧
hudu://articles/{id}	ID による記事の詳細

開発

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Clean build output
npm run clean

ライセンス

Apache-2.0