Customer MCP Server

Customer MCP Server は、Model Context Protocol (MCP) を用いて LLM と顧客データを接続するプロジェクトです。AI クライアントが安全かつ明確な制御フレームワークに基づいて顧客データにアクセスできるようにします。

システム概要

このシステムは、LLM が定義されたツールを介してのみ顧客情報を照会できるように設計されており、データベースに直接アクセスする必要はありません。

対応機能

• 顧客の基本情報を取得

• ベクトル埋め込みによるセマンティック検索で顧客のコミュニケーション履歴を検索

• 購入情報と金融取引を exact value で要約

• 取引の監査ログ（audit log）を記録

• プロンプトインジェクションと不正アクセスを防止

アーキテクチャ

LLM Client
    |
    | MCP Protocol
    v
MCP Server (Python)
    |
    +-------------------+
    |                   |
    v                   v
Semantic Search      SQL / Financial
PostgreSQL + pgvector PostgreSQL

主な機能

1. 顧客プロフィール

• customer_id、name、email、phone、created_at などの顧客基本情報を取得

2. インタラクションのセマンティック検索

• 埋め込みベクトルを使用して顧客の会話・インタラクション履歴を検索

• refund issue、complaint、billing concern など、幅広い意味の質問に対するセマンティック検索に適しています

3. 財務サマリー

• データベースから注文数と合計購入額を計算

• SQL aggregation を使用して、正確で信頼性の高い値を取得

• ハッシュ参照付きの取引監査ログ（audit log）を返す

ハイブリッドクエリの例

例となる質問:

"顧客はどのような問題を報告したことがあり、合計購入額はいくらですか"

フロー:

search_customer_interactions()

    |
    v

pgvector 類似度検索

    +

get_customer_purchase_summary()

    |
    v

SQL 集計

    |
    v

結合された検証済みレスポンス

処理手順:

1. MCP Server は interaction_history に対して pgvector によるセマンティック検索を実行します

2. MCP Server は purchase_orders に対して SQL 集計による財務サマリーを取得します

3. 結果を結合します:

• 顧客コンテキスト

• 関連インタラクション

• 正確な財務金額

LLM に返送します

4. セキュリティガードレール

• プロンプトインジェクションパターンを検出

• データアクセス前に customer_id を検証

• MCP ツールを介したデータアクセスのみに制限

使用技術

• Python 3.12+

• FastMCP

• asyncpg

• pydantic

• openai

• google-genai

• PostgreSQL 17 + pgvector

• Docker Compose

プロジェクト構造

customer-mcp/
├── app/
│   ├── config.py
│   ├── database.py
│   ├── embeddings.py
│   ├── mcp_server.py
│   ├── security.py
│   └── tools/
│       ├── customer.py
│       ├── financial.py
│       └── semantic_search.py
├── docs/
│   └── ARCHITECTURE.md
├── sql/
│   ├── 01_extensions.sql
│   ├── 02_schema.sql
│   ├── 03_indexes.sql
│   ├── 04_seed.sql
│   └── 05_security.sql
├── docker-compose.yml
├── requirements.txt
├── test_customer.py
├── test_embedding.py
├── test_financial.py
├── test_search.py
├── test_security.py
└── README.md

前提条件

• Python 3.12 以降

• Docker Desktop

• PyPI からパッケージをインストールするためのネットワークアクセス

インストールとセットアップ

1. 仮想環境の作成

py -3.12 -m venv venv

Windows の場合:

venv\Scripts\activate

2. 依存関係のインストール

pip install -r requirements.txt

3. 環境変数の設定

.env ファイルを以下の例に従って作成します。

DATABASE_URL=postgresql://mcp_readonly_user:CHANGE_ME@localhost:5432/customer_mcp

GEMINI_API_KEY=your_gemini_api_key_here

4. PostgreSQL データベースの起動

docker compose up -d

Docker Compose は PostgreSQL + pgvector コンテナを作成し、sql/ フォルダ内の SQL スクリプトからデータベースを自動的に初期化します。

注記: SQL スクリプトは docker-entrypoint-initdb.d 内に配置され、PostgreSQL ボリュームが初めて作成されたときにのみ実行されます。

完全に再初期化する場合:

docker compose down -v

docker compose up -d

初期化の順序

sql/01_extensions.sql PostgreSQL 拡張機能を有効化 pgvector を有効化 sql/02_schema.sql 顧客テーブルを作成 インタラクション履歴テーブルを作成 購入テーブルを作成 不変の監査構造を作成 sql/03_indexes.sql データベースインデックスを作成 セマンティック検索用の pgvector HNSW インデックスを作成 sql/04_seed.sql デモ顧客データを挿入 インタラクション履歴を挿入 購入レコードを挿入 監査レコードを挿入 sql/05_security.sql 読み取り専用データベースユーザーを作成 SELECT 権限を付与

コンテナの確認

docker ps

5. MCP サーバーの実行

python -m app.mcp_server

MCP Inspector

MCP ツールは UI からも確認できます。

mcp-inspector python -m app.mcp_server

利用可能な MCP ツール

get_customer_profile

顧客のプロフィール情報を取得します。

データソース:

• customers テーブル

戻り値:

• customer_id

• first_name

• last_name

• email

• phone

• created_at

入力例:

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000"
}

search_customer_interactions

pgvector を使用してインタラクション履歴をセマンティック検索します。

入力例:

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "query": "refund issue",
  "limit": 3
}

get_customer_purchase_summary

SQL 集計から正確な値（exact value）で購入額サマリーを取得します。

入力例:

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000"
}

利用可能な MCP ツール

テスト

リポジトリのルートから次のテストファイルを実行できます。

python test_embedding.py
python test_search.py
python test_financial.py
python test_security.py
python test_customer.py

セキュリティに関する注意事項

• LLM はデータベースに直接アクセスできません

• データアクセスは MCP ツール経由のみ

• customer_id の入力検証を実施

• プロンプトインジェクションパターンを検出

• 財務データは SQL 集計を使用して正確な値（exact value）を返す

• 監査ログは不変の追記専用構造（immutable append-only structure）です

• MCP 用データベースユーザーは最小権限（least privilege）を適用

• UPDATE / DELETE / DDL 操作は許可されません