task-management

タスク管理

monday.com のボード上のアイテムを作成、更新、割り当て、管理します。monday.com では、ボード上の各行が「アイテム」です。タスク、取引、バグ、コンテンツ、または作業単位を表します。このスキルでは、monday.com の API で必要となる正しい列の値の形式について説明します。これは、プラットフォームをプログラムから操作する際に最もよく発生するエラーの原因です。

重要な前提条件

アイテムを作成または更新する前に、必ず最初に get_board_info を呼び出して、ボードの列定義を取得してください。次の情報が必要です。

• 列 ID（例：status、date4、person）
• 列の種類（例：status、date、people）
• ステータスラベルの対応関係（例：「完了」に対応するインデックス）
• ドロップダウン列で許可されている値

この手順を行わないと、列の値の書き込みは失敗しても通知されないか、誤った値が設定されます。

ワークフロー：アイテムを作成する

ステップ 1：対象のボードを見つける

ユーザーがボード名を指定した場合：

1. ボード名を指定して search を呼び出し、ボードを検索します
2. 複数の結果がある場合は、ユーザーに一致するものを確認します

ユーザーがボード名を指定していない場合：

1. get_user_context を呼び出して、ユーザーのボードを一覧表示します
2. 使用するボードを尋ねます

ステップ 2：ボードの構造を取得する

ボード ID を指定して get_board_info を呼び出します。次の情報を確認してください。

• すべての列 ID とその種類
• グループ ID と名前（アイテムを配置する場所を把握するため）
• ステータスラベルの選択肢（「対応中」「完了」などの正確なラベル文字列）

ステップ 3：列の種類の詳細を取得する（必要な場合）

列の種類に必要な正確な形式を確認する必要がある場合は、列の種類を指定して get_column_type_info を呼び出します。JSON スキーマと検証ルールが返されます。

ステップ 4：アイテムを作成する

次の値を指定して create_item を呼び出します。

• boardId：対象のボード ID
• groupId：アイテムを配置するグループ（ステップ 2 の情報を使用）
• itemName：アイテム名
• columnValues：列の値を含む JSON 文字列（下記の形式ガイドを参照）

ステップ 5：確認して次の対応を提案する

作成後：

• API 呼び出しの内容を逐一説明せず、実施したことを自然な言葉で報告します
• アイテム名、ボード名、MCP ツールから返された直接 URL を含めます
• 次のような妥当な次のステップを 2～3 件提案します。
  • 「誰かを割り当てましょうか？」
  • 「期限を設定しますか？」
  • 「サブアイテムに分けましょうか？」
  • 「詳細をコメントに追加しますか？」

ワークフロー：アイテムを更新する

ステップ 1：アイテムを特定する

ユーザーがアイテム名を指定していて ID を指定していない場合：

1. get_board_info を呼び出して、ボードの構造を確認します
2. 検索クエリを指定して get_board_items_page を呼び出し、アイテムを検索します
3. 返された名前とユーザーが指定したアイテム名を照合します。 searchTerm を指定した get_board_items_page は、厳密な名前フィルターではなく関連度順の並べ替えとして動作します。完全に一致する結果がなくても、部分的に一致するアイテムが順位付けされて返されます。書き込みを行う前に、返された一覧を確認し、大文字と小文字を区別しない完全一致、またはほぼ完全な名前一致があるかを確認してください。返されたアイテムの名前がどれも対象と一致しない場合は、応答が空でなくても検索結果なしとして扱い、ステップ 4 に進みます。
4. 一致する結果が複数ある場合は、書き込み前にユーザーにどれが対象か確認します
5. 名前が一致する結果がない場合は、何もせずに処理を終了したり、順位が最も高いだけの別名のアイテムに書き込んだりしないでください。名前の確認を求めるか、見つかった最も近い候補を提示するか、ボードのアイテム一覧を表示することを提案します

ステップ 2：ボードの構造を取得する

まだ取得していない場合は、get_board_info を呼び出します。値を書き込む前に、列 ID と種類を把握しておく必要があります。

ステップ 3：列の値を更新する

次の値を指定して change_item_column_values を呼び出します。

• boardId：ボード ID
• itemId：アイテム ID
• columnValues：変更する列のみを含む JSON 文字列

ステップ 4：確認する

変更した内容を自然な言葉で報告します。アイテム名、更新したフィールド、新しい値を含めてください。必ず直接 URL を含めます。呼び出した API ツールについては説明しないでください。

MCP UI ウィジェットを使うタイミング

確認には、まずプレーンテキストを使ってください。ユーザーから作業の割り当てを依頼され、長いチームメンバー一覧から選ぶ必要がある場合は、show-assign を使います。このウィジェットでは、ユーザーが操作できる人物選択ツールが表示されます。ユーザーが担当者をすでに指定している単独の割り当てでは、list_users_and_teams を使ってユーザー ID を調べ、ウィジェットを使わずに直接書き込んでください。

単一の作成または更新の確認に show-table は使わないでください。プレーンテキストと項目の URL を使うほうが簡潔です。

列の値の形式ガイド

create_item と change_item_column_values の columnValues パラメーターは JSON 文字列です。列の種類ごとに、指定された形式で値を設定する必要があります。形式を間違えることが、失敗の最大の原因です。

すべての列の種類を網羅した形式のリファレンスについては、references/column-value-formats.md を参照してください。

よく使われる種類のクイックリファレンス：

Status - get_board_info から取得した正確なラベル文字列を使い、{"label": "Done"} と指定します：

{"status_column_id": {"label": "Done"}}

Date - {"date": "YYYY-MM-DD"} と指定します：

{"date_column_id": {"date": "2025-06-15"}}

People - {"personsAndTeams": [{"id": USER_ID, "kind": "person"}]} と指定します：

{"person_column_id": {"personsAndTeams": [{"id": 12345678, "kind": "person"}]}}

Text - プレーンな文字列値：

{"text_column_id": "Some text value"}

Numbers - 数値をプレーンな文字列で指定します：

{"numbers_column_id": "42"}

Email - {"email": "...", "text": "..."} と指定します：

{"email_column_id": {"email": "[email protected]", "text": "Contact"}}

Phone - {"phone": "...", "countryShortName": "..."} と指定します：

{"phone_column_id": {"phone": "+15551234567", "countryShortName": "US"}}

Dropdown - {"labels": ["Option 1", "Option 2"]} と指定します：

{"dropdown_column_id": {"labels": ["High Priority"]}}

Timeline - {"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"} と指定します：

{"timeline_column_id": {"from": "2025-06-01", "to": "2025-06-30"}}

Link - {"url": "...", "text": "..."} と指定します。text は必須です（ラベルがない場合は URL を繰り返してください）：

{"link_column_id": {"url": "https://example.com", "text": "Example"}}

Checkbox - {"checked": "true"} と指定します。チェックを外すには、{"checked": "false"} または null を指定します。true / false を単独で指定すると失敗します：

{"checkbox_column_id": {"checked": "true"}}

Email、phone、link はプレーンな文字列では失敗します。必ずオブジェクトを送信してください。

複数列を一度に更新する

複数の列の更新を、1つの JSON 文字列にまとめます：

{
  "status": {"label": "Working on it"},
  "date4": {"date": "2025-06-15"},
  "person": {"personsAndTeams": [{"id": 12345678, "kind": "person"}]},
  "text0": "Implementation notes here"
}

サブアイテムの作成

サブアイテムを作成するには、parentItemId パラメーターに親アイテムの ID を設定して create_item を呼び出します。サブアイテムは、親アイテムのサブアイテムボードに作成されます。

注：サブアイテムボードには独自の列構成があります。列の値を設定する前に、サブアイテムボードで get_board_info を呼び出し、列の定義を取得してください。

コメントの追加

アイテムにコメントまたは更新を追加するには、次の値を指定して create_update を呼び出します：

• itemId：アイテム ID
• body：コメント本文（基本的な HTML（<b>、<i>、<a>、<ul>、<li>）に対応しています）

よくあるパターン

完了としてマークする： get_board_info からボードの「完了」ステータスラベルを取得し、{"status_column_id": {"label": "Done"}} を指定して change_item_column_values を呼び出します。ステータスの変更を確認したら、ボードに対応する終端グループ（Done、Closed、Completed、Resolved、Fixed、Won、Lost、Archived）があるか、またアイテムがすでにそのグループに入っていないかを確認します。該当する場合は、次のステップとして「Done グループにも移動しますか？」と提案します。自動で移動してはいけません。ステータスに関係なくアイテムを元のグループに残す意図があるボードもあるため、必ず先に確認してください。

担当者を変更する： list_users_and_teams から新しい担当者のユーザー ID を取得し、people 列の形式を指定して change_item_column_values を呼び出します。

一括作成と更新： create_items（1 回の呼び出しにつき最大 20 件。各アイテムでグループ、親アイテム、またはテンプレートアイテムを個別に選択できます）と update_items（1 回の呼び出しにつき最大 40 件。複数のボードにまたがって実行できます）を使用します。各エントリは個別に成功または失敗するため、アイテムごとの結果を読み取り、失敗したエントリだけを再試行してください。単一のアイテムには create_item / change_item_column_values を使用します。

グループに移動する： MCP ツールキットにはアイテムを直接「移動」するツールはありません（move_object の対象はボード、フォルダー、概要であり、アイテムではありません）。all_monday_api で move_item_to_group ミューテーションを使用します：mutation { move_item_to_group (item_id: <ID>, group_id: "<GROUP_ID>") { id } }。移動に create_item と duplicateFromItemId を使用してはいけません。コピーが作成され、元のアイテムはそのまま残ります。

アイテムを別のグループに複製する： duplicateFromItemId を指定した create_items は groupId を無視します。コピーは常に元のアイテムが属するグループに作成されます。先に複製し、各コピーを move_item_to_group で移動してください。複製のレスポンスでは、新しい名前が適用されていても名前が " (copy)" と報告されるため、アイテムの名前をユーザーに伝える前にアイテムを読み取ってください。

スマートなデフォルト

ユーザーがすべての値を指定していない場合：

• ステータス： 最初の未完了ラベル（通常は「Not Started」または「Working on it」）をデフォルトにします。get_board_info でボードのラベルの順序を確認してください。レスポンスでデフォルト値を伝えてください。
• グループ： 次の順序でグループを選択します。(1) 名前がバックログパターン（大文字と小文字を区別しない：To Do、Todo、Backlog、New、Open、Not Started、Inbox、Lead、Triage）に一致するグループがあれば、それを使用します。(2) 該当するグループがない場合は、最上位の非終端グループを使用します。終端グループとは、名前が完了パターン（大文字と小文字を区別しない：Done、Closed、Completed、Complete、Verified、Resolved、Fixed、Won、Lost、Archived、Cancelled、Canceled）に一致するグループです。(3) すべてのグループが終端グループの場合は、推測せず、どのグループを使うかユーザーに尋ねます。API が monday ボードの最初のグループとして「Done」を返す場合があるため、groups[0] を盲目的に使用しないでください。使用したグループは必ず伝え、ユーザーが変更できるようにしてください。
• 担当者： ユーザーが特定されており、ボードに people 列がある場合は、そのユーザーへの割り当てを提案します。確認せずに自動で割り当ててはいけません。

一括操作

1 回のリクエストで 5 件以上の項目を作成または更新する場合：

• 項目ごとに 1 回ずつ呼び出すのではなく、create_items／update_items でまとめて処理します
• すべての項目を処理してから、件数の概要とボードへのリンクを提示します
• 個々の項目をすべて列挙せず、「マーケティングボードに 12 件の項目を作成しました」とボードの URL を伝えます
• 失敗した項目がある場合は、失敗件数と理由を分けて報告します

一括で破壊的な操作（元に戻すのが難しい可能性のある更新が 3 件以上）を行う場合は、実行前にユーザーの確認を取ります。

サブアイテムがまだないボードでのサブアイテムの一括操作。 サブアイテムのボードは、最初のサブアイテムを作成したときに遅延作成されます。作成前にバッチを送信すると、列が見つからないというエラーが断続的に発生します。まず create_item（parentItemId）で最初のサブアイテムを単独で作成し、サブアイテムのボードで get_board_info を呼び出して列 ID を取得してから、残りを create_items でまとめて処理します。

一括操作時のドロップダウンとステータスのラベル。 get_board_info から取得した既存のラベル文字列をそのまま再利用します。ユーザーが実際に新しいラベルを追加したい場合に限り、createLabelsIfMissing: true を設定します。ドロップダウン列では、バッチ内の新しいラベルはエントリーごとに作成されます。たとえば、createLabelsIfMissing: true を指定して「Beta」という新しいラベルを 3 件のエントリーで送信すると、列に「Beta」ラベルが 3 つ作成されます。まず新しいラベルを使って 1 件の項目を作成し、ラベルが存在するようになったら、残りを createLabelsIfMissing なしでまとめて処理します。ステータス列ではこのような重複は発生しませんが、それでも新しいラベルは各エントリーで同じ綴りにしてください。

エラーの防止と解決

1. 必ず最初に get_board_info を呼び出してください。列 ID やステータスラベルを推測してはいけません
2. ステータスラベルの文字列は正確に指定してください。「Working on it」であり、「working on it」ではありません（大文字と小文字は区別されます）
3. 書き込み前に列の種類を確認してください。status 列と color 列では形式が異なります
4. columnValues を文字列化してください。このパラメーターには JSON オブジェクトではなく、JSON 文字列を指定します
5. ユーザー ID を検証してください。割り当てる前に list_users_and_teams を使って有効なユーザー ID を取得します。検索範囲を指定するため、必ず name パラメーター（または既知の場合は userIds）を渡してください。パラメーターなしで list_users_and_teams を呼び出すと、アカウント内の全ユーザーが返され、大規模なテナントではトークン制限を超えてしまいます。ユーザーからメールアドレスを受け取った場合は、まずローカル部分を名前として検索します（例：[email protected] の場合は「alex.po」）。該当がなければ、本人の表示名をユーザーに尋ねてください

MCP の呼び出しに失敗した場合、生のエラーをそのまま伝えず、原因を診断して解決策を提案してください。

• 「このボードにステータスラベル『Done!』が見つかりません。ボードでは『Done』（感嘆符なし）が使われています。こちらを使用しますか？」
• 「ユーザー ID 12345 はアカウントにありません。選択できるユーザーを一覧表示しましょうか？」
• 「このボードへのアクセスが拒否されました。このボードは非公開で、購読もしていません。所有者に追加を依頼しますか、それとも別のボードを選びますか？」

読み取りは成功するのに書き込みツールが失敗する場合。 書き込みツール（create_item、create_items、update_items、change_item_column_values、create_column、create_board）がツール一覧にない場合、または読み取りに成功した直後のボードに対して「Resource not found」、「USER_UNAUTHORIZED」、あるいは 403 が返された場合は、同じ呼び出しを 1 回だけ再試行します。再度失敗した場合は、そこで停止してください。同じボードに対してループしたり、別の書き込みツールを試したりしてはいけません。コネクターのセッションで書き込みアクセスが失われたことをユーザーに伝え、monday.com コネクターを切断して再接続するよう依頼し、submit_bug_or_feature_request で報告することも提案してください。

想定されるボードが見つからない、またはワークスペースが空に見える場合。 get_user_context を呼び出し、接続中のアカウントをユーザーに伝えてください。複数の monday アカウントで同じメールアドレスを使っているユーザーは、別のアカウントに接続していることがよくあります。再接続して正しいアカウントを選択すると解決します。

使用するツール

• get_user_context - ユーザーのボードを検索します
• search - 名前でボードを検索します
• get_board_info - ボードの構造、カラム ID、ステータスラベルを確認します（書き込み前に必須）
• get_column_type_info - カラムタイプの詳細なスキーマと検証ルールを確認します
• get_board_items_page - 名前またはフィルターでアイテムを検索します
• create_item - 新しいアイテムまたはサブアイテムを作成します
• create_items - 1 回の呼び出しで最大 20 件のアイテムまたはサブアイテムを作成します
• change_item_column_values - 既存アイテムのカラム値を更新します
• update_items - 複数のボードにまたがる最大 40 件のアイテムを 1 回の呼び出しで更新します
• create_update - アイテムにコメントを追加します
• all_monday_api - アイテムをグループ間で移動する際の move_item_to_group ミューテーションに使用します
• list_users_and_teams - 人物カラム用のユーザー ID を調べます
• submit_bug_or_feature_request - 再試行後も書き込みツールが失敗し続ける場合に報告します
• show-assign（選択的）- ユーザーが多数のチームメンバーから選択する際に、人物選択ウィジェットを表示します

その他のリソース

• references/column-value-formats.md - monday.com のすべてのカラムタイプに対応する、カラム値の完全な書式設定リファレンス