Frontapp MCP Server

Frontapp MCP サーバー

公式の https://dev.frontapp.com/docs/mcp-server をご利用ください。

LLM（大規模言語モデル）をFrontappの顧客コミュニケーションプラットフォームと連携するためのModel Context Protocol（MCP）サーバーです。

📚 /docsにある完全なドキュメントを見る

概要

このプロジェクトは、LLMとFrontapp APIの間をつなぐMCPサーバーを実装しています。LLMが自然言語コマンドを使ってFrontappのデータ（会話、連絡先、タグなど）にアクセスして操作し、Frontappのワークフローを自動化できるようにします。

このサーバーは、FrontappのWebhookを使用したリアルタイム更新とイベント駆動型の自動化をサポートしています。

機能

• 会話管理：会話の取得、作成、更新、管理
• 連絡先管理：連絡先情報へのアクセスと更新
• タグ管理：会話へのタグの適用と削除
• 受信トレイ管理：受信トレイ情報へのアクセス
• ユーザー管理：ユーザー詳細の取得
• Webhook連携：Frontappからのリアルタイムイベントの受信と処理
• セキュアな認証：Webhook署名の検証とAPI認証の処理
• セキュアな認証情報の保存：AES-256暗号化による機密情報の保存
• HTTPSサポート：TLS/SSL暗号化による安全な通信

アーキテクチャ

MCPサーバーは、モジュール型アーキテクチャを採用しています。

1. APIゲートウェイ：LLMからのリクエストとFrontappからのWebhookを処理します
2. リクエストハンドラー：LLMからのリクエストを処理し、Frontapp APIと連携します
3. Webhookハンドラー：FrontappからのWebhookを処理し、LLMのコンテキストを更新します
4. Frontapp APIクライアント：Frontapp APIと連携するロジックをカプセル化します
5. データモデル：LLM、MCPサーバー、Frontapp間でやり取りするデータの構造を定義します
6. 設定：MCPサーバーの設定を保存します

前提条件

• Node.js（v16以降）
• npmまたはyarn
• Frontapp APIの認証情報
• Webhook用の一般公開URL（本番環境で使用する場合）

インストール

Smithery経由でのインストール

Smitheryを使って、Claude Desktop用のfrontapp-mcpを自動的にインストールするには：

npx -y @smithery/cli install @zqushair/frontapp-mcp --client claude

詳しいインストール手順については、インストールガイドをご覧ください。

クイックスタート：

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

   git clone https://github.com/zqushair/Frontapp-MCP.git
   cd Frontapp-MCP
   

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

   npm install
   

3. .envファイルを作成して設定します：

   cp .env.example .env
   # Edit the .env file with your Frontapp API credentials
   

4. プロジェクトをビルドして起動します：

   npm run build
   npm start
   

ドキュメント

包括的なドキュメントは/docsディレクトリにあります。

• 📖 メインドキュメント - 概要と紹介
• 🔧 インストールガイド - 詳細なセットアップ手順
• 📚 APIリファレンス - 利用可能なツールとエンドポイント
• 🔔 Webhook連携 - リアルタイムイベントの処理
• 🔒 認証情報の保存ガイド - 認証情報の安全な管理
• 🔐 HTTPSセットアップガイド - 安全な通信のセットアップ
• 💻 開発ガイド - プロジェクトへの貢献

使用方法

APIの使用方法

Frontapp MCP連携では、MCPプロトコルを通じてLLMが呼び出せる一連のツールを公開しています。利用可能なツールとそのパラメーターの詳細については、APIリファレンスをご覧ください。

クライアントライブラリ

このプロジェクトには、LLMがMCPサーバーとやり取りするために使用できるTypeScriptクライアントライブラリ（src/frontapp-mcp-client.ts）が含まれています。

import { FrontappMcpClient } from './frontapp-mcp-client.js';

// Create a client instance
const client = new FrontappMcpClient('http://localhost:3000');

// Get a list of conversations
const conversations = await client.getConversations({ status: 'open' });

// Send a message to a conversation
await client.sendMessage('cnv_123', 'Hello, how can I help you today?');

クライアントライブラリには、次の機能があります。

• 利用可能なすべてのツールに対応する型安全なメソッド
• カスタムエラーハンドラーによるエラー処理
• 指数バックオフによる再試行ロジック
• 包括的なTypeScriptインターフェース

クライアントの使用例全体は、src/examples/client-usage-example.tsにあります。

Webhook Integration

この統合では、リアルタイムのイベント通知を受け取るために、Frontapp からの Webhook を受信して処理できます。Webhook 統合の詳細については、Webhook 統合ガイドをご覧ください。

開発

開発の詳細については、開発ガイドをご覧ください。

開発用クイックコマンド

# Start development server with hot reloading
npm run dev

# Run tests
npm run test:api
npm run test:conversations
npm run test:tags
npm run test:contacts
npm run test:webhooks

# Lint and format code
npm run lint
npm run format

# Build for production
npm run build

# Check TypeScript types without compiling
npm run typecheck

Docker によるデプロイ

このプロジェクトには、コンテナ化されたデプロイ用の Dockerfile が含まれています。このマルチステージビルドプロセスにより、最適化された本番環境向けイメージが作成されます。

Docker イメージのビルド

# Build the Docker image
docker build -t frontapp-mcp .

# Run the Docker container
docker run -p 3000:3000 --env-file .env frontapp-mcp

Docker ビルドのトラブルシューティング

Docker のビルドプロセス中に TypeScript エラーが発生した場合、ビルドを成功させるには事前に修正する必要があります。よくある問題は次のとおりです。

1. Webhook ハンドラーの型エラー（開発ガイドのTypeScript の型安全性のセクションをご覧ください）
2. undefined の可能性がある値に対する型アサーションの不足
3. オプショナルプロパティの不適切な処理

こうした問題を早期に発見して修正できるよう、Docker イメージをビルドする前に、必ずローカルで npm run typecheck または npm run build を実行してください。

セキュリティに関する考慮事項

• AES-256 暗号化を使用する認証情報マネージャーで、API 認証情報を安全に保管してください
• 提供されているスクリプト npm run generate-key を使用して、強力な暗号化キーを生成してください
• 組み込みの HTTPS サポートを使用して、すべての通信で HTTPS を有効にしてください
• 開発用の自己署名証明書を生成してください：npm run generate-cert
• 本番環境では、信頼できる認証局の証明書を使用してください
• Webhook の署名を検証して、Frontapp から送信されたことを確認してください
• 不正利用を防ぐために、レート制限を実装してください
• インジェクション攻撃を防ぐために、すべての受信データを検証してください

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については LICENSE ファイルをご覧ください。

貢献

貢献を歓迎します！プロジェクトへの貢献方法については、開発ガイドをご覧ください。

謝辞

• Frontapp API ドキュメント
• Model Context Protocol