Customer MCP Server

Customer MCP Server 是一个用于将 LLM 与客户数据连接的项目，使用 Model Context Protocol (MCP) 使 AI 客户端能够安全地、在明确控制框架下访问客户数据。

系统概述

本系统旨在让 LLM 只能通过预定义的工具询问客户信息，而无需直接访问数据库。

支持的功能

• 获取客户基本信息

• 使用向量嵌入对客户沟通历史进行语义搜索

• 以精确值汇总购买数据和金融交易

• 记录交易审计日志

• 防止提示注入和未经授权的数据访问

Related MCP server: safedb-mcp

架构

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. 交互语义搜索

• 使用嵌入向量搜索客户的对话/交互历史

• 适用于对宽泛问题的语义搜索，例如退款问题、投诉、账单疑虑

3. 财务摘要

• 从数据库计算订单数量和总购买金额

• 使用 SQL 聚合以确保准确可靠的值

• 返回带哈希引用的交易审计日志

混合查询示例

示例问题：

"客户曾经报告过什么问题，总购买金额是多少？"

流程：

search_customer_interactions()

    |
    v

pgvector 相似度搜索

    +

get_customer_purchase_summary()

    |
    v

SQL 聚合

    |
    v

组合验证响应

处理步骤：

1. MCP 服务器调用语义搜索 从 interaction_history 使用 pgvector

2. MCP 服务器获取财务摘要 从 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 脚本自动初始化数据库。

注意： docker-entrypoint-initdb.d 中的 SQL 脚本仅在首次创建 PostgreSQL volume 时执行。

如果需要完全重新初始化：

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

还可以通过 UI 检查 MCP 工具。

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 聚合获取精确的购买金额数据

示例输入：

{
  "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 聚合以返回精确值

• 审计日志是不可变的仅追加结构

• MCP 使用的数据库用户采用最小权限

• 不允许 UPDATE / DELETE / DDL 操作