Huly MCP

Huly MCP

Huly MCP は、Huly と連携する、機能を網羅した MCP サーバーです。npm では @firfi/huly-mcp として公開されています。

Huly Platform のデプロイに接続でき、Platform Collective および TraceX のフォークでも動作するはずです。Intabia の 0.8.33 ／モデル 0.8.4 との互換性はテスト済みです。既知の不足点は issue #279 で追跡しています。フォークのサポートは非公式です。

Huly CLI の代替手段

Huly CLI、ターミナルネイティブの Huly 連携、または MCP サーバーを実行する代わりとなるスクリプト作成・自動化手段をお探しですか？Huly CLI は、Huly 向けの機能を網羅したコマンドラインインターフェイスです。@firfi/huly-cli として公開されており、Huly MCP と同等の Huly 操作をすべて実行できます。人が読みやすい形式または JSON 形式で出力する、スキーマを考慮したネイティブコマンドとして、同じ Huly 操作を提供します。ファイルを使った入力、アップロード、ダウンロードにも対応しています。

Huly MCP と Huly CLI はこのモノレポで一緒にメンテナンスされ、共通の操作レジストリを利用しています。そのため、操作の入力、出力、警告、型付きエラーが常に一致します。コマンドの完全なリファレンスについてはHuly CLI のドキュメントをご覧ください。また、CLI の例、Huly 自動化のパターン、Huly MCP と CLI の比較もご覧ください。

インストール

Node.js の要件

Huly MCP には Node.js 22.19.0 以降が必要です。MCP クライアントは Node.js ランタイムを提供しません。node、npx、および #!/usr/bin/env node を使うパッケージ実行ファイルは、MCP クライアントが実行される環境の Node.js を参照します。インストール前に、その環境を確認してください。

node --version

MCP クライアントが古いランタイムで Huly MCP を起動すると、Huly MCP は互換性のないアプリケーションを読み込まず、診断専用の MCP サーフェスを初期化します。サーバーの指示と get_huly_startup_diagnostic ツールには、検出された実行ファイルと必要なバージョンが表示され、同じ unsupported Node.js runtime 診断が標準エラー出力に書き込まれます。Node.js をアップグレードするか、互換性のある Node.js 実行ファイルの絶対パスを使用するよう MCP サーバーのコマンドを設定してから、MCP サーバーを再起動してください。ランタイムをアップグレードするまで、Huly の操作は利用できません。

標準構成では Huly API トークンを使用し、ほとんどの MCP クライアントで動作します。

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "MCP_TRANSPORT": "stdio-resident",
        "HULY_URL": "https://your-huly-instance.example.com",
        "HULY_TOKEN": "your-huly-api-token",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

対象のデプロイで対応している場合は、Huly のアカウント設定で作成した管理対象 API トークンを使用してください。管理対象トークンは 1 つのワークスペースに紐付けられ、有効期限が設定され、アカウントのパスワードを変更せずに失効させることができます。ただし、そのワークスペース内ではアカウントのすべての権限を引き継ぐため、自動化に必要なワークスペースロール、スペースのメンバーシップ、データアクセス権のみを持つ専用の統合アカウントを使用してください。古い Huly デプロイでは管理対象トークンの設定が表示されない場合があります。その場合、互換性のための代替手段としてメールアドレスとパスワードによる認証も引き続き利用できます。

ツール公開のデフォルト設定

デフォルト（HULY_TOOL_MODE=auto）では、Huly MCP は470個のツールを一括で公開することを避け、現在のMCPクライアントに合わせて最適化されます。claude-code のセッションには、ネイティブのHulyツールが提供されます。Codex、Cursor、Windsurf、Copilot、OpenCode、Claude AI／Desktop形式のクライアント、および不明なクライアントには、小規模なプロキシインターフェース（list_tool_categories、search_tools、get_tool_schema、invoke_tool）が提供されます。

クライアントがネイティブツール名を直接呼び出した場合は、そのツールが引き続き実行されますが、多くのクライアントは tools/list で返されたツールしか呼び出しません。すべてのHulyツールを最初から利用できるようにするには HULY_TOOL_MODE=native を設定するか、TOOLSETS ／ TOOLS を使って、よく使うネイティブツールを指定しながらプロキシ経由の検出機能を利用できます。

[mcp_servers.huly]
startup_timeout_sec = 120
command = "npx"
args = ["-y", "@firfi/huly-mcp@latest"]

[mcp_servers.huly.env]
MCP_TRANSPORT = "stdio-resident"
HULY_URL = "https://your-huly-instance.example.com"
HULY_TOKEN = "your-huly-api-token"
HULY_WORKSPACE = "yourworkspace"

claude mcp add huly \
  -e MCP_TRANSPORT=stdio-resident \
  -e HULY_URL=https://your-huly-instance.example.com \
  -e HULY_TOKEN=your-huly-api-token \
  -e HULY_WORKSPACE=yourworkspace \
  -- npx -y @firfi/huly-mcp@latest

{
  "servers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "MCP_TRANSPORT": "stdio-resident",
        "HULY_URL": "https://your-huly-instance.example.com",
        "HULY_TOKEN": "your-huly-api-token",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

{
  "mcp": {
    "huly": {
      "type": "local",
      "command": ["npx", "-y", "@firfi/huly-mcp@latest"],
      "environment": {
        "MCP_TRANSPORT": "stdio-resident",
        "HULY_URL": "https://your-huly-instance.example.com",
        "HULY_TOKEN": "your-huly-api-token",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

pi install npm:pi-mcp-adapter

更新

@latest タグを指定すると、パッケージランナーは最新バージョンを取得します。一部のMCPクライアントはサーバープロセスや解決済みのインストールを保持するため、更新時にはサーバーを再起動するか、再追加してください。

メンテナー向け本番リリース

推奨される認定済み Node.js ランタイムを使用し、クリーンで最新の master チェックアウトから公開します。

mise exec [email protected] -- pnpm local-release

ホストでより新しい Node.js バージョンが有効になっている場合も、このコマンドをそのまま使用してください。リリースビルドで受け入れられるのは、CI が認定した厳密な Node.js バージョンのみです。これはパッケージのランタイム要件より意図的に対象を絞っています。事前確認、再実行時の動作、検証については、本番リリースガイドを参照してください。

共有常駐 stdio

セットアップ例では MCP_TRANSPORT=stdio-resident を明示的に選択しています。MCP クライアントは引き続き stdio を使用し、同じ OS ユーザーで動作する互換性のあるクライアントは、小規模なネイティブブリッジを介して Node バックエンドを共有します。Linux および macOS の arm64/x64 バイナリが含まれているため、Rust のインストールは不要です。常駐起動の30秒間、アプリケーションリクエストはバッファリングされます。起動に失敗すると、通常の stdio が起動し、バッファリングされたアプリケーション入力が一度だけディスパッチされます。稼働中の常駐バックエンドに障害が発生した場合、再接続やアプリケーションリクエストの再送は行われません。

MCP_TRANSPORT を省略すると、引き続き通常の stdio が選択され、既存のインストールとの互換性が保たれます。クライアントごとに別々のバックエンドを使用するには、MCP_TRANSPORT=stdio を明示的に設定してください。設定を変更した後は、MCP クライアントを再起動してください。

手動常駐バックエンド

実験的な手動常駐バックエンドの使用方法では、独立した stdio ホストが、明示的に起動されたローカルバックエンドを非公開のアタッチメントファイルを通じて選択できます。完全な適格性評価は引き続き保留中です。

HTTP トランスポート

デフォルトでは、サーバーは stdio トランスポートを使用します。HTTP トランスポートを使用するには：

HULY_URL=https://your-huly-instance.example.com \
HULY_TOKEN=your-huly-api-token \
HULY_WORKSPACE=yourworkspace \
MCP_TRANSPORT=http \
npx -y @firfi/huly-mcp@latest

デフォルトでは、サーバーは http://127.0.0.1:3000/mcp でリッスンします。

MCP_HTTP_PORT および MCP_HTTP_HOST で設定します：

MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-mcp@latest

HTTP MCP プロトコルのサポート

どちらのトランスポートも、Effect AI の MCP サーバーとプロトコルアダプターを使用して実装されています。サーバーは、リリース済みの MCP 2026-07-28 ステートレスプロトコルと、MCP 2025-06-18 互換プロトコルを設定します。最新の HTTP では、POST ごとに1つの JSON-RPC メッセージ、Accept: application/json, text/event-stream、MCP-Protocol-Version: 2026-07-28、Mcp-Method、メソッド固有の Mcp-Name、およびリクエストごとの _meta.io.modelcontextprotocol/* クライアントメタデータが必要です。レガシー HTTP は、返された Mcp-Session-Id を使用する初期化済みセッションと、リクエスト単位のバインディングを持つステートレス呼び出しに対応しています。Huly の認証情報は、環境変数またはサポートされている x-huly-* ヘッダーで別途設定します。

実装の境界と現在の検証記録については、MCP トランスポートのアーキテクチャと認定を参照してください。

ホスト型またはトンネル経由の HTTP デプロイでは、MCP エンドポイントのベアラートークンを必須にできます：

MCP_TRANSPORT=http \
MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
npx -y @firfi/huly-mcp@latest

その場合、HTTP クライアントは次を送信する必要があります：

Authorization: Bearer <MCP_AUTH_TOKEN>

MCP_AUTH_TOKEN が保護するのは、MCP HTTP /mcp エンドポイントのみです。これは HULY_TOKEN とは無関係で、Huly への認証には使用されず、HULY_EMAIL / HULY_PASSWORD / HULY_TOKEN の代わりにもなりません。Huly の認証情報は、引き続きプロセスの環境変数、またはホスト型 URL デプロイの場合はサポートされている x-huly-* ヘッダーを通じて指定する必要があります。stdio デプロイでは MCP_AUTH_TOKEN を使用しません。

CLI と stdio のプロファイル共有

huly auth login --profile work でプロファイルを保存し、stdio MCP サーバーの環境で MCP_TRANSPORT=stdio-resident と HULY_PROFILE=work を設定します。両方のプロセスは、同じ OS ユーザーと設定ディレクトリで実行する必要があります。stdio がアクティブな CLI プロファイルを暗黙的に引き継ぐことはありません。保存されたトークンはインスタンス URL とワークスペースに紐付けられており、これらを変更した場合は、再度ログインするか、認証情報を環境変数にすべて設定する必要があります。CLI プロファイルの手順を参照してください。HTTP の設定に変更はありません。

ホスト型 HTTP ヘッダーの設定

ホスト型 URL のデプロイでは、サーバープロセスを MCP_TRANSPORT=http に設定してください。ホスティングレイヤーはセッションごとの Huly 認証情報をリクエストヘッダーとして転送できるため、プロセス全体に適用される HULY_* 環境変数を使わずに、1 台のホスト型サーバーで異なる Huly ワークスペースに対応できます。

サポートされている v1 ヘッダー：

サポート対象の x-huly-* ヘッダーが含まれている場合、必須ヘッダーをすべて指定する必要があり、サポート対象外の x-huly-* ヘッダーは拒否されます。サポート対象外の x-huly-* ヘッダーのみ（プロキシのトレース ID など）が含まれるリクエストでは、プロセスの環境設定が使用されます。不足している値が環境変数で補われることはありません。ホスト型ヘッダー設定 v1 では、メールアドレス／パスワード認証はサポートされていません。

Smithery の公開スキーマの例については、docs/SMITHERY_URL_PUBLISH.md を参照してください。

環境変数

*認証：HULY_TOKEN を推奨します。HULY_EMAIL と HULY_PASSWORD は、Huly のデプロイ環境が管理対象の API トークンをサポートしていない場合、または他の互換性上の制約によりパスワード認証が必要な場合に限り使用してください。

起動と初期化

ツールの検出では、操作ハンドラーを読み込んだり、Huly の起動を待ったりせず、生成済みのカタログを読み込みます。ハンドラーはツールグループごとに必要に応じて読み込まれ、並行して行われる呼び出しではグループの読み込みが共有されます。ツール定義を変更した後は、pnpm update-tool-catalog を実行してください。カタログが古い場合、ビルドは失敗します。

stdio では、最初のツール一覧リクエストにより、プロセスが所有する Huly 接続がバックグラウンドで開始されます。完全な Huly モデルを必要とする呼び出しは、同じ初期化が完了するまで待機します。待機中の呼び出しをキャンセルしても、他の呼び出しの初期化はキャンセルされません。モデルの初期化に失敗した場合、後続の呼び出しで再試行できます。プロジェクト一覧の取得には別の REST 読み取りを使用するため、完全なモデルの初期化を待ちません。その他の操作では、完全なモデルを保持し、従来の動作を維持します。

デフォルトのトランスポートは引き続き stdio です。MCP ホストが起動する各プロセスは、それぞれ独自の接続とモデルを所有します。HTTP を使用すると、クライアント間で稼働中のサーバーを共有できます。リクエストの認証情報ヘッダーから作成される接続では、必要になった時点でのみモデルを初期化します。CLI でもこのオンデマンド方式が使用されます。

組み込み診断ツール

get_version は、現在のサーバーバージョンと最新の npm バージョンを返します。

get_huly_context は、Huly に接続せず、現在の MCP セッションのサニタイズ済みランタイム／設定コンテキストを返します。パッケージバージョン、トランスポート、認証モード、サニタイズ済みの Huly URL のオリジン／ホスト／プロトコル、ワークスペース、タイムアウト、設定ソース、ネイティブツールのスコープフィルタリング、および解決済みのネイティブ／プロキシツールの公開範囲を報告します。トークン、パスワード、メールアドレスの値、認証情報ヘッダー、URL パス、URL クエリ文字列、URL 認証情報は返されません。

MCP リソース

サーバーは、resources/read をサポートするクライアント向けに、読み取り専用の MCP リソースを JSON コンテキストとして公開します。

resources/list は、現在有効なプロジェクトの具体的なリソースを返します。課題リソースはテンプレートベースです。resources/templates/list を使って、対応している課題 URI テンプレートを確認してから、既知の課題 URI を読み取ってください。

バックログ

機能のバックログと SDK の互換性に関するメモは、docs/BACKLOG.md にあります。

利用可能なツール

解決済みのツール公開範囲が proxy の場合、クライアントには組み込みツールに加えて、次のプロキシメタツールが表示されます。その場合、ネイティブの Huly ツールはプロキシ候補カタログを通じて検出・呼び出しされます。クライアントがネイティブツール名を直接呼び出した場合も、正確なネイティブツール名でディスパッチされます。ただし、これは PROXY_OUTPUT_STRICT のスコープ規則に従い、非表示のネイティブツールは tools/list で公開されません。

プロキシのメタツール

TOOLSETS カテゴリ： projects、issues、comments、milestones、documents、storage、attachments、contacts、channels、calendar、time tracking、search、associations、activity、notifications、workspace、approvals、boards、cards、collaborators、custom-fields、drive、hr、inventory、labels、leads、mail、templates、model-administration、planner、preferences、processes、recruiting、sdk-discovery、security-administration、sequence-administration、spaces、support、tag-categories、tags、task-management、test-management、user-statuses、views、virtual-office、workbench、workflow-statuses

プロジェクト

課題

コメント

マイルストーン

ドキュメント

ストレージ

添付ファイル

連絡先

Channels

Calendar

時間の記録

検索

関連付け

アクティビティ

通知

ワークスペース

承認

ボード

カード

コラボレーター

カスタムフィールド

ドライブ

Hr

Inventory

ラベル

リード

メール

テンプレート

モデル管理

プランナー

設定

プロセス

採用

SDK の検出

セキュリティ管理

シーケンス管理

スペース

サポート

タグカテゴリー

タグ

タスク管理

テスト管理

ユーザーステータス

ビュー

バーチャルオフィス

Workbench

ワークフローステータス

ソースからのビルド

公開パッケージにはネイティブの常駐ブリッジが含まれています。Rust はビルド依存関係です。 ソースからビルドするには、Node.js、pnpm、Rustup、Python 3、Bash が必要です。固定された Rust ツールチェーン、Zig リンカー、クロスコンパイル用 SDK を一度準備します。

pnpm setup:native
pnpm build
pnpm test:native

ビルドツールは、チェックアウト先や公開パッケージの外部にある、プラットフォーム固有のユーザーキャッシュに保存されます。 ブリッジは単一の Rust I/O ループです。MCP プロトコルの処理、認可、キャンセルは共有 Node バックエンドが引き続き担当します。

トラブルシューティング

特殊文字を含むパスワードの代替手段

Huly のパスワードに *、%、!、# などの文字が含まれている場合、-e や --env などの CLI 環境変数フラグを使って渡すと失敗することがあります。シェルがこれらの文字をプロセスに渡す前に解釈するためです。

解決策：シェル経由でパスワードを渡す代わりに、MCP 設定ファイルを直接編集します。

• Codex：~/.codex/config.toml
• Claude Code：~/.claude.json（ユーザースコープ）または .mcp.json（プロジェクトスコープ）
• Claude Desktop：インストールのセクションに記載されている場所にある claude_desktop_config.json
• VS Code と Cursor：インストールのセクションに記載されているクライアント設定の場所を使用します。実際の認証情報を含むワークスペースファイルをコミットしないでください
• Windsurf：Windsurf の MCP 設定ファイルを直接編集します
• OpenCode：~/.config/opencode/opencode.json

Claude の JSON 設定では、上記のシェルで問題になる文字をそのまま記述できます。" や \ など、JSON で予約されている文字は通常どおりエスケープする必要があります。

{
  "mcpServers": {
    "huly": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "MCP_TRANSPORT": "stdio-resident",
        "HULY_URL": "https://your-huly-instance.com",
        "HULY_EMAIL": "[email protected]",
        "HULY_PASSWORD": "p@ss*w0rd!#%",
        "HULY_WORKSPACE": "your-workspace"
      }
    }
  }
}

デプロイ環境で管理された API トークンがサポートされている場合は、このパスワードの代替手段ではなく HULY_TOKEN を使用してください（ 環境変数を参照）。

MCP クライアントに「Failed to reconnect」と表示される

MCP 設定を変更した後、一部のクライアント（Claude Code など）では、再接続だけでなく完全な再起動が必要です。アプリケーションを完全に終了してから、再度開いてください。

次の方法で、接続が正常に機能するかを個別に確認できます。

claude mcp list  # Should show "Connected"

セルフホスト Huly：ログイン失敗が続くとアカウントがロックされる

Huly では、API 認証に 5 回失敗すると、パスワードログインがロックされます。パスワードの設定に誤りがある場合など、初期設定時によく発生します。ロック状態は、サービスを再起動してもデータベースに残ります。

症状：MCP サーバーから PasswordLoginLocked エラーが返され、Huly のウェブ UI に「Password login is locked due to too many failed attempts. Please use an OTP login method to unlock your account.」と表示されます（SMTP が設定されていない場合、OTP は機能しません）。

修正方法 — CockroachDB のロックカウンターをリセットします。

# Find your account UUID and check lock status
docker exec -e PGPASSWORD=<your_cockroach_password> <cockroach_container> \
  cockroach sql --host=localhost --user=<db_user> --database=defaultdb --insecure \
  -e "SELECT uuid, failed_login_attempts FROM global_account.account;"

# Reset the counter
docker exec -e PGPASSWORD=<your_cockroach_password> <cockroach_container> \
  cockroach sql --host=localhost --user=<db_user> --database=defaultdb --insecure \
  -e "UPDATE global_account.account SET failed_login_attempts = 0 WHERE uuid = '<your_account_uuid>';"

CockroachDB の認証情報は、Huly の compose.yml で確認するか、docker exec <cockroach_container> env | grep COCKROACH を実行して確認できます。

Windows 固有の注意事項

• Bash ラッパースクリプト（.env ファイルを読み込むもの）は、Windows 上で MCP クライアントから起動した場合、安定して動作しないことがあります。MCP 設定 JSON で環境変数を直接設定してください。
• SSH 経由の Docker イメージの取得は、認証情報マネージャーの問題により、Windows で失敗することがあります。必要に応じて、サーバーのデスクトップからイメージを取得してください。