VTION E-Commerce MCP Server

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.txt

2.配置

# 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秒查询超时

认证

⚠️ 重要：此服务器不包括身份验证。生产：

1. 添加身份验证中间件（JWT、API密钥、OAuth）
2. 使用特定于环境的凭据
3. 启用数据库行级安全性（RLS）
4. 在反向代理（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

部署

渲染

1. 创建新的Web服务
2. 连接GitHub存储库
3. 设置构建命令： pip install -r requirements.txt
4. 设置启动命令： python server.py
5. 从以下位置添加环境变量 .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