Stateset MCP Server

StateSet MCP サーバー

StateSet API と連携する、本番環境に対応した Model Context Protocol（MCP）サーバーです。標準化されたインターフェースを通じて、包括的な E コマースおよびサプライチェーン業務管理を提供します。エンタープライズグレードの信頼性、パフォーマンス、可観測性を備えています。

📖 ドキュメント

• アーキテクチャガイド - システム設計とコンポーネントの概要
• テストガイド - テスト戦略とカバレッジ
• API ドキュメント - TypeDoc で生成された API リファレンス
• コントリビューションガイド - コントリビューションの方法

🚀 機能

コア機能

• 166 個の MCP ツール：注文、返品、在庫、製品、顧客、出荷、製造、財務業務の CRUD 操作を包括的に提供し、ワークフローを完全にサポートします
• 高度な検索：すべてのリソースを対象に、複数のフィルター、並べ替え、ページネーション、集計、全文検索を利用できます
• バッチ操作：並列処理数とエラー処理を設定し、複数の操作をアトミックに実行できます
• リアルタイム更新：WebSocket によるライブイベントのストリーミングとリソース変更通知をサポートします
• リソーステンプレート：URI ベースのリソースアクセス（例：stateset-order:///ORD-123）

エンタープライズグレードの信頼性

• インテリジェントキャッシュ：適応型 TTL、自動キャッシュウォーミング、分散キャッシュ向けのオプションの Redis サポートを備えた LRU／LFU／FIFO キャッシュ戦略
• サーキットブレーカー：障害を自動検出して回復し、連鎖障害を防止します
• レート制限：ツールごとの制限とバースト処理に対応したトークンバケットアルゴリズム
• コネクションプーリング：ヘルスチェックと自動再接続による効率的な接続の再利用
• グレースフルデグラデーション：サービスが利用できない場合、古いキャッシュデータを使ったフォールバック戦略に自動的に切り替えます
• リトライ戦略：ジッターとインテリジェントなエラー分類を備えた指数バックオフ
• グレースフルシャットダウン：接続、キャッシュ、バックグラウンドタスクを適切にクリーンアップします

セキュリティと検証

• 入力のサニタイズ：XSS 防止、SQL インジェクション対策、コマンドインジェクション検出、HTML タグの除去
• パストラバーサル対策：パストラバーサルの試みを検出してブロックします
• API キーのセキュリティ：ログやエラーメッセージ内の API キーを自動的に隠し、機密データをマスキングします
• リクエスト検証：包括的な型チェックを備えた Zod スキーマ
• CORS と Helmet：セキュリティヘッダーとクロスオリジンリクエスト保護

可観測性

• 構造化ログ：相関 ID とリクエストコンテキストを備えた Pino ベースの JSON ロギング
• リクエスト相関：分散トレーシングのため、非同期処理全体に相関 ID を伝播します
• Prometheus メトリクス：リクエスト数、処理時間、エラー率、キャッシュヒット率、キュー長
• ツールメトリクス：処理時間のヒストグラム、エラー率、カテゴリ分析を含む、ツールごとの実行状況の追跡
• ヘルスチェック：Kubernetes デプロイ向けの liveness および readiness プローブ
• OpenTelemetry：分散トレーシングをサポートします（オプション）
• パフォーマンス監視：リクエスト時間、リトライの追跡、サーキットブレーカーの状態、処理の遅いツールの検出

開発者エクスペリエンス

• 型安全：最大限の型安全性と IntelliSense サポートを実現する TypeScript 5.7 で構築されています
• 十分なテスト：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 クライアントに接続する

サーバーは MCP 通信に stdio トランスポートを使用します。

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	1 時間あたりの API リクエスト最大数	1000
REQUESTS_PER_MINUTE	1 分あたりの 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	メトリクスの収集間隔（ms）	60000
HEALTH_CHECK_INTERVAL	ヘルスチェックの間隔（ms）	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：提供されている Docker イメージを使用して ECS または EKS にデプロイします
• 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"
}

🤝 貢献

皆さまからの貢献を歓迎します！詳細については、貢献ガイドをご覧ください。

開発ワークフロー

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％以上に維持してください
• Conventional Commits を使用してください
• すべての公開 API を文書化してください
• 複雑な関数には JSDoc コメントを追加してください

📄 ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。

🙏 謝辞

• MCP 仕様については Model Context Protocol に感謝します
• 包括的な e コマース API については StateSet に感謝します
• すべての貢献者とユーザーに感謝します

🔧 トラブルシューティング

よくある問題

サーバーが起動しない

# 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
   

2. レート制限を調整する

   REQUESTS_PER_HOUR=5000
   REQUESTS_PER_MINUTE=200
   BURST_SIZE=50
   

3. バッチ操作を使用する

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

4. コネクションプーリング

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

5. サーキットブレーカーを調整する

   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、コマンドインジェクション、パストラバーサル対策）
• ログ内の機密データのマスキング

近日公開

• GraphQL API のサポート
• Webhook イベントの配信
• マルチテナントのサポート
• AI による分析と予測の強化
• 人気の e コマースプラットフォームとの連携
• リアルタイム分析ダッシュボード
• 監査ログとコンプライアンス機能

検討中

• stdio に加えて HTTP/REST トランスポートをサポート
• 高パフォーマンスが求められる環境向けの gRPC サポート
• カスタムツール用のプラグインシステム
• マルチリージョンデプロイのサポート
• 高度なワークフロー自動化

🙏 クレジット

以下を使用して構築されています：

• Model Context Protocol SDK - MCP の実装
• TypeScript - 型安全な開発
• Zod - スキーマ検証
• Axios - HTTP クライアント
• Pino - 高パフォーマンスなロギング
• Jest - テストフレームワーク
• WebSocket (ws) - リアルタイム通信