状态集MCP服务器
用于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```bash
npm install -g stateset-mcp-server
### 使用Docker```bash
docker pull stateset/mcp-server:latest
来源```bash
git clone https://github.com/stateset/mcp-server.git
cd mcp-server
npm install
npm run build
## 🏃 快速开始
### 1.安装```bash
# 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.配置```bash
Copy environment template
cp .env.example .env
Edit .env with your StateSet API credentials
Required: STATESET_API_KEY=your_api_key_here
### 3.运行服务器```bash
# 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通信:```javascript
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服务器:```javascript
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 |
时间电路保持打开(ms) | 60000 |
CIRCUIT_BREAKER_RESET_TIMEOUT |
重置尝试前的时间(ms) | 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 |
启用OpenTetry跟踪 | false |
服务器配置
| 变量 | 描述 | 默认值 |
|---|---|---|
NODE_ENV |
环境(开发/阶段/生产/测试) | production |
LOG_LEVEL |
日志记录级别(跟踪/调试/信息/警告/错误/致命) | info |
API_TIMEOUT_MS |
请求超时(毫秒) | 10000 |
WEBSOCKET_PORT |
WebSocket服务器端口 | 8081 |
METRICS_INTERVAL |
度量收集间隔(ms) | 60000 |
HEALTH_CHECK_INTERVAL |
健康检查间隔(ms) | 30000 |
💡 使用示例
基本操作```javascript
// 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 }
});
### 高级搜索```javascript
// 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'
}
});
批量操作```javascript
// 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 }
}
});
### 退货处理工作流程```javascript
// 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}`
}
});
制造工作流程```javascript
// 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'
}
});
### 资源访问```javascript
// 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
示例用法:```javascript
// 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
### 设置```bash
# 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文档 |
🧪 测试
运行测试```bash
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转换
- ✅ 工具调度器和注册表
- ✅ 批处理操作
- ✅ 健康检查端点
### 写作测试```typescript
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:```bash
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部署```yaml
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工具进行健康监测:```javascript
// 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工具访问详细指标:```javascript
// 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日志:```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. 分叉存储库
1. 创建要素分支(`git checkout -b feature/amazing-feature`)
1. 提交您的更改(`git commit -m 'Add amazing feature'`)
1. 推到分支(`git push origin feature/amazing-feature`)
1. 打开拉取请求
### 代码规范
- 遵循TypeScript的最佳实践
- 保持80%以上的测试覆盖率
- 使用常规提交
- 记录所有公共API
- 为复杂函数添加JSDoc注释
## 📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
## 🙏 致谢
- 模型上下文协议 对于MCP规范
- 渲染状态集 用于综合电子商务API
- 我们所有的贡献者和用户
## 🔧 故障排除
### 常见问题
#### 服务器无法启动```bash
# Check if API key is set
echo $STATESET_API_KEY
# Verify environment file
cat .env
# Check for port conflicts
lsof -i :8081
速率限制错误```javascript
// 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
#### 断路器打开```javascript
// 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
缓存问题```javascript
// 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连接失败```bash
# Check if WebSocket port is available
lsof -i :8081
# Verify WebSocket is enabled
grep FEATURE_WEBSOCKET .env
# Check firewall rules
sudo ufw status
调试模式
启用详细日志以进行故障排除:```bash
LOG_LEVEL=debug npm run dev
## 🚀 性能提示
### 优化以实现高吞吐量
1. **启用缓存**```bash
CACHE_ENABLED=true
CACHE_TTL=600 # Increase TTL for less volatile data
CACHE_MAX_SIZE=5000
- 调整速率限制```bash
REQUESTS_PER_HOUR=5000
REQUESTS_PER_MINUTE=200
BURST_SIZE=50
1. **使用批处理操作**```javascript
// Instead of multiple single calls
await client.callTool({
name: 'stateset_batch_create_orders',
arguments: { orders: [...], options: { parallel: true } }
});
- 连接池```bash
Already enabled by default
Adjust pool size if needed in code
1. **断路器调谐**```bash
CIRCUIT_BREAKER_THRESHOLD=10 # Allow more failures
CIRCUIT_BREAKER_TIMEOUT=30000 # Faster recovery
📞 支持
- 📧 电子邮件: support@stateset.io
- 📚 文档: docs.stateset.io
- 🐛 问题: GitHub问题
- 🌐 网站: 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) -实时通信
