Deployhq MCP Server

🚀 DeployHQ MCP Server

DeployHQ用のモデルコンテキストプロトコル（MCP）サーバーです。Claude DesktopやClaude CodeなどのAIアシスタントが、あなたのDeployHQデプロイメントとやり取りできるようになります。

✨ 主な機能

• DeployHQ APIとの完全統合：プロジェクト、サーバー、デプロイメントにアクセスできます。
• 簡単なインストール：npxで直接使用でき、インストール不要です。
• Claude DesktopとClaude Codeで動作：両方のMCPクライアントに対応したstdioトランスポートを使用します。
• セキュア：資格情報は環境変数を通じて管理され、保存されることはありません。
• 型安全：TypeScriptとZodバリデーションを使用して構築されています。
• 複数のトランスポート：stdio（主要）、SSE、HTTP（ホスティング用にオプション）
• 本番環境での使用に耐える：包括的なエラーハンドリングとロギングが備わっています。

📋 利用可能なツール

MCPサーバーは、AIアシスタント用の7つのツールを提供します。

list_projects

あなたのDeployHQアカウント内のすべてのプロジェクトをリストします。

返り値：リポジトリ情報とデプロイメントステータスを含むプロジェクトの配列。

get_project

特定のプロジェクトに関する詳細情報を取得します。

パラメーター：

• permalink (文字列)：プロジェクトのパーマリンクまたは識別子

list_servers

プロジェクトに設定されたすべてのサーバーをリストします。

パラメーター：

• project (文字列)：プロジェクトのパーマリンク

list_deployments

ページネーションをサポートしたプロジェクトのデプロイメントをリストします。

パラメーター：

• project (文字列)：プロジェクトのパーマリンク
• page (数値、オプション)：ページネーションのページ番号
• server_uuid (文字列、オプション)：サーバーのUUIDでフィルタリング

get_deployment

特定のデプロイメントに関する詳細情報を取得します。

パラメーター：

• project (文字列)：プロジェクトのパーマリンク
• uuid (文字列)：デプロイメントのUUID

get_deployment_log

特定のデプロイメントのデプロイメントログを取得します。デプロイメントの失敗をデバッグするのに役立ちます。

パラメーター：

• project (文字列)：プロジェクトのパーマリンク
• uuid (文字列)：デプロイメントのUUID

返り値：テキスト形式の完全なデプロイメントログ

create_deployment

プロジェクトに新しいデプロイメントを作成します。

パラメーター：

• project (文字列)：プロジェクトのパーマリンク
• parent_identifier (文字列)：サーバーまたはサーバーグループのUUID
• start_revision (文字列)：開始コミットハッシュ
• end_revision (文字列)：終了コミットハッシュ
• branch (文字列、オプション)：デプロイするブランチ
• mode (文字列、オプション)："queue" または "preview"
• copy_config_files (ブール値、オプション)：設定ファイルをコピーする
• run_build_commands (ブール値、オプション)：ビルドコマンドを実行する
• use_build_cache (ブール値、オプション)：ビルドキャッシュを使用する
• use_latest (文字列、オプション)：最新のデプロイされたコミットを開始点として使用する

🚀 クイックスタート

Claude Codeでの簡単なインストール

Claude Code用の最速のインストール方法は次の通りです。

claude mcp add --transport stdio deployhq --env DEPLOYHQ_EMAIL=your-email@example.com --env DEPLOYHQ_API_KEY=your-api-key --env DEPLOYHQ_ACCOUNT=your-account -- npx -y deployhq-mcp-server

your-email@example.com、your-api-key、your-account をあなたの実際のDeployHQの資格情報に置き換えてください。

手動設定（Claude DesktopとClaude Codeの両方に対応）

同じ設定が両方のクライアントで機能します。docs/claude-config.json からコピーし、あなたの資格情報を追加してください。

Claude Desktopの場合：

設定ファイルを編集します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

その後、Claude Desktopを再起動します。

Claude Codeの場合：

プロジェクトディレクトリ内の .claude.json ファイルに追加します。

設定：

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-password",
        "DEPLOYHQ_ACCOUNT": "your-account-name"
        // オプション: "LOG_LEVEL": "INFO"  (ERROR, INFO, or DEBUG)
      }
    }
  }
}

注意：必要なのは3つのDeployHQの資格情報のみです。LOG_LEVEL はオプションで、デフォルトは INFO です。

使用開始

設定が完了したら、ClaudeにDeployHQとのやり取りを依頼できます。

• "List all my DeployHQ projects"（私のすべてのDeployHQプロジェクトをリストして）
• "Show me the servers for project X"（プロジェクトXのサーバーを表示して）
• "Get the latest deployment status for project Y"（プロジェクトYの最新のデプロイメントステータスを取得して）
• "Create a new deployment for project Z"（プロジェクトZに新しいデプロイメントを作成して）
• "Show me the deployment log for the latest deployment"（最新のデプロイメントのデプロイメントログを表示して）

💡 一般的な使用例

デプロイメントステータスの確認

User: What's the status of my latest deployment for my-app?
Claude: [Uses list_deployments → get_deployment → shows status]

失敗したデプロイメントのデバッグ

User: Why did the last deployment fail for my-app?
Claude: [Uses list_deployments → get_deployment_log → analyzes log]

最新の変更をデプロイする

User: Deploy the latest changes to production for my-app
Claude: [Uses list_servers → list_deployments → create_deployment with use_latest]

完全なワークフローの例

User: I want to deploy my-app to production with the latest changes

Claude will:
1. Use list_projects to find "my-app"
2. Use list_servers to find production server UUID
3. Use list_deployments with use_latest to get last revision
4. Use create_deployment to queue deployment
5. Use get_deployment to show status
6. Use get_deployment_log if anything fails

🔧 設定オプション

環境変数

必須

• DEPLOYHQ_EMAIL：あなたのDeployHQのログインメールアドレス
• DEPLOYHQ_API_KEY：あなたのDeployHQのパスワード/APIキー
• DEPLOYHQ_ACCOUNT：あなたのDeployHQのアカウント名（URL https://ACCOUNT.deployhq.com から）

オプション

• LOG_LEVEL：ログの詳細度を制御します - ERROR、INFO、または DEBUG（デフォルト: INFO）
• NODE_ENV：環境モード - production または development

ログレベル

LOG_LEVEL 環境変数でログの詳細度を制御できます。

• ERROR：エラーのみ表示
• INFO：情報とエラーを表示（デフォルト）
• DEBUG：詳細なAPI呼び出しを含むすべてのログを表示

例：

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-password",
        "DEPLOYHQ_ACCOUNT": "your-account-name",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

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

サーバーが起動しない

問題：サーバーが起動直後に終了する

解決策：

• すべての必須環境変数が設定されていることを確認してください。
• Node.jsのバージョンが18以上であることを確認してください：node --version
• Claude Desktop/Codeのログにエラーメッセージがないか確認してください。
• 詳細情報を得るために LOG_LEVEL=DEBUG を設定してみてください。

認証エラー

問題："Authentication failed" または401/403エラー

解決策：

• あなたのメールアドレスとAPIキーが正しいことを確認してください。
• あなたのAPIキーが期限切れになっていないことを確認してください。
• あなたのアカウントでAPIアクセスが有効になっていることを確認してください。
• 同じ資格情報でDeployHQのウェブインターフェイスにログインしてみてください。

プロジェクトが見つからない

問題："Project not found" または404エラー

解決策：

• list_projects を使用して正確なパーマリンク形式を確認してください。
• プロジェクトのパーマリンクは大文字と小文字が区別されます。
• あなたがDeployHQでそのプロジェクトにアクセスできることを確認してください。

デプロイメントの作成がブロックされる

問題：デプロイメントを作成しようとしたときに "Server is running in read-only mode" エラーが表示される

解決策：

• 読み取り専用モードはデフォルトでは無効になっていますが、あなたが有効にしている可能性があります。
• 読み取り専用モードを無効にするには、環境変数に DEPLOYHQ_READ_ONLY=false を設定してください。
• または、--read-only=false のCLIフラグを使用してください。
• 読み取り専用モードの詳細な手順については、Security セクションを参照してください。

デプロイメントが失敗する

問題：デプロイメントが作成されたが、すぐに失敗する

解決策：

• get_deployment_log を使用して詳細なエラーログを確認してください。
• list_servers でサーバーのUUIDが正しいことを確認してください。
• 開始と終了のリビジョンがリポジトリ内に存在することを確認してください。
• サーバーに正しいデプロイキーが設定されていることを確認してください。

接続タイムアウト

問題："Request timeout" エラー

解決策：

• あなたのインターネット接続を確認してください。
• DeployHQ APIがアクセス可能であることを確認してください：curl https://YOUR_ACCOUNT.deployhq.com
• 大きなデプロイメントリストは時間がかかる場合があります - ページネーションを使用してください。
• DeployHQが問題を抱えている場合は、しばらく待ってからもう一度試してみてください。

ログが表示されない

問題：ログ出力が表示されない

解決策：

• ログはstderrに出力されます（stdioトランスポートの場合）。
• Claude Desktop/Codeのログの場所を確認してください。
  • macOS: ~/Library/Logs/Claude/
  • Windows: %APPDATA%\Claude\logs\
• 詳細な出力を得るために LOG_LEVEL=DEBUG を設定してください。
• ホストモードの場合は、Digital Oceanのログを確認してください。

DeployHQの資格情報の取得方法

1. ユーザー名：あなたのDeployHQのログインメールアドレス
2. パスワード：あなたのDeployHQのパスワード
3. アカウント：あなたのDeployHQのアカウント名（URL https://ACCOUNT.deployhq.com で表示されます）

🏗️ アーキテクチャ

┌─────────────────┐                    ┌─────────────┐
│  Claude Desktop │    stdio/JSON-RPC  │  DeployHQ   │
│  or Claude Code │◄──────────────────►│  API        │
│                 │    (via npx)       │             │
│  Environment    │                    │             │
│  Variables ─────┼───────────────────►│ Basic Auth  │
└─────────────────┘                    └─────────────┘

• Claude Desktop/Code：npx を通じてサーバーを起動するMCPクライアント
• MCP Server：環境変数から資格情報を読み取り、stdioを通じて通信します。
• DeployHQ API：HTTP Basic Authenticationを使用したREST API

📦 前提条件

• Node.js 18以上（Node 20以上が推奨）
• APIアクセスが有効なDeployHQアカウント

注意：サーバーはHTTPリクエストに node-fetch を使用しています。開発ツール（ESLint、Vitest）にはNode 18以上が必要です。

🔧 ローカル開発

1. リポジトリをクローンする

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

2. 依存関係をインストールする

npm install

3. テストを実行する

npm test              # すべてのテストを実行
npm run test:watch    # 開発用のウォッチモードで実行
npm run test:coverage # カバレッジレポートを生成
npm run test:ui       # デバッグ用のインタラクティブUIで実行

4. プロジェクトをビルドする

npm run build

5. ローカルでstdioトランスポートをテストする

# まずビルドする
npm run build

# 環境変数を使用してテストする
DEPLOYHQ_EMAIL="your-email@example.com" \
DEPLOYHQ_API_KEY="your-api-key" \
DEPLOYHQ_ACCOUNT="your-account" \
node dist/stdio.js

サーバーはstdioモードで起動し、stdinでJSON-RPCメッセージを待機します。

6. Claude Codeでテストする

ローカルの .claude.json をビルドされたバージョンを使用するように設定します。

{
  "mcpServers": {
    "deployhq": {
      "command": "node",
      "args": ["/path/to/deployhq-mcp-server/dist/stdio.js"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-password",
        "DEPLOYHQ_ACCOUNT": "your-account-name"
      }
    }
  }
}

🧪 テスト

このプロジェクトには、Vitestを使用した包括的なテストスイートが含まれています。

テストカバレッジ：

• ✅ ツールスキーマバリデーション - 有効/無効な入力を持つすべての7つのMCPツールスキーマ
• ✅ APIクライアントメソッド - モックされたレスポンスを持つすべてのDeployHQ APIメソッド
• ✅ エラーハンドリング - 認証、バリデーション、およびネットワークエラー
• ✅ MCPサーバーファクトリ - サーバーの作成と設定

テストの実行：

npm test              # すべてのテストを実行
npm run test:watch    # 開発用のウォッチモードで実行
npm run test:coverage # カバレッジレポートを生成
npm run test:ui       # デバッグ用のインタラクティブUIで実行

テスト統計：

• 3つのテストスイートにわたる50以上のテスト
• ツール、api-client、mcp-serverモジュールをカバー
• 分離された単体テストのためにモックされたfetchを使用

🔒 セキュリティ

読み取り専用モード（オプション）

デフォルトでは、MCPサーバーはデプロイメントの作成を含むすべての操作を許可します。これはほとんどのユーザーに推奨される設定です。

誤ったデプロイメントから追加の保護を求めるユーザーのために、サーバーにはデプロイメントの作成をブロックするオプションの読み取り専用モードが含まれています。

デフォルトの動作（設定不要）：

• ✅ デプロイメントはデフォルトで許可されています
• ✅ すべての操作が機能します：リスト、取得、およびデプロイメントの作成
• ✅ デフォルトで完全な機能を備えています

読み取り専用モードを有効にする場合：

• AIを介した誤ったデプロイメントから追加の保護が必要な場合
• 本番環境に接続しており、追加の安全層が必要な場合
• デプロイメントを監視するための読み取りアクセスのみが必要な場合
• まだ統合をテストしていて、慎重に進みたい場合

重要：読み取り専用モードは完全にオプションです。これを使用しなくてもサーバーは完全に機能します。

読み取り専用モードの有効化方法：

環境変数を使用する場合：

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-api-key",
        "DEPLOYHQ_ACCOUNT": "your-account",
        "DEPLOYHQ_READ_ONLY": "true"
      }
    }
  }
}

CLIフラグを使用する場合：

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": [
        "-y",
        "deployhq-mcp-server",
        "--read-only"
      ],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-api-key",
        "DEPLOYHQ_ACCOUNT": "your-account"
      }
    }
  }
}

設定の優先順位：

1. CLIフラグ --read-only（最も高い優先順位）
2. 環境変数 DEPLOYHQ_READ_ONLY
3. デフォルト値: false（デプロイメントが許可されています）

追加のセキュリティに関する注意事項

• デプロイメントログには機密情報が含まれる場合があります：デプロイメントログには環境変数、APIキー、その他の機密情報が含まれる可能性があります。ログを取得するツールを使用する際には、特にサードパーティのAIサービスとの連携では注意してください。
• 最小限の権限のAPIキーを使用してください：MCPアクセス用に必要最小限の権限を持つ専用のAPIキーを作成してください。読み取り専用と読み書きの操作には別々のキーを検討してください。
• MCPのアクティビティを監査してください：特に本番環境では、MCPの使用状況を監視してください。定期的にログを確認し、予期しない動作がないか確認してください。
• 環境変数：資格情報は保存されることはなく、環境変数を通じてのみ渡されます。
• HTTPS：npxを使用する場合、資格情報はあなたのマシンにローカルに留まります。
• テレメトリなし：DeployHQ APIに直接送信される以外のデータは送信されません。

🌐 オプション：ホスト型デプロイメント

サーバーは、SSE/HTTPトランスポートを使用したホスト型サービスとしてもデプロイできます。これはウェブ統合や共有チームアクセスに便利です。

🚀 Digital Oceanへのデプロイメント

オプション1：ダッシュボードを使用する

1. リポジトリを準備する：

   git add .
   git commit -m "Initial commit"
   git push origin main
   

2. 新しいアプリを作成する：

   • Digital Ocean Apps にアクセスします。
   • "Create App" をクリックします。
   • あなたのGitHubリポジトリを選択します。
   • ブランチ（main）を選択します。

3. アプリを設定する：

   • Digital Oceanは自動的にDockerfileを検出します。
   • または .do/app.yaml 設定を使用します。

4. 環境変数を設定する：

   • アプリ設定 → 環境変数に移動します。
   • 以下を暗号化された変数として追加します。
     • DEPLOYHQ_EMAIL
     • DEPLOYHQ_API_KEY
     • DEPLOYHQ_ACCOUNT
   • 以下を通常の変数として追加します。
     • NODE_ENV=production
     • PORT=8080
     • LOG_LEVEL=info

5. デプロイする：

   • "Next" をクリックし、"Create Resources" をクリックします。
   • デプロイが完了するのを待ちます。

6. カスタムドメインを設定する（オプション）：

   • 設定 → ドメインに移動します。
   • mcp.deployhq.com を追加します。
   • 指示に従ってDNSレコードを更新します。

オプション2：doctl CLIを使用する

1. doctlをインストールする：

   # macOS
   brew install doctl
   
   # Linux
   cd ~
   wget https://github.com/digitalocean/doctl/releases/download/v1.104.0/doctl-1.104.0-linux-amd64.tar.gz
   tar xf doctl-1.104.0-linux-amd64.tar.gz
   sudo mv doctl /usr/local/bin
   

2. 認証する：

   doctl auth init
   

3. .do/app.yaml を更新する：

   • github.repo フィールドをあなたのリポジトリに編集します。
   • 必要に応じてインスタンスサイズを確認し、調整します。

4. アプリを作成する：

   doctl apps create --spec .do/app.yaml
   

5. 環境シークレットを設定する：

   # アプリIDを取得する
   doctl apps list
   
   # 環境変数を更新する（APP_IDを置き換える）
   doctl apps update APP_ID --spec .do/app.yaml
   

6. ログを表示する：