Keap MCPサーバー

Keap CRMデータとやり取りするための高性能なModel Context Protocol (MCP) サーバーです。HTTP/2サポート、包括的な診断機能、一括操作などの高度な機能を備えています。

機能

コアとなる連絡先とタグの管理

• 包括的な連絡先管理 - 連絡先のリスト表示、検索、フィルタリング、詳細情報の取得

• 高度なタグ操作 - 作成、クエリ、バッチ操作を含む完全なタグライフサイクル管理

• タグのバッチ操作 - 複数の連絡先に対して効率的にタグを適用または削除

• カスタムフィールド操作 - カスタムフィールド値による連絡先の検索と、カスタムフィールドの一括更新

• 複雑な論理フィルタリング - ネストされた条件を持つAND、OR、NOT演算子のサポート

パフォーマンスと最適化

• HTTP/2サポート - コネクションプーリングによる接続パフォーマンスの向上

• インテリジェントなレート制限 - 適応型バックオフ戦略を備えた1日のリクエスト制限

• クエリ最適化 - パフォーマンス分析を伴う、サーバーサイドとクライアントサイドのインテリジェントなフィルタリング

• パフォーマンス監視 - リアルタイムのクエリ分析と最適化の提案

• 永続キャッシュ - API呼び出しを減らしパフォーマンスを向上させるSQLiteベースのキャッシュ

高度な機能

• 包括的な診断 - APIパフォーマンスメトリクス、システム監視、ヘルスチェック

• 強化されたエラー処理 - さまざまなエラータイプに対する指数バックオフを備えた堅牢なリトライロジック

• カスタムフィールドの一括更新 - 複数の連絡先にわたってカスタムフィールド値を効率的に設定

• 高度なフィルタ演算子 - BETWEEN、IN、SINCE、STARTS_WITHなど15種類以上の演算子

• IDリスト操作 - 連絡先およびタグIDセットを扱うためのユーティリティ関数

Related MCP server: claude-cli-mcp

アーキテクチャ

Keap MCPサーバーは、効率化された高性能なアーキテクチャを採用しています：

• APIクライアント (src/api/client.py) - HTTP/2、レート制限、診断機能を備えた強化されたKeap API通信

• MCPツール (src/mcp/) - 最適化された包括的なMCPプロトコル実装

• キャッシュマネージャー (src/cache/) - インテリジェントな無効化機能を備えたSQLiteベースの永続キャッシュ

• 最適化エンジン (src/mcp/optimization/) - クエリ最適化とパフォーマンス分析

• スキーマ (src/schemas/) - データ検証とモデル

• ユーティリティ (src/utils/) - 連絡先処理とフィルタリングのための共有ユーティリティ

MCPツール

このサーバーは17種類の包括的なMCPツールを公開しています：

連絡先操作

1. list_contacts - フィルタリングとページネーションによる連絡先リスト表示（最適化済み）

2. search_contacts_by_email - メールアドレスによる連絡先検索

3. search_contacts_by_name - 名前による連絡先検索

4. get_contact_details - 特定の連絡先の詳細情報取得

5. query_contacts_by_custom_field - カスタムフィールド値による連絡先クエリ

タグ操作

6. get_tags - オプションのフィルタリングによるタグ取得

7. get_tag_details - 特定のタグの詳細情報取得

8. get_contacts_with_tag - 特定のタグを持つ連絡先の取得

9. create_tag - 新しいタグの作成

タグ管理（バッチ操作）

10. modify_tags - 連絡先へのタグ追加または削除

11. apply_tags_to_contacts - バッチ操作を使用した、複数の連絡先への複数タグ適用

12. remove_tags_from_contacts - 複数の連絡先からの複数タグ削除

カスタムフィールド管理

13. set_custom_field_values - 複数の連絡先にわたるカスタムフィールド値の一括更新

高度なクエリとパフォーマンス操作

14. query_contacts_optimized - 最適化とパフォーマンス分析を備えた高度な連絡先クエリ

15. analyze_query_performance - クエリパフォーマンスと最適化の可能性の分析

システム操作

16. get_api_diagnostics - 包括的なAPI診断とパフォーマンスメトリクス

ユーティリティ操作

17. intersect_id_lists - 複数のIDリストの積集合の検索

はじめに

前提条件

• Python 3.9以上

• Keap API認証情報

インストール

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

   git clone https://github.com/yourusername/keapmcp.git
   cd keapmcp

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

   pip install -r requirements.txt

3. Keap API認証情報を設定します：

   • アプリケーションは設定に .env ファイルを使用します

   • APIキーはkeapsyncからコピーされていますが、必要に応じて変更可能です

   • 設定には以下が含まれます：

     KEAP_API_KEY=your_api_key_here
     KEAP_API_BASE_URL=https://api.infusionsoft.com/crm/rest/v1
     KEAP_MCP_HOST=127.0.0.1
     KEAP_MCP_PORT=5000
     KEAP_MCP_LOG_LEVEL=INFO
     KEAP_MCP_LOG_FILE=keap_mcp_server.log
     KEAP_MCP_CACHE_ENABLED=true
     KEAP_MCP_CACHE_TTL=3600

サーバーの実行

python run.py --host 127.0.0.1 --port 5000

コマンドラインオプション：

• --host - バインドするホスト（デフォルト: 127.0.0.1）

• --port - リッスンするポート（デフォルト: 5000）

• --log-level - ログレベル（デフォルト: INFO）

• --log-file - ログファイルパス（デフォルト: keap_mcp_server.log）

• --no-console-log - コンソールログを無効化

テストとカバレッジ

Keap MCPサーバーには、信頼性と正しい動作を保証するための包括的なテストスイートが含まれており、CI/CDパイプラインに完全に統合されています。

クイックテスト

Makefileを使用して簡単にテストを実行できます：

# Run all unit tests
make test

# Run tests with coverage reporting  
make coverage

# Generate HTML coverage report
make coverage-html

# Run service-specific tests
make test-services
make test-models

# Full development workflow
make dev-test

CI/CD統合

プロジェクトには自動テストとカバレッジレポートが含まれています：

• 継続的インテグレーション: Python 3.9、3.10、3.11でテストを実行

• カバレッジ追跡: 60%以上のカバレッジを強制

• コミット前チェック: コードフォーマット、リンティング、セキュリティチェック

• カバレッジバッジ: メインブランチで自動更新

テストカテゴリ

• ユニットテスト (tests/unit/) - 包括的なモックを使用した個別のコンポーネントテスト

• 統合テスト (tests/integration/) - エンドツーエンドの機能検証

• パフォーマンステスト (tests/performance/) - 負荷と最適化の検証

• API検証 - Keap APIレスポンス形式の検証

カバレッジ要件

• 現在のカバレッジ: 55%の統合カバレッジ（コンポーネントにより異なる）

• APIクライアント: 包括的なモックを使用したコア機能のテスト済み

• MCPツール: モック依存関係を使用した統合テスト

• キャッシュシステム: 包括的な永続性とパフォーマンスのテスト

• ユーティリティ: 連絡先処理とフィルタリング機能のテスト済み

• 最適化: パフォーマンス分析とクエリ最適化をカバー

特定のテストの実行

# Run all tests
python -m pytest tests/ -v

# With coverage reporting
python -m pytest tests/ --cov=src --cov-fail-under=90

# Integration tests (requires running server)
python -m pytest tests/integration/ -v

MCPサーバーの使用方法

例：連絡先リストの表示（最適化済み）

{
  "function": "list_contacts",
  "params": {
    "filters": [
      { "field": "email", "operator": "contains", "value": "@company.com" }
    ],
    "limit": 50,
    "include": ["id", "given_name", "family_name", "email"]
  }
}

注：list_contactsは現在、パフォーマンス向上のために内部で最適化エンジンを使用しています。詳細なパフォーマンスメトリクスについては、query_contacts_optimizedを直接使用してください。

例：メールアドレスによる検索

{
  "function": "search_contacts_by_email",
  "params": {
    "email": "john.doe@company.com",
    "include": ["id", "given_name", "family_name", "email", "tags"]
  }
}

例：タグの取得

{
  "function": "get_tags",
  "params": {
    "include_categories": true,
    "limit": 100
  }
}

例：タグのバッチ操作

{
  "function": "apply_tags_to_contacts",
  "params": {
    "tag_ids": ["123", "456"],
    "contact_ids": ["1001", "1002", "1003"]
  }
}

例：カスタムフィールドクエリ

{
  "function": "query_contacts_by_custom_field",
  "params": {
    "field_id": "7",
    "field_value": "Engineering",
    "operator": "contains",
    "include": ["id", "given_name", "family_name", "email"]
  }
}

例：新しいタグの作成

{
  "function": "create_tag",
  "params": {
    "name": "VIP Customer",
    "description": "High-value customer segment",
    "category_id": "2"
  }
}

例：カスタムフィールドの一括更新

{
  "function": "set_custom_field_values",
  "params": {
    "field_id": "7",
    "contact_ids": ["1001", "1002", "1003"],
    "common_value": "VIP Customer"
  }
}

または、連絡先ごとに個別の値を指定する場合：

{
  "function": "set_custom_field_values",
  "params": {
    "field_id": "7",
    "contact_values": {
      "1001": "Gold Tier",
      "1002": "Silver Tier", 
      "1003": "Bronze Tier"
    }
  }
}

例：API診断

{
  "function": "get_api_diagnostics",
  "params": {}
}

例：IDリストの積集合

{
  "function": "intersect_id_lists",
  "params": {
    "lists": [
      {"list_id": "active_contacts", "item_ids": ["1", "2", "3", "4"]},
      {"list_id": "newsletter_subscribers", "item_ids": ["2", "3", "5", "6"]}
    ],
    "id_field": "item_ids"
  }
}

パフォーマンス機能

HTTP/2サポート

サーバーは、コネクションプーリングとキープアライブ接続を備えたHTTP/2を使用してパフォーマンスを向上させています。

レート制限

• 1日のリクエスト制限（デフォルトで1日25,000リクエスト）

• インテリジェントなバックオフ戦略

• レート制限の監視と診断

キャッシュ戦略

• SQLiteベースの永続キャッシュ

• インテリジェントなキャッシュ無効化

• TTLベースの有効期限

• キャッシュヒット/ミス追跡

エラー処理

• リトライのための指数バックオフ

• タイムアウト、ネットワーク、HTTPエラーに対する異なる戦略

• 包括的なエラー追跡と診断

ライセンス

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