Tugboat MCP Server

Tugboat MCP サーバー

Tugboat API と連携するための Model Context Protocol（MCP）サーバーです。このサーバーを使うと、Claude などの AI アシスタントが、標準化された MCP インターフェースを通じて Tugboat のリソースにアクセスし、操作できるようになります。

MCP とは？

Model Context Protocol（MCP）は、AI アシスタントと外部データソースやツールをシームレスに統合するために Anthropic が作成したオープンプロトコルです。AI モデルが以下を行うための標準化された方法を提供します。

• リソース（データとコンテキスト）へのアクセス
• ツール（アクションを実行する関数）の利用
• プロンプト（テンプレート化されたワークフロー）の利用

この Tugboat MCP サーバーは、Claude などの AI アシスタントに Tugboat の API 機能を公開するために、このプロトコルを実装しています。

機能

• Tugboat のプロジェクト、プレビュー、リポジトリへのアクセス
• プレビューの作成、ビルド、更新、削除
• Tugboat リソースの検索
• プレビューのログ表示
• stdio と HTTP の両方のトランスポートに対応
• 認証および認可に対応

アーキテクチャ

このサーバーはモジュール式のアーキテクチャを採用しています。

• コア：メインサーバーのセットアップと設定管理
• リソース：Tugboat のエンティティを MCP リソースとして公開
• ツール：Tugboat API と連携する関数を実装
• ユーティリティ：API クライアントと設定ユーティリティ
• 認証：認証と認可の管理
• ミドルウェア：認証のための HTTP リクエスト処理

インストール

# Clone the repository
git clone https://github.com/yourusername/tugboat-mcp.git
cd tugboat-mcp

# Install dependencies
npm install

# Build the project
npm run build

使用方法

環境変数

以下の環境変数が必要です。

• TUGBOAT_API_KEY：Tugboat API キー
• TRANSPORT_TYPE：使用するトランスポート（stdio または http、デフォルトは stdio）
• PORT：HTTP トランスポートで使用するポート（デフォルトは 3000）
• TUGBOAT_API_URL：Tugboat API のベース URL（デフォルトは https://api.tugboatqa.com/v3）

Claude Desktop でのセットアップ

設定

1. Claude Desktop の設定ファイルを作成または編集します。

   macOS：

   touch "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
   open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
   

   Windows：

   code %APPDATA%\Claude\claude_desktop_config.json
   

2. Tugboat MCP サーバーの設定を追加します。

   {
     "mcpServers": {
       "tugboat-mcp": {
         "command": "node",
         "args": ["/path/to/tugboat-mcp/dist/index.js"],
         "env": {
           "TUGBOAT_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

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

Claude Desktop での認証

Claude Desktop を使用する場合、設定で指定した TUGBOAT_API_KEY 環境変数を通じて認証が自動的に処理されます。Claude Desktop が使用する stdio トランスポートでは、HTTP トランスポートで必要となる明示的な認証手順は不要です。

Claude とのやり取りの例

Claude を通じて Tugboat を操作する方法の例を紹介します。

1. Claude Desktop を開き、新しい会話を開始します。

2. MCP サーバーが正しく設定されていれば、下部ツールバーにツールアイコン（ハンマー）が表示されます。

3. Claude に Tugboat の操作を依頼します。

   Can you list my Tugboat projects?
   

   Claude は MCP サーバーを使ってプロジェクトを取得し、表示します。

   I've found the following Tugboat projects:
   
   1. Website Redesign (ID: abc123)
      - Created: 2023-05-15
      - Previews: 7
   
   2. API Integration (ID: def456)
      - Created: 2023-08-20
      - Previews: 3
   
   Would you like to see details for any specific project?
   

4. 次に、特定のプロジェクトやプレビューについて尋ねることができます。

   Show me the previews for the Website Redesign project.
   

   Claude は MCP サーバーを使ってプレビューを取得し、表示します。

   Here are the previews for the Website Redesign project:
   
   1. Homepage Update (ID: prev789)
      - Status: Running
      - Created: 2023-09-10
      - URL: https://prev789.tugboatqa.com
   
   2. Nav Menu Fix (ID: prev012)
      - Status: Building
      - Created: 2023-09-15
   
   Would you like to see logs for any of these previews?
   

Cursor でのセットアップ

設定

1. Cursor の設定を開きます。
2. 「Features > MCP Servers」に移動します。
3. 「+ Add New MCP Server」ボタンをクリックします。
4. 以下の情報を入力します。
   • 名前：「tugboat-mcp」と入力します。
   • タイプ：タイプとして「command」を選択します。
   • コマンド：サーバーを実行するコマンドを入力します。

     env TUGBOAT_API_KEY=your-api-key-here node /path/to/tugboat-mcp/dist/index.js
     

Cursor での認証

Claude Desktop と同様に、Cursor では設定で指定した環境変数を通じて認証が自動的に処理されます。MCP サーバーは TUGBOAT_API_KEY を使って Tugboat API に対する認証を行います。

Cursor での操作例

Cursor で Tugboat MCP サーバーを使用する方法は次のとおりです。

1. Cursor を開き、プロジェクトに移動します。

2. Cmd+L（Mac）または Ctrl+L（Windows/Linux）を押して、AI パネルを開きます。

3. AI パネルの右上で「Agent」が選択されていることを確認します。

4. Cursor に Tugboat で操作するよう依頼します。

   Can you create a new preview in my Tugboat repository def456 using the branch "feature/new-button" and name it "Button Feature Test"?
   

   Cursor は MCP サーバーを使用してプレビューを作成します。

   I'll create a new preview for you in repository def456.
   
   I've created a preview named "Button Feature Test" using the branch "feature/new-button". 
   
   Preview ID: prev345
   Status: Building
   
   The preview will be available at https://prev345.tugboatqa.com once the build is complete.
   
   Would you like me to check the build status or perform any other actions with Tugboat?
   

5. Cursor にほかの Tugboat 操作を依頼して、会話を続けることができます。

HTTP トランスポートを直接使用する

HTTP トランスポートでサーバーを実行し、直接操作することもできます。

# Start the server with HTTP transport
TUGBOAT_API_KEY=your-api-key TRANSPORT_TYPE=http npm start

HTTP トランスポートでの認証

HTTP トランスポートを使用する場合は、明示的に認証する必要があります。

1. 認証トークンを取得します。

   curl -X POST http://localhost:3000/auth/login
   

   レスポンス：

   {
     "success": true,
     "token": "your-tugboat-api-key"
   }
   

2. トークンを使用して MCP エンドポイントにアクセスします。

   curl -X POST http://localhost:3000/mcp \
     -H "Authorization: Bearer your-tugboat-api-key" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'
   

利用可能なリソース

リソース URI	説明
tugboat://projects	すべてのプロジェクトを一覧表示
tugboat://project/{id}	特定のプロジェクトの詳細を取得
tugboat://previews	すべてのプレビューを一覧表示
tugboat://preview/{id}	特定のプレビューの詳細を取得
tugboat://preview/{id}/logs	特定のプレビューのログを取得
tugboat://repositories	すべてのリポジトリを一覧表示
tugboat://repository/{id}	特定のリポジトリの詳細を取得

利用可能なツール

プロジェクト

ツール	説明	パラメーター
listProjects	すべてのプロジェクトを一覧表示	-
getProject	特定のプロジェクトの詳細を取得	id
updateProject	プロジェクトの設定を更新	id、name（任意）、domain（任意）
deleteProject	プロジェクトを削除	id、confirm
getProjectRepos	プロジェクトのリポジトリを取得	id
getProjectJobs	プロジェクトのジョブを取得	id、children（任意）、limit（任意）
getProjectStats	プロジェクトの統計情報を取得	id、item、after（任意）、before（任意）、limit（任意）
searchProjects	プロジェクトを検索	query

プレビュー

ツール	説明	パラメーター
createPreview	新しいプレビューを作成	repo、ref、name（任意）、config（任意）
buildPreview	プレビューをビルド	previewId
refreshPreview	プレビューを更新	previewId
deletePreview	プレビューを削除	previewId
getPreview	特定のプレビューの詳細を取得	previewId
updatePreview	プレビューの設定を更新	previewId、name（任意）、locked（任意）、anchor（任意）、anchor_type（任意）、config（任意）
getPreviewJobs	プレビューのジョブを取得	previewId、active（任意）
getPreviewStatistics	プレビューの統計情報を取得	previewId、item、limit（任意）、before（任意）、after（任意）
clonePreview	プレビューを複製	previewId、name（任意）、expires（任意）
startPreview	プレビューを開始	previewId
stopPreview	プレビューを停止	previewId
suspendPreview	プレビューを一時停止	previewId
searchPreviews	プレビューを検索	query、state（任意）

リポジトリ

ツール	説明	パラメーター
createRepository	新しいリポジトリを作成します	project、provider、repository、auth（任意）、その他複数の任意設定
getRepository	特定のリポジトリの詳細を取得します	id
updateRepository	リポジトリの設定を更新します	id、その他複数の任意設定
deleteRepository	リポジトリを削除します	id、confirm
updateRepositoryAuth	リポジトリのプロバイダー認証を更新します	id、auth
getRepositoryPreviews	リポジトリのプレビューを取得します	id
getRepositoryBranches	リポジトリのブランチを取得します	id
getRepositoryTags	リポジトリのタグを取得します	id
getRepositoryPullRequests	リポジトリのプルリクエストを取得します	id
getRepositoryJobs	リポジトリのジョブを取得します	id、action（任意）、children（任意）、limit（任意）
getRepositoryRegistries	リポジトリの Docker レジストリを取得します	id
getRepositoryStats	リポジトリの統計情報を取得します	id、item、after（任意）、before（任意）、limit（任意）
createRepositorySSHKey	リポジトリ用の新しい SSH キーを生成します	id、type（任意）、bits（任意）

プロンプトの例

利用可能な Tugboat プロジェクトを一覧表示する

What Tugboat projects do I have access to?

新しいプレビューを作成する

Create a new preview in repository 5f7c8d9e3b2a1c0e7f6d5a4b named "feature-branch-test" using the "feature/new-homepage" branch.

プレビューのログを確認する

Show me the logs for preview 3a2b1c0d9e8f7g6h5i4j.

プロジェクトの詳細を取得する

Show me the details for project 5d810c19f6f8203d5b65ef01.

プロジェクトを更新する

Update the name of project 5d810c19f6f8203d5b65ef01 to "Website Redesign 2.0".

プロジェクトのリポジトリを一覧表示する

What repositories belong to project 5d810c19f6f8203d5b65ef01?

プロジェクトの統計情報を表示する

Get the size statistics for project 5d810c19f6f8203d5b65ef01 from the last 30 days.

リポジトリを作成する

Create a new GitHub repository for the TugboatQA/demo project in project 5d810c19f6f8203d5b65ef01 using my personal access token ghp_abc123.

リポジトリの詳細を取得する

Show me the details for repository 5d810c19f6f82083ed65ef03.

リポジトリの設定を更新する

Update repository 5d810c19f6f82083ed65ef03 to enable autorebuild and autoredeploy.

リポジトリのブランチを一覧表示する

What branches are available in repository 5d810c19f6f82083ed65ef03?

リポジトリのプレビューを表示する

Show me all the previews for repository 5d810c19f6f82083ed65ef03.

開発

# Run in development mode
npm run dev

# Run tests
npm test

プロジェクト構成

tugboat-mcp/
├── src/
│   ├── index.ts              # Main entry point
│   ├── resources/            # MCP resources implementation
│   │   └── index.ts          # Resource registration
│   ├── tools/                # MCP tools implementation
│   │   └── index.ts          # Tool registration
│   ├── middleware/           # HTTP middleware
│   │   └── auth.ts           # Authentication middleware
│   ├── utils/                # Utility functions
│   │   ├── api-client.ts     # Tugboat API client
│   │   ├── auth.ts           # Authentication utilities
│   │   ├── config.ts         # Configuration management
│   │   └── openapi.yaml      # Tugboat API specification
│   ├── test.ts               # Test script for stdio transport
│   └── test-http.ts          # Test script for HTTP transport
├── dist/                     # Compiled JavaScript files
├── node_modules/             # Node.js dependencies
├── package.json              # Project metadata and dependencies
├── tsconfig.json             # TypeScript configuration
├── README.md                 # Project documentation
└── TODO.md                   # Task list and progress tracking

コントリビューション

コントリビューションを歓迎します！作業が必要な項目については、TODO.md ファイルをご覧ください。

ライセンス

MIT

テスト

このサーバーには、機能が正しく動作することを確認するための包括的なテストスイートが含まれています。テストは Jest を使用して記述されており、認証、API クライアント、その他のコンポーネントのユニットテストが含まれています。

テストの実行

テストを実行するには、次のコマンドを使用します。

# Run all tests
npm test

# Run tests in watch mode (useful during development)
npm run test:watch

# Run tests with coverage report
npm run test:coverage

テストの構成

テストは tests ディレクトリ内に、次の構成で整理されています。

• auth.test.ts - 認証マネージャーとミドルウェアのテスト
• api-client.test.ts - Tugboat API クライアントのテスト
• 機能の拡張に合わせて、テストファイルが追加される予定です

新しいテストの追加

新しい機能を追加する際は、コードの品質を確保し、リグレッションを防ぐために、対応するテストも追加してください。テストファイルには [component].test.ts という命名規則を使用してください。