VTION电子商务MCP服务器
一种模型上下文协议（MCP）服务器，提供对VTION电子商务分析数据的安全、只读访问。内置FastAPI和PostgreSQL，同时支持MCP原生协议和REST API。
特性
- MCP协议支持：全面实施用于AI代理集成的模型上下文协议
- 多种运输方式:
- FastMCP（stdio）用于直接MCP客户端集成 - 基于web的客户端的HTTP/SSE - 用于传统HTTP客户端的REST API
- 设计安全：只读访问、查询验证、连接池
- 渐进式上下文加载：具有4个上下文级别的高效数据发现
- 并行查询执行：多个查询同时执行以获得最佳性能
- 自动限制：原始查询限制为5行，聚合查询限制为1000行
- 丰富的查询工具：模式检查、样本数据、灵活查询
建筑
VTION-ECOM/
├── vtion_ecom_mcp.py # Main MCP server with FastMCP
├── server.py # Standalone HTTP/SSE server
├── requirements.txt # Python dependencies
├── .env.example # Configuration template
├── .gitignore # Git ignore rules
└── README.md # This file快速开始
1.安装
# Clone the repository
git clone
cd VTION-ECOM
# Install dependencies
pip install -r requirements.txt2.配置
# Copy environment template
cp .env.example .env
# Edit .env with your database credentials
nano .env所需的环境变量：
DATASET_1_NAME=vtion_ecom
DATASET_1_DESC=VTION E-commerce platform analytics data
DATASET_1_CONNECTION=postgresql://postgres:PASSWORD@host:port/db?sslmode=require
DATASET_1_DICTIONARY={"table1":"desc","table2":"desc"}3.运行服务器
选项A:FastMCP模式（适用于MCP客户端）
python vtion_ecom_mcp.py选项B:HTTP/SSE模式（适用于web客户端）
python server.py
# Server runs on http://localhost:10000选项C：生产部署
uvicorn server:app --host 0.0.0.0 --port 10000 --workers 4数据库配置
MCP服务器连接到您的Supabase PostgreSQL数据库。连接字符串已在中配置 .env.example:
postgresql://postgres:Vtion%402023%23@db.yjiotntmzaukbmgxeqvq.supabase.co:5432/postgres?sslmode=require重要：密码是URL编码的(Vtion@2023# → Vtion%402023%23)
预期架构
服务器可以使用任何PostgreSQL模式。常见的电子商务表格包括：
products-带库存的产品目录orders-订单历史和交易customers-客户概况和人口统计cart_items-购物车数据user_sessions-用户参与度指标
服务器将在运行时自动发现您的架构。
用法
MCP工具
服务器提供5个MCP工具：
1. get_context(level, dataset_id?)
渐进式上下文加载：
- 级别0：全球规则和准则
- 级别1：列出所有数据集
- 2级：特定数据集的模式（需要dataset_id）
- 级别3：包含示例数据的完整详细信息（需要dataset_id）
# Get global rules
get_context(level=0)
# List all datasets
get_context(level=1)
# Get schema for dataset 1
get_context(level=2, dataset_id=1)
# Get full details with samples
get_context(level=3, dataset_id=1)2. list_available_datasets()
列出所有已配置的数据集及其元数据。
list_available_datasets()3. get_dataset_schema(dataset_id)
获取数据集的完整架构（相当于 get_context(level=2)).
get_dataset_schema(dataset_id=1)4. query_dataset(dataset_id, query, response_format?)
对数据集执行SQL SELECT查询。
# Simple query
query_dataset(
dataset_id=1,
query="SELECT * FROM products WHERE category = 'Electronics' LIMIT 10"
)
# Aggregated query
query_dataset(
dataset_id=1,
query="SELECT category, COUNT(*) as count, AVG(price) as avg_price FROM products GROUP BY category"
)
# JSON response format
query_dataset(
dataset_id=1,
query="SELECT * FROM orders WHERE status = 'completed'",
response_format="json"
)并行执行：呼叫 query_dataset() 多次-它们会自动并行执行！
# These three queries execute concurrently:
query_dataset(1, "SELECT category, COUNT(*) FROM products GROUP BY category")
query_dataset(1, "SELECT status, COUNT(*) FROM orders GROUP BY status")
query_dataset(1, "SELECT gender, COUNT(*) FROM customers GROUP BY gender")5. get_dataset_sample(dataset_id, table_name, limit?)
从特定表中获取示例行。
get_dataset_sample(
dataset_id=1,
table_name="products",
limit=20
)REST API端点
跑步时 server.py，这些HTTP端点可用：
健康检查
curl http://localhost:10000/
# or
curl http://localhost:10000/health答复：
{
"status": "ok",
"service": "VTION E-Commerce MCP Server",
"datasets": 1,
"version": "1.0",
"mcp_endpoint": "/mcp",
"mcp_protocol_version": "2025-06-18"
}列出数据集
curl http://localhost:10000/datasets执行查询
curl -X POST http://localhost:10000/query \
-H "Content-Type: application/json" \
-d '{
"dataset_id": 1,
"query": "SELECT * FROM products LIMIT 5"
}'MCP协议端点
POST /mcp使用JSON-RPC 2.0通过HTTP实现完整的MCP协议。
安全
查询限制
- 只允许SELECT：INSERT、UPDATE、DELETE、DROP等被阻止
- 自动限制：原始查询最多5行，聚合查询最多1000行
- 连接池：防止资源耗尽
- 超时保护：60秒查询超时
认证
⚠️ 重要：此服务器不包括身份验证。生产：
- 添加身份验证中间件（JWT、API密钥、OAuth）
- 使用特定于环境的凭据
- 启用数据库行级安全性（RLS）
- 在反向代理（nginx、Cloudflare）后面运行
发展
测试连接
# Test database connectivity
python -c "
import asyncio
import asyncpg
async def test():
conn = await asyncpg.connect('postgresql://...')
print('Connected!')
tables = await conn.fetch('SELECT table_name FROM information_schema.tables WHERE table_schema = \\'public\\'')
print('Tables:', [t['table_name'] for t in tables])
await conn.close()
asyncio.run(test())
"添加多个数据集
编辑 .env 要添加更多数据集：
# Dataset 1
DATASET_1_NAME=vtion_ecom
DATASET_1_CONNECTION=postgresql://...
DATASET_1_DESC=Main e-commerce data
DATASET_1_DICTIONARY={"products":"Product catalog"}
# Dataset 2
DATASET_2_NAME=analytics
DATASET_2_CONNECTION=postgresql://...
DATASET_2_DESC=Analytics warehouse
DATASET_2_DICTIONARY={"events":"User events"}自定义业务逻辑
服务器从继承业务逻辑 印度分析mcp:
- 查询验证：修改
query_dataset()在vtion_ecom_mcp.py - 响应格式：更新
format_markdown_table()助手 - 添加自定义工具：使用
@mcp.tool()装饰器 - 模式自定义：编辑
DATASET_1_DICTIONARY在.env
部署
渲染
- 创建新的Web服务
- 连接GitHub存储库
- 设置构建命令：
pip install -r requirements.txt - 设置启动命令：
python server.py - 从以下位置添加环境变量
.env
码头工人
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
ENV PORT=10000
EXPOSE 10000
CMD ["python", "server.py"]docker build -t vtion-mcp .
docker run -p 10000:10000 --env-file .env vtion-mcp铁路/Fly.io
两者都支持使用环境变量从GitHub自动部署。
故障排除
连接问题
# Test database connection
psql "postgresql://postgres:Vtion%402023%23@db.yjiotntmzaukbmgxeqvq.supabase.co:5432/postgres?sslmode=require"未找到数据集
检查环境变量是否已设置：
env | grep DATASET_查询错误
- 使用验证表名
get_dataset_schema() - 检查列名是否与架构匹配
- 确保查询是有效的SQL SELECT语句
导入错误
pip install --upgrade -r requirements.txt鸣谢
许可证
MIT许可证-有关详细信息，请参阅许可证文件
支持
对于问题和疑问：
- GitHub问题： /问题
- 电子邮件：support@vtion.com