MCP销售🛍️
服务器 模型上下文协议（MCP） 管理购物车和产品系统。设计用于在 Cloudflare员工 数据基础 PostgreSQL 英语 Supabase.
📋 特点
- MCP 服务器：完整实现用于AI/LLM客户机之间通信的MCP协议
- 无服务器：在没有服务器管理的CloudFlare Workers中可执行
- 数据库：postgresql en subase with ssl
- 连接池：HyperDrive用于高效的连接管理
- 对象关系映射：Drizzle ORM段落查询类型安全
- TypeScript：完整类型以最大限度地安全
- 模块化：可扩展且易于维护的工具体系结构
🛠️ 堆栈技术
- 运行时：Cloudflare Workers+Wrangler
- 语言：TypeScript
- 数据库：PostgreSQL（Supabase）
- 连接池：Hyperdrive
- 对象关系映射：淋ORM
- MCP-SDK：模型上下文协议
- 验证：Zod模式
📦 安装
先决条件
- Node.js 18+
- npm o pnpm
- Subase上的帐户(https://supabase.com)使用postgresql项目
- CloudFlare上的帐户（用于部署）
步骤
- 克隆存储库
git clone https://github.com/PietrantuonoFranco/mcp-sales.git
cd mcp-sales/mcp- 安装依赖项
npm install
# o
pnpm install- 配置环境变量
# Crear archivo .env en la carpeta mcp
# (usado por el script de migración desde Excel)
# Formato: postgresql://usuario:contraseña@host:puerto/nombre_base_datos
# Nota: Con Supabase puede ser necesario agregar ?ssl=true al final
echo DATABASE_URL="postgresql://user:password@host:5432/database?ssl=true" > .env- 验证CloudFlare类型配置
npm run cf-typegen🚀 发展
启动本地服务器
npm run dev服务器将在 http://127.0.0.1:8787
档案结构
mcp-sales/
├── README.md
├── docs/
│ ├── database/ # Diagramas y docs de BD
│ └── states/ # Documentación de estados
├── prompts/ # Prompts para desarrollo con AI
│ ├── 1_role.md
│ ├── 2_mental_model.md
│ ├── 3_gold_rules.md
│ └── 4_mcp_usage.md
└── mcp/ # Carpeta principal del proyecto
├── src/
│ ├── index.ts # Entry point principal
│ ├── server.ts # Configuración del MCP Server
│ ├── db/
│ │ ├── database.ts # Inicialización de PostgreSQL
│ │ ├── migrations/ # Migraciones SQL generadas
│ │ ├── queries/ # Queries reutilizables
│ │ │ ├── cartitemQueries.ts
│ │ │ ├── cartQueries.ts
│ │ │ └── productQueries.ts
│ │ ├── schemas/ # Definiciones Drizzle de tablas
│ │ │ ├── cartItemSchema.ts
│ │ │ ├── cartSchema.ts
│ │ │ ├── productSchema.ts
│ │ │ └── index.ts
│ │ └── seeds/ # Scripts de migración de datos
│ │ ├── migrate.ts
│ │ └── data/
│ ├── lib/ # Utilidades y tipos compartidos
│ │ ├── interfaces/
│ │ │ └── EnvInterface.ts
│ │ └── utils/
│ │ └── productUtils.ts
│ ├── tools/ # MCP Tools (handlers de acciones)
│ │ ├── listCategoriesAndTypeOfGarment.ts
│ │ ├── listProducts.ts
│ │ ├── getProduct.ts
│ │ ├── createCart.ts
│ │ ├── addToCart.ts
│ │ ├── updateCart.ts
│ │ ├── getCart.ts
│ │ ├── removeFromCart.ts
│ │ ├── clearCart.ts
│ │ └── index.ts
│ └── schemas/
│ └── inputSchemas.ts # Validación Zod de inputs
├── test/ # Tests
├── wrangler.jsonc # Configuración Wrangler
├── drizzle.config.ts # Configuración Drizzle
├── package.json
├── tsconfig.json
└── vitest.config.mts🧰 可用工具
每个工具都是MCP公开的端点。输入模式是在 mcp/src/schemas/inputSchemas.ts.
list_categories_and_types
获取库存中可用服装类型及其类别的唯一列表。
输入：
{}输出：
{
"totalCategorias": 3,
"totalTipos": 5,
"categorias": ["Hombre", "Mujer", "Niños"],
"tiposPrenda": ["Camiseta", "Pantalón", "Chaqueta", "Falda", "Sudadera"],
"mapeoCompleto": [
{ "categoria": "Mujer", "tipoPrenda": "Camiseta" }
]
}list_products
列出所有带有可选过滤器的产品。
输入：
{
"tipoPrenda": "Camiseta",
"color": "Azul",
"disponible": true
}get_product
获取特定产品的详细信息。
输入：
{
"id": 1
}create_cart
创建新的购物车。
输入：
{
"conversationId": "user-123" // opcional
}add_to_cart
将产品添加到购物车或更新其数量。
输入：
{
"productId": 5,
"quantity": 2,
"conversationId": "user-123"
}update_item_quantity
更新购物车中项目的数量。
输入：
{
"cartItemId": 1,
"quantity": 5
}
Nota: `quantity` puede ser `0` para eliminar el item.get_cart
获取包含所有项目的完整购物车。
输入：
{
"conversationId": 1
}输出：
{
"found": true,
"cart": { ... },
"items": [
{
"id": 1,
"cartId": 1,
"productId": 5,
"qty": 2,
"product": { ... },
"subtotal": 100,
"precioAplicado": 50
}
],
"itemCount": 1,
"total": 100
}remove_from_cart
根据其唯一ID从购物车中删除项目。
输入：
{
"cartItemId": 1
}clear_cart
完全清空您的购物车 cartId.
输入：
{
"conversationId": 1
}🧪 与MCP检查员一起测试
您可以使用官方检查员与MCP交互并以图形方式测试工具。
- 确保秘密
MCP_API_KEY（在检查员中为标题使用相同的值）：
wrangler secret put MCP_API_KEY- 启动本地服务器：
npm run dev- 检查员执行：
npx @modelcontextprotocol/inspector- 在检查员中，选择“HTTP（Web标准）”传输并配置：
- 网址：
http://127.0.0.1:8787 - 头球
x-api-key:
然后您将能够发现并运行这些工具(list_products, get_product等）直接从接口。
💾 数据库
从Excel初始化数据库
npm run migrateEl脚本 migrate 李 mcp/src/db/seeds/data/products.xlsx 并在表中创建记录 product.
确保文件存在： mcp/src/db/seeds/data/products.xlsx.
运球迁移
- 生成迁移：
npm run db:generate- 应用迁移：
npm run db:migrate- 模式推送（无迁移）：
npm run db:push注意：没有脚本 db:studio 目前定义。关于本地SSL的说明
在本地环境中运行连接到基础（迁移或从Excel加载）的命令时，如果您的环境出现SSL问题，可能需要禁用证书验证。
- Linux/macOS：
NODE_TLS_REJECT_UNAUTHORIZED=0 npm run db:migrate
NODE_TLS_REJECT_UNAUTHORIZED=0 npm run migrate- Windows（PowerShell）：
$env:NODE_TLS_REJECT_UNAUTHORIZED=0
npm run db:migrate
# o
npm run migrate- Windows（CMD）：
set NODE_TLS_REJECT_UNAUTHORIZED=0 && npm run db:migrate
set NODE_TLS_REJECT_UNAUTHORIZED=0 && npm run migrate仅用于当地发展。在生产中，您可以在不禁用验证的情况下正确配置SSL（PostgreSQL+HyperDrive）。
🌐 部署Cloudflare
1.配置器Wrangler
档案馆 mcp/wrangler.jsonc 它已经包括基本配置：
{
"name": "mcp",
"main": "src/index.ts",
"compatibility_date": "2025-09-27",
"compatibility_flags": ["nodejs_compat"],
"hyperdrive": [
{
"binding": "DB",
"id": "",
"localConnectionString": "postgresql://postgres:postgres@localhost:5432/devdb"
}
]
}为什么是HyperDrive？ Supabase使用严格限制的连接池。HyperDrive充当维护持久连接池的代理，避免在CloudFlare Workers的无服务器环境中耗尽连接。
2.环境变量和约束
- 对于从Excel迁移的本地脚本，请使用
.env骗局DATABASE_URL你知道的。 - 对于生产中的工人，使用您的Supabase连接字符串（项目中的Connect>Orms>Drizzle>.env字符串）配置HyperDrive。
3.部署
npm run deploy服务器将在 https://mcp-sales..workers.dev
📊 数据模型
表格： product
- id (PK)
- tipo_prenda
- disponible
- talla
- color
- cantidad_disponible
- precio_50_u
- precio_100_u
- precio_200_u
- categoria
- descripcion
- fecha_creacion
- fecha_actualizacion表格： cart
- id (PK)
- conversation_id
- fecha_creacion
- fecha_actualizacion表格： cart_item
- id (PK)
- cart_id (FK)
- product_id (FK)
- qty
- fecha_creacion🔒 安全
- SSL/TLS：与PostgreSQL的安全连接
- 验证：所有输入中的Zod模式
- 类型安全：TypeScript严格模式
🧪 测试
npm run test📝 环境变量
要求：
DATABASE_URL：数据库连接字符串（格式：postgresql://postgres.[proyecto-ref]:[password]@aws-0-[region].pooler.supabase.com:5432/postgres?ssl=true)
- 从你的项目中获得它，你知道： 连接>ORM>Drizzle>.env - 重要：可能需要添加 ?ssl=true SSL连接的URL结尾
______________________________________________________________________