StateSet MCP

状态集MCP服务器

  ](https://badge.fury.io/js/stateset-mcp-server)   ](https://nodejs.org/) 

用于StateSet API集成的生产就绪模型上下文协议（MCP）服务器，通过标准化接口提供全面的电子商务和供应链运营管理。具有企业级可靠性、性能和可观察性。

📖 文档

• 架构指南 -系统设计和组件概述
• 测试指导 -测试策略和覆盖范围
• API 文档 -生成的TypeDoc API引用
• 贡献指南 -如何做出贡献

🚀 特性

核心能力

• 166 MCP工具：通过完整的工作流支持，完成订单、退货、库存、产品、客户、发货、制造和财务操作的CRUD操作
• 高级搜索：跨所有资源的多过滤器搜索，包括排序、分页、聚合和全文搜索
• 批量操作：通过可配置的并行性和错误处理原子地执行多个操作
• 实时更新：WebSocket支持实时事件流和资源更改通知
• 资源模板：基于URI的资源访问（例如。， stateset-order:///ORD-123)

企业级可靠性

• 智能高速缓存：LRU/LFU/FIFO缓存策略，具有自适应TTL、自动缓存预热和可选的分布式缓存Redis支持
• 断路器：自动故障检测和恢复，以防止级联故障
• 速率限制：具有每个工具限制和突发支持的令牌桶算法
• 连接池：通过健康检查和自动重新连接实现高效的连接重用
• 故障弱化：当服务不可用时，使用过时的缓存数据自动回退策略
• 重试策略：具有抖动和智能错误分类的指数退避
• 优雅地关闭：正确清理连接、缓存和后台任务

安全与验证

• 输入消毒：XSS防御、SQL注入保护、命令注入检测和HTML标记剥离
• 路径横向保护：检测和阻止路径遍历尝试
• API密钥安全：使用敏感数据屏蔽对日志和错误消息进行自动编辑
• 请求验证：具有全面类型检查的Zod模式
• CORS和头盔：安全标头和跨源请求保护

可观测性

• 结构化日志记录：基于Pino的JSON日志记录，带有相关ID和请求上下文
• 请求关联：通过异步操作传播的分布式跟踪相关ID
• 普罗米修斯指标：请求计数、持续时间、错误率、缓存命中率和队列长度
• 工具指标：使用持续时间直方图、错误率和类别分析进行每工具执行跟踪
• 健康检查：Kubernetes部署的生存性和就绪性探测
• 开放遥测：分布式跟踪支持（可选）
• 性能监控：请求计时、重试跟踪、断路器状态和慢速工具检测

开发者体验

• 类型安全：使用TypeScript 5.7构建，以实现最大的类型安全性和IntelliSense支持
• 测试良好：297项测试通过21个测试套件的测试，覆盖单元和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 并配置以下变量：

所需配置

速率限制

缓存

Redis配置（可选）

断路器

功能开关

服务器配置

💡 使用示例

基本操作

// Create a customer
const customer = await client.callTool({
  name: 'stateset_create_customer',
  arguments: {
    email: 'customer@example.com',
    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
• 自治系统号: 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

项目脚本

🧪 测试

运行测试

# 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: 'test@example.com',
      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"

云部署

• 亚马逊云服务：使用提供的Docker镜像的ECS或EKS
• 谷歌云：部署到云运行或GKE
• Azure：使用容器实例或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"
}

🤝 贡献

我们欢迎捐款！请查看我们的 贡献指南 了解详情。

开发流程

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

代码规范

• 遵循TypeScript的最佳实践
• 保持80%以上的测试覆盖率
• 使用常规提交
• 记录所有公共API
• 为复杂函数添加JSDoc注释

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 模型上下文协议 对于MCP规范
• 渲染状态集 用于综合电子商务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

🚀 性能提示

优化以实现高吞吐量

1. 启用缓存

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

1. 调整速率限制

   REQUESTS_PER_HOUR=5000
   REQUESTS_PER_MINUTE=200
   BURST_SIZE=50

1. 使用批处理操作

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

1. 连接池

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

1. 断路器调谐

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

📞 支持

• 📧 电子邮件: support@stateset.io
• 💬 Discord 的中文翻译是“不和谐”或“纷争”。: 加入我们的社区
• 📚 文档: docs.stateset.io
• 🐛 问题:
• 🌐 网站: stateset.io

🗺️ 路线图

最近完成

• \[x\] 基于Redis的分布式缓存
• \[x\] 混合内存/Rdis缓存，具有自动回退功能
• \[x\] 请求分布式跟踪的关联ID
• \[x\] 具有指数回退和抖动的重试策略
• \[x\] 具有自动TTL调谐和缓存预热功能的自适应缓存
• \[x\] 优雅的降级，自动回退
• \[x\] 使用持续时间直方图收集每个工具的指标
• \[x\] 增强的输入验证（XSS、命令注入、路径遍历保护）
• \[x\] 日志中的敏感数据屏蔽

即将推出

• \[\]GraphQL API支持
• \[\]Webhook事件传递
• \[\]多租户支持
• \[\]增强的人工智能洞察力和预测能力
• \[\]与流行的电子商务平台集成
• \[\]实时分析仪表板
• \[\]审核日志记录和合规性功能

考虑中

• HTTP/REST传输与stdio一起使用
• 对高性能场景的gRPC支持
• 自定义工具插件系统
• 多区域部署支持
• 高级工作流自动化

🙏 鸣谢

内置：

• 模型上下文协议SDK -MCP实施
• TypeScript -类型安全开发
• 萨德 -架构验证
• 阿西奥斯 -HTTP客户端
• 皮诺 -高性能日志记录
• 测试 -测试框架
• Websocket（WS） -实时通信