Teamwork MCP

チームワークMCP

Teamwork API に接続し、Teamwork プロジェクトおよびタスクと対話するための簡素化されたインターフェースを提供する MCP サーバー。

特徴

• チームワークAPIに接続する
• プロジェクトとタスクを取得する
• タスクの作成、更新、削除
• RESTful APIエンドポイント
• エラー処理とログ記録
• カーソルや他のアプリケーションとの統合のためのMCPサーバー

前提条件

• Node.js (v14.17 以上、18 以上または最新の LTS バージョンを推奨)
• npmまたはyarn
• APIアクセス可能なチームワークアカウント

利用可能なチームワークMCPツール

MCP サーバーを通じて次のツールを利用できます。

プロジェクトツール

• getProjects - チームワークからすべてのプロジェクトを取得する
• getCurrentProject - 現在のプロジェクトの詳細を取得します
• createProject - チームワークで新しいプロジェクトを作成する

タスクツール

• getTasks - チームワークからすべてのタスクを取得する
• getTasksByProjectId - チームワーク内の特定のプロジェクトからすべてのタスクを取得します
• getTaskListsByProjectId - チームワーク内の特定のプロジェクトからすべてのタスクリストを取得します
• getTasksByTaskListId - Teamwork から特定のタスク リスト ID のすべてのタスクを取得します。
• getTaskById - Teamwork から ID で特定のタスクを取得します
• createTask - チームワークで新しいタスクを作成する
• createSubTask - チームワークで親タスクの下に新しいサブタスクを作成します
• updateTask - チームワーク内の既存のタスクを更新する
• deleteTask - チームワークからタスクを削除する
• getTasksMetricsComplete - チームワークで完了したタスクの合計数を取得します
• getTasksMetricsLate - チームワークで遅延したタスクの合計数を取得します
• getTaskSubtasks - チームワーク内の特定のタスクのすべてのサブタスクを取得します
• getTaskComments - チームワークから特定のタスクのコメントを取得します

コメントツール

• createComment - タスク/メッセージ/ノートブックに関連するコメントを作成する

会社のツール

• getCompanies - オプションのフィルタリングを使用して、Teamwork からすべての会社を取得します
• getCompanyById - IDで特定の会社を取得する
• createCompany - Teamworkで新しい会社を作成する
• updateCompany - 既存の会社の情報を更新する
• deleteCompany - チームワークから会社を削除する

人材ツール

• getPeople - チームワークからすべての人々を取得する
• getPersonById - Teamwork から ID で特定の人物を取得します
• getProjectPeople - チームワークから特定のプロジェクトに割り当てられたすべてのユーザーを取得します
• addPeopleToProject - チームワークの特定のプロジェクトに人を追加する
• deletePerson - チームワークから人を削除する
• updatePerson - 個人の情報（タイムゾーン、名前、メールなど）を更新します
• getProjectsPeopleMetricsPerformance - 人材指標のパフォーマンスを取得する
• getProjectsPeopleUtilization - 人材活用率を取得する
• getProjectPerson - プロジェクトの特定の人物を取得する

レポートツール

• getProjectsReportingUserTaskCompletion - ユーザーのタスク完了レポートを取得する
• getProjectsReportingUtilization - CSV および HTML 形式のさまざまな利用状況レポートを取得します

時間ツール

• getTime - すべての時間エントリを取得する
• getProjectsAllocationsTime - プロジェクトの割り当て時間を取得する
• getTimezones - Teamwork で利用可能なすべてのタイムゾーンを取得します (ユーザーのタイムゾーンを更新するときに便利です)

インストール

1. リポジトリをクローンします。
   git clone https://github.com/readingdancer/teamwork-mcp.git cd teamwork-mcp
2. 依存関係:
   npm install
3. .env.exampleファイルに基づいて.envファイルを作成します。
   cp .env.example .env
4. Teamwork の資格情報を使用して.envファイルを更新します。

構成

アプリケーションを構成するには、 .envファイルを編集します。

• PORT : サーバーが実行されるポート (デフォルト: 3000)
• NODE_ENV : 環境（開発、本番、テスト）
• LOG_LEVEL : ログレベル（情報、エラー、デバッグ）
• TEAMWORK_DOMAIN : チームワークドメイン名 (例: https://your-company.teamwork.comの場合は「your-company」)
• TEAMWORK_USERNAME : チームワークのユーザー名（メール）
• TEAMWORK_PASSWORD : チームワークのパスワード

資格情報の設定

Teamwork の資格情報は、次の 3 つの方法で提供できます。

1. 環境変数: 環境でTEAMWORK_DOMAIN 、 TEAMWORK_USERNAME 、およびTEAMWORK_PASSWORD設定します。
2. .env ファイル: 上記のように必要な変数を含む.envファイルを作成します。
3. コマンドライン引数: アプリケーションの実行時に資格情報を渡します:

または短縮形を使用します:

ツールフィルタリング

次のコマンドライン引数を使用して、MCP サーバーで使用できるツールを制御できます。

1. 許可リスト: 特定のツールのみを公開します:
   node build/index.js --allow-tools=getProjects,getTasks,getTaskById
   または短縮形を使用します:
   node build/index.js --allow=getProjects,getTasks,getTaskById
2. 拒否リスト: 指定されたツールを除くすべてのツールを公開します。
   node build/index.js --deny-tools=deleteTask,updateTask
   または短縮形を使用します:
   node build/index.js --deny=deleteTask,updateTask

グループによるツールフィルタリング

フィルタリングするツールのグループを指定できるようになりました。これにより、MCPサーバーで利用可能なツールをより柔軟に制御できます。使用可能なグループは以下のとおりです。

• プロジェクト: プロジェクト関連のすべてのツールが含まれます。
• タスク: タスク関連のすべてのツールが含まれます。
• People : 人に関するすべてのツールが含まれます。
• レポート: レポート関連のすべてのツールが含まれます。
• 時間: 時間に関連するすべてのツールが含まれます。
• コメント: 特定のコメント ツールが含まれます。

ツールフィルタリングにおけるグループの使用

これらのグループを許可リストまたは拒否リストに指定することで、グループ内のすべてのツールを許可または除外できます。例：

1. グループを含む許可リスト: 特定のツール グループのみを公開します。
   node build/index.js --allow-tools=Tasks,People
   または短縮形を使用します:
   node build/index.js --allow=Tasks,People
2. グループ付き拒否リスト: 指定されたグループ内のツールを除くすべてのツールを公開します。
   node build/index.js --deny-tools=Reporting,Time
   または短縮形を使用します:
   node build/index.js --deny=Reporting,Time

デフォルトでは、許可リストも拒否リストも指定されていない場合、すべてのツールが公開されます。両方指定されている場合は、許可リストが優先されます。

セキュリティ強化のため、ツール フィルタリングは次の 2 つのレベルで適用されます。

1. 利用可能なツールを一覧表示する場合（許可リストまたは拒否リストにないツールは表示されません）
2. ツール呼び出しを実行するとき（フィルタリングされたツールを呼び出そうとするとエラーが発生して拒否されます）

チームワークプロジェクトの設定

現在のソリューションをチームワーク プロジェクトに関連付けるには、次の方法を使用できます。

設定ファイルの使用

次の構造で、プロジェクトのルートに.teamworkファイルを作成できます。

このシンプルな構成ファイルは、ソリューションを特定の Teamwork プロジェクトに関連付けます。将来的には、このファイルを使用して詳細を保存する可能性があります。

構成が完了すると、MCP は Teamwork プロジェクトを見つけて現在のソリューションに関連付けることができるようになり、作業中のソリューションに関連するプロジェクトとタスクを取得するために必要な API 呼び出しの数が削減されます。

使用法

NPXの使用（推奨）

Teamwork MCP を使用する最も簡単な方法は npx を使用することです。

設定オプションを渡すこともできます:

アプリケーションの構築

注: MCP のみを使用する場合は、これは必要ありません。上記の NPX の手順を使用してください。

アプリケーションをビルドします。

これにより、TypeScriptコードがコンパイルされ、MCPサーバーとして使用できるようになります。

MCPサーバーとして実行

ユーザー名、パスワード、URL に .env ファイルを使用している場合、またはそれらを環境変数に保存している場合は、Cursor や他のアプリケーションとの統合のために MCP サーバーとして実行するには、次の手順を実行します。

注意: リポジトリを保存した場所に基づいて、ドライブとパスの詳細を変更することを忘れないでください。

または、行引数を使用して渡すこともできます。

短縮形も使用できます:

MCPインスペクターの使用

デバッグのために MCP インスペクタを実行するには:

カーソル（およびその他の MCP クライアント）への追加

この MCP サーバーをカーソルに追加するには:

0.47より前のバージョン

1. カーソル設定 > 機能 > MCP を開く
2. 「+新しいMCPサーバーを追加」をクリックします
3. サーバーの名前を入力します（例：「Teamwork API」）
4. トランスポートタイプとして「stdio」を選択します
5. サーバーを実行するコマンドnpx @vizioz/teamwork-mcpを入力し、上記のように資格情報とドメイン コマンド ライン引数を追加します。
   • ツールのフィルタリング オプションを含めることができます: --allow=getProjects,getTasksまたは--deny=deleteTask
6. 「追加」をクリック

0.47以降のバージョン（設定を手動で編集）

上記の許可または拒否の引数を追加する場合は、次のように追加するだけです。上記の例のいずれかを追加できます。また、以下に示すように、グループと個々のツールの両方を追加することもできます。

Teamwork MCP ツールが Composer の Cursor Agent で使用できるようになります。

ライセンス

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

免責事項

このプロジェクトはTeamwork.comと提携、承認、または後援されていません。パッケージ名（@vizioz/teamwork-mcp）における「Teamwork」という名称の使用は、Teamwork.com APIとの互換性を示すための説明目的のみに使用されています。