Tiflux MCP

🤖 TiFlux MCP サーバー

Claude Code やその他の AI クライアントと TiFlux を統合する Model Context Protocol (MCP) サーバー

🚀 クイックスタート

TiFlux MCP サーバーは、Model Context Protocol (MCP) を通じて、Claude Code やその他の AI クライアントから TiFlux の機能に直接アクセスできるようにします。チケット管理、チャット操作、顧客管理、カスタムフィールドの探索まで、すべてを AI クライアントからシームレスに操作できます。

npm install -g @tiflux/mcp

✨ 主な機能

• 🎫 チケット管理: 包括的なフィルタリングによるチケットの取得・作成・更新・クローズ・一覧表示
• 📊 ステージと SLA 履歴: チケットステージの完全な履歴を、ステージごとの SLA 結果とともに検査
• 💬 内部コミュニケーション: ファイル添付付きでチケットの内部コミュニケーションを作成・一覧表示
• ⏱️ 時間追跡 (アポイントメント): チケットに対する作業時間アポイントメントの作成・一覧表示
• 💌 チャット管理: 受信トレイ/自分/対応中/アーカイブ済みチャットの一覧表示、チャット詳細の取得、チャットの転送/リンク、WhatsApp メッセージの送信、チャットの終了
• 🗂️ デスク探索: チャットを離れることなく、利用可能なデスクの一覧表示と完全なデスク設定 (SLA、フィールド、動作) の検査
• 🔍 カスタムフィールドの探索: 3 つの階層すべて (エンティティ → フィールド → オプション) でカスタムフィールドを探索し、LLM が正しいオプション ID を使ってチェックボックス/単一選択フィールドを正確に入力できるようにする
• 👥 顧客 CRUD: 顧客の完全な CRUD — 取得・作成・更新・フィルタ付き一覧、関連デスク/技術グループ、ポータルユーザー、メール権限
• 📎 ファイルアップロードサポート: 内部コミュニケーションに最大 10 ファイル (各 25MB) を添付
• 🔌 API 統合: TiFlux API v2 との直接統合
• 🔐 環境設定: 環境変数による安全な設定
• 🧪 包括的なテスト: 100% モック分離による自動テスト

📦 インストール

npm install -g @tiflux/mcp

💻 使用方法

Claude Code での使用

MCP 設定に以下を追加します:

{
  "tiflux": {
    "command": "npx",
    "args": ["@tiflux/mcp@latest"]
  }
}

その他の MCP クライアントでの使用

npx @tiflux/mcp@latest

URL 経由 (HTTP トランスポート)

エンドポイント: https://mcp.tiflux.com/mcp

claude mcp add tiflux-lambda --transport http https://mcp.tiflux.com/mcp --header "x-tiflux-api-key:APIKEY" -s project

手動設定

.claude/settings.json または ~/.claude.json に追加します:

{
  "mcpServers": {
    "tiflux": {
      "type": "url",
      "url": "https://mcp.tiflux.com/mcp",
      "headers": {
        "x-tiflux-api-key": "YOUR_API_KEY"
      }
    }
  }
}

エンドポイント

エンドポイント	メソッド	認証	説明
/mcp	GET	不要	サーバー情報
/mcp	POST	必要	MCP 操作
/health	GET	不要	ヘルスチェック

Web 経由 (OAuth 2.0) — Claude web & ChatGPT コネクタ

MCP over OAuth 2.0 をサポートするあらゆる AI プラットフォーム — Claude (claude.ai / デスクトップ) や ChatGPT など — で、ローカルインストール不要で TiFlux をコネクタとして使用できます。TiFlux MCP サーバー URL を指すカスタムコネクタを追加するだけです。

MCP サーバー URL (コネクタに貼り付け):

https://mcp.tiflux.com

コネクタの追加:

• Claude (claude.ai / デスクトップ): 設定 → コネクタ → カスタムコネクタを追加 → https://mcp.tiflux.com を貼り付け → 接続。
• ChatGPT: 設定 → コネクタ (または GPT 構築時に 追加) → https://mcp.tiflux.com を貼り付け → 接続。

認可の仕組み:

1. コネクタを追加すると、プラットフォームが自動的に TiFlux 認可ページを開きます。
2. ページには TiFlux API キーを生成するためのステップバイステップガイドが表示されます:
   • app.tiflux.com にログイン
   • プロフィール写真をクリック → Minha conta
   • Sessões タブを開く
   • Sessões API の下で "Gerar novo token de sessão" をクリック
   • 生成されたキーをコピーして認可フォームに貼り付け
3. 認可後、プラットフォームは Bearer トークンを受け取り、以降のすべての MCP リクエストに使用します — キーを再度扱う必要はありません。

Claude Code やローカル/スクリプトでの API キーヘッダー直接使用については、上記の URL 経由 (HTTP トランスポート) を参照してください。

サポートされる認証方式:

方式	ヘッダー	使用場面
API キー (直接)	x-tiflux-api-key: YOUR_API_KEY	Claude Code、ローカル SDK、スクリプト
Bearer トークン (OAuth)	Authorization: Bearer <token>	Claude.ai、ChatGPT、Web コネクタ

OAuth 2.0 エンドポイント:

エンドポイント	説明
GET /.well-known/oauth-authorization-server	OAuth サーバーメタデータ (RFC 8414)
POST /register	動的クライアント登録 (RFC 7591)
GET /authorize	認可ページ (ユーザーが API キーを入力)
POST /authorize	フォーム送信 — 認可コードを発行
POST /token	トークン交換とリフレッシュ

⚙️ 設定

TiFlux API 認証情報を含む .env ファイルを作成します:

# TiFlux API Configuration
TIFLUX_API_KEY=your_api_key_here

# Default values for ticket creation
TIFLUX_DEFAULT_CLIENT_ID=1
TIFLUX_DEFAULT_DESK_ID=1
TIFLUX_DEFAULT_PRIORITY_ID=1
TIFLUX_DEFAULT_CATALOG_ITEM_ID=1

🛠️ 利用可能なツール

get_ticket

ID で特定のチケットを取得します。ステータス、優先度、デスク、ステージ、カタログ、担当者、顧客、監査データ、SLA、URL を含む包括的な情報を返します。

パラメータ:

• ticket_number (string, 必須): 取得するチケット番号
• show_entities (boolean, 任意): チケットにリンクされたすべてのカスタムフィールドを含める
• include_filled_entity (boolean, 任意): 値が入力されたカスタムフィールドのみを含める

戻り値: 以下を含む包括的なチケット情報:

• ステータス (ID、名前、オープン/クローズフラグ)
• 優先度 (ID、名前)
• デスク (ID、内部名、表示名、アクティブ状態)
• ステージ (ID、名前、最初/最後ステージフラグ、最大時間)
• サービスカタログ (アイテム ID、アイテム名、エリア、カタログ)
• 担当者 (ID、名前、メール、タイプ、技術グループ)
• 顧客 (ID、名前、法人名、アクティブ状態)
• 監査 (作成者 ID、オリジン、作成/更新日時)
• SLA (ステータス、有効期限、期限)
• 追加情報 (フォロワー、作業時間、再オープン、内部/外部 URL)

v1.4.0 の新機能: 1 回の呼び出しで完全なチケットメタデータを取得できるよう、フィールドを拡張。

create_ticket

TiFlux に新しいチケットを作成します。

パラメータ:

• title (string, 必須): チケットのタイトル
• description (string, 必須): チケットの説明。Markdown (太字、リスト、見出し、コード) を受け付けます — MCP は API に送信する前に自動的に HTML に変換します。
• client_id (number, 任意): 顧客 (企業) ID
• client_name (string, 任意): 自動検索用の顧客 (企業) 名 (client_id の代替)。ユーザーが明示的に「クライアント」または「企業」と言った場合のみ使用してください。
• desk_id (number, 任意): デスク ID
• desk_name (string, 任意): 自動検索用のデスク/チーム名 (desk_id の代替)。部分名を受け付けます — 例: "cansados" は "Dev - Cansados" に解決されます (スマート名前解決を参照)。ユーザーがエンティティを限定せずに名前を参照した場合は、これを優先してください。
• priority_id (number, 任意): 優先度 ID
• services_catalogs_item_id (number, 任意): サービスカタログアイテム ID
• catalog_item_name (string, 任意): 自動検索用のカタログアイテム名 (services_catalogs_item_id の代替。desk_id または desk_name が必要)
• status_id (number, 任意): ステータス ID
• requestor_id (number, 任意): リクエスタ ID (チケットを起票する人物。選択した顧客に属している必要があります)。ID をすでに知っている場合はこれを直接渡してください — 自動解決ルックアップをスキップします。
• requestor_name (string, 任意): リクエスタ名。requestor_id と requestor_email の両方を指定せずに指定した場合、MCP はこれを既存の requestor_id に自動的に解決しようとします (「ゴースト」リクエスタの作成を回避)。複数の一致が見つかった場合は、曖昧性を解消するためのリストを返します。一致がない場合は、以前の動作 (名前をそのまま送信) にフォールバックします。
• requestor_email (string, 任意): リクエスタのメール。指定した場合、MCP は名前から ID への自動解決を試みません — メールは十分に正確な識別子です。
• requestor_telephone (string, 任意): リクエスタの電話
• responsible_id (number, 任意): 担当ユーザー ID
• responsible_name (string, 任意): 自動検索用の担当ユーザー名 (responsible_id の代替)
• followers (string, 任意): カンマ区切りのフォロワーメール
• parent_ticket_number (number, 任意): 親チケット番号 — 作成されたチケットはこのチケットの子としてリンクされます
• files_base64 (array, 任意): base64 エンコードされたファイルの配列 [{content: "base64...", filename: "file.png"}] (最大 10 ファイル、各 25MB)

v2.4.0 の新機能: files_base64 による base64 ファイルアップロードをサポート。チケットは multipart/form-data として送信されます。サーバーモード (Lambda) に関する注意: files_base64 ペイロードは、API Gateway の 6MB 制限の対象となります。

破壊的変更 (v2.8.0): パラメータ files (ローカルパス) は削除されました。base64 経由でファイルを送信するには新しいツール upload_ticket_files を使用するか、files_base64 経由で直接ファイルを渡してください。

update_ticket

TiFlux の既存チケットを更新します。

パラメータ:

• ticket_id (string, 必須): 更新するチケットの ID
• title (string, 任意): 新しいチケットのタイトル
• description (string, 任意): 新しいチケットの説明。Markdown (太字、リスト、見出し、コード) を受け付けます — MCP は API に送信する前に自動的に HTML に変換します。
• client_id (number, 任意): 新しい顧客 ID
• desk_id (number, 任意): 新しいデスク ID
• desk_name (string, 任意): 自動検索用のデスク名 (desk_id の代替)。部分名を受け付けます — 例: "cansados" は "Dev - Cansados" に解決されます (スマート名前解決を参照)
• stage_id (number, 任意): ステージ/フェーズ ID
• stage_name (string, 任意): 自動検索用のステージ名 (stage_id の代替。desk_id または desk_name が必要)
• responsible_id (number, 任意): 担当ユーザー ID (割り当てを解除するには null を使用)
• responsible_name (string, 任意): 自動検索用の担当ユーザー名 (responsible_id の代替)
• followers (string, 任意): カンマ区切りのフォロワーメール
• services_catalogs_item_id (number, 任意): 特定のアイテムでデスクを更新するためのカタログアイテム ID
• catalog_item_name (string, 任意): 自動検索用のカタログアイテム名 (services_catalogs_item_id の代替。desk_id または desk_name が必要)

注記: ticket_id とともに、少なくとも 1 つのオプションフィールドを指定する必要があります。

update_ticket_entities

TiFlux のチケットのカスタムフィールド (エンティティ) を更新します。リクエストあたり最大 50 フィールドをサポート。名前付きオプションが複数あるチェックボックスフィールドの場合は、entity_field_option_id を指定してオプションごとに 1 アイテムを送信します。オプション ID の探索には list_entity_field_options を使用してください。

パラメータ:

• ticket_number (string, 必須): 更新するチケット番号
• entities (array, 必須): 更新するカスタムフィールドのリスト。複数選択チェックボックスフィールドの場合は、オプションごとに 1 アイテムを送信します。

エンティティオブジェクトの構造:

• entity_field_id (number, 必須): カスタムフィールド ID (get_ticket または list_entity_fields で取得)
• value (string, 必須): フィールド値。受け入れられる型:
  • text: 文字列
  • text_area: 文字列
  • currency: 文字列としての float (例: "150.55")
  • phone: 数字のみ (例: "47999999999")
  • email: 文字列
  • link: http/https/ftp で始まる URL
  • date: YYYY-MM-DD 形式
  • single_select: 文字列としてのオプション ID
  • checkbox: 文字列としての boolean "true"/"false"
  • 必須でないフィールドをクリアするには null を使用
• entity_field_option_id (number, 任意): チェックボックス複数選択フィールドのオプション ID。ID の取得には list_entity_field_options を使用。複数選択チェックボックスの場合は、同じ entity_field_id と異なる entity_field_option_id を持つアイテムをオプションごとに 1 つ送信します。
• country_code (string, 任意): 国コード (ブラジル国外の電話フィールド用)

例 — シンプルなテキスト/日付フィールド:

{
  "ticket_number": "123",
  "entities": [
    {
      "entity_field_id": 72,
      "value": "New value"
    },
    {
      "entity_field_id": 73,
      "value": "2025-01-15"
    }
  ]
}

例 — 名前付きオプションが複数あるチェックボックス:

{
  "ticket_number": "12345",
  "entities": [
    { "entity_field_id": 81, "entity_field_option_id": 11, "value": "true" },
    { "entity_field_id": 81, "entity_field_option_id": 12, "value": "false" },
    { "entity_field_id": 81, "entity_field_option_id": 13, "value": "true" }
  ]
}

cancel_ticket

TiFlux の特定のチケットをキャンセルします。

パラメータ:

• ticket_number (string, 必須): キャンセルするチケット番号 (例: "37"、"123")

例:

{
  "ticket_number": "84429"
}

list_tickets

フィルタオプション付きでチケットを一覧表示します。

パラメータ:

• desk_ids (string, 任意): カンマ区切りのデスク ID (例: "1,2,3")
• desk_name (string, 任意): 自動 ID 解決用のデスク/チーム名。部分名を受け付けます — 例: "cansados" は "Dev - Cansados" に解決されます (スマート名前解決を参照)。ユーザーがエンティティを限定せずに名前を参照した場合は、このフィールドを優先してください。
• client_ids (string, 任意): カンマ区切りの顧客 (企業) ID (例: "1,2,3")
• client_name (string, 任意): 自動検索用の顧客 (企業) 名。ユーザーが明示的に「クライアント」「企業」と言った場合、または既知の法人名を指定した場合のみ使用してください。個人の場合は requestor_email を優先してください。
• stage_ids (string, 任意): カンマ区切りのステージ ID (例: "1,2,3")
• stage_name (string, 任意): ステージ名 (desk_name と併用する必要があります)
• responsible_ids (string, 任意): カンマ区切りの担当 (割り当てられたアテンダント) ユーザー ID (ID をすでに持っている場合に使用)
• responsible_name (string, 任意): 自動解決用の担当ユーザー名。管理者 (GET /users 経由) と非管理者ユーザー (アテンダントグループへのフォールバック経由) の両方で動作します。ユーザーが「担当」「割り当て先」と言って名前を指定した場合に使用してください。
• requestor_ids (string, 任意): カンマ区切りのリクエスタ (チケットを起票した人物) ID (例: "1,2,3")。人物 (企業ではなく) でフィルタする場合に使用します。ID は search_user(type="client") で解決してください。
• requestor_email (string, 任意): リクエスタ (チケットを起票した人物) のメール。ユーザーが人物を参照するか、メールを直接指定した場合に使用します。ID を解決するための往復を避けられます。
• offset (number, 任意): ページ番号 (デフォルト: 1)
• limit (number, 任意): 1 ページあたりの件数 (デフォルト: 20、最大: 200)
• is_closed (boolean, 任意): クローズ済みチケットを含める (デフォルト: false)
• date_type (string, 任意): フィルタ用の日付タイプ: "created_at" (作成日、デフォルト) または "solved_in_time" (解決/クローズ日)
• start_datetime (string, 任意): ISO 8601 形式の開始日時フィルタ (例: "2024-05-15T00:00:00Z")。date >= start_datetime のチケットをフィルタします
• end_datetime (string, 任意): ISO 8601 形式の終了日時フィルタ (例: "2024-05-15T23:59:59Z")。date <= end_datetime のチケットをフィルタします

注記: 少なくとも 1 つのフィルタ (desk_ids/desk_name、client_ids/client_name、stage_ids/stage_name、responsible_ids/responsible_name、requestor_ids、または requestor_email) が必要です。

例 — リクエスタのメールでフィルタ:

{
  "requestor_email": "joao@empresa.com",
  "is_closed": false
}

日付フィルタの例:

// List tickets created in a specific date range (including closed ones)
{
  "desk_name": "Support",
  "date_type": "created_at",
  "start_datetime": "2024-01-01T00:00:00Z",
  "end_datetime": "2024-01-31T23:59:59Z",
  "is_closed": true
}

// List tickets resolved in a specific period
{
  "desk_name": "Support",
  "date_type": "solved_in_time",
  "start_datetime": "2024-01-01T00:00:00Z",
  "end_datetime": "2024-01-31T23:59:59Z",
  "is_closed": true
}

close_ticket

TiFlux の特定のチケットをクローズします。

パラメータ:

• ticket_number (string, 必須): クローズするチケット番号 (例: "37"、"123")

例:

{
  "ticket_number": "84429"
}

成功レスポンス:

**Ticket #84429 fechado com sucesso!**

**Mensagem:** Ticket 84429 closed successfully

*Ticket fechado via API TiFlux*

create_ticket_answer

特定のチケットに新しい回答 (顧客コミュニケーション) を作成します。

パラメータ:

• ticket_number (string, 必須): 回答を作成するチケット番号
• text (string, 必須): 顧客に送信される回答内容。Markdown (太字、リスト、見出し、コード) を受け付けます — MCP は API に送信する前に自動的に HTML に変換します。
• with_signature (boolean, 任意): 回答にユーザー署名を含める (デフォルト: false)
• files_base64 (array, 任意): base64 エンコードされたファイルの配列 [{content: "base64...", filename: "file.pdf"}] (最大 10 ファイル、各 40MB)

v1.3.0 の新機能: files_base64 パラメータによる base64 ファイルアップロードをサポート。

破壊的変更 (v2.8.0): パラメータ files (ローカルパス) は削除されました。base64 経由でファイルを送信するには新しいツール upload_ticket_files を使用するか、files_base64 経由で直接ファイルを渡してください。

例:

{
  "ticket_number": "123",
  "text": "Hello, your issue has been resolved.",
  "with_signature": true,
  "files_base64": [{"content": "JVBERi0x...", "filename": "attachment.pdf"}]
}

search_client

名前で顧客を検索します (ショートカット — 名前のみ)。完全なフィルタとページネーションには list_clients を使用してください。

パラメータ:

• client_name (string, 必須): 検索する顧客名 (部分一致をサポート)

list_clients

フィルタとページネーション付きで顧客を一覧表示します。search_client の完全版 — ステータス、名前、CPF/CNPJ フィルタを受け付けます。

パラメータ:

• active (boolean, 任意): ステータスでフィルタ: true = アクティブのみ、false = 非アクティブのみ。省略するとすべて。
• name (string, 任意): 名前でフィルタ (部分一致)
• social_revenue (string, 任意): CPF/CNPJ でフィルタ
• offset (number, 任意): ページ番号 (デフォルト: 1)
• limit (number, 任意): 1 ページあたりの件数 (デフォルト: 20、最大: 200)

例:

{
  "active": true,
  "name": "Acme",
  "limit": 10
}

get_client

ID で顧客の完全な詳細を取得します。

パラメータ:

• client_id (number, 必須): 顧客 ID (search_client または list_clients で取得)
• show_entities (boolean, 任意): レスポンスにカスタムフィールド (エンティティ) を含める (デフォルト: false)

例:

{
  "client_id": 42,
  "show_entities": true
}

create_client

TiFlux に新しい顧客を作成します。必須は name と social のみで、その他のフィールドはすべてオプションであり、指定された場合にのみ送信されます。

パラメータ:

• name (string, 必須): 顧客の通称 (nome fantasia)
• social (string, 必須): 顧客の法人名 (razão social)
• social_revenue (string, 任意): CPF または CNPJ
• desk_ids (array of numbers, 任意): 関連付けるデスク ID
• add_all_desks (boolean, 任意): すべてのデスクを関連付ける
• technical_group_ids (array of numbers, 任意): 関連付ける技術グループ ID
• status (boolean, 任意): アクティブ (true) または非アクティブ (false) — デフォルト: true
• max_agents (number, 任意): 許可される最大エージェント数
• email_financial (string, 任意): 財務担当の連絡先メール
• anotations (string, 任意): 内部メモ
• billing_report_type (string, 任意): detailed_with_appointment、detailed、synthetic、または "" (空)

例:

{
  "name": "Acme Corp",
  "social": "Acme Corporação Ltda",
  "social_revenue": "12.345.678/0001-99",
  "desk_ids": [1, 2]
}

update_client

既存の顧客を更新します (部分更新 — 指定されたフィールドのみが送信されます)。

パラメータ:

• client_id (number, 必須): 更新する顧客 ID
• create_client のすべてのフィールド (すべて任意)

例:

{
  "client_id": 42,
  "status": false,
  "email_financial": "novo@empresa.com"
}

update_client_entities

顧客のカスタムフィールド (エンティティ) を更新します。リクエストあたり最大 50 フィールドをサポート。複数オプションがあるチェックボックスフィールドの場合は、entity_field_id + entity_field_option_id + value: "true"/"false" を指定してオプションごとに 1 アイテムを送信します。

パラメータ:

• client_id (number, 必須): 更新する顧客 ID
• entities (array, 必須): カスタムフィールドのリスト。各アイテム:
  • entity_field_id (number, 必須): カスタムフィールド ID
  • value (string, 必須): フィールド値 (クリアする場合は null)
  • entity_field_option_id (number, 任意): チェックボックス/単一選択のオプション ID
  • country_code (string, 任意): 電話フィールドの国コード

例:

{
  "client_id": 42,
  "entities": [
    { "entity_field_id": 72, "value": "TI" },
    { "entity_field_id": 80, "entity_field_option_id": 12, "value": "true" }
  ]
}

get_client_desks

顧客に関連付けられたデスクを一覧表示します。

パラメータ:

• client_id (number, 必須): 顧客 ID
• offset (number, 任意): ページ番号 (デフォルト: 1)
• limit (number, 任意): 1 ページあたりの件数 (デフォルト: 20、最大: 200)

get_client_technical_groups

顧客に関連付けられた技術グループを一覧表示します。

パラメータ:

• client_id (number, 必須): 顧客 ID
• offset (number, 任意): ページ番号 (デフォルト: 1)
• limit (number, 任意): 1 ページあたりの件数 (デフォルト: 20、最大: 200)

create_client_user

顧客のポータルユーザーを作成します。ユーザーがクライアントポータルにアクセスできるようにします。

パラメータ:

• client_id (number, 必須): ユーザーを関連付ける顧客 ID
• name (string, 必須): ユーザーのフルネーム
• email (string, 必須): ユーザーのメール — ポータルログインに使用
• extension (string, 任意): 電話内線
• authorization_flow (boolean, 任意): ポータルアクセスに認可を要求
• telephone (string, 任意): 電話番号
• country_code (string, 任意): 電話番号の国コード

例:

{
  "client_id": 42,
  "name": "João Silva",
  "email": "joao@empresa.com",
  "telephone": "11999999999"
}

add_client_email_permission

顧客に代わってチケットを起票するための認可されたドメインまたはメールを追加します。

パラメータ:

• client_id (number, 必須): 顧客 ID
• address (string, 必須): この顧客のチケットを起票するために認可されたドメイン (例: @empresa.com.br) または特定のメール

例:

{
  "client_id": 42,
  "address": "@empresa.com.br"
}

search_user

チケットの担当者として使用するユーザーを名前で検索します。

パラメータ:

• name (string, 必須): 検索するユーザー名 (部分一致をサポート、名前とメールを検索)
• type (string, 任意): ユーザータイプフィルタ (client、attendant、admin)
• active (boolean, 任意): アクティブ (true) または非アクティブ (false) ユーザーでフィルタ
• limit (number, 任意): 1 ページあたりの件数 (デフォルト: 20、最大: 200)
• offset (number, 任意): ページ番号 (デフォルト: 1)

非管理者サポート (アテンダントグループへのフォールバック): API キーが非管理者ユーザーに属する場合、GET /users は 403 を返します。この場合、ツールは自動的にアテンダントグループ (GET /technical-groups) とそのメンバー (GET /technical-groups/{id}/users) の列挙にフォールバックし、名前によるファジーマッチングを適用します。結果は管理者パスと同一で、パラメータ変更は不要です。フォールバックが使用された場合、出力に注記が追加されます。

実装上の注意: 管理者ユーザーの場合、TiFlux API は /users エンドポイントで名前ベースのフィルタリングをサポートしていません — ツールは最大 200 ユーザーを取得し、クライアント側でフィルタします。非管理者ユーザーの場合、ツールは技術グループのチェーンを使用し、複数のグループに現れるユーザーを重複排除します。

例:

{
  "name": "John",
  "type": "attendant",
  "active": true
}

search_stage

チケット更新で使用する特定のデスクのステージを検索します。

パラメータ:

• desk_id (number, 任意): ステージを検索するデスク ID
• desk_name (string, 任意): 自動検索用のデスク名 (desk_id の代替)。部分名を受け付けます — 例: "cansados" は "Dev - Cansados" に解決されます (スマート名前解決を参照)
• limit (number, 任意): 1 ページあたりの件数 (デフォルト: 20、最大: 200)
• offset (number, 任意): ページ番号 (デフォルト: 1)

注記: 少なくとも 1 つのパラメータ (desk_id または desk_name) を指定する必要があります。

例:

{
  "desk_name": "Suporte",
  "limit": 20
}

search_catalog_item

自由テキスト用語、または特定のデスク内の名前/フィルタでサービスカタログアイテムを検索します。search を使用してキーワードでアイテムを探索します (サーバー側、カタログ名、エリア名、またはアイテム名に一致)。catalog_item_name を使用して名前で特定のアイテムを特定します (クライアント側、正確に 1 件一致した場合は単一の詳細に折りたたまれます)。

パラメータ:

• desk_id (number, 任意): カタログアイテムを検索するデスク ID
• desk_name (string, 任意): 自動検索用のデスク名 (desk_id の代替)。部分名を受け付けます — 例: "cansados" は "Dev - Cansados" に解決されます (スマート名前解決を参照)
• search (string, 任意): カタログ名、エリア名、アイテム名を横断するサーバー側検索用の自由テキスト用語。部分一致、大文字小文字を区別せず、アクセントを区別しません。完全な階層 (カタログ → エリア → アイテム) を含むリストを返します。area_id/catalog_id と組み合わせて範囲を絞り込むことができます。
• catalog_item_name (string, 任意): 検索するカタログアイテム名 (アイテム名のみに対するクライアント側部分一致)。1 件一致 → 詳細ビュー、複数 → リスト付きエラー。より広範な探索には search を使用してください。
• area_id (number, 任意): 結果をフィルタするサービスエリア ID
• catalog_id (number, 任意): 結果をフィルタするサービスカタログ ID
• limit (number, 任意): 1 ページあたりの件数 (デフォルト: 20、最大: 200)
• offset (number, 任意): ページ番号 (デフォルト: 1)

注記: desk_id または desk_name の少なくとも 1 つと、search、catalog_item_name、area_id、または catalog_id の少なくとも 1 つを指定する必要があります。

例 — 自由テキスト検索 (探索に推奨):

{
  "desk_name": "Support",
  "search": "infra",
  "limit": 10
}

例 — 名前で特定のアイテムを特定:

{
  "desk_name": "Support",
  "catalog_item_name": "Installation",
  "limit": 10
}

💬 内部コミュニケーション

create_internal_communication

チケットに新しい内部コミュニケーションを作成します。

パラメータ:

• ticket_number (string, 必須): コミュニケーションを作成するチケット番号
• text (string, 必須): コミュニケーションの内容。Markdown (太字、リスト、見出し、コード) を受け付けます — MCP は API に送信する前に自動的に HTML に変換します。
• files_base64 (array, 任意): base64 エンコードされたファイルの配列 [{content: "base64...", filename: "file.pdf"}] (最大 10 ファイル、各 25MB)

v1.3.0 の新機能: files_base64 パラメータによる base64 ファイルアップロードをサポート。

破壊的変更 (v2.8.0): パラメータ files (ローカルパス) は削除されました。base64 経由でファイルを送信するには新しいツール upload_ticket_files を使用するか、files_base64 経由で直接ファイルを渡してください。

例:

{
  "ticket_number": "123",
  "text": "Internal communication content",
  "files_base64": [{"content": "base64...", "filename": "relatorio.pdf"}]
}

list_internal_communications

チケットの内部コミュニケーションを一覧表示します。

パラメータ:

• ticket_number (string, 必須): コミュニケーションを一覧表示するチケット番号
• offset (number, 任意): ページ番号 (デフォルト: 1)
• limit (number, 任意): 1 ページあたりのコミュニケーション数 (デフォルト: 20、最大: 200)

get_ticket_files

特定のチケットに添付されたすべてのファイルを取得します。

パラメータ:

• ticket_number (string, 必須): ファイルを取得するチケット番号

戻り値: 以下を含むファイルの詳細リスト:

• ファイル ID、名前、コンテンツタイプ
• ファイルサイズ (KB/MB/GB でフォーマット)
• ダウンロード URL
• 作成日と作成者情報

例:

{
  "ticket_number": "123"
}

upload_ticket_files

TiFlux の既存チケットにファイルをアップロードします。ファイルは base64 エンコードされたコンテンツとして提供する必要があります。

パラメータ:

• ticket_number (string, 必須): ファイルを添付するチケット番号 (例: "123"、"456")
• files_base64 (array, 必須): base64 エンコードされたファイルの配列 [{content: "base64...", filename: "file.pdf"}] (最大 10 ファイル、各 25MB)

例:

{
  "ticket_number": "123",
  "files_base64": [
    {"content": "base64encodedcontent...", "filename": "relatorio.md"},
    {"content": "base64encodedcontent...", "filename": "screenshot.png"}
  ]
}

戻り値: アップロードされたファイルのリストを含む確認。

注記: アップロードされたテキストファイル (.md、.txt、.csv、.json) は適切な charset=utf-8 コンテンツタイプで送信され、TiFlux ポータルでの文字エンコーディング問題 (文字化け) を防ぎます。

delete_ticket_file

TiFlux のチケットに添付されたファイルを削除します。

パラメータ:

• ticket_number (string, 必須): ファイルを削除するチケット番号 (例: "123"、"456")
• file_id (string, 必須): 削除するファイルの ID (get_ticket_files で取得)

例:

{
  "ticket_number": "123",
  "file_id": "456"
}

戻り値: ファイルが削除されたことの確認。

get_ticket_stages_slas

デスクのステージを移動する際のチケットの完全な履歴を、各ステージの SLA 結果とともに一覧表示します。SLA 監査、エスカレーションレビュー、ボトルネック分析に役立ちます。

パラメータ:

• ticket_number (string, 必須): チケット番号 (例: "123"、"456")
• offset (number, 任意): ページ番号 (デフォルト: 1)
• limit (number, 任意): 1 ページあたりの件数 (デフォルト: 20、最大: 200)

戻り値: 各ステージ遷移について、フォーマット済みの出力に以下が含まれます:

• ステージ名とデスク
• 活動時間内の滞在時間 (HH:MM)
• SLA が達成されたかどうか (✅ Sim / ❌ Não)
• SLA 有効期限のタイムスタンプ
• チケットがステージに進入した日時と、それを移動させた人物
• (もしあれば) このステージでチケットが対応された日時と、その担当者

空の結果: アクティブな SLA を持たないデスクのチケットは、説明メッセージとともに空のリストを返します — これは想定された動作であり、エラーではありません。

例:

{
  "ticket_number": "32",
  "offset": 1,
  "limit": 20
}

list_ticket_answers

特定のチケットの回答 (顧客とのコミュニケーション) をページネーション付きで一覧表示します。

パラメータ:

• ticket_number (integer, 必須): 回答を一覧表示するチケット番号
• offset (number, 任意): ページ番号 (デフォルト: 1)
• limit (number, 任意): 1 ページあたりの回答数 (デフォルト: 20、最大: 200)

戻り値: 各回答に含まれるもの:

• 著者名、日時、オリジン (agent、client など)
• ファイル数インジケータ
• コンテンツのプレビュー (最初の 200 文字)
• 次ページへのヒントを含むページネーション情報

例:

{
  "ticket_number": 123,
  "offset": 1,
  "limit": 20
}

get_ticket_answer

チケットからの特定の回答の完全な詳細を、添付ファイルを含めて取得します。

パラメータ:

• ticket_number (integer, 必須): チケット番号
• answer_id (integer, 必須): 取得する回答の ID

戻り値:

• 完全な回答内容 (切り捨てなし)、著者、日付、オリジン
• 名前、種類、サイズ、ダウンロード URL を含む添付ファイルの完全なリスト

例:

{
  "ticket_number": 123,
  "answer_id": 501
}

delete_ticket_answer

TiFlux のチケットから回答 (顧客コミュニケーション) を削除します。

パラメータ:

• ticket_number (string, 必須): 回答を削除するチケット番号 (例: "123"、"456")
• answer_id (string, 必須): 削除する回答の ID (list_ticket_answers または get_ticket_answer で取得)

例:

{
  "ticket_number": "123",
  "answer_id": "501"
}

戻り値: 回答が削除されたことの確認。

delete_ticket_answer_file

TiFlux の特定のチケット回答に添付されたファイルを削除します。

パラメータ:

• answer_id (string, 必須): ファイルを削除する回答の ID (list_ticket_answers または get_ticket_answer で取得)
• file_id (string, 必須): 削除するファイルの ID (get_ticket_answer の files[].id フィールドで取得)

例:

{
  "answer_id": "501",
  "file_id": "1"
}

戻り値: ファイルが削除されたことの確認。

get_ticket_histories

チケットのイベント履歴 (タイムライン) を一覧表示し、フィールド変更、ステージ遷移、その他のイベントを表示します。ページネーション付き。

パラメータ:

• ticket_number (integer, 必須): 履歴を取得するチケット番号
• offset (number, 任意): ページ番号 (デフォルト: 1)
• limit (number, 任意): 1 ページあたりのイベント数 (デフォルト: 20、最大: 200)
• history_of (integer, 任意): チケットエリアでフィルタ (例: 1 = アポイントメント)
• type_id_attr (integer, 任意): 属性タイプでフィルタ
• operation (integer, 任意): 操作タイプでフィルタ — history_of=1 の場合のみ有効

戻り値: 各イベントについて:

• アクションの説明、ユーザー、日時、イベントタイプと操作
• 変更されたフィールドの古い値 → 新しい値の差分

例:

{
  "ticket_number": 123,
  "history_of": 1
}

reopen_ticket

クローズまたはキャンセルされたチケットを再オープンします。請求済みのチケットは再オープンできません。

パラメータ:

• ticket_number (integer, 必須): 再オープンするチケット番号
• disapproval_reason (string, 任意): レビュー待ちのチケットを再オープンする場合に必須 (否認ベースの再オープン)

ビジネスルール:

• 請求済みのチケットは再オープンできません (API は 422 を返します)
• レビュー/承認待ちのチケットを再オープンする場合、disapproval_reason は必須です

例:

{
  "ticket_number": 123,
  "disapproval_reason": "The solution did not resolve the issue"
}

get_internal_communication

特定の内部コミュニケーションを完全な内容で取得します。

パラメータ:

• ticket_number (string, 必須): コミュニケーションを含むチケット番号
• communication_id (string, 必須): 取得する内部コミュニケーションの ID

update_internal_communication

チケットの既存の内部コミュニケーションのテキストを更新します。コミュニケーションの作成者のみが編集できます。

パラメータ:

• ticket_number (string, 必須): コミュニケーションが存在するチケット番号 (例: "123"、"456")
• communication_id (string, 必須): 更新する内部コミュニケーションの ID (list_internal_communications または get_internal_communication で取得)
• text (string, 必須): 内部コミュニケーションの新しい内容。Markdown (太字、リスト、見出し、コード) を受け付けます — MCP は API に送信する前に自動的に HTML に変換します。

例:

{
  "ticket_number": "123",
  "communication_id": "101",
  "text": "Updated communication content with **important** details."
}

戻り値: 更新されたコミュニケーション内容を含む確認。

注記: TiFlux API はコミュニケーションの作成者のみが編集を許可します。認証されたユーザーがコミュニケーションを作成していない場合は 403 エラーが返されます。

delete_internal_communication

TiFlux のチケットから内部コミュニケーションを削除します。

パラメータ:

• ticket_number (string, 必須): コミュニケーションを削除するチケット番号 (例: "123"、"456")
• communication_id (string, 必須): 削除する内部コミュニケーションの ID (list_internal_communications で取得)

例:

{
  "ticket_number": "123",
  "communication_id": "101"
}

戻り値: 内部コミュニケーションが削除されたことの確認。

⏱️ アポイントメント (時間追跡)

免責事項: アポイントメントの作成 (create_appointment) は、非有償アポイントメントで構成されたデスクのチケットでのみサポートされます。アポイントメントの一覧表示 (list_appointments) は任意のデスクで動作し、利用可能な場合は評価 (valorization) の詳細をレンダリングします。

create_appointment

特定のチケットに新しいアポイントメント (作業時間記録) を作成します。非有償アポイントメントで構成されたデスクのチケットでのみ動作します。

パラメータ:

• ticket_number (string, 必須): アポイントメントを作成するチケット番号
• date (string, 必須): YYYY-MM-DD 形式のアポイントメント日付。将来の日付は許可されません。
• init_time (string, 必須): HH:MM 形式の開始時刻 (例: "09:00"、"14:30")
• end_time (string, 必須): HH:MM 形式の終了時刻。init_time 以上である必要があります。
• description (string, 必須): 実施した作業の説明

例:

{
  "ticket_number": "123",
  "date": "2025-01-15",
  "init_time": "09:00",
  "end_time": "10:30",
  "description": "Investigation and fix of the reported issue"
}

list_appointments

特定のチケットのアポイントメント (作業時間記録) を任意のフィルタ付きで一覧表示します。利用可能な場合、各アポイントメントカードには評価の詳細 (対応タイプ、契約または単発サービス、移動シフト、金額) とジオロケーションエントリが含まれます。

パラメータ:

• ticket_number (string, 必須): アポイントメントを一覧表示するチケット番号
• user_id (number, 任意): アポイントメントを作成したユーザーの ID でフィルタ
• start_date (string, 任意): この日付以降のアポイントメントを返す (YYYY-MM-DD)
• end_date (string, 任意): この日付までのアポイントメントを返す (YYYY-MM-DD)
• offset (number, 任意): ページ番号 (デフォルト: 1)
• limit (number, 任意): 1 ページあたりのアポイントメント数 (デフォルト: 20、最大: 200)

戻り値: 各アポイントメントカードには、日付、時間範囲、アテンダント、顧客 (利用可能な場合)、説明が表示されます。デスクで評価が有効になっている場合、カードには以下も含まれます:

• 対応タイプ: 外部 (Externo)、リモート (Remoto)、または内部 (Interno)
• サービス種別: 単発 (Avulso) で単発サービス名付き、または契約で契約名付き
• 移動シフト名と金額 (該当する場合)
• 保証と手動金額フラグ (true の場合のみ表示)
• R$ X,XX としてフォーマットされた金額

valorization が null の場合 (評価なしで構成されたデスク)、上記のフィールドは表示されません。

ジオロケーション行 (📍 Localização: lat, lon) は、API がアポイントメントの locations を返す場合にレンダリングされます。

例:

{
  "ticket_number": "123",
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "limit": 50
}

💌 チャット

get_chat

ID で特定のチャットの詳細を表示します。ステータス、顧客、担当者、部門、オリジン、評価、日付を含むカードを返します。

パラメータ:

• id (number, 必須): チャットの数値 ID (数値文字列も受け付けます — ハンドラが parseInt を呼び出します)

戻り値: 以下を含む、関連するすべてのチャットフィールドを持つカード:

• ステータス (アーカイブ済み、キャンセル済み、オンライン、回答待ち)
• 顧客とリクエスタ名
• 部門と担当アテンダント
• オリジンチャネルとルーム
• リンクされたチケット番号
• 評価レーティング (利用可能な場合は 1〜5)
• 最後の顧客メッセージ (150 文字で切り捨て)
• タイムスタンプ (作成、更新、引き受け)

例:

{
  "id": 42
}

list_inbox_chats

受信トレイ (未引き受け) のチャットを、部門、顧客、オリジン、ページネーションの任意フィルタ付きで一覧表示します。

パラメータ:

• offset (number, 任意): ページ番号 (デフォルト: 1、最小: 1)
• limit (number, 任意): 1 ページあたりのチャット数 (デフォルト: 20、最大: 200)
• department_id (number, 任意): 部門 ID でフィルタ
• client_id (number, 任意): 顧客 ID でフィルタ
• requestor_id (number, 任意): リクエスタ ID でフィルタ — 0 より大きい必要があります
• number (number, 任意): WhatsApp 連絡先番号でフィルタ — WhatsApp ライセンスが必要
• origins (string, 任意): カンマ区切りのオリジンチャネル: chat、site_widget、campaign、whatsapp、whatsapp_web、gupshup、whatsapp_cloud
• started_by (string, 任意): チャット開始者タイプ: Client、Attendant、Campaign、API

例:

{
  "origins": "whatsapp",
  "limit": 10,
  "offset": 1
}

list_my_chats

認証済みユーザー (API キーの所有者) が引き受けたチャットを、任意フィルタとページネーション付きで一覧表示します。

パラメータ:

• offset (number, 任意): ページ番号 (デフォルト: 1、最小: 1)
• limit (number, 任意): 1 ページあたりのチャット数 (デフォルト: 20、最大: 200)
• department_id (number, 任意): 部門 ID でフィルタ
• client_id (number, 任意): 顧客 ID でフィルタ
• requestor_id (number, 任意): リクエスタ ID でフィルタ — 0 より大きい必要があります
• number (number, 任意): WhatsApp 連絡先番号でフィルタ — WhatsApp ライセンスが必要
• origins (string, 任意): カンマ区切りのオリジンチャネル (list_inbox_chats を参照)
• started_by (string, 任意): チャット開始者タイプ (list_inbox_chats を参照)

例:

{
  "department_id": 3,
  "limit": 20
}

list_in_attendance_chats

組織の対応中チャットをすべて、担当者、ステータス、ページネーションの任意フィルタ付きで一覧表示します。

パラメータ:

• offset (number, 任意): ページ番号 (デフォルト: 1、最小: 1)
• limit (number, 任意): 1 ページあたりのチャット数 (デフォルト: 20、最大: 200)
• department_id (number, 任意): 部門 ID でフィルタ
• client_id (number, 任意): 顧客 ID でフィルタ
• requestor_id (number, 任意): リクエスタ ID でフィルタ — 0 より大きい必要があります
• number (number, 任意): WhatsApp 連絡先番号でフィルタ — WhatsApp ライセンスが必要
• origins (string, 任意): カンマ区切りのオリジンチャネル (list_inbox_chats を参照)
• started_by (string, 任意): チャット開始者タイプ (list_inbox_chats を参照)
• user_id (number, 任意): 担当アテンダント ID でフィルタ
• status (string, 任意): 対応ステータスでフィルタ: waiting_client、waiting_attendance、triage

例:

{
  "user_id": 7,
  "status": "triage"
}

list_archived_chats

アーカイブ済みチャット (終了またはキャンセル) を任意フィルタ付きで一覧表示します。対応の評価とキャンセルステータスを表示します。

パラメータ:

• offset (number, 任意): ページ番号 (デフォルト: 1、最小: 1)
• limit (number, 任意): 1 ページあたりのチャット数 (デフォルト: 20、最大: 200)
• department_id (number, 任意): 部門 ID でフィルタ
• client_id (number, 任意): 顧客 ID でフィルタ
• requestor_id (number, 任意): リクエスタ ID でフィルタ — 0 より大きい必要があります
• number (number, 任意): WhatsApp 連絡先番号でフィルタ — WhatsApp ライセンスが必要
• origins (string, 任意): カンマ区切りのオリジンチャネル (list_inbox_chats を参照)
• started_by (string, 任意): チャット開始者タイプ (list_inbox_chats を参照)
• canceled (boolean, 任意): true = キャンセルされたチャットのみ、false = 正常に終了したもののみ、省略 = すべてのアーカイブ済みチャット

例:

{
  "canceled": false,
  "limit": 50
}

update_chat

既存のチャットを更新します: アテンダントの転送 (user_id)、部門の転送 (department_id)、および/またはチャットをチケットにリンク (ticket_number)。キャンセルまたは終了していないチャットのみ更新できます。

パラメータ:

• id (number, 必須): チャット ID (数値文字列を受け付けます — ハンドラが parseInt を実行)
• user_id (number, 任意): チャットの転送先アテンダント
• user_name (string, 任意): 自動検索用のアテンダント名 (user_id の代替。user_id が優先されます)。注意 (BL-007): 管理者 API キーが必要です — GET /users は非管理者アカウントでは 403 を返します。その場合は user_id を直接使用してください。
• department_id (number, 任意): チャットの転送先部門。department_name はありません — v2 API には部門検索エンドポイントがありません。
• ticket_number (number, 任意): チャットにリンクするチケット番号

注記: user_id / user_name / department_id / ticket_number の少なくとも 1 つが必要です。いずれも指定されていない場合、ツールは API を呼び出さずに親切な警告を返します。

例:

{
  "id": 37,
  "user_id": 1,
  "ticket_number": 127
}

戻り値: 適用された変更のリストを含む Markdown の確認。

send_message

WhatsApp でメッセージを送信し、送信時にチャットを作成します。自由メッセージ (message) または HSM テンプレート / チャットテンプレート (template_id) を使用し、両方は決して一緒に使用しないでください。

message はプレーンテキストです (Markdown/HTML ではありません)。 WhatsApp は独自のマークアップ (太字にアスタリスク、斜体にアンダースコア) を使用します。HTML はそのまま表示されて