freshservice-automation

Rube MCP による Freshservice の自動化

Rube MCP を通じて、Composio の Freshservice ツールキットを使用し、Freshservice の IT サービス管理業務を自動化します。

前提条件

• Rube MCP に接続済みであること（RUBE_SEARCH_TOOLS が利用可能）
• freshservice ツールキットを使用する RUBE_MANAGE_CONNECTIONS 経由の有効な Freshservice 接続
• 常に最初に RUBE_SEARCH_TOOLS を呼び出し、現在のツールスキーマを取得すること

セットアップ

Rube MCP を取得する：クライアント設定で https://rube.app/mcp を MCP サーバーとして追加します。ホストの信頼設定／認証設定を完了してください。エンドポイントを追加するだけでは、Freshservice への接続は確立されません。

1. RUBE_SEARCH_TOOLS が応答することを確認し、Rube MCP が利用可能であることを確かめます
2. ツールキットに freshservice を指定して RUBE_MANAGE_CONNECTIONS を呼び出します
3. 接続が ACTIVE でない場合は、返された認証リンクから Freshservice の認証を完了します
4. ワークフローを実行する前に、接続ステータスが ACTIVE であることを確認します

レコードと通知に関する制限事項

書き込みを行う前に、テナント／ワークスペース、正確なチケット ID、要求されたフィールドを確認してください。チケット／サービスリクエストによって通知の送信、承認やプロビジョニングの開始、連絡先の作成が行われる場合があります。読み取りリクエストは、これらの操作を許可するものではありません。送信メールには、宛先と内容について明示的な許可が必要です。レポートではチケットの個人情報や秘密情報をマスキングし、最新の ID／ステータスコードを確認するため、検出したスキーマを使用してください。一括変更では、ID リストを事前に確認し、結果が不確かな場合や一部のみ成功した場合は、再試行する前にチケットごとの結果を照合してください。

主なワークフロー

1. チケットの一覧表示と検索

使用する場面：チケットの検索、一覧表示、絞り込みを行いたい場合

ツールの順序：

1. FRESHSERVICE_LIST_TICKETS - 任意のフィルタリングとページネーションを指定してチケットを一覧表示します［必須］
2. FRESHSERVICE_GET_TICKET - 特定のチケットの詳細情報を取得します［任意］

一覧表示の主なパラメーター：

• filter：定義済みフィルター（'all_tickets'、'deleted'、'spam'、'watching'）
• updated_since：この時刻以降に更新されたチケットを取得するための ISO 8601 タイムスタンプ
• order_by：並べ替えフィールド（'created_at'、'updated_at'、'status'、'priority'）
• order_type：並べ替え順（'asc' または 'desc'）
• page：ページ番号（1 から始まります）
• per_page：1 ページあたりの結果数（1～100、デフォルトは 30）
• include：追加フィールド（'requester'、'stats'、'description'、'conversations'、'assets'）

取得の主なパラメーター：

• ticket_id：一意のチケット ID または display_id
• include：含める追加フィールド

注意点：

• デフォルトでは、過去 30 日間に作成されたチケットのみが返されます
• 古いチケットを取得するには updated_since を使用します
• include の値ごとに追加の API クレジットを消費します
• page は 1 から始まり、最小値は 1 です
• per_page の最大値は 100、デフォルトは 30 です
• チケット ID には、内部 ID または UI に表示される display_id を使用できます

2. チケットの作成

使用する場面：新しいインシデントやリクエストを記録したい場合

ツールの順序：

1. FRESHSERVICE_CREATE_TICKET - 新しいチケットを作成します［必須］

主なパラメーター：

• subject：チケットの件名（必須）
• description：チケットの HTML 形式の説明（必須）
• status：チケットのステータス - 2（Open）、3（Pending）、4（Resolved）、5（Closed）（必須）
• priority：チケットの優先度 - 1（Low）、2（Medium）、3（High）、4（Urgent）（必須）
• email：リクエスターのメールアドレス（email または requester_id のいずれかを指定）
• requester_id：リクエスターのユーザー ID
• type：チケットの種類（'Incident' または 'Service Request'）
• source：チャネル - 1（Email）、2（Portal）、3（Phone）、4（Chat）、5（Twitter）、6（Facebook）
• impact：影響度 - 1（Low）、2（Medium）、3（High）
• urgency：緊急度 - 1（Low）、2（Medium）、3（High）、4（Critical）

注意点：

• subject、description、status、priority はすべて必須です
• リクエスターを特定するため、email または requester_id のいずれかを指定する必要があります
• ステータスと優先度には、文字列名ではなく数値コードを使用します
• 説明では HTML 形式を使用できます
• メールアドレスが既存の連絡先と一致しない場合、新しい連絡先が作成されます

3. チケットの一括更新

使用するタイミング：ユーザーが複数のチケットを一度に更新したい場合

ツールの順序：

1. FRESHSERVICE_LIST_TICKETS - 更新するチケットを検索します［前提条件］
2. FRESHSERVICE_BULK_UPDATE_TICKETS - 複数のチケットを更新します［必須］

主なパラメーター：

• ids：更新するチケットIDの配列（必須）
• update_fields：更新するフィールドの辞書（必須）
  • 使用可能なキー：'subject'、'description'、'status'、'priority'、'responder_id'、'group_id'、'type'、'tags'、'custom_fields'

注意点：

• 一括更新は内部で順番に更新を実行するため、大量のチケットを処理すると時間がかかる場合があります
• 指定したすべてのチケットに同じフィールド更新が適用されます
• 1件のチケットの更新に失敗しても、ほかのチケットは更新に成功する場合があります。個々の結果はレスポンスで確認してください
• 1回の呼び出しで、チケットごとに異なるフィールドを選択して更新することはできません
• カスタムフィールドには、表示名ではなく内部フィールド名を使用する必要があります

4. 送信メールによるチケットの作成

使用するタイミング：ユーザーが送信メール通知を送ってチケットを作成したい場合

ツールの順序：

1. FRESHSERVICE_CREATE_TICKET_OUTBOUND_EMAIL - メール通知付きでチケットを作成します［必須］

主なパラメーター：

• email：依頼者のメールアドレス（必須）
• subject：メールの件名／チケットの件名（必須）
• description：HTML形式のメール本文
• status：チケットのステータス（2=オープン、3=保留中、4=解決済み、5=クローズ）
• priority：チケットの優先度（1=低、2=中、3=高、4=緊急）
• cc_emails：CCメールアドレスの配列
• email_config_id：送信元アドレスのメール設定ID
• name：依頼者名

注意点：

• メールを送信しながら、/api/v2/tickets エンドポイント経由で標準のチケットを作成します
• メールアドレスが既存の連絡先と一致しない場合、指定された名前で新しい連絡先が作成されます
• email_config_id によって、通知の送信元として表示されるメールアドレスが決まります

5. サービスリクエストの作成

使用するタイミング：ユーザーがサービスカタログのリクエストを送信したい場合

ツールの順序：

1. FRESHSERVICE_CREATE_SERVICE_REQUEST - カタログ項目のサービスリクエストを作成します［必須］

主なパラメーター：

• item_display_id：カタログ項目の表示ID（必須）
• email：依頼者のメールアドレス
• quantity：リクエストする項目数（デフォルト：1）
• custom_fields：サービス項目フォームのカスタムフィールド値
• parent_ticket_id：親チケットの表示ID（子リクエストの場合）

注意点：

• item_display_id は、Admin > Service Catalog > 項目のURLで確認できます（例：/service_catalog/items/1）
• カスタムフィールドのキーは、サービス項目フォームのフィールド名と一致させる必要があります
• 数量を指定しない場合、デフォルトは1です
• サービスリクエストには、カタログ項目に定義された承認ワークフローが適用されます

よく使われるパターン

ステータスコード一覧

コード	ステータス
2	オープン
3	保留中
4	解決済み
5	クローズ

優先度コード一覧

コード	優先度
1	低
2	中
3	高
4	緊急

ページネーション

• page（1始まり）と per_page（最大100）パラメーターを使用します
• リクエストごとに page を1ずつ増やします
• 返された結果数が per_page 未満になるまで続けます
• デフォルトのページサイズは30です

日付範囲でチケットを検索する

1. Call FRESHSERVICE_LIST_TICKETS with updated_since='2024-01-01T00:00:00Z'
2. Optionally add order_by='updated_at' and order_type='desc'
3. Paginate through results

既知の注意点

数値コード：

• ステータスと優先度には、文字列ではなく数値を使用します
• ソースチャネルには数値コード（1～6）を使用します
• 影響度と緊急度には数値コード（1～3または1～4）を使用します

日付による絞り込み：

• デフォルトでは、過去30日間のチケットのみが返されます
• それより古いチケットには updated_since パラメーターを使用します
• 日付形式はISO 8601です（例：'2024-01-01T00:00:00Z'）

レート制限：

• Freshservice APIにはアカウントごとのレート制限があります
• 各 include オプションは追加のAPIクレジットを消費します
• 429レスポンスを受信した場合は、バックオフを実装します

レスポンスの解析：

• レスポンスデータは data または data.data の下にネストされている場合があります
• フォールバックパターンを使って、堅牢に解析してください
• チケットIDは数値の整数です

クイックリファレンス

タスク	ツールスラッグ	主なパラメータ
チケットの一覧表示	FRESHSERVICE_LIST_TICKETS	filter, updated_since, page, per_page
チケットの取得	FRESHSERVICE_GET_TICKET	ticket_id, include
チケットの作成	FRESHSERVICE_CREATE_TICKET	subject, description, status, priority, email
一括更新	FRESHSERVICE_BULK_UPDATE_TICKETS	ids, update_fields
送信メールチケット	FRESHSERVICE_CREATE_TICKET_OUTBOUND_EMAIL	email, subject, description
サービスリクエスト	FRESHSERVICE_CREATE_SERVICE_REQUEST	item_display_id, email, quantity

使用する場合

このスキルは、概要に記載されたワークフローまたはアクションを実行する場合に適用されます。

制限事項

• このスキルは、タスクが上記のスコープに明確に一致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代替として扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が欠けている場合は、作業を中断して確認を求めてください。