SegmentMCP-基于人工智能的客户细分服务器

🎯 概述

SegmentMCP是一个智能模型上下文协议（MCP）服务器，它将自然语言查询转换为可操作的客户细分。它弥合了用简单英语思考的业务利益相关者与需要结构化SQL查询的技术系统之间的差距，实现了对客户数据见解的民主化访问。

🚀 问题陈述

挑战

由于几个关键障碍，现代企业在客户细分方面举步维艰：

技术复杂性：营销团队需要SQL知识来创建客户细分
洞察时间：手动查询编写和验证需要数小时或数天
易出错流程：手写的SQL查询通常包含语法错误或逻辑错误
可访问性有限：只有技术用户可以创建和修改客户细分
结果不一致：不同的团队成员为类似的业务需求创建不同的查询

解决方案

SegmentMCP通过提供以下功能消除了这些障碍：

自然语言接口：“寻找30岁以上有住房贷款的已婚客户”
自动生成SQL：人工智能驱动的查询创建和优化
内置验证：自动查询测试和错误检测
处理透明度：所有处理步骤的完整分解
集成就绪架构：连接下游系统的框架

🏗️ 建筑

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │───▶│   MCP Server     │───▶│  Kaggle Dataset │
│ (Claude/Custom) │    │  (FastMCP)       │    │ (45K+ records)  │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │   Agent Pipeline │
                       │                  │
                       │ 1. Intent Parser │ ← GPT-4.1
                       │ 2. Data Mapper   │ ← Rule-based
                       │ 3. Query Gen     │ ← GPT-4.1  
                       │ 4. Validator     │ ← Rule-based
                       │ 5. Activator     │ ← Simulation
                       └──────────────────┘

基于代理的处理管道

意图分析代理 -使用GPT-4.1将自然语言转换为结构化条件
数据映射器代理 -将业务术语映射到数据库模式字段
查询生成器代理 -在AI的帮助下创建优化的SQL查询
验证代理 -测试查询的语法、性能和安全性
活化剂 -执行细分并与下游系统集成

📁 项目结构

SegmentMCP/
├── agents/                    # AI processing agents
│   ├── intent_parser.py      # Natural language → criteria
│   ├── data_mapper.py        # Business terms → DB fields  
│   ├── query_generator.py    # Criteria → SQL
│   ├── validation_agent.py   # SQL validation & testing
│   └── activation_agent.py   # Segment execution
├── database/
│   └── kaggle_connector.py   # Dataset management
├── models/
│   └── schemas.py            # Pydantic data models
├── data/                     # Dataset storage
│   ├── bank-full.csv        # Bank customer dataset
│   └── bank_deposit.db      # SQLite database
├── main.py                   # Core MCP server
├── demo_server.py           # Demo mode (no OpenAI)
├── http_server.py           # Direct HTTP API
├── http_wrapper.py          # MCP protocol wrapper
├── demo_http_wrapper.py     # Demo HTTP wrapper
├── config.py                # Configuration management
├── generate_claude_config.py # Claude Desktop setup
├── validate_schemas.py      # Schema validation
├── validate_config_usage.py # Config usage checker
├── test_config_integration.py # Config testing
└── requirements.txt         # Dependencies

📊 数据集信息

银行客户数据集

来源：Kaggle“银行定期存款订阅”数据集
记录：45211名银行客户
列：17个属性，包括人口统计、财务和活动数据
格式：CSV，带分号分隔符
存储：自动转换为SQLite进行查询

关键数据字段

人口统计：年龄、工作、婚姻状况、教育程度
金融的：余额、住房贷款、个人贷款、违约状态
活动：联系方式、持续时间、活动编号、以前的联系人
目标：定期存款认购（是/否）

数据处理

自动CSV检测和加载
SQLite转换以实现高效查询
模式自省和验证
用于测试的样本数据生成

当前数据源支持

主要的，重要的：单个Kaggle数据集连接器
建筑：可扩展的连接器模式已准备好用于其他源
存储：具有CSV导入的本地SQLite数据库
未来：框架支持PostgreSQL、MySQL、BigQuery连接器

✨ 特性

🧠 智能查询处理

自然语言理解：使用GPT-4.1解析复杂的业务需求
上下文感知映射：自动将业务术语映射到数据库字段
查询优化：使用自动LIMIT子句和优化生成高效的SQL
错误预防：内置验证可防止危险操作（DELETE、UPDATE、DROP）

🔒 安全与验证

操作限制：阻止DELETE、UPDATE、DROP操作
性能限制：自动LIMIT子句和行数警告
语法验证：执行前查询测试
输入验证：查询结构和内容验证
只读访问：数据库操作仅限于SELECT语句

🔌 集成就绪

MCP协议：原生支持AI助手集成
REST API：web应用程序的HTTP端点
可扩展架构：框架已为多个数据源做好准备
模拟下游激活：返回CRM、电子邮件、分析系统的集成目标

*注意：当前版本模拟下游集成。真正的API连接需要进一步开发。*

📊 综合结果

示例数据预览：激活前查看实际客户记录
处理透明度：使用时间戳完整分解所有代理处理步骤
性能指标：处理时间跟踪、查询执行时间和行数估计
信心评分：基本置信度报告和模糊术语检测
验证结果：带有警告和错误检测的详细验证报告
架构信息：包含示例值和数据类型的完整数据库架构

🛠️ 实施用例

1.营销活动管理

{
  "query": "High-value customers who haven't been contacted in 6 months",
  "use_case": "Re-engagement campaign targeting",
  "output": "Segment for email marketing platform"
}

2.风险评估

{
  "query": "Customers with loans but negative balance trends",
  "use_case": "Credit risk monitoring",
  "output": "Alert list for risk management team"
}

3.产品推荐

{
  "query": "Young professionals without housing loans",
  "use_case": "Mortgage product targeting",
  "output": "Prospect list for sales team"
}

4.客户成功

{
  "query": "Long-term customers with declining engagement",
  "use_case": "Churn prevention",
  "output": "Priority list for customer success managers"
}

5.合规报告

{
  "query": "All customers contacted more than regulatory limit",
  "use_case": "Compliance monitoring",
  "output": "Audit report for regulatory team"
}

📈 产出利用率

集成架构（框架就绪）

该系统为与下游系统集成提供了基础：

当前实施情况

模拟激活：返回分段的目标系统列表（仅限模拟）
处理结果：完整的客户数据和SQL查询以供导出
分段存储：具有唯一ID的内存段管理
API结构：为webhook和API集成准备好的框架

集成框架（尚未实施）

CRM系统：架构支持Salesforce、HubSpot、Pipedrive集成
电子邮件平台：框架已准备好用于Mailchimp、SendGrid连接
广告平台：为脸书、谷歌、领英API准备的结构
分析工具：设计支持Tableau、Power BI数据导出

*注：当前版本提供了框架和模拟响应。真正的API集成需要额外的开发工作。*

业务流程集成

营销工作流程

Natural Language Query → Segment Creation → Campaign Launch → Performance Tracking

销售流程

Lead Qualification → Segment Assignment → Automated Outreach → Conversion Tracking

客户成功

Health Score Monitoring → Risk Segment Identification → Intervention Campaigns → Retention Metrics

🚀 入门指南

先决条件

Python 3.8+
OpenAI API密钥
Kaggle API凭证（可选，用于数据集访问）

安装

克隆存储库

git clone https://github.com/tejasayya/SegmentMCP.git
cd SegmentMCP

安装依赖项

pip install -r requirements.txt

配置环境

# Create .env file
OPENAI_API_KEY=your_openai_api_key_here
KAGGLE_USERNAME=your_kaggle_username
KAGGLE_KEY=your_kaggle_key

生成便携式Claude桌面配置

python generate_claude_config.py

这创造了 claude_mcp_config_generated.json 为您的系统提供正确的路径。

这有什么作用：

生成跨平台Claude Desktop配置
自动检测项目路径和数据目录
验证配置并报告问题
创建适用于任何系统的可移植配置

验证模式和配置（可选）

python validate_schemas.py          # Validate data schemas
python validate_config_usage.py     # Check config usage
python test_config_integration.py   # Test config integration

这些验证模式、检查配置使用情况和测试集成。

🧪 验证和测试工具

该项目包括全面的验证和测试基础设施：

架构验证

python validate_schemas.py

验证所有Pydantic模式
测试错误情况和边缘条件
生成架构文档
确保数据模型的一致性

配置验证

python validate_config_usage.py

检查所有配置值是否实际使用
标识未使用的配置
验证配置值范围
测试环境变量覆盖

集成测试

python test_config_integration.py

测试代理配置加载
验证跨组件的配置集成
检查环境变量支持
测试配置验证逻辑

直接测试

python test_demo_direct.py      # Test demo server directly
python test_http_requests.py    # Test HTTP endpoints
python test_mcp_client.py       # Test MCP protocol

选择您的服务器模式

OpenAI版本说明：如果您遇到OpenAI兼容性问题，可能需要升级：

pip install openai>=2.0.0  # Upgrade from 1.35.15 if needed

🎯 服务器选项

选项1：完整MCP服务器（生产）

python main.py

✅ 完整的人工智能驱动的自然语言处理
✅ 需要OpenAI API密钥
✅ 用于Claude Desktop集成
✅ 带有GPT的完整代理管道

选项2：演示模式（不需要OpenAI）

python demo_server.py

✅ 基于规则的查询解析（无人工智能）
✅ 在没有OpenAI API密钥的情况下工作
✅ 有利于测试和开发
❌ 仅限于预定义的模式

选项3:HTTP测试接口

对于Postman/HTTP API测试，请选择一种方法：

A）直接HTTP服务器（建议用于开发）

python http_server.py
# Server runs on http://localhost:8001

优点：快速、可靠、易于调试、直接方法调用
缺点：绕过MCP协议验证
用于：日常开发、Postman测试、快速迭代

B） MCP协议包装器（协议验证）

python http_wrapper.py
# Server runs on http://localhost:8001

优点：测试实际的MCP实现，符合协议，验证MCP服务器
缺点：更复杂，子流程开销更大，调试更困难
用于：验证MCP服务器是否正常工作，协议测试

C）演示HTTP包装器（无OpenAI）

python demo_http_wrapper.py
# Server runs on http://localhost:8002

优点：无需OpenAI API即可工作，适用于基本测试，无需API成本
缺点：仅限于基于规则的解析，没有人工智能功能
用于：在没有API成本、基本功能验证的情况下进行测试

🤔 您应该使用哪台服务器？

用例	推荐服务器	为什么
Claude桌面集成	`main.py`	带AI的完整MCP协议
开发/测试	`http_server.py`	使用Postman进行快速HTTP测试
MCP协议验证	`http_wrapper.py`	确保MCP服务器正常工作
无OpenAI API密钥	`demo_server.py` 或 `demo_http_wrapper.py`	无API成本的工程
生产部署	`main.py`	完整的功能集

测试API

curl -X POST "http://localhost:8001/create-segment" \
     -H "Content-Type: application/json" \
     -d '{"query": "Married customers with age over 30"}'

MCP集成

对于AI助手集成，请运行MCP服务器：

python main.py

🔧 体系结构决策

为什么有多个服务器文件？

此项目提供了多种运行服务器的方法，以满足不同的开发和部署需求：

核心MCP服务器(`main.py`)

目的：Claude Desktop的生产MCP服务器
特性：与OpenAI集成的完整AI管道
协议：通过stdio的纯MCP

演示版本(`demo_server.py`)

目的：无API成本的开发
特性：基于规则的解析，无OpenAI依赖
为什么：允许在没有API密钥的情况下测试核心功能

HTTP接口-两种方法

直接集成(http_server.py)

方法：直接进口和使用 SegmentationMCPServer 类
推理：开发更快，调试更容易，测试可靠
权衡：绕过MCP协议，但更适合HTTP API需求

协议包装器(http_wrapper.py)

方法：将MCP服务器作为子进程启动，通过JSON-RPC进行通信
推理：测试实际的MCP实施，验证协议合规性
权衡：更复杂，但可确保MCP服务器实际工作

为什么两种HTTP方法？

发展速度: http_server.py 用于快速迭代和Postman测试
协议验证: http_wrapper.py 确保MCP服务器正常工作
不同的需求：直接呼叫与协议测试的目的不同

OpenAI版本兼容性

问题：该项目最初使用 openai>=1.30.0,=2.0.0 如果遇到初始化错误：

pip install openai>=2.0.0

为什么：较新的OpenAI版本具有不同的客户端初始化模式和更好的稳定性。

📡 API 参考

创建细分市场

发布 /create-segment

根据自然语言描述创建客户细分。

请求正文：

{
  "query": "Description of desired customer segment in plain English"
}

答复：

{
  "status": "success",
  "segment_id": "SEG_ABCD1234",
  "customer_count": 1500,
  "downstream_systems": ["CRM_System", "Email_Marketing_Platform", "Ad_Platform"],
  "generated_query": "SELECT * FROM bank_customers WHERE marital = 'married' AND age > 30 LIMIT 1000",
  "validation_sample": [
    {"age": 35, "job": "management", "marital": "married", "balance": 2143, "housing": "yes"},
    {"age": 42, "job": "technician", "marital": "married", "balance": 1506, "housing": "no"}
  ],
  "estimated_rows": 1500,
  "processing_steps": {
    "intent_parsing": {
      "parsed_criteria": {
        "conditions": [{"field": "marital", "operator": "=", "value": "married"}, {"field": "age", "operator": ">", "value": 30}],
        "logical_operators": ["AND"]
      },
      "confidence": 0.9,
      "ambiguous_terms": [],
      "parsing_notes": ["Successfully parsed natural language query"],
      "timestamp": "2024-01-15T10:30:01Z",
      "processing_time_ms": 1250
    },
    "data_mapping": {
      "business_terms": {"age": "age", "marital": "marital"},
      "table_mappings": {"customers": "bank_customers"},
      "field_mappings": {"marital": "marital", "age": "age"},
      "timestamp": "2024-01-15T10:30:02Z",
      "processing_time_ms": 150
    },
    "query_generation": {
      "sql_query": "SELECT * FROM bank_customers WHERE marital = 'married' AND age > 30 LIMIT 1000",
      "optimized": true,
      "estimated_rows": 1500,
      "tables_used": ["bank_customers"],
      "optimization_notes": ["Added LIMIT clause for safety"],
      "timestamp": "2024-01-15T10:30:03Z",
      "processing_time_ms": 800
    },
    "validation": {
      "is_valid": true,
      "issues": [],
      "warnings": ["Query returns large number of rows: 1500"],
      "sample_data": [
        {"age": 35, "job": "management", "marital": "married", "balance": 2143},
        {"age": 42, "job": "technician", "marital": "married", "balance": 1506}
      ],
      "row_count": 1500,
      "timestamp": "2024-01-15T10:30:04Z",
      "processing_time_ms": 200
    }
  }
}

获取细分市场信息

获取 /segment/{segment_id}

检索有关已创建段的信息。

获取数据库架构

获取 /schema

获取当前数据库架构信息。

健康检查

获取 /health

服务器健康状态终结点。

⚙️ 高级配置

环境变量

所有配置值都支持环境变量重写：

# Model Configuration
export OPENAI_MODEL="gpt-4.1"
export OPENAI_TEMPERATURE="0.1" 
export OPENAI_MAX_TOKENS="1000"

# Agent-Specific Models
export INTENT_PARSER_MODEL="gpt-4.1"
export QUERY_GENERATOR_MODEL="gpt-4.1"

# Performance Settings
export MAX_QUERY_ROWS="1000"
export DEFAULT_QUERY_LIMIT="1000"
export VALIDATION_SAMPLE_SIZE="5"
export MAX_SAFE_ROWS="100000"
export WARNING_ROW_THRESHOLD="50000"

# Timeouts
export INTENT_PARSER_TIMEOUT="15"
export QUERY_GENERATOR_TIMEOUT="20" 
export VALIDATION_TIMEOUT="10"
export ACTIVATION_TIMEOUT="25"

代理配置

每个代理都会自动加载配置：

意图解析器：型号选择、温度、超时设置
查询生成器：模型、优化规则、查询限制、安全设置
验证器：性能阈值、样本大小、行数限制
激活剂：超时设置、下游系统配置

基本环境变量

OPENAI_API_KEY：AI驱动的查询生成所需
OPENAI_MODEL：要使用的模型（默认值：gpt-4.1）
KAGGLE_USERNAME：用于数据集访问
KAGGLE_KEY：Kaggle API密钥
DATABASE_PATH：本地数据库文件的路径
MAX_QUERY_ROWS：每个查询的最大行数（默认值：1000）

🔍 查询示例

基本细分

"Customers over 25 years old"
"Married customers with housing loans"
"High balance customers without personal loans"

高级标准

"Customers contacted more than 3 times but never converted"
"Young professionals with tertiary education and no defaults"
"Retired customers with high balances who were contacted in May"

商业专用条款

"High-value prospects for mortgage products"
"At-risk customers for retention campaigns"
"Premium customers for exclusive offers"

🛡️ 安全考虑

数据保护

日志中未存储敏感数据
只读数据库访问（仅限SELECT操作）
查询验证可防止危险操作
本地数据处理（无外部数据传输）

访问控制

人工智能功能所需的OpenAI API密钥
仅限本地文件系统访问
框架已准备好用于身份验证系统

合规

本地数据处理维护隐私
处理审计要求的透明度
框架支持合规功能

⚠️ 当前限制

什么是模拟（非真实）

下游一体化：返回系统名称，但实际上并未连接到CRM/电子邮件平台
多数据库：仅支持单个Kaggle数据集，不支持多个数据源
高级安全：仅进行基本验证，不进行完全参数化查询

什么是真实和有效的

MCP协议：完全实现与Claude Desktop的集成
人工智能处理：用于自然语言处理的真正GPT-4.1集成
SQL生成：实际查询创建和验证
HTTP API：用于测试和集成的工作REST端点
全面验证：广泛的测试和验证基础设施

🆘 支持

内置验证工具

python validate_schemas.py -全面的模式验证
python validate_config_usage.py -配置使用分析
python test_config_integration.py -集成测试
python generate_claude_config.py -安装协助

社区

-Bug报告和功能请求

______________________________________________________________________

Segment MCP

快速接入

详细介绍