Frontapp MCP サーバー

大規模言語モデル (LLM) を Frontapp の顧客コミュニケーションプラットフォームに統合するためのモデルコンテキストプロトコル (MCP) サーバー。

概要

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

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

特徴

会話管理: 会話を取得、作成、更新、管理する
連絡先管理: 連絡先情報にアクセスして更新する
タグ管理: 会話にタグを適用および削除する
受信トレイ管理: 受信トレイ情報にアクセスする
ユーザー管理: ユーザーの詳細を取得する
Webhook統合: Frontappからリアルタイムイベントを受信して処理する
安全な認証:Webhook 署名を検証し、API 認証を処理します
安全な資格情報ストレージ: AES-256暗号化を使用して機密情報を保存します
HTTPSサポート：TLS/SSL暗号化による安全な通信

建築

MCP サーバーはモジュール型アーキテクチャに従います。

API ゲートウェイ: LLM からの受信リクエストと Frontapp からの Webhook を処理します
リクエストハンドラ: LLM からのリクエストを処理し、Frontapp API と対話します。
Webhook ハンドラー: Frontapp からの Webhook を処理し、LLM コンテキストを更新します。
Frontapp APIクライアント: Frontapp APIと対話するためのロジックをカプセル化します
データモデル: LLM、MCPサーバー、Frontapp間で交換されるデータの構造を定義します。
構成: 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

詳細なインストール手順については、『インストールガイド』を参照してください。

クイックスタート:

リポジトリをクローンします。
git clone https://github.com/zqushair/Frontapp-MCP.git cd Frontapp-MCP
依存関係をインストールします:
npm install
.envファイルを作成して構成します。
cp .env.example .env # Edit the .env file with your Frontapp API credentials
プロジェクトをビルドして開始します。
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統合

この統合により、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 エラーが発生した場合、ビルドを成功させる前にエラーを修正する必要があります。よくある問題には次のようなものがあります。

Webhook ハンドラの型エラー (開発ガイドのTypeScript 型安全性セクションを参照)
潜在的に未定義の値に対する型アサーションが欠落している
オプションプロパティの不適切な処理

これらの問題を早期に検出して修正するには、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 MCP Server

Integrations