MCP FreeScout

FreeScout MCP サーバー

FreeScout ヘルプデスクのチケット管理向け MCP（Model Context Protocol）サーバーです。このサーバーは、FreeScout チケットとの連携、問題の分析、顧客対応の管理を行うためのツールを提供します。

機能

• 🎫 チケット管理: FreeScout チケットの取得、分析、更新
• 🔍 インテリジェント分析: チケットを自動分析し、問題の種類、根本原因、解決策を判定
• 💬 返信の下書き: チケット分析に基づいて顧客への返信を生成
• 📊 高度な検索: 相対時間指定（「7d」「24h」）をサポートする一級のフィルターパラメーター
• 🔒 型安全性: 構造化出力を備えた完全な Zod スキーマ検証
• 🔁 信頼性: 一時的な障害に対する指数バックオフ付きの自動リトライロジック
• ⚡ プロトコル対応の stdio: 新しい buildServer ファクトリーが 2025 年代および 2026 年の MCP stdio クライアントの両方に対応

v3 ランタイム

• Node.js 24 以上が必要です。
• Zod 4 の入力スキーマを備えた @modelcontextprotocol/server 2.x を使用します。
• 同一のサーバーファクトリーから、2025 年のレガシーハンドシェイクと 2026 年の stdio プロトコルの両方に対応します。
• 出力スキーマを宣言することなく、安定した分析結果と書き込み操作の結果のために structuredContent を提供します。
• FreeScout の成功時の 204 No Content 更新レスポンスを受け入れ、チケット更新を開始したユーザー ID を記録します。

インストール

前提条件

• Node.js 24 以上
• API アクセスが有効になっている FreeScout インスタンス

クイックスタート（推奨）

この MCP サーバーを最も簡単に使用する方法は npx です：

Claude Desktop の場合

Claude Desktop の設定（macOS では ~/Library/Application Support/Claude/claude_desktop_config.json）に以下を追加します：

{
  "mcpServers": {
    "freescout": {
      "command": "npx",
      "args": ["@verygoodplugins/mcp-freescout@latest"],
      "env": {
        "FREESCOUT_URL": "https://your-freescout-domain.com",
        "FREESCOUT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor IDE の場合

Cursor の MCP 設定に以下を追加します：

方法 1: Cursor 設定 UI から

1. Cursor 設定を開きます（Cmd/Ctrl + ,）
2. 「MCP」を検索します
3. 「Edit in settings.json」をクリックします
4. MCP サーバーの設定を追加します

方法 2: 手動設定 Cursor の settings.json に以下を追加するか、~/.cursor/mcp.json を作成します：

{
  "mcp": {
    "servers": {
      "freescout": {
        "command": "npx",
        "args": ["@verygoodplugins/mcp-freescout@latest"],
        "env": {
          "FREESCOUT_URL": "https://your-freescout-domain.com",
          "FREESCOUT_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}

サーバーは、その環境で設定された FreeScout インスタンスとのみ通信します。

手動インストール（代替方法）

サーバーをローカルにインストールして実行する場合：

1. このリポジトリをクローンします：

git clone https://github.com/verygoodplugins/mcp-freescout.git
cd mcp-freescout

2. 依存関係をインストールします：

npm install

3. TypeScript コードをビルドします：

npm run build

4. ローカルインストールを使用するように MCP クライアントを設定します：

{
  "mcpServers": {
    "freescout": {
      "command": "node",
      "args": ["/path/to/mcp-freescout/dist/index.js"],
      "env": {
        "FREESCOUT_URL": "https://your-freescout-domain.com",
        "FREESCOUT_API_KEY": "your-api-key-here"
      }
    }
  }
}

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

サーバーを直接実行します：

npm start

または、自動リロード付きの開発モードで実行します：

npm run dev

利用可能なツール

コアなチケット操作

freescout_get_ticket

FreeScout チケットをそのすべての詳細と会話スレッドとともに取得します。

パラメーター:

• ticket（必須）: チケット ID、番号、または FreeScout URL
• includeThreads（任意）: 会話スレッドを含める（デフォルト: true）

自然言語の例:

• 「チケット #12345 を見せて」
• 「FreeScout チケット 34811 の詳細を取得して」
• 「チケット https://support.example.com/conversation/12345 を取得して」
• 「チケット 12345 には何が入っている？」
• 「チケット #34811 の会話を開いて」

例:

{
  "ticket": "12345",
  "includeThreads": true
}

例: 会話スレッド付きの FreeScout チケットの取得

freescout_analyze_ticket

チケットを分析し、問題の種類、根本原因、および推奨される解決策を判定します。

パラメータ:

• ticket (必須): チケット ID、番号、または FreeScout URL

自然言語の例:

• "チケット #12345 を分析してください"
• "チケット 34811 はどのような種類の問題ですか？"
• "このチケットを分析して、バグかどうか教えてくれますか？"
• "チケット #12345 を調べて根本原因を判定してください"
• "このチケットはバグですか、それとも機能リクエストですか？"

戻り値:

• 顧客情報
• 問題の説明と分類
• コードスニペットとエラーメッセージ
• 再現性の状況
• 根本原因の分析
• バグか機能リクエストかサードパーティの問題かの判定

例: 問題分類を伴うインテリジェントなチケット分析

freescout_add_note

チーム内のコミュニケーションのために、チケットに内部メモを追加します。

パラメータ:

• ticket (必須): チケット ID、番号、または FreeScout URL
• note (必須): メモの内容
• userId (任意): メモのユーザー ID (デフォルトは環境変数の設定)

自然言語の例:

• "チケット #12345 に『ステージングで再現しました』というメモを追加してください"
• "このチケットに内部メモを残してください"
• "チームメモを追加: 『顧客が修正の動作を確認しました』"
• "チケット 34811 へのメモ: 『開発チームにエスカレーションします』"
• "このチケットに内部ドキュメントを追加してください"

freescout_update_ticket

チケットのステータスまたは担当者の割り当て (あるいはその両方) を更新します。

パラメータ:

• ticket (必須): チケット ID、番号、または FreeScout URL
• status (任意): 新しいステータス ('active'、'pending'、'closed'、'spam')
• assignTo (任意): チケットを割り当てるユーザー ID

自然言語の例:

• "チケット #12345 をクローズしてください"
• "チケット 34811 を pending にしてください"
• "このチケットをユーザー ID 2 に割り当ててください"
• "チケットのステータスを active に設定してください"
• "チケット #12345 のステータスを closed に更新し、ユーザー 1 に割り当ててください"

freescout_create_draft_reply

送信前に編集できる下書き返信を FreeScout に作成します。このツールを使用すると、LLM が返信内容を生成し、それを下書きとして FreeScout に直接保存できます。FreeScout で正しく表示されるよう、Markdown 形式を自動的に HTML に変換します。

パラメータ:

• ticket (必須): チケット ID、番号、または FreeScout URL
• replyText (必須): 下書き返信の内容 (LLM によって生成され、Markdown 形式をサポート)
• userId (任意): 下書きを作成するユーザー ID (デフォルトは環境設定)
• to (任意): TO 受信者のリスト。省略すると既存の受信者が保持され、[] を渡すとクリアされます。
• cc (任意): CC 受信者のリスト。省略すると既存の受信者が保持され、[] を渡すとクリアされます。
• bcc (任意): BCC 受信者のリスト。省略すると既存の受信者が保持され、[] を渡すとクリアされます。

自然言語の例:

• 「チケット #12345 の下書き返信を作成して」
• 「このチケットへの顧客向け返信を下書きして」
• 「修正内容を説明する下書き返信を生成して保存して」
• 「チケット 34811 の顧客への下書き返信を書いて」
• 「顧客に感謝し、解決策を説明する下書き返信を作成して」

受信者フィールドを省略した場合、サーバーは可能であれば FreeScout から現在の会話の受信者を保持します。FreeScout が会話上の既存の to 受信者を公開していない場合は、通常のデフォルトの顧客受信者の動作が保持されます。

Markdown のサポート:

• 太字テキスト: **text** または __text__ → text
• 斜体テキスト: *text* または _text_ → text
• コード: `code` → code
• 番号付きリスト: 1. item → 適切な順序付きリスト
• 箇条書きリスト: - item または * item → 適切な順序なしリスト
• 改行: 二重改行は段落を作成し、単一改行は改行を作成します

ワークフロー:

1. freescout_get_ticket_context を使用して顧客情報とチケットの詳細を取得します
2. LLM に Markdown 形式を使用してパーソナライズされた返信を作成させます
3. freescout_create_draft_reply を使用して下書きを FreeScout に保存します (Markdown は自動的に HTML に変換されます)
4. 送信前に FreeScout で下書きを確認して編集します

例: パーソナライズされた顧客対応を含む下書き返信のワークフロー

freescout_get_ticket_context

パーソナライズされた返信の作成に役立つチケットコンテキストと顧客情報を取得します。

パラメータ:

• ticket (必須): チケット ID、番号、または FreeScout URL

自然言語の例:

• 「返信を書くためにチケット #12345 のコンテキストを取得して」
• 「返信を下書きするために顧客情報とチケットの詳細が必要です」
• 「パーソナライズされた返信を書けるようにこのチケットのコンテキストを収集して」
• 「チケット 34811 の顧客情報と問題の詳細を取得して」
• 「顧客への返信の作成に役立つチケットコンテキストを取得して」

戻り値:

• 顧客の名前とメールアドレス
• チケットの件名とステータス
• 問題の説明と分析
• 最近の顧客およびチームのメッセージ
• 分析結果 (バグか機能かサードパーティの問題か)

freescout_search_tickets

FreeScout インスタンス全体でチケットを検索します。

パラメータ:

• query (必須): 検索クエリ
• status (任意): ステータスで絞り込み ('active'、'pending'、'closed'、'spam'、'all')
• mailboxId (任意): 特定のメールボックス ID で絞り込み (指定しない場合はすべてのメールボックスを検索)

自然言語の例:

• 「'OAuth error' を含むチケットを検索して」
• 「'HighLevel' を含む保留中のチケットをすべて見つけて」
• 「'plugin conflicts' に関するクローズ済みチケットを検索して」
• 「顧客 '[email protected]' からのチケットを探して」
• 「'authentication' に関連するアクティブなチケットをすべて見つけて」
• 「'bug report' を含むメールボックス 1 のチケットを検索して」
• 「ステータスが保留中のメールボックス 2 のチケットを見つけて」

検索パラメータ (v2.0+):

• textSearch (任意): チケットの内容/件名に対するプレーンテキスト検索
• assignee (任意): 'unassigned' | 'any' | user_id (数値)
• status (任意): 'active' | 'pending' | 'closed' | 'spam' | 'all'
• state (任意): 'published' | 'deleted'
• mailboxId (任意): 特定のメールボックス ID で絞り込み
• updatedSince (任意): ISO 日付、または「7d」「24h」「30m」のような相対時間
• createdSince (任意): ISO 日付、または相対時間
• page (任意): ページネーションのページ番号 (最小: 1)
• pageSize (任意): 1 ページあたりの結果数 (最小: 1、最大: 100)

AI エージェント向けの検索のヒント:

• 未割り当てのチケットの場合: assignee: "unassigned" を status: "active" とともに使用します
• 最近のチケットの場合: 過去 7 日間なら updatedSince: "7d" を使用します
• 特定のユーザーの場合: assignee: 123 (ユーザー ID 番号) を使用します
• ステータス "active" = オープン/アクティブなチケット (「open」は無効なので注意)
• メールボックスで絞り込む場合は、まず freescout_get_mailboxes を使用します
• フィルターを組み合わせる: { textSearch: "error", assignee: "unassigned", updatedSince: "24h" }

freescout_get_mailboxes

FreeScout インスタンスで利用可能なすべてのメールボックスの一覧を取得します。

パラメータ: なし

自然言語の例:

• 「利用可能なメールボックスをすべて表示して」
• 「FreeScout のメールボックスを一覧表示して」
• 「どのメールボックスが設定されている?」
• 「メールボックス情報を取得して」

ワークフローの例

基本的なチケット分析

// Analyze a ticket to understand the issue
await mcp.callTool('freescout_analyze_ticket', {
  ticket: '12345',
});

完全なチケット対応ワークフロー

// 1. Analyze the ticket to understand the issue
const analysis = await mcp.callTool('freescout_analyze_ticket', {
  ticket: '12345',
});

// 2. Get ticket context for personalized reply
const context = await mcp.callTool('freescout_get_ticket_context', {
  ticket: '12345',
});

// 3. Create a draft reply directly in FreeScout
await mcp.callTool('freescout_create_draft_reply', {
  ticket: '12345',
  replyText: `Hi ${context.customer.name},

Thank you for reaching out! Based on my analysis, I can see that ${analysis.issueDescription}.

Here's what I found:

1. **Issue Type**: ${analysis.isBug ? 'Bug' : 'Configuration/Feature Request'}
2. **Root Cause**: ${analysis.rootCause || 'Under investigation'}

I'll look into this and get back to you shortly with a solution.

Best regards,
[Your name]`,
  cc: ['[email protected]'],
});

// 4. Update ticket status and assignment
await mcp.callTool('freescout_update_ticket', {
  ticket: '12345',
  status: 'active',
  assignTo: 1,
});

// 5. Add an internal note with findings
await mcp.callTool('freescout_add_note', {
  ticket: '12345',
  note: `Analysis complete:
- Is Bug: ${analysis.isBug}
- Third-party Issue: ${analysis.isThirdPartyIssue}
- Root Cause: ${analysis.rootCause}`,
});

返信ドラフト作成ワークフロー

// 1. Get ticket context for personalized reply
const context = await mcp.callTool('freescout_get_ticket_context', {
  ticket: '34811',
});

// 2. Create draft reply in FreeScout (LLM crafts the content)
await mcp.callTool('freescout_create_draft_reply', {
  ticket: '34811',
  replyText: `Hi ${context.customer.name},

Thank you for reporting the HighLevel OAuth authorization issue! Your experience with the EngageBay LiveChat plugin conflict has been really valuable.

Based on what we learned from your case, I've added a new plugin conflict detection system to WP Fusion. In the next update (v3.46.7), users will see:

🔍 **Plugin Conflict Detection**
- Automatic detection of known conflicting plugins  
- Warning messages before HighLevel authorization
- Clear guidance when conflicts are detected

This should prevent the confusion you experienced and help other users avoid similar issues.

The update should be available within the next few weeks. Thanks for your patience and for helping us improve the plugin!

Best regards,
Jack`,
  to: ['[email protected]'],
  cc: ['[email protected]'],
});

// The draft is now saved in FreeScout and can be reviewed/edited before sending

バグ以外の問題の処理

// For third-party issues or feature requests
const reply = await mcp.callTool('freescout_create_draft_reply', {
  ticket: '12345',
  replyText: 'This is a limitation of the Elementor plugin that we cannot override.',
});

アーキテクチャ

コンポーネント

1. FreeScout API クライアント (freescout-api.ts)

   • FreeScout とのすべての API 通信を処理します
   • 認証とリクエストのフォーマットを管理します
   • チケット解析ユーティリティを提供します

2. チケットアナライザー (ticket-analyzer.ts)

   • インテリジェントなチケット内容の分析
   • 問題の分類 (バグ vs 機能 vs 設定)
   • コードスニペットとエラーの抽出
   • 根本原因の特定

3. MCP サーバー (index.ts)

   • ツールの登録とリクエスト処理
   • stdio 接続ごとの新しいサーバーファクトリ
   • レスポンスのフォーマットとエラー処理

データフロー

MCP client (2025 or 2026) → stdio entry → buildServer → FreeScout API
                                                   ↓
                                            Ticket analysis
                                                   ↓
                                            Response to client

開発

開発モードでの実行

npm run dev

テストの実行

npm test

リンティング

npm run lint

本番用ビルド

npm run build

設定

必須の環境変数

変数	説明	例
FREESCOUT_URL	FreeScout インスタンスの URL	https://support.example.com
FREESCOUT_API_KEY	FreeScout API キー	your-api-key-here

任意の環境変数

変数	説明	デフォルト
FREESCOUT_DEFAULT_USER_ID	割り当てのデフォルトユーザー ID	1

高度な設定例

より細かく制御するには、追加の環境変数を指定できます:

{
  "mcpServers": {
    "freescout": {
      "command": "npx",
      "args": ["@verygoodplugins/mcp-freescout@latest"],
      "env": {
        "FREESCOUT_URL": "https://support.example.com",
        "FREESCOUT_API_KEY": "your-api-key",
        "FREESCOUT_DEFAULT_USER_ID": "2"
      }
    }
  }
}

FreeScout API のセットアップ

1. 管理者として FreeScout インスタンスにログインします
2. 管理 → API キー に移動します
3. 適切な権限を持つ新しい API キーを作成します:
   • 会話の閲覧
   • 会話の更新
   • スレッドの作成（メモ用）

ベストプラクティス

チケット分析

• 修正を実装する前に、必ずチケットを分析してください
• 修正を試みる前に、サードパーティの制限を確認してください
• チームのメモで再現性を検証してください

顧客とのコミュニケーション

• レビュー用に返信の下書きを生成します
• 顧客とのやり取りに修正内容の説明を含めます
• バグ以外の事項には説明的な返信を使用します

v1.x から v2.0 への移行

破壊的変更

freescout_search_tickets ツールは、明示的なフィルターパラメータを備えた形に再設計されました。従来のクエリ文字列構文はサポートされなくなりました。

変更前 (v1.x):

{
  "query": "assignee:null",
  "status": "active"
}

変更後 (v2.0):

{
  "assignee": "unassigned",
  "status": "active"
}

テキスト検索の場合:

{
  "textSearch": "authentication error",
  "assignee": "unassigned",
  "updatedSince": "7d"
}

採用すべき新機能

1. 相対時間フィルター: ISO 日付を計算する代わりに、"7d"、"24h"、"30m" を使用します
2. ページネーション: 大量の結果セットには page および pageSize パラメータを追加します
3. 構造化出力: 安定した分析結果と書き込み結果には structuredContent が含まれます。ツールは出力スキーマを宣言しません

自動リトライ

サーバーは、失敗したリクエストを指数バックオフで自動的にリトライするようになりました。設定は不要です — より確実に動作するだけです。

トラブルシューティング

よくある問題

API 接続エラー

• FreeScout の URL にプロトコル (https://) が含まれていることを確認してください
• FreeScout で API キーの権限を確認してください
• FreeScout インスタンスで API アクセスが有効になっていることを確認してください
• v2.0 の新機能: サーバーは一時的な接続エラーを自動的にリトライします

チケット解析の問題

• サーバーはチケット ID、番号、および完全な URL を受け付けます
• URL は自動的に解析され、チケット ID が抽出されます
• 数値入力はチケット ID として扱われます

レート制限 (429 エラー)

• v2.0 の新機能: サーバーはレート制限を自動的に検出し、バックオフします
• リトライロジックにはジッター付きの指数バックオフが含まれます
• 手動での介入は不要です

コントリビューション

コントリビューションを歓迎します！ 以下をお願いします:

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. テストを伴う変更を行います
4. プルリクエストを送信します

ライセンス

GPL-3.0 ライセンス - 詳細は LICENSE ファイルを参照してください

サポート

問題、質問、または提案については:

• GitHub で issue を作成する
• Very Good Plugins に問い合わせる
• ドキュメントを確認してください

---

Built with 🧡 by Very Good Plugins

ロードマップ

• チケットのバッチ操作
• リアルタイム更新のための Webhook サポート
• よくある返信のためのテンプレートシステム
• CI/CD パイプラインとの統合
• 高度な検索フィルター
• チケットのメトリクスと分析
• 顧客返信の多言語サポート
• 添付ファイルの処理
• カスタムフィールドのサポート
• 自動テスト統合