ParseQri MCP-CSV智能套件
CSV文件的自然语言数据分析\ 使用由AI代理支持的纯英语处理、查询和可视化CSV数据
   
______________________________________________________________________
🌟 概述
ParseQri MCP是一个综合数据分析平台，它将模型上下文协议（MCP）的强大功能与智能多代理系统相结合，使用自然语言处理和分析CSV数据。该套件由两个主要部分组成：
- CSV_MCP -MCP服务器通过标准化协议公开数据处理工具
- CSV_代理 -用于自然语言到SQL转换的智能代理系统
🎯 主要特点
🚀 自然语言查询
用简单的英语提问，立即获得SQL支持的见解：
- _“按收入显示前10名客户”_
- _“按地区划分的平均贷款金额是多少？”_
- _“查找上个月价值>1000美元的所有订单”_
🔄 无缝CSV处理
- 自动上传：删除CSV文件，它们将被自动处理
- 多用户支持：每个用户的独立数据存储
- 智能元数据提取：AI驱动的模式理解
- 类型推断：自动数据类型检测
🧠 智能AI代理
具有专用代理的模块化架构：
- 意图分类
- 模式理解
- SQL生成和验证
- 查询执行
- 响应格式
- 数据可视化
- 查询缓存（Redis）
📊 内置可视化
自动生成图表和图形：
- 折线图、条形图、散点图
- 热图、饼图、直方图
- 高级统计可视化
⚡ 性能优化
- 基于Redis的查询缓存
- ChromaDB元数据索引
- 智能模式筛选
- 连接池
______________________________________________________________________
📦 包含内容
🗂️ CSV_MCP服务器
公开CSV处理功能的模型上下文协议服务器：
关键工具：
upload_csv-上传和处理CSV文件query_data-执行自然语言查询delete_data-清理表和元数据list_tables-查看可用数据集
支持的模式：
- 标准模式 -适用于Claude Desktop和MCP客户端
- HTTP/SSE模式 -用于远程访问和web集成
🤖 CSV_Agent系统
多代理文本到SQL处理管道：
代理组件：
- 数据摄入代理 -CSV验证和加载
- 模式理解代理 -数据库架构提取
- 意图分类代理 -查询类型检测
- SQL生成代理 -自然语言→ SQL转换
- SQL验证代理 -查询正确性验证
- 查询执行代理 -安全执行SQL
- 响应格式化代理 -自然语言响应
- 可视化代理 -图表生成
- 元数据索引器代理 -语义元数据存储
- 查询缓存代理 -基于Redis的缓存
- PostgreSQL处理程序代理 -数据库操作
______________________________________________________________________
🛠️ 安装
先决条件
- Python 3.8+
- PostgreSQL 13+
- 奥拉玛 （LLM能力）
- 瑞迪斯 （可选，用于缓存）
快速开始
- 克隆仓库
git clone https://github.com/Sonadas21/ParseQri_MCP.git
cd ParseQri_MCP- 设置PostgreSQL
# Create database
createdb parseqri
# Or using psql
psql -U postgres
CREATE DATABASE parseqri;- 安装CSV_Agent依赖项
cd CSV_Agent
pip install -r requirements.txt- 安装CSV_MCP依赖项
cd ../CSV_MCP
pip install -r requirements.txt- 配置数据库连接
更新 CSV_Agent/config.json 使用您的PostgreSQL凭据：
{
"agents": {
"postgres_handler": {
"params": {
"db_url": "postgresql://username:password@localhost:5432/parseqri"
}
}
}
}- 启动Ollama
ollama serve
# Pull required models
ollama pull PetrosStav/gemma3-tools:4b
ollama pull llama3.1:8b-instruct-q4_K_M
ollama pull qwen3:4b- 启动Redis （可选，用于缓存）
# Using Docker
docker run -d -p 6379:6379 redis:latest
# Or use the provided script
cd CSV_Agent
./redis-docker.sh # Linux/Mac
redis-docker.bat # Windows______________________________________________________________________
🚀 用法
使用CSV_MCP服务器
适用于克劳德桌面（标准模式）
- 配置Claude桌面
添加到您的Claude Desktop配置中：
{
"mcpServers": {
"csv-mcp": {
"command": "python",
"args": ["d:/Projects/C2CAS_Projects/Deployable/ParseQri_MCP/CSV_MCP/server.py"],
"env": {}
}
}
}- 重新启动克劳德桌面
- 在对话中使用工具
User: Upload this CSV file: d:/data/customers.csv
Claude: [Uses upload_csv tool]
User: Show me the top 5 customers by revenue
Claude: [Uses query_data tool]HTTP/SSE模式（远程访问）
cd CSV_MCP
# Start HTTP server
python server.py --http --host 0.0.0.0 --port 8000
# Server now available at:
# http://localhost:8000
# SSE endpoint: http://localhost:8000/sseMCP检验员测试
cd CSV_MCP
npx @modelcontextprotocol/inspector python server.py直接使用CSV_Agent
简单查询示例
cd CSV_Agent
python main.py "What is the average loan amount?"自动CSV处理
# Place CSV files in uploads/ folder
cp mydata.csv uploads/
# Run query (auto-processes new files)
python main.py "Show me all records from mydata"文件监视器模式
# Continuously monitor uploads/ folder
python watch_data_folder.py
# Add files to uploads/ - they'll be processed automatically______________________________________________________________________
📖 示例工作流
工作流程1：上传和查询
# Using CSV_MCP tools in Claude or other MCP client
# 1. Upload CSV
upload_csv(
file_path="d:/data/sales_2024.csv",
user_id="john_doe",
table_name="sales"
)
# 2. Query the data
query_data(
query="What were the total sales by region?",
user_id="john_doe",
table_name="sales"
)
# 3. List all tables
list_tables(user_id="john_doe")
# 4. Delete when done
delete_data(
user_id="john_doe",
table_name="sales",
confirm=true
)工作流程2：直接代理使用
from core.orchestrator import Orchestrator
# Initialize
config_path = "CSV_Agent/config.json"
orchestrator = Orchestrator(config_path)
# Upload CSV
result = orchestrator.upload_csv(
file_path="sales.csv",
user_id="analyst_1",
table_name="monthly_sales"
)
# Query
response = orchestrator.process_query(
query="Show me monthly trends",
user_id="analyst_1",
table_name="monthly_sales"
)
print(response['natural_language_response'])
print(response['sql_query'])______________________________________________________________________
🏗️ 建筑
系统概述
┌─────────────────────────────────────────────────────────────┐
│ MCP Clients │
│ (Claude Desktop, Custom Apps) │
└────────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CSV_MCP Server │
│ (FastMCP Protocol) │
└────────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CSV_Agent System │
│ (Orchestrator) │
└─────┬───────────────────────────────────────────────────┬───┘
│ │
▼ ▼
┌─────────────────┐ ┌──────────────────┐
│ Agent Pipeline │ │ Data Stores │
├─────────────────┤ ├──────────────────┤
│ • Intent │ │ • PostgreSQL │
│ • Schema │◄──────────────────────────│ (CSV Data) │
│ • SQL Gen │ │ │
│ • Validation │ │ • ChromaDB │
│ • Execution │◄──────────────────────────│ (Metadata) │
│ • Formatting │ │ │
│ • Visualization │ │ • Redis │
│ • Caching │◄──────────────────────────│ (Query Cache) │
└─────────────────┘ └──────────────────┘数据处理流程
CSV Upload Flow:
┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌───────────┐
│ CSV │───▶│ Validation │───▶│ Metadata │───▶│PostgreSQL │
│ File │ │ & Parsing │ │ Extraction │ │ Storage │
└──────────┘ └──────────────┘ └──────┬───────┘ └───────────┘
│
▼
┌──────────────┐
│ ChromaDB │
│ Indexing │
└──────────────┘
Query Processing Flow:
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Natural │───▶│ Intent │───▶│ Schema │───▶│ SQL │───▶│ Query │
│ Language │ │Classifier│ │ Filter │ │Generator │ │Execution │
└──────────┘ └──────────┘ └──────────┘ └──────────┘ └────┬─────┘
│
┌───────────────────────────────────────────────────┘
│
▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Response │◄───│ Format │◄───│ Cache │
│ to User │ │ Results │ │ Check │
└──────────┘ └──────────┘ └──────────┘______________________________________________________________________
⚙️ 配置
CSV_代理配置
编辑 CSV_Agent/config.json:
{
"agents": {
"postgres_handler": {
"params": {
"db_url": "postgresql://user:pass@host:5432/dbname",
"schema": "public"
}
},
"query_cache": {
"params": {
"redis_host": "localhost",
"redis_port": 6379,
"ttl_seconds": 86400,
"use_fallback": true
}
},
"metadata_indexer": {
"params": {
"llm_model": "PetrosStav/gemma3-tools:4b",
"api_base": "http://localhost:11434",
"chroma_persist_dir": "../data/db_storage"
}
}
}
}LLM模型配置
该系统针对特定任务使用不同的Olama模型：
| 代理 | 型号 | 用途 |
|---|---|---|
| 意图分类 | gemma3-tools:4b | 快速意图检测 |
| 模式理解 | gemma3-tools:4b | 模式分析 |
| SQL生成 | llama3.1:8b | 复杂的SQL创建 |
| SQL验证 | llama3.1:8b | 查询验证 |
| 响应格式 | qwen3:4b | 自然语言响应 |
| 可视化 | gemma3-tools:4b | 图表生成 |
多用户数据隔离
每个用户都有独立的存储：
User: john_doe
├── PostgreSQL Tables: sales_john_doe, customers_john_doe
├── ChromaDB Collection: john_doe_metadata
└── Metadata Files: db_storage/john_doe/______________________________________________________________________
🧪 测试与开发
运行测试
cd CSV_Agent
python -m pytest tests/测试单个代理
# Test SQL generation
python simplified_query.py "show me all customers"
# Test cache
python inspect_cache.py
# Clear databases
python clear_databases.py调试模式
启用详细登录 config.json:
{
"logging": {
"level": "DEBUG",
"file": "textsql.log"
}
}______________________________________________________________________
📚 文档
每个组件都有详细的文档：
- CSV_MCP文档 -MCP服务器设置和API
- CSV_MCP快速入门 -快速入门指南
- CSV_MCP故障排除 -常见问题
- CSV_Agent文档 -代理系统详细信息
- 多用户指南 -多用户设置
- Redis缓存指南 -缓存配置
______________________________________________________________________
🐛 故障排除
常见问题
PostgreSQL连接失败
# Check PostgreSQL is running
pg_isready
# Verify credentials
psql -U username -d parseqri
# Update config.json with correct credentials找不到Ollama
# Start Ollama service
ollama serve
# Verify models are available
ollama list
# Pull missing models
ollama pull PetrosStav/gemma3-tools:4bChromaDB权限错误
# Ensure write permissions
chmod -R 755 data/db_storage
# Or on Windows, check folder permissions in PropertiesCSV上传失败
- 验证文件路径是否为绝对路径
- 检查CSV编码（建议使用UTF-8）
- 确保CSV有标题
- 检查列名中的特殊字符
查询返回空结果
- 使用
list_tables验证表是否存在 - 确保
user_id匹配上传用户 - 不要在table_name中包含user_id后缀
- 检查查询语法
______________________________________________________________________
🔒 安全考虑
- SQL注入防护：所有查询在执行前都经过验证
- 用户隔离：每个用户的数据都使用前缀表进行隔离
- 参数化查询：代理人使用事先准备好的声明
- 输入验证：CSV文件在处理前经过验证
- 访问控制：配置具有最低所需权限的数据库用户
______________________________________________________________________
🚦 性能提示
- 启用Redis缓存：显著加快重复查询的速度
docker run -d -p 6379:6379 redis:latest- 优化PostgreSQL：为频繁查询的列添加索引
CREATE INDEX idx_user_column ON table_name(column_name);- 使用适当的LLM模型：平衡速度与精度
- 快速： gemma3-tools:4b - 准确： llama3.1:8b
- 批处理：一次上传多个CSV
- ChromaDB维护：定期清理旧元数据
python clear_databases.py______________________________________________________________________
🗺️ 路线图
- \[ \] 数据库代理 -直接MySQL、PostgreSQL、MSSQL连接
- \[ \] Excel支持 -.xlsx文件处理
- \[ \] 高级分析 -统计分析代理
- \[ \] 实时流媒体 -实时数据处理
- \[ \] Web用户界面 -基于浏览器的界面
- \[ \] API网关 -用于集成的REST API
- \[ \] 容器化 -完整的Docker编写设置
- \[ \] 云部署 -AWS/Azure/GCP模板
______________________________________________________________________
🤝 贡献
欢迎投稿！请按照以下步骤操作：
- 分叉存储库
- 创建要素分支(
git checkout -b feature/AmazingFeature) - 提交您的更改(
git commit -m 'Add some AmazingFeature') - 推到分支(
git push origin feature/AmazingFeature) - 打开拉取请求
______________________________________________________________________
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
______________________________________________________________________
👥 作者
ParseQri开发团队
- Sona 这 *初步工作* - 索纳达斯21
______________________________________________________________________
🙏 致谢
- 模型上下文协议 -用于标准化的AI集成协议
- 奥拉玛 -用于本地LLM推理
- 色度数据库 -矢量数据库功能
- FastMCP -适用于Python MCP服务器框架
- PostgreSQL社区 -对于强大的数据库系统
______________________________________________________________________
📞 支持
对于问题、疑问或功能请求：
- GitHub问题: 报告错误
- 电子邮件: dass21656@gmail.com
- 文档：查看文档/文件夹以获取详细指南
______________________________________________________________________
由...制作❤️ ParseQri团队
⭐ 如果这个项目对你有帮助，请在GitHub上给我们打个星！