Frontapp MCP サーバー

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

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

概要

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

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

Related MCP server: OpenAPI MCP Server

特徴

• 会話管理: 会話を取得、作成、更新、管理する

• 連絡先管理: 連絡先情報にアクセスして更新する

• タグ管理: 会話にタグを適用および削除する

• 受信トレイ管理: 受信トレイ情報にアクセスする

• ユーザー管理: ユーザーの詳細を取得する

• 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統合

この統合により、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. 潜在的に未定義の値に対する型アサーションが欠落している

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ドキュメント

• モデルコンテキストプロトコル