StateSet MCP

MCP浏览器工具

提供方 stateset

浏览器工具 stdio · 本地进程 API Key 社区 / 第三方
查看接入方式

用于StateSet API集成的生产就绪模型上下文协议(MCP)服务器,通过标准化接口提供全面的电子商务和供应链运营管理。

一句话选型结论

按资料字段整理

StateSet MCP 属于浏览器工具类 MCP 服务器,stdio · 本地进程,API Key,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类浏览器工具 传输方式stdio · 本地进程 鉴权API Key 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 153 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

浏览器工具
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量153暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

适用场景

HTML本地部署电子商务供应链管理API集成企业级可靠性实时更新

安装与配置

stdio · 本地进程 API Key
客户端在本机拉起子进程,数据不出本机
docker run --env-file .env stateset-mcp-server

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Docker,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 153 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
自动操作网页

打开页面、点击、填表,把浏览器动作交给模型执行。

抓取结构化数据

把页面内容整理成表格或 JSON,省掉手工复制粘贴。

关键流程回归

按步骤检查页面是否正常,回归时少漏环节。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 153 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在浏览器工具场景里让模型直接调用外部能力的人。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
StateSet MCP当前 153 stdio · 本地进程 本地部署 有 2026-05-17
Playwright MCP Server 21 stdio · 本地进程 本地部署 有 2026-05-18
Fetch 9a2682de 1 SSE · 服务端推送 支持远程部署 有 2026-05-18
Browser 738d52bc 未标注 stdio · 本地进程 本地部署 有 2026-05-17
MCP 40600ece 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Skyvern MCP 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

浏览器工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方stateset上游标注的维护方 stateset
分类浏览器工具本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Docker本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

34.3 KB
来自项目仓库与上游目录的原文,未做删改

状态集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
  1. 调整速率限制```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 } }
});
  1. 连接池```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) -实时通信

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
StateSet MCP 怎么安装?

在客户端按下面的安装命令接入:docker run --env-file .env stateset-mcp-server。装完在客户端配置里引用同一个包或端点。

StateSet MCP 怎么在客户端里配置?

它的传输方式未标注,在客户端 MCP 配置里按官方文档填写启动命令和参数,保存后重启客户端生效。

StateSet MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

StateSet MCP 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

StateSet MCP 能提供哪些能力?

资料显示约 153 个工具;能力标签包括 电子商务、HTML、实时更新。具体工具清单以官方文档为准。

StateSet MCP 需要什么运行环境?

运行时为 Docker;属于本地进程,需要在本机装好运行环境。

StateSet MCP 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。