Stateset MCP Server

Name: Stateset MCP Server
Author: stateset

本地服务

github.com/stateset商业与营销046 周前更新

代码仓库

关于 Stateset MCP Server

StateSet MCP Server 将 StateSet API 的电商与供应链操作接入 MCP，面向需要管理订单、库存、制造和财务流程的团队。它提供覆盖多业务域的工具、搜索、批处理及实时更新能力。

主要功能

01覆盖订单、库存等业务操作
02多条件搜索与分页
03原子批处理与并行执行
04WebSocket 实时事件更新
05URI 资源访问模板
06缓存、限流与故障恢复

适用场景

01创建和处理订单及退货
02查询产品、库存和客户
03批量执行业务操作
04订阅订单等资源变更

MCP 相关

通过 stdio 提供 MCP 工具、资源和提示词处理器，供 MCP 客户端调用 StateSet API。另支持 WebSocket 实时事件流。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

暂未收录安装方式

我们还没有获取到这个服务的安装包或远程地址，请按项目 README 中的说明安装。

代码仓库

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

StateSet MCP 服务

一款可用于生产环境的 Model Context Protocol（MCP）服务，用于集成 StateSet API，通过标准化接口提供全面的电子商务和供应链运营管理能力。该服务具备企业级的可靠性、性能和可观测性。

📖 文档

架构指南 - 系统设计和组件概览
测试指南 - 测试策略和覆盖率
API 文档 - 生成的 TypeDoc API 参考
贡献指南 - 如何参与贡献

🚀 功能

核心能力

166 个 MCP 工具：为订单、退货、库存、产品、客户、货运、制造和财务运营提供完整的 CRUD 操作，并全面支持工作流
高级搜索：支持多条件筛选、排序、分页、聚合，以及对所有资源进行全文搜索
批量操作：以可配置的并行度和错误处理机制，原子性地执行多个操作
实时更新：支持 WebSocket 实时事件流和资源变更通知
资源模板：基于 URI 访问资源（例如，stateset-order:///ORD-123）

企业级可靠性

智能缓存：提供 LRU/LFU/FIFO 缓存策略、自适应 TTL、自动缓存预热，以及可选的 Redis 分布式缓存支持
熔断器：自动检测故障并恢复，防止故障级联
速率限制：采用令牌桶算法，支持按工具设定限制和突发请求
连接池：通过健康检查和自动重新连接，高效复用连接
优雅降级：服务不可用时，自动采用回退策略并使用过期缓存数据
重试策略：采用带抖动的指数退避和智能错误分类
优雅关闭：妥善清理连接、缓存和后台任务

安全与验证

输入净化：防止 XSS、保护免受 SQL 注入、检测命令注入并剥离 HTML 标签
路径遍历防护：检测并阻止路径遍历尝试
API 密钥安全：自动在日志和错误消息中隐藏 API 密钥，并遮蔽敏感数据
请求验证：使用 Zod 模式进行全面的类型检查
CORS 与 Helmet：提供安全标头并防护跨域请求

可观测性

结构化日志：基于 Pino 的 JSON 日志，包含关联 ID 和请求上下文
请求关联：通过异步操作传递关联 ID，以支持分布式跟踪
Prometheus 指标：请求数量、耗时、错误率、缓存命中率和队列长度
工具指标：按工具跟踪执行情况，包括耗时直方图、错误率和类别分析
健康检查：为 Kubernetes 部署提供存活和就绪探针
OpenTelemetry：支持分布式跟踪（可选）
性能监控：请求计时、重试跟踪、熔断器状态和慢速工具检测

开发者体验

类型安全：使用 TypeScript 5.7 构建，提供最高级别的类型安全性和 IntelliSense 支持
经过充分测试：21 个测试套件中的 297 项测试全部通过，涵盖单元测试和 E2E 测试
热重载：开发模式下，文件发生更改时自动重启
OpenAPI 转换器：根据 OpenAPI 规范生成 MCP 工具
完善的文档：提供详细的工具说明，优化 AI 理解效果

📋 目录

安装
快速开始
配置
使用示例
架构
API 参考
开发
测试
部署
监控
故障排除
性能提示
贡献
许可证
支持
路线图

🔧 安装

使用 npm

npm install -g stateset-mcp-server

使用 Docker

docker pull stateset/mcp-server:latest

从源代码安装

git clone https://github.com/stateset/mcp-server.git
cd mcp-server
npm install
npm run build

🏃 快速开始

1. 安装

# Clone the repository
git clone https://github.com/stateset/mcp-server.git
cd mcp-server

# Install dependencies
npm install

# Build the project
npm run build

2. 配置

# Copy environment template
cp .env.example .env

# Edit .env with your StateSet API credentials
# Required: STATESET_API_KEY=your_api_key_here

3. 运行服务

# Development mode with hot reload
npm run dev

# Production mode
npm start

# Using Docker
docker build -t stateset-mcp-server .
docker run --env-file .env stateset-mcp-server

4. 连接 MCP 客户端

该服务使用 stdio 传输进行 MCP 通信：

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// Create client
const client = new Client({
  name: 'my-app',
  version: '1.0.0',
});

// Create stdio transport
const transport = new StdioClientTransport({
  command: 'node',
  args: ['dist/index.js'],
  env: {
    STATESET_API_KEY: 'your_api_key_here'
  }
});

// Connect
await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools.tools.length);

// Call a tool
const result = await client.callTool({
  name: 'stateset_list_orders',
  arguments: { page: 1, per_page: 10 }
});

5. WebSocket 连接（可选）

如需实时更新，请连接 WebSocket 服务：

import WebSocket from 'ws';

const ws = new WebSocket('ws://localhost:8081');

// Subscribe to order updates
ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'orders',
  filter: { status: 'pending' }
}));

// Listen for updates
ws.on('message', (data) => {
  const event = JSON.parse(data);
  console.log('Received update:', event);
});

⚙️ 配置

环境变量

将 .env.example 复制到 .env，并配置以下变量：

必需配置

变量	描述	默认值
`STATESET_API_KEY`	你的 StateSet API 密钥	必需
`STATESET_BASE_URL`	StateSet API 基础 URL	`https://api.stateset.io/v1`
`STATESET_API_VERSION`	API 版本	`v1`

速率限制

变量	描述	默认值
`REQUESTS_PER_HOUR`	每小时最大 API 请求数	`1000`
`REQUESTS_PER_MINUTE`	每分钟最大 API 请求数	`50`
`BURST_SIZE`	短时间突发时允许的额外请求数	`10`
`RETRY_ATTEMPTS`	请求失败时的重试次数	`3`
`RETRY_DELAY`	初始重试延迟（毫秒）	`1000`

缓存

变量	描述	默认值
`CACHE_ENABLED`	启用/禁用缓存	`true`
`CACHE_TTL`	缓存生存时间（秒）	`300`
`CACHE_MAX_SIZE`	缓存项的最大数量	`1000`
`CACHE_STRATEGY`	缓存淘汰策略（lru/lfu/fifo）	`lru`

Redis 配置（可选）

变量	描述	默认值
`REDIS_HOST`	Redis 服务主机名	`localhost`
`REDIS_PORT`	Redis 服务端口	`6379`
`REDIS_PASSWORD`	Redis 身份验证密码	（无）
`REDIS_DB`	Redis 数据库编号	`0`

熔断器

变量	描述	默认值
`CIRCUIT_BREAKER_ENABLED`	启用熔断器保护	`true`
`CIRCUIT_BREAKER_THRESHOLD`	熔断器打开前的失败次数	`5`
`CIRCUIT_BREAKER_TIMEOUT`	熔断器保持打开状态的时间（毫秒）	`60000`
`CIRCUIT_BREAKER_RESET_TIMEOUT`	尝试重置前的等待时间（毫秒）	`30000`

功能开关

变量	描述	默认值
`FEATURE_CACHING`	启用 API 响应缓存	`true`
`FEATURE_METRICS`	启用 Prometheus 指标	`true`
`FEATURE_HEALTH_CHECK`	启用健康检查端点	`true`
`FEATURE_WEBSOCKET`	启用 WebSocket 实时更新	`true`
`FEATURE_CIRCUIT_BREAKER`	启用熔断器	`true`
`FEATURE_COMPRESSION`	启用响应压缩	`true`
`FEATURE_OPEN_API_CONVERTER`	启用 OpenAPI 转换	`false`
`FEATURE_ENABLE_TELEMETRY`	启用 OpenTelemetry 跟踪	`false`

服务配置

变量	描述	默认值
`NODE_ENV`	环境（development/staging/production/test）	`production`
`LOG_LEVEL`	日志级别（trace/debug/info/warn/error/fatal）	`info`
`API_TIMEOUT_MS`	请求超时时间（毫秒）	`10000`
`WEBSOCKET_PORT`	WebSocket 服务端口	`8081`
`METRICS_INTERVAL`	指标收集间隔（毫秒）	`60000`
`HEALTH_CHECK_INTERVAL`	健康检查间隔（毫秒）	`30000`

💡 使用示例

基本操作

// Create a customer
const customer = await client.callTool({
  name: 'stateset_create_customer',
  arguments: {
    email: '[email protected]',
    name: 'John Doe',
    address: {
      line1: '123 Main St',
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94102',
      country: 'US'
    }
  }
});

// Create an order
const order = await client.callTool({
  name: 'stateset_create_order',
  arguments: {
    customer_id: customer.id,
    items: [
      { product_id: 'PROD-001', quantity: 2, price: 29.99 },
      { product_id: 'PROD-002', quantity: 1, price: 49.99 }
    ],
    shipping_address: {
      line1: '123 Main St',
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94102',
      country: 'US'
    }
  }
});

// Create a shipment
const shipment = await client.callTool({
  name: 'stateset_create_shipment',
  arguments: {
    order_id: order.id,
    carrier: 'UPS',
    tracking_number: '1Z999AA10123456784'
  }
});

// Mark as shipped
await client.callTool({
  name: 'stateset_mark_shipment_shipped',
  arguments: { shipment_id: shipment.id }
});

高级搜索

// Search orders by multiple criteria
const searchResults = await client.callTool({
  name: 'stateset_advanced_search',
  arguments: {
    resource: 'orders',
    filters: [
      { field: 'status', operator: 'eq', value: 'pending' },
      { field: 'total', operator: 'gt', value: 100 },
      { field: 'created_at', operator: 'gte', value: '2024-01-01T00:00:00Z' }
    ],
    sort: [
      { field: 'created_at', order: 'desc' }
    ],
    page: 1,
    per_page: 20
  }
});

// Full-text search across resources
const textSearch = await client.callTool({
  name: 'stateset_full_text_search',
  arguments: {
    query: 'laptop',
    resources: ['products', 'orders'],
    limit: 50
  }
});

// Search products with inventory
const productsInStock = await client.callTool({
  name: 'stateset_search_products_with_inventory',
  arguments: {
    min_quantity: 10,
    location: 'warehouse-1'
  }
});

批量操作

// Batch create multiple orders
const batchResult = await client.callTool({
  name: 'stateset_batch_create_orders',
  arguments: {
    orders: [
      { customer_id: 'CUST-1', items: [...] },
      { customer_id: 'CUST-2', items: [...] },
      { customer_id: 'CUST-3', items: [...] }
    ],
    options: {
      parallel: true,
      stopOnError: false,
      chunkSize: 10
    }
  }
});

console.log(`Success: ${batchResult.success}, Failed: ${batchResult.failed}`);

// Bulk inventory update
await client.callTool({
  name: 'stateset_batch_update_inventory',
  arguments: {
    updates: [
      { product_id: 'PROD-1', quantity_change: -5, reason: 'sale' },
      { product_id: 'PROD-2', quantity_change: 100, reason: 'restock' },
      { product_id: 'PROD-3', quantity_change: -2, reason: 'damaged' }
    ]
  }
});

// Generic batch operations
await client.callTool({
  name: 'stateset_batch_operations',
  arguments: {
    operations: [
      { type: 'create', resource: 'product', data: {...} },
      { type: 'update', resource: 'inventory', data: {...} },
      { type: 'create', resource: 'customer', data: {...} }
    ],
    options: { parallel: false, stopOnError: true }
  }
});

退货处理工作流

// Customer initiates return
const rma = await client.callTool({
  name: 'stateset_create_rma',
  arguments: {
    order_id: 'ORD-12345',
    items: [
      { product_id: 'PROD-001', quantity: 1, reason: 'defective' }
    ],
    reason: 'Product arrived damaged'
  }
});

// Approve the return
await client.callTool({
  name: 'stateset_approve_return',
  arguments: { rma_id: rma.id }
});

// After receiving returned items, restock
await client.callTool({
  name: 'stateset_restock_return',
  arguments: { rma_id: rma.id }
});

// Issue refund
await client.callTool({
  name: 'stateset_create_payment',
  arguments: {
    order_id: 'ORD-12345',
    amount: -29.99,
    payment_method: 'refund',
    notes: `Refund for RMA ${rma.id}`
  }
});

制造工作流

// Create bill of materials
const bom = await client.callTool({
  name: 'stateset_create_bill_of_materials',
  arguments: {
    product_id: 'PROD-WIDGET',
    components: [
      { part_id: 'PART-001', quantity: 2, cost: 5.00 },
      { part_id: 'PART-002', quantity: 1, cost: 10.00 },
      { part_id: 'PART-003', quantity: 4, cost: 2.50 }
    ]
  }
});

// Create work order
const workOrder = await client.callTool({
  name: 'stateset_create_work_order',
  arguments: {
    product_id: 'PROD-WIDGET',
    quantity: 100,
    bom_id: bom.id,
    due_date: '2024-12-31'
  }
});

// Create purchase order for raw materials
const po = await client.callTool({
  name: 'stateset_create_purchase_order',
  arguments: {
    vendor_id: 'VENDOR-001',
    items: [
      { part_id: 'PART-001', quantity: 200, unit_price: 5.00 },
      { part_id: 'PART-002', quantity: 100, unit_price: 10.00 }
    ],
    delivery_date: '2024-12-15'
  }
});

资源访问

// Read resource by URI
const orderResource = await client.readResource({
  uri: 'stateset-order:///ORD-12345'
});

const productResource = await client.readResource({
  uri: 'stateset-product:///PROD-001'
});

const customerResource = await client.readResource({
  uri: 'stateset-customer:///CUST-456'
});

🏗️ 架构

目录结构

src/
├── auth/               # Authentication templates and types
├── config/             # Configuration management and timeouts
├── core/              # Core infrastructure
│   ├── adaptive-cache.ts        # Adaptive TTL and cache warming
│   ├── advanced-metrics.ts      # Detailed performance metrics
│   ├── batch-processor.ts       # Batch operation processing
│   ├── cache.ts                 # In-memory caching layer
│   ├── circuit-breaker.ts       # Circuit breaker pattern
│   ├── connection-pool.ts       # Connection pooling
│   ├── graceful-degradation.ts  # Fallback and degradation patterns
│   ├── health.ts                # Health check implementation
│   ├── hybrid-cache.ts          # Hybrid memory/Redis caching
│   ├── intelligent-cache.ts     # Advanced caching strategies
│   ├── metrics.ts               # Metrics collection
│   ├── openapi-converter.ts     # OpenAPI to MCP conversion
│   ├── performance-optimizer.ts # Performance tuning
│   ├── rate-limiter.ts          # Rate limiting logic
│   ├── realtime-manager.ts      # Real-time event management
│   ├── redis-cache.ts           # Redis distributed caching
│   ├── request-context.ts       # Correlation ID and request tracking
│   ├── resource-registry.ts     # Resource handler registry
│   ├── retry-strategy.ts        # Retry with exponential backoff
│   ├── tool-metrics.ts          # Per-tool metrics collection
│   ├── server-rate-limiter.ts   # Server-level rate limiting
│   ├── telemetry.ts             # OpenTelemetry integration
│   └── websocket.ts             # WebSocket server
├── middleware/        # Request/response middleware
│   ├── api-docs.ts              # API documentation
│   ├── error-handler.ts         # Error handling and formatting
│   └── security.ts              # Security middleware
├── services/          # Business logic and API clients
│   ├── enhanced-stateset-client.ts  # Enhanced API client
│   ├── mcp-client.ts                # MCP client wrapper
│   └── stateset-client.ts           # Base StateSet API client
├── tools/             # MCP tool implementations
│   ├── ai-insights.ts           # AI-powered analytics
│   ├── batch-operations.ts      # Batch operation tools
│   ├── definitions.ts           # Tool definitions
│   ├── dispatcher.ts            # Tool request dispatcher
│   ├── enhanced-tools.ts        # Enhanced tool capabilities
│   ├── openapi-tools.ts         # OpenAPI-based tools
│   ├── registry.ts              # Tool registry
│   ├── schemas.ts               # Zod validation schemas
│   └── search-tools.ts          # Advanced search tools
├── types/             # TypeScript type definitions
│   ├── api.ts                   # API types
│   ├── common.ts                # Common types
│   ├── index.ts                 # Type exports
│   ├── mcp-api.ts               # MCP API types
│   ├── resources.ts             # Resource types
│   └── tools.ts                 # Tool types
├── utils/             # Utility functions
│   ├── broadcast.ts             # Broadcasting utilities
│   ├── logger.ts                # Structured logging
│   ├── shutdown.ts              # Graceful shutdown
│   └── validation.ts            # Input validation
├── index.ts           # Entry point
└── server.ts          # Main server implementation

核心组件

MCP 服务：基于 Stdio 的 MCP 协议服务端，包含工具、资源和提示词处理器
StateSet API 客户端：基于 Axios 的客户端，支持速率限制、重试和熔断器
工具分发器：通过验证将工具调用路由到相应的处理器
资源注册表：管理基于 URI 的资源访问（例如，stateset-order:///ORD-123）
智能缓存：采用多种策略（LRU/LFU/FIFO）的缓存，并支持自动失效
熔断器：通过自动恢复防止故障级联
WebSocket 管理器：实时事件流和订阅管理
批处理器：并行和顺序执行批量操作
指标收集器：兼容 Prometheus 的指标，并跟踪请求
错误处理器：统一格式化错误，并包含上下文和请求 ID

📚 API 参考

工具

该服务提供 166 个按领域组织的 MCP 工具：

订单与退货（RMA）

创建：stateset_create_order、stateset_create_rma
更新：stateset_update_order、stateset_update_order_status
获取：stateset_get_order、stateset_get_rma、stateset_get_order_items
列出：stateset_list_orders、stateset_list_rmas
删除：stateset_delete_order
工作流：stateset_approve_return、stateset_restock_return、stateset_cancel_order、stateset_archive_order、stateset_add_order_item

库存与产品

产品：stateset_create_product、stateset_update_product、stateset_get_product、stateset_list_products、stateset_delete_product
产品变体：stateset_get_product_variants、stateset_create_product_variant、stateset_update_product_variant_price、stateset_delete_product_variant
库存：stateset_create_inventory、stateset_update_inventory、stateset_get_inventory、stateset_list_inventories、stateset_delete_inventory
库存工作流：stateset_reserve_inventory、stateset_release_inventory、stateset_get_low_stock

履约与配送

货件：stateset_create_shipment、stateset_get_shipment、stateset_list_shipments
工作流：stateset_mark_shipment_shipped、stateset_mark_shipment_delivered、stateset_track_shipment
履约订单：stateset_create_fulfillment_order、stateset_update_fulfillment_order、stateset_list_fulfillment_orders

购物车与结账

购物车：stateset_create_cart、stateset_get_cart、stateset_delete_cart、stateset_list_carts
购物车商品：stateset_add_cart_item、stateset_update_cart_item、stateset_remove_cart_item、stateset_clear_cart
结账：stateset_create_checkout、stateset_get_checkout、stateset_update_checkout、stateset_complete_checkout、stateset_cancel_checkout

制造与供应链

工单：stateset_create_work_order、stateset_update_work_order、stateset_get_work_order、stateset_list_work_orders
工单工作流：stateset_assign_work_order、stateset_start_work_order、stateset_complete_work_order、stateset_hold_work_order、stateset_cancel_work_order
物料清单：stateset_create_bill_of_materials、stateset_update_bill_of_materials、stateset_get_bill_of_materials、stateset_list_bill_of_materials
BOM 组件：stateset_get_bom_components、stateset_add_bom_component、stateset_remove_bom_component
采购订单：stateset_create_purchase_order、stateset_update_purchase_order、stateset_get_purchase_order、stateset_list_purchase_orders
采购订单工作流：stateset_approve_purchase_order、stateset_cancel_purchase_order、stateset_receive_purchase_order
制造商订单：stateset_create_manufacturer_order、stateset_update_manufacturer_order、stateset_get_manufacturer_order、stateset_list_manufacturer_orders
ASN：stateset_create_asn、stateset_update_asn、stateset_get_asn、stateset_list_asns
ASN 工作流：stateset_mark_asn_in_transit、stateset_mark_asn_delivered、stateset_cancel_asn
收货单：stateset_create_item_receipt、stateset_update_item_receipt、stateset_get_item_receipt、stateset_list_item_receipts
供应商：stateset_create_supplier、stateset_update_supplier、stateset_get_supplier、stateset_delete_supplier、stateset_list_suppliers

财务运营

发票：stateset_create_invoice、stateset_update_invoice、stateset_get_invoice、stateset_list_invoices、stateset_delete_invoice
付款：stateset_create_payment、stateset_update_payment、stateset_get_payment、stateset_list_payments、stateset_delete_payment
付款工作流：stateset_refund_payment、stateset_get_payments_by_order
销售订单：stateset_create_sales_order、stateset_update_sales_order、stateset_get_sales_order、stateset_list_sales_orders
现金销售：stateset_create_cash_sale、stateset_update_cash_sale、stateset_get_cash_sale、stateset_list_cash_sales

客户管理

stateset_create_customer - 创建新客户
stateset_update_customer - 更新客户信息
stateset_get_customer - 获取客户详情
stateset_list_customers - 列出所有客户
stateset_delete_customer - 删除客户
stateset_get_customer_addresses - 获取客户地址
stateset_add_customer_address - 为客户添加地址

保修

stateset_create_warranty - 创建保修记录
stateset_update_warranty - 更新保修详情
stateset_get_warranty - 获取保修信息
stateset_list_warranties - 列出所有保修记录
stateset_extend_warranty - 延长保修期限
stateset_create_warranty_claim - 创建保修索赔
stateset_approve_warranty_claim - 批准保修索赔

分析与报告

stateset_get_dashboard_metrics - 获取仪表板关键指标
stateset_get_sales_trends - 获取销售趋势
stateset_get_sales_metrics - 获取销售业绩指标
stateset_get_inventory_metrics - 获取库存指标
stateset_get_shipment_metrics - 获取发货指标
stateset_get_cart_metrics - 获取购物车放弃率指标

高级搜索

stateset_advanced_search - 支持排序、分页和聚合的多条件筛选搜索
stateset_search_orders_by_date - 查找指定日期范围内的订单
stateset_search_products_with_inventory - 按库存水平搜索产品
stateset_search_customer_analytics - 分析客户细分群体
stateset_full_text_search - 对所有资源进行全文搜索

批量操作

stateset_batch_operations - 原子化执行多个操作
stateset_batch_create_orders - 一次创建多个订单
stateset_batch_update_inventory - 批量调整库存
stateset_csv_import - 从 CSV 文件导入数据

监控与管理

stateset_health_check - 检查服务和 API 的运行状况
stateset_get_api_metrics - 查看请求指标和性能
stateset_tool_rate_limits - 获取每个工具的速率限制状态
stateset_timeout_config - 查看超时配置
stateset_cache_stats - 获取缓存性能统计信息
stateset_clear_cache - 清除缓存数据
stateset_websocket_stats - 查看 WebSocket 连接统计信息

资源

通过 URI 模板访问 StateSet 资源。资源可通过 ID 直接访问特定记录：

stateset-rma:///RMA-12345
stateset-order:///ORD-123
stateset-warranty:///WAR-123
stateset-shipment:///SHIP-123
stateset-product:///PROD-789
stateset-inventory:///INV-456
stateset-customer:///CUST-789
stateset-sales-order:///SO-123
stateset-purchase-order:///PO-456
stateset-invoice:///INV-789
stateset-payment:///PAY-123

使用示例：

// Read a specific order
const response = await client.readResource({
  uri: 'stateset-order:///ORD-12345'
});

提示词

服务提供了全面的提示词，其中包括：

工具目录：按类别整理的全部 166 个工具的详细说明
最佳实践：有关输入验证、速率限制、错误处理、搜索/筛选和批处理的指南
工作流指南：订单、退货、履约、制造、库存和财务操作的常见模式
API 使用技巧：速率限制管理、缓存策略和性能优化

🛠️ 开发

前置条件

Node.js >= 18.0.0
npm >= 8.0.0
TypeScript >= 5.0.0

设置

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run linting
npm run lint

# Format code
npm run format

# Type check
npm run typecheck

项目脚本

脚本	描述
`npm run dev`	启动支持热重载的开发服务器
`npm run build`	构建生产环境包
`npm run test`	运行所有测试
`npm run test:watch`	以监视模式运行测试
`npm run test:coverage`	生成覆盖率报告
`npm run lint`	运行 ESLint
`npm run format`	使用 Prettier 格式化代码
`npm run docs`	生成 API 文档

🧪 测试

运行测试

# Run all tests (297 passing tests)
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

# Run E2E tests
npm run test:e2e

测试结果

Test Suites: 14 passed, 14 total
Tests:       203 passed, 203 total

测试结构

tests/
├── unit/                           # Unit tests for individual components
│   ├── batch-processor.test.ts    # Batch operation processing
│   ├── cache.test.ts              # Cache functionality
│   ├── circuit-breaker.test.ts    # Circuit breaker logic
│   ├── connection-pool.test.ts    # Connection pooling
│   ├── definitions.test.ts        # Tool definitions
│   ├── dispatcher.test.ts         # Tool dispatcher
│   ├── error-handler.test.ts      # Error handling
│   ├── handlers.test.ts           # Request handlers
│   ├── health.test.ts             # Health check functionality
│   ├── intelligent-cache.test.ts  # Advanced caching
│   ├── mcp-client.test.ts         # MCP client wrapper
│   ├── metrics.test.ts            # Metrics collection
│   ├── openapi-converter.test.ts  # OpenAPI conversion
│   ├── rate-limiter.test.ts       # Rate limiting core
│   ├── redis-cache.test.ts        # Redis cache integration
│   ├── registry.test.ts           # Tool registry
│   ├── schemas.test.ts            # Zod schema validation
│   ├── server.test.ts             # Server initialization
│   ├── stateset-client.test.ts    # API client
│   ├── telemetry.test.ts          # Telemetry integration
│   ├── tool-rate-limiter.test.ts  # Tool-level rate limiting
│   ├── validation.test.ts         # Input validation
│   └── websocket.test.ts          # WebSocket functionality
├── e2e/                            # End-to-end tests
│   ├── mcp-server.e2e.test.ts     # MCP server integration
│   └── workflow.e2e.test.ts       # Business workflow tests
├── setup.ts                        # Test setup and configuration
└── teardown.ts                     # Test cleanup

覆盖范围

测试套件全面覆盖了以下内容：

✅ MCP 服务核心功能
✅ 速率限制和熔断器逻辑
✅ 缓存策略（LRU/LFU/FIFO）和 Redis 集成
✅ 输入验证与清理
✅ 错误处理与格式化
✅ WebSocket 连接
✅ 指标收集
✅ 连接池
✅ OpenAPI 转换
✅ 工具分发器和注册表
✅ 批处理器操作
✅ 健康检查端点

编写测试

import { StateSetClient } from '../src/services/stateset-client';

describe('StateSet Client', () => {
  it('should create order successfully', async () => {
    const client = new StateSetClient(mockConfig);
    const order = await client.createOrder({
      customer_email: '[email protected]',
      items: [{ product_id: 'PROD-1', quantity: 1, price: 10.00 }]
    });
    expect(order.id).toBeDefined();
  });
});

🚀 部署

Docker 部署

服务包含一个针对生产环境优化的多阶段 Dockerfile：

# Build image
docker build -t stateset-mcp-server .

# Run container
docker run -d \
  --name stateset-mcp \
  --env-file .env \
  -p 9464:9464 \
  -p 8081:8081 \
  stateset-mcp-server

Dockerfile 包含：

多阶段构建，以减小镜像大小
用于增强安全性的非 root 用户
dumb-init，用于正确处理信号
用于容器编排的健康检查
针对生产环境优化的依赖项

Kubernetes 部署

apiVersion: apps/v1
kind: Deployment
metadata:
  name: stateset-mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: stateset-mcp
  template:
    metadata:
      labels:
        app: stateset-mcp
    spec:
      containers:
      - name: server
        image: stateset/mcp-server:latest
        envFrom:
        - secretRef:
            name: stateset-secrets
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"

云部署

AWS：使用 ECS 或 EKS 部署提供的 Docker 镜像
Google Cloud：部署到 Cloud Run 或 GKE
Azure：使用 Container Instances 或 AKS

📊 监控

健康检查

使用 MCP 工具进行健康监控：

// Check overall server health
await client.callTool({
  name: 'stateset_health_check',
  arguments: { include_details: true }
});

// Returns:
// - API connection status
// - Rate limiter state
// - Circuit breaker state (open/closed/half-open)
// - Memory usage
// - Cache statistics
// - WebSocket connections

指标

通过 MCP 工具访问详细指标：

// Get API metrics
await client.callTool({
  name: 'stateset_get_api_metrics',
  arguments: {}
});

// Get cache statistics
await client.callTool({
  name: 'stateset_cache_stats',
  arguments: { namespace: 'orders' }
});

// Get rate limit status
await client.callTool({
  name: 'stateset_tool_rate_limits',
  arguments: { category: 'read' }
});

// Get WebSocket statistics
await client.callTool({
  name: 'stateset_websocket_stats',
  arguments: {}
});

跟踪的关键指标：

totalRequests - API 请求总数
requestsInLastHour - 最近的请求数
averageRequestTime - 平均响应时间（毫秒）
queueLength - 当前速率限制队列长度
cacheHitRate - 缓存有效率
circuitBreakerState - 保护状态
activeConnections - WebSocket 连接数

日志记录

支持配置级别的结构化 JSON 日志：

{
  "level": "info",
  "time": "2024-01-01T12:00:00.000Z",
  "context": "api",
  "method": "POST",
  "url": "/orders",
  "duration": 123,
  "status": 200,
  "msg": "API request completed"
}

🤝 参与贡献

欢迎贡献！详情请参阅贡献指南。

开发工作流

Fork 此仓库
创建功能分支（git checkout -b feature/amazing-feature）
提交更改（git commit -m 'Add amazing feature'）
将分支推送到远程仓库（git push origin feature/amazing-feature）
发起 Pull Request

代码规范

遵循 TypeScript 最佳实践
保持测试覆盖率在 80% 以上
使用 Conventional Commits 规范
为所有公共 API 编写文档
为复杂函数添加 JSDoc 注释

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🙏 致谢

感谢 Model Context Protocol 提供 MCP 规范
感谢 StateSet 提供全面的电商 API
感谢所有贡献者和用户

🔧 故障排除

常见问题

服务无法启动

# Check if API key is set
echo $STATESET_API_KEY

# Verify environment file
cat .env

# Check for port conflicts
lsof -i :8081

速率限制错误

// Check rate limit status
await client.callTool({
  name: 'stateset_tool_rate_limits',
  arguments: {}
});

// Increase limits in .env
REQUESTS_PER_HOUR=2000
REQUESTS_PER_MINUTE=100

熔断器已打开

// Check health status
await client.callTool({
  name: 'stateset_health_check',
  arguments: { include_details: true }
});

// Circuit breaker will automatically reset after timeout
// Or disable in .env for testing:
CIRCUIT_BREAKER_ENABLED=false

缓存问题

// Clear cache if data seems stale
await client.callTool({
  name: 'stateset_clear_cache',
  arguments: { namespace: 'orders' }
});

// Check cache statistics
await client.callTool({
  name: 'stateset_cache_stats',
  arguments: {}
});

WebSocket 连接失败

# Check if WebSocket port is available
lsof -i :8081

# Verify WebSocket is enabled
grep FEATURE_WEBSOCKET .env

# Check firewall rules
sudo ufw status

调试模式

启用详细日志以排查问题：

LOG_LEVEL=debug npm run dev

🚀 性能提示

针对高吞吐量进行优化

启用缓存

CACHE_ENABLED=true
CACHE_TTL=600  # Increase TTL for less volatile data
CACHE_MAX_SIZE=5000

调整速率限制

REQUESTS_PER_HOUR=5000
REQUESTS_PER_MINUTE=200
BURST_SIZE=50

使用批量操作

// Instead of multiple single calls
await client.callTool({
  name: 'stateset_batch_create_orders',
  arguments: { orders: [...], options: { parallel: true } }
});

连接池

# Already enabled by default
# Adjust pool size if needed in code

调整熔断器

CIRCUIT_BREAKER_THRESHOLD=10  # Allow more failures
CIRCUIT_BREAKER_TIMEOUT=30000  # Faster recovery

📞 支持

📧 电子邮件：[email protected]
💬 Discord：加入我们的社区
📚 文档：docs.stateset.io
🐛 问题反馈：GitHub Issues
🌐 网站：stateset.io

🗺️ 路线图

近期已完成

基于 Redis 的分布式缓存
混合内存/Redis 缓存，支持自动回退
用于分布式追踪的请求关联 ID
采用指数退避和抖动的重试策略
自适应缓存，支持自动调整 TTL 和缓存预热
优雅降级，支持自动回退
按工具收集指标，并提供耗时直方图
增强输入验证（防范 XSS、命令注入和路径遍历）
在日志中屏蔽敏感数据

即将推出

考虑中

除 stdio 外，支持 HTTP/REST 传输
支持用于高性能场景的 gRPC
用于自定义工具的插件系统
支持多区域部署
高级工作流自动化

🙏 致谢

基于以下项目构建：

Model Context Protocol SDK - MCP 实现
TypeScript - 类型安全开发
Zod - 模式验证
Axios - HTTP 客户端
Pino - 高性能日志记录
Jest - 测试框架
WebSocket (ws) - 实时通信

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。