Simplified MCP Server

Simplified MCP Server

Claude、Cursor、Kiro（およびその他の MCP 対応プラットフォーム）とSimplified の APIをシームレスに統合する、Model Context Protocol（MCP）サーバーです。このサーバーを使用すると、LLM は標準化された MCP ツールを通じて Simplified のサービスを利用でき、複数のプラットフォームでソーシャルメディアアカウントの管理や投稿の作成ができます。

特長

• MCP プロトコルを完全サポート：公式の @modelcontextprotocol/sdk を使用して構築
• ソーシャルメディア管理：ソーシャルメディアアカウントと投稿を包括的に管理
• マルチプラットフォーム対応：Facebook、Instagram、Twitter、LinkedIn、TikTok、YouTube、Pinterest、Threads、Google Business Profile、Bluesky に対応
• 型安全な実装：完全な型安全性を備えた TypeScript で記述
• 堅牢なエラー処理：詳細なエラーメッセージを含む包括的なエラー処理
• 設定可能なログ：デバッグと監視のためにログレベルを調整可能
• プラットフォーム固有の機能：Google Business Profile、TikTok、YouTube、Instagram などの高度なプラットフォーム固有設定
• スケジュール設定に対応：プラットフォーム固有の設定を指定して、スケジュール投稿を作成
• 認証管理：自動リトライロジックを備えた、安全な API トークン管理

インストール

前提条件

• Node.js 18.0.0 以降
• npm 8.0.0 以降
• Simplified API トークン

NPM からインストール

npm install -g simplified-mcp-server

ソースからインストール

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

DXT ファイルをパッケージ化

npm install -g @anthropic-ai/dxt
npx @anthropic-ai/dxt pack        

設定

サーバーは環境変数を使用して設定します。プロジェクトのルートに .env ファイルを作成するか、環境変数を設定してください。

必須の設定

変数	説明	例
SIMPLIFIED_API_TOKEN	Simplified API トークン	sk_live_abc123...

任意の設定

変数	説明	デフォルト	選択肢
SIMPLIFIED_API_BASE_URL	Simplified API のベース URL	https://api.simplified.com	有効な URL
LOG_LEVEL	ログの詳細レベル	info	debug、info、warn、error
REQUEST_TIMEOUT	API リクエストのタイムアウト（ms）	30000	正の数値
RETRY_ATTEMPTS	リトライ回数	3	0 以上の数値
RETRY_DELAY	リトライ間隔（ms）	1000	正の数値

ワークフローツールの設定

このサーバーは、利用可能なワークフローを自動的に検出してツールを登録する、動的なワークフローツールに対応しています。この機能はデフォルトでは無効で、環境変数を設定して有効にできます。

変数	説明	デフォルト	範囲／選択肢
WORKFLOWS_ENABLED	動的なワークフローツールを有効にする	false	true、false
WORKFLOW_DISCOVERY_INTERVAL	自動更新の間隔（ms）	0（無効）	0-86400000（0 = 無効）
WORKFLOW_EXECUTION_TIMEOUT	実行タイムアウト（ms）	300000（5 分）	1000-3600000
WORKFLOW_MAX_CONCURRENT_EXECUTIONS	同時実行数の上限	10	1-100
WORKFLOW_FILTER_PATTERNS	カンマ区切りの名前パターン	``（なし）	ワイルドカードパターン
WORKFLOW_STATUS_CHECK_INTERVAL	ステータス確認の間隔（ms）	5000	1000-300000
WORKFLOW_RETRY_ATTEMPTS	失敗時のリトライ回数	3	0-10

設定例

# Required
SIMPLIFIED_API_TOKEN=sk_live_your_token_here

# Optional - Basic Configuration
SIMPLIFIED_API_BASE_URL=https://api.simplified.com
LOG_LEVEL=info
REQUEST_TIMEOUT=30000
RETRY_ATTEMPTS=3
RETRY_DELAY=1000

# Optional - Workflow Configuration
WORKFLOWS_ENABLED=true
WORKFLOW_DISCOVERY_INTERVAL=300000
WORKFLOW_EXECUTION_TIMEOUT=600000
WORKFLOW_MAX_CONCURRENT_EXECUTIONS=10
WORKFLOW_FILTER_PATTERNS=data-*,report-*
WORKFLOW_STATUS_CHECK_INTERVAL=5000
WORKFLOW_RETRY_ATTEMPTS=3

環境別の設定例

開発環境

# Development settings for faster feedback
WORKFLOWS_ENABLED=true
WORKFLOW_DISCOVERY_INTERVAL=60000          # 1 minute refresh
WORKFLOW_EXECUTION_TIMEOUT=120000          # 2 minute timeout
WORKFLOW_MAX_CONCURRENT_EXECUTIONS=5       # Lower concurrency
WORKFLOW_STATUS_CHECK_INTERVAL=2000        # 2 second polling
WORKFLOW_RETRY_ATTEMPTS=1                  # Fewer retries
LOG_LEVEL=debug

本番環境

# Production settings for stability and performance
WORKFLOWS_ENABLED=true
WORKFLOW_DISCOVERY_INTERVAL=600000         # 10 minute refresh
WORKFLOW_EXECUTION_TIMEOUT=600000          # 10 minute timeout
WORKFLOW_MAX_CONCURRENT_EXECUTIONS=20      # Higher concurrency
WORKFLOW_STATUS_CHECK_INTERVAL=10000       # 10 second polling
WORKFLOW_RETRY_ATTEMPTS=5                  # More retries
LOG_LEVEL=warn

使用方法

プログラムからの使用

import { SimplifiedMCPServer } from 'simplified-mcp-server';
import { ConfigurationManager } from 'simplified-mcp-server/config';

async function startServer() {
  const config = ConfigurationManager.loadConfig();
  const server = new SimplifiedMCPServer(config);
  await server.start();
}

startServer().catch(console.error);

Claude との統合

Claude の MCP 設定にサーバーを追加します。

{
   "mcpServers": {
      "simplified": {
        "command": "node",
        "args": [
          "{PATH_TO_CLONED_REPOSITORY}/dist/cli.js",
          "start"
        ],
        "env": {
          "SIMPLIFIED_API_TOKEN": "your_token_here",
          "SIMPLIFIED_API_BASE_URL": "https://api.simplified.com",
          "LOG_LEVEL": "info",
          "WORKFLOWS_ENABLED": "true",
          "WORKFLOW_EXECUTION_TIMEOUT": "600000"
        }
      }
    }
}

DXT 拡張機能をインストールします。

Extensions -> Advanced settings -> Install Extension...

simplified-mcp.dxt ファイルを選択します。 トークンを追加します。

Kiro との統合

Kiro の MCP 設定にサーバーを追加します。

{
  "mcpServers": {
    "simplified": {
      "command": "simplified-mcp-server",
      "env": {
        "SIMPLIFIED_API_TOKEN": "your_token_here",
        "WORKFLOWS_ENABLED": "true",
        "WORKFLOW_DISCOVERY_INTERVAL": "300000",
        "WORKFLOW_EXECUTION_TIMEOUT": "600000"
      }
    }
  }
}

利用可能なツール

サーバーは、プラットフォーム固有の機能を備えた包括的なソーシャルメディア管理ツールに加え、機能を拡張する動的ワークフローツールを提供します。

生成されるツール

サーバーのツールの大部分は、simplified-apikit の OpenAPI 仕様から生成されます。npm run generate:tools を実行すると再生成できます。このコマンドは、SIMPLIFIED_APIKIT_SPECS_PATH で設定されたパス（デフォルトでは simplified-apikit リポジトリのローカルチェックアウト）から仕様を読み込み、コミット対象の TypeScript 記述子ファイルを src/tools/generated/ に書き込みます。上流の仕様が変更されたら、再生成して更新された src/tools/generated/ ファイルをコミットしてください。

ツールは仕様ごとに 1 つのグループにまとめられています。グループは social_media、smp_pm、celeryhq、image_tools、video_tools、audio_tools、comments、agent_notification です。各グループは個別に有効／無効を切り替えられます。

変数	説明	デフォルト
TOOLS_SOCIAL_MEDIA_ENABLED	social_media グループを有効／無効にします	true
TOOLS_SMP_PM_ENABLED	smp_pm グループを有効／無効にします	true
TOOLS_CELERYHQ_ENABLED	celeryhq グループを有効／無効にします	true
TOOLS_IMAGE_TOOLS_ENABLED	image_tools グループを有効／無効にします	true
TOOLS_VIDEO_TOOLS_ENABLED	video_tools グループを有効／無効にします	true
TOOLS_AUDIO_TOOLS_ENABLED	audio_tools グループを有効／無効にします	true
TOOLS_COMMENTS_ENABLED	comments グループを有効／無効にします	true
TOOLS_AGENT_NOTIFICATION_ENABLED	agent_notification グループを有効／無効にします	true

ツール呼び出しで指定されなかった場合に使用する、デフォルトのワークスペーススコープ用ヘッダーを設定する任意の変数が 2 つあります。

変数	説明
SIMPLIFIED_ORGANIZATION_ID	リクエストヘッダーとして送信されるデフォルトの組織 ID
SIMPLIFIED_SPACE_ID	リクエストヘッダーとして送信されるデフォルトのスペース ID

ソーシャルメディアツール

ソーシャルメディアアカウントや投稿を管理するためのツールです。

get_social_media_accounts

接続されているすべてのソーシャルメディアアカウントを取得します。

パラメーター：

• network（任意）：プラットフォームで絞り込みます（facebook、instagram、linkedin、tiktok、youtube、pinterest、threads、google、bluesky、tiktokBusiness）

例：

{
  "name": "get_social_media_accounts",
  "arguments": {
    "network": "instagram"
  }
}

create_social_media_post

Google、TikTok、Threads、YouTube、Facebook、LinkedIn、Instagram、Pinterest 向けのプラットフォーム固有の設定を使用して、新しいソーシャルメディア投稿を作成します。

パラメーター：

• message（必須）：投稿メッセージ／コンテンツ（1～5000 文字）
• accountId（必須）：ソーシャルメディアアカウント ID
• action（必須）：実行するアクション（schedule、add_to_queue、draft）
• date（任意）：投稿の予約日時（形式：YYYY-MM-DD HH:MM）
• media（任意）：添付するメディアファイル URL の配列（最大 10 件）
• additional（任意）：プラットフォーム固有の投稿設定とメタデータ

基本的な例：

{
  "name": "create_social_media_post",
  "arguments": {
    "message": "Excited to announce our new product launch! 🚀",
    "accountId": "acc_fb123",
    "action": "schedule",
    "date": "2024-01-22 12:00",
    "media": [
      "https://example.com/product-image.jpg",
      "https://example.com/launch-video.mp4"
    ],
    "additional": {}
  }
}

メディアファイル

media パラメーターには、メディアファイルを指す URL 文字列の配列を指定します。

{
  "media": [
    "https://example.com/image1.jpg",
    "https://example.com/video.mp4",
    "https://example.com/image2.png"
  ]
}

メディアの要件：

• 投稿ごとのメディアファイルは最大 10 件です
• URL は一般公開されている必要があります
• 対応形式はプラットフォームによって異なります（画像：JPG、PNG、GIF、動画：MP4、MOV など）

プラットフォーム固有の機能

additional パラメーターでは、プラットフォーム固有の設定を指定できます。

Google ビジネス プロフィール

{
  "additional": {
    "google": {
      "post": {
        "title": "New Product Launch",
        "topicType": "OFFER",
        "couponCode": "LAUNCH20",
        "callToActionUrl": "https://example.com/product",
        "callToActionType": "SHOP",
        "termsConditions": "Valid until end of month"
      }
    }
  }
}

TikTok／TikTok Business

{
  "additional": {
    "tiktok": {
      "post": {
        "brandContent": true,
        "privacyStatus": "PUBLIC_TO_EVERYONE",
        "duetDisabled": false,
        "commentDisabled": false
      },
      "channel": { "value": "direct" },
      "postType": { "value": "video" }
    }
  }
}

YouTube

{
  "additional": {
    "youtube": {
      "post": {
        "title": "Product Launch Video",
        "license": "standard",
        "privacyStatus": "public",
        "selfDeclaredMadeForKids": "no"
      },
      "postType": { "value": "short" }
    }
  }
}

Instagram

{
  "additional": {
    "instagram": {
      "postReel": {
        "audioName": "Trending Audio Track",
        "shareToFeed": true
      },
      "postType": { "value": "reel" }
    }
  }
}

Pinterest

{
  "additional": {
    "pinterest": {
      "post": {
        "link": "https://example.com/product",
        "title": "Amazing Product",
        "imageAlt": "Product showcase image"
      }
    }
  }
}

LinkedIn

{
  "additional": {
    "linkedin": {
      "audience": { "value": "PUBLIC" }
    }
  }
}

Facebook

{
  "additional": {
    "facebook": {
      "postType": { "value": "feed" }
    }
  }
}

Threads

{
  "additional": {
    "threads": {
      "channel": { "value": "direct" }
    }
  }
}

動的ワークフローツール

このサーバーは、workflows-list-tool が提供するワークフローに基づいて、ツールを自動的に検出して登録する動的ワークフローツールに対応しています。この機能により、コードを変更することなく、ワークフローベースの機能を標準的な MCP ツールとして公開できます。

ワークフローツールの有効化

動的なワークフローツールを有効にするには、次の環境変数を設定します。

WORKFLOWS_ENABLED=true

有効にすると、サーバーは次の処理を行います。

1. workflows-list-tool を呼び出して、利用可能なワークフローを検出します
2. 検出した各ワークフローに対して、MCP ツールを自動的に登録します
3. 標準の MCP ツール呼び出しを通じて、ワークフローの実行を処理します
4. 実行中のワークフローのステータス確認機能を提供します

ワークフローツールの検出

サーバーは、ワークフロー定義の配列を返す workflows-list-tool を呼び出して、ワークフローを検出します。各ワークフローは次のスキーマに準拠している必要があります。

{
  "id": "workflow-123",
  "name": "Data Analysis Workflow",
  "description": "Analyzes data and generates reports",
  "category": "analytics",
  "version": "1.0.0",
  "inputSchema": {
    "type": "object",
    "properties": {
      "dataset": {
        "type": "string",
        "description": "Path to the dataset file"
      },
      "format": {
        "type": "string",
        "enum": ["csv", "json", "xlsx"],
        "description": "Data format"
      }
    },
    "required": ["dataset"]
  },
  "executionType": "async",
  "metadata": {
    "estimatedDuration": "5-10 minutes",
    "resourceRequirements": "medium"
  }
}

ワークフローツールの使用

検出されたワークフローツールは、標準の MCP ツール一覧に表示され、他のツールと同じように呼び出せます。

{
  "name": "workflow-data-analysis-workflow",
  "arguments": {
    "dataset": "/path/to/data.csv",
    "format": "csv"
  }
}

ワークフロー実行の流れ

1. ツール呼び出し：MCP クライアントがパラメーターを指定してワークフローツールを呼び出します
2. 実行開始：サーバーがワークフロー実行エンドポイントに POST リクエストを送信します
3. ステータスのポーリング：サーバーがワークフローのステータスを、最小 1000ms の間隔でポーリングします
4. 結果の返却：サーバーが標準の MCP 形式でワークフローの結果を返します

実行レスポンスの例：

{
  "success": true,
  "data": {
    "workflowId": "workflow-123",
    "executionId": "exec-456",
    "status": "COMPLETED",
    "results": {
      "summary": "Analysis completed successfully",
      "reportUrl": "https://example.com/report.pdf",
      "metrics": {
        "recordsProcessed": 10000,
        "executionTime": "4m 32s"
      }
    }
  }
}

ワークフローのステータス確認

サーバーには、ワークフローの実行状況を監視するための組み込みの workflow-status-check ツールがあります。

{
  "name": "workflow-status-check",
  "arguments": {
    "workflowId": "workflow-123",
    "executionId": "exec-456"
  }
}

ステータスレスポンスには、次の情報が含まれます。

• 現在の実行ステータス（RUNNING、COMPLETED、FAILED、CANCELLED）
• 開始時刻と終了時刻
• 進行状況（利用可能な場合）
• 入力パラメーターと出力結果
• エラーの詳細（失敗した場合）

ワークフロー設定オプション

検出と更新

# Enable automatic workflow discovery
WORKFLOWS_ENABLED=true

# Refresh workflows every 5 minutes (300000ms)
WORKFLOW_DISCOVERY_INTERVAL=300000

実行管理

# Set workflow execution timeout to 10 minutes
WORKFLOW_EXECUTION_TIMEOUT=600000

# Allow up to 15 concurrent workflow executions
WORKFLOW_MAX_CONCURRENT_EXECUTIONS=15

# Check workflow status every 3 seconds
WORKFLOW_STATUS_CHECK_INTERVAL=3000

ワークフローのフィルタリング

# Only expose workflows matching these patterns
WORKFLOW_FILTER_PATTERNS=data-*,report-*,analysis-*

# This would expose workflows like:
# - data-processing-workflow
# - report-generation-workflow  
# - analysis-customer-workflow
# But not:
# - admin-cleanup-workflow
# - test-workflow

エラー処理

# Retry failed workflow operations up to 5 times
WORKFLOW_RETRY_ATTEMPTS=5

ワークフローツールの例

データ処理ワークフロー

{
  "name": "workflow-data-processor",
  "arguments": {
    "inputFile": "sales-data-2024.csv",
    "operations": ["clean", "aggregate", "analyze"],
    "outputFormat": "json"
  }
}

レポート生成ワークフロー

{
  "name": "workflow-monthly-report",
  "arguments": {
    "month": "2024-01",
    "includeCharts": true,
    "recipients": ["[email protected]"],
    "format": "pdf"
  }
}

機械学習ワークフロー

{
  "name": "workflow-ml-training",
  "arguments": {
    "dataset": "customer-behavior.csv",
    "algorithm": "random-forest",
    "testSplit": 0.2,
    "hyperparameters": {
      "n_estimators": 100,
      "max_depth": 10
    }
  }
}

プラットフォーム固有のオプション一覧

プラットフォーム	利用可能なオプション	説明
Google Business Profile	title、topicType、couponCode、callToActionUrl、callToActionType、termsConditions	CTA と特典を含むビジネス投稿の拡張機能
TikTok/TikTok Business	brandContent、privacyStatus、duetDisabled、stitchDisabled、commentDisabled	コンテンツ設定とエンゲージメント制御
YouTube	title、license、privacyStatus、selfDeclaredMadeForKids	動画のメタデータとコンプライアンス設定
Instagram	audioName、shareToFeed、postType	リール固有の設定とフィードへの共有
Pinterest	link、title、imageAlt	ピンのリンク先とアクセシビリティ
LinkedIn	audience	プロフェッショナル向けオーディエンスのターゲティング
Facebook	postType	コンテンツタイプの指定
Threads	channel	公開方法

ワークフローツール

検出したワークフローから自動的に生成される動的ツールです。これらのツールは、WORKFLOWS_ENABLED=true の場合にのみ利用できます。

workflow-status-check

実行中のワークフローのステータスを確認します。

パラメーター：

• workflowId（必須）：元のワークフロー ID
• executionId（必須）：ワークフローの実行 ID（UUID）

例：

{
  "name": "workflow-status-check",
  "arguments": {
    "workflowId": "data-processor-v2",
    "executionId": "8f496b6a-c905-41bb-b7b7-200a8982ab30"
  }
}

レスポンス：

{
  "success": true,
  "data": {
    "status": "RUNNING",
    "progress": 65,
    "startTime": 1753703781802,
    "estimatedCompletion": "2024-01-22T12:45:00Z",
    "input": {
      "dataset": "sales-data.csv",
      "format": "csv"
    },
    "output": null
  }
}

動的ワークフローツール

検出した各ワークフローは、workflow-{workflow-name} という命名パターンの個別の MCP ツールになります。ツールのパラメーターは、ワークフローの入力スキーマに基づいて動的に生成されます。

ワークフローツールの例：

• workflow-data-analysis - データセットを分析し、インサイトを生成します
• workflow-report-generator - レポートを自動生成します
• workflow-image-processor - 画像を処理および変換します
• workflow-email-campaign - ターゲットを絞ったメールキャンペーンを送信します
• workflow-backup-system - システムのバックアップを実行します

動的ツールの例：

{
  "name": "workflow-customer-segmentation",
  "arguments": {
    "customerData": "customers-2024.csv",
    "segmentationCriteria": ["age", "purchase_history", "location"],
    "outputFormat": "json",
    "includeVisualization": true
  }
}

動的ツールのレスポンス：

{
  "success": true,
  "data": {
    "executionId": "exec-789",
    "status": "COMPLETED",
    "results": {
      "segments": [
        {
          "name": "High Value Customers",
          "count": 1250,
          "criteria": "age: 25-45, purchases: >$500/month"
        },
        {
          "name": "Occasional Buyers",
          "count": 3400,
          "criteria": "age: 18-65, purchases: $50-$500/month"
        }
      ],
      "visualizationUrl": "https://example.com/segments-chart.png",
      "executionTime": "3m 45s"
    }
  }
}

エラー処理

サーバーは、詳細なエラーメッセージを含む包括的なエラー処理を提供します。

エラーの種類

• 設定エラー：設定がない、または無効です
• 認証エラー：API トークンが無効または期限切れです
• API エラー：Simplified の API で発生したエラーです
• ツール実行エラー：ツールの実行中に発生したエラーです
• 検証エラー：ツールのパラメーターが無効です
• ワークフロー検出エラー：ワークフローの検出または検証に問題があります
• ワークフロー実行エラー：ワークフローの実行に失敗しました
• ワークフロータイムアウトエラー：ワークフローの実行がタイムアウトの上限を超えました

エラーレスポンス形式

{
  "success": false,
  "error": "Error message",
  "details": {
    "type": "AUTHENTICATION_ERROR",
    "code": 401,
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

ワークフロー固有のエラー例

ワークフロー検出エラー

{
  "success": false,
  "error": "Failed to discover workflows",
  "details": {
    "type": "WORKFLOW_DISCOVERY_ERROR",
    "message": "workflows-list-tool is not available",
    "timestamp": "2024-01-01T00:00:00.000Z",
    "retryAfter": 300
  }
}

ワークフロー実行エラー

{
  "success": false,
  "error": "Workflow execution failed",
  "details": {
    "type": "WORKFLOW_EXECUTION_ERROR",
    "workflowId": "data-processor",
    "executionId": "exec-123",
    "status": "FAILED",
    "message": "Invalid input format: expected CSV, got JSON",
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

ワークフロータイムアウトエラー

{
  "success": false,
  "error": "Workflow execution timed out",
  "details": {
    "type": "WORKFLOW_TIMEOUT_ERROR",
    "workflowId": "long-running-analysis",
    "executionId": "exec-456",
    "timeout": 300000,
    "elapsed": 300001,
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

開発

ソースからのビルド

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

テストの実行

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

開発モード

# Start in development mode with auto-reload
npm run dev

# Start in development mode with watch
npm run dev:watch

プロジェクト構成

simplified-mcp-server/
├── src/
│   ├── index.ts              # Main entry point
│   ├── server.ts             # MCP server implementation
│   ├── cli.ts                # Command line interface
│   ├── config/
│   │   └── configuration.ts  # Configuration management
│   ├── tools/
│   │   ├── registry.ts       # Tool registry
│   │   ├── definitions.ts    # Tool definition utilities
│   │   └── implementations/  # Tool implementations
│   │       ├── social-media-tools.ts  # Social media management tools
│   │       └── index.ts               # Tool exports
│   ├── api/
│   │   └── client.ts         # Simplified API client
│   ├── utils/
│   │   ├── errors.ts         # Error handling utilities
│   │   └── logger.ts         # Logging utilities
│   └── types/
│       └── index.ts          # TypeScript type definitions
├── tests/                    # Test files
├── dist/                     # Compiled JavaScript
└── docs/                     # Documentation

ワークフロー設定ガイド

ワークフローツールについて

ワークフローツールは、外部のワークフロー定義に基づいてツールを自動的に検出、登録することで、サーバーの機能を拡張します。これにより、複雑なビジネスプロセス、データパイプライン、自動化ワークフローをシンプルな MCP ツールとして公開できます。

設定パラメーターの説明

WORKFLOWS_ENABLED

目的：ワークフロー機能のマスタースイッチ
デフォルト：false
推奨：workflows-list-tool を利用できる場合にのみ true に設定してください

# Enable workflow tools
WORKFLOWS_ENABLED=true

WORKFLOW_DISCOVERY_INTERVAL

目的：利用可能なワークフローのリストを更新する頻度
デフォルト：0（無効）
範囲：0-86400000 ms（0 = 無効、最大 = 24 時間）
推奨：

• 開発環境：迅速に反復できるよう 60000（1 分）
• 本番環境：安定性を確保するため 600000（10 分）
• ワークフローがほとんど変更されない場合は 0 に設定します

# Refresh every 5 minutes
WORKFLOW_DISCOVERY_INTERVAL=300000

# Disable automatic refresh
WORKFLOW_DISCOVERY_INTERVAL=0

WORKFLOW_EXECUTION_TIMEOUT

目的：ワークフローの完了を待つ最大時間
デフォルト：300000 ms（5 分）
範囲：1000-3600000 ms（1 秒から 1 時間）
推奨：最も実行時間の長いワークフローに合わせて設定してください

# For quick workflows (e.g., data validation)
WORKFLOW_EXECUTION_TIMEOUT=30000

# For long workflows (e.g., ML training)
WORKFLOW_EXECUTION_TIMEOUT=1800000

WORKFLOW_MAX_CONCURRENT_EXECUTIONS

目的：リソースの枯渇を防ぐため、同時に実行できるワークフローの数を制限します
デフォルト：10
範囲：1-100
推奨：

• 開発環境：リソースが制限された環境では 3-5
• 本番環境：サーバーの容量に応じて 10-20

# Conservative limit for development
WORKFLOW_MAX_CONCURRENT_EXECUTIONS=3

# Higher limit for production
WORKFLOW_MAX_CONCURRENT_EXECUTIONS=20

WORKFLOW_FILTER_PATTERNS

目的：ツールとして公開するワークフローを制御します
デフォルト：``（空 - すべてのワークフローを公開）
形式：ワイルドカードパターンをカンマ区切りで指定
例：

# Only expose data-related workflows
WORKFLOW_FILTER_PATTERNS=data-*

# Multiple patterns
WORKFLOW_FILTER_PATTERNS=data-*,report-*,analysis-*

# Exclude test workflows
WORKFLOW_FILTER_PATTERNS=*,-test-*,-dev-*

# Expose all workflows (default)
WORKFLOW_FILTER_PATTERNS=

WORKFLOW_STATUS_CHECK_INTERVAL

目的：実行中にワークフローのステータスを確認する頻度
デフォルト：5000 ms（5 秒）
範囲：1000-300000 ms（1 秒から 5 分）
推奨：応答性と API 負荷のバランスを考慮して設定してください

# Frequent polling for interactive workflows
WORKFLOW_STATUS_CHECK_INTERVAL=2000

# Less frequent polling to reduce API load
WORKFLOW_STATUS_CHECK_INTERVAL=10000

WORKFLOW_RETRY_ATTEMPTS

目的：ワークフロー操作に失敗した場合の再試行回数
デフォルト：3
範囲：0-10
推奨：

• 開発環境：失敗を迅速に把握するため 1
• 本番環境：信頼性を高めるため 3-5

# No retries for testing
WORKFLOW_RETRY_ATTEMPTS=0

# More retries for production reliability
WORKFLOW_RETRY_ATTEMPTS=5

設定のベストプラクティス

開発環境

# Fast feedback, lower resource usage
WORKFLOWS_ENABLED=true
WORKFLOW_DISCOVERY_INTERVAL=60000
WORKFLOW_EXECUTION_TIMEOUT=120000
WORKFLOW_MAX_CONCURRENT_EXECUTIONS=3
WORKFLOW_STATUS_CHECK_INTERVAL=2000
WORKFLOW_RETRY_ATTEMPTS=1
WORKFLOW_FILTER_PATTERNS=dev-*,test-*
LOG_LEVEL=debug

本番環境

# Stability and performance focused
WORKFLOWS_ENABLED=true
WORKFLOW_DISCOVERY_INTERVAL=600000
WORKFLOW_EXECUTION_TIMEOUT=600000
WORKFLOW_MAX_CONCURRENT_EXECUTIONS=15
WORKFLOW_STATUS_CHECK_INTERVAL=5000
WORKFLOW_RETRY_ATTEMPTS=3
WORKFLOW_FILTER_PATTERNS=prod-*
LOG_LEVEL=warn

テスト環境

# Predictable behavior for tests
WORKFLOWS_ENABLED=false
WORKFLOW_DISCOVERY_INTERVAL=0
WORKFLOW_EXECUTION_TIMEOUT=30000
WORKFLOW_MAX_CONCURRENT_EXECUTIONS=1
WORKFLOW_STATUS_CHECK_INTERVAL=1000
WORKFLOW_RETRY_ATTEMPTS=0
LOG_LEVEL=error

設定の検証

サーバーは起動時にすべてのワークフロー設定を検証し、無効な値に対して詳細なエラーメッセージを表示します。

# Example validation error
Configuration validation failed:
Invalid configuration values: workflowExecutionTimeout: Workflow execution timeout must be at least 1000ms (1 second)

Workflow configuration guidelines:
- Set WORKFLOW_DISCOVERY_INTERVAL to 0 to disable automatic refresh
- Use WORKFLOW_FILTER_PATTERNS to limit which workflows are exposed (e.g., "data-*,report-*")
- Minimum WORKFLOW_STATUS_CHECK_INTERVAL is 1000ms to avoid excessive API calls
- WORKFLOW_EXECUTION_TIMEOUT should be set based on your longest-running workflows

パフォーマンスに関する考慮事項

API のレート制限

• レート制限を避けるため、WORKFLOW_DISCOVERY_INTERVAL は 60 秒以上に設定してください
• ステータスのポーリングには、WORKFLOW_STATUS_CHECK_INTERVAL を 2 秒以上に設定してください
• API の合計負荷を考慮してください：検出 +（同時実行数 × ステータス確認回数）

リソース管理

• WORKFLOW_MAX_CONCURRENT_EXECUTIONS の値が大きい場合は、メモリ使用量を監視してください
• 実行時間の長いワークフローでは、WORKFLOW_EXECUTION_TIMEOUT の延長が必要になる場合があります
• ワークフローのフィルタリングを使用して、登録されるツールの数を減らしてください

監視に関する推奨事項

# Enable detailed logging for monitoring
LOG_LEVEL=info

# Set reasonable limits
WORKFLOW_MAX_CONCURRENT_EXECUTIONS=10
WORKFLOW_EXECUTION_TIMEOUT=300000

# Monitor workflow performance
WORKFLOW_STATUS_CHECK_INTERVAL=5000

トラブルシューティング

よくある問題

サーバーが起動しない

問題：設定エラーが発生し、サーバーを起動できません。

解決方法：

1. .env ファイルに SIMPLIFIED_API_TOKEN が含まれていることを確認します
2. API トークンが有効であることを確認します
3. Node.js のバージョンが 18.0.0 以降であることを確認します

# Check Node.js version
node --version

# Verify environment variables
echo $SIMPLIFIED_API_TOKEN

認証エラー

問題：API 呼び出しが認証エラーで失敗します。

解決方法：

1. API トークンが正しく、有効期限が切れていないことを確認します
2. トークンに必要な権限があることを確認します
3. API ベース URL が正しいことを確認します

ツールの実行エラー

問題：ツールがエラーを返す、または予期しない結果を返します。

解決方法：

1. ツールのパラメーターが想定されるスキーマと一致していることを確認します
2. API エンドポイントが存在し、アクセス可能であることを確認します
3. 詳細なエラー情報については、サーバーログを確認します

# Enable debug logging
LOG_LEVEL=debug simplified-mcp-server

接続の問題

問題：Simplified API に接続できません。

解決方法：

1. インターネット接続を確認します
2. API ベース URL にアクセスできることを確認します
3. ファイアウォールによる制限がないか確認します
4. ヘルスチェックツールを使用して接続状況を診断します

ワークフローツールの問題

問題：ワークフローツールがツール一覧に表示されません。

解決方法：

1. 環境で WORKFLOWS_ENABLED=true が設定されていることを確認します
2. workflows-list-tool が利用可能で、応答していることを確認します
3. ワークフロー定義が想定されるスキーマと一致していることを確認します
4. ワークフローの検出エラーについて、サーバーログを確認します

# Enable debug logging to see workflow discovery details
LOG_LEVEL=debug simplified-mcp-server

問題：ワークフローの実行がタイムアウトする、または失敗します。

解決方法：

1. 実行時間の長いワークフローでは、WORKFLOW_EXECUTION_TIMEOUT を大きくします
2. workflow-status-check ツールを使用してワークフローのステータスを確認します
3. ワークフローのパラメーターが想定されるスキーマと一致していることを確認します
4. ワークフロー実行システムが利用可能か確認します

# Increase timeout to 10 minutes for long workflows
WORKFLOW_EXECUTION_TIMEOUT=600000

問題：同時に実行されるワークフローが多すぎるため、エラーが発生します。

解決方法：

1. リソース使用量を制限するため、WORKFLOW_MAX_CONCURRENT_EXECUTIONS の値を小さくします
2. アプリケーションでワークフローのキューイングを実装します
3. 利用が集中する時間帯にシステムリソースを監視します

# Limit to 5 concurrent executions
WORKFLOW_MAX_CONCURRENT_EXECUTIONS=5

問題：ワークフローの検出頻度が高すぎて、API のレート制限が発生します。

解決方法：

1. API 呼び出しを減らすため、WORKFLOW_DISCOVERY_INTERVAL の値を大きくします
2. 0 に設定すると、自動検出が無効になり、手動での更新が必要になります
3. アプリケーションでワークフローのキャッシュを実装します

# Refresh workflows every 30 minutes instead of every 5 minutes
WORKFLOW_DISCOVERY_INTERVAL=1800000

# Or disable automatic discovery
WORKFLOW_DISCOVERY_INTERVAL=0

問題：一部のワークフローしか検出されません。

解決方法：

1. WORKFLOW_FILTER_PATTERNS の設定を確認します
2. ワークフロー名がフィルターパターンと一致していることを確認します
3. すべての利用可能なワークフローを表示するには、フィルターを削除します

# Remove all filters to see all workflows
WORKFLOW_FILTER_PATTERNS=

# Or adjust patterns to include more workflows
WORKFLOW_FILTER_PATTERNS=*

デバッグモード

詳細なトラブルシューティングのため、デバッグログを有効にします：

LOG_LEVEL=debug simplified-mcp-server

ヘルスチェック

組み込みのヘルスチェックツールを使用して、サーバーの状態を確認します：

{
  "name": "simplified-health-check",
  "arguments": {
    "includeDetails": true
  }
}

ワークフローのトラブルシューティングガイド

ワークフローの検出に関する問題

症状：WORKFLOWS_ENABLED=true に設定しているにもかかわらず、ツール一覧にワークフローツールが表示されません

診断手順：

1. デバッグログを有効にします：LOG_LEVEL=debug
2. ワークフロー検出に関するメッセージがあるか、サーバー起動ログを確認します
3. workflows-list-tool が利用可能で、応答していることを確認します

よくある原因と解決方法：

# Cause: workflows-list-tool not found
# Solution: Ensure the tool is properly registered and available
LOG_LEVEL=debug simplified-mcp-server
# Look for: "Workflow discovery failed: workflows-list-tool not found"

# Cause: Invalid workflow definitions
# Solution: Check workflow schema compliance
# Look for: "Skipping invalid workflow: missing required field 'name'"

# Cause: All workflows filtered out
# Solution: Check filter patterns
WORKFLOW_FILTER_PATTERNS=  # Remove filters temporarily

症状：ワークフローは検出されますが、ツールが登録されません

診断手順：

1. ログにツール名の競合がないか確認します
2. ワークフロー名が有効な MCP ツール名であることを確認します
3. スキーマ検証エラーがないか確認します

解決方法：

# Enable detailed tool registration logging
LOG_LEVEL=debug

# Check for naming conflicts
# Look for: "Tool name conflict: workflow-data-processor already exists"

# Verify workflow names contain only valid characters
# Valid: data-processor, report_generator, analysis123
# Invalid: data processor, report-generator!, análisis

ワークフローの実行に関する問題

症状：ワークフローの実行がタイムアウトします

診断手順：

1. ワークフローの実行ログを確認します
2. ワークフローが実際に実行中であることを確認します
3. ワークフローのステータスを手動で監視します

解決方法：

# Increase timeout for long-running workflows
WORKFLOW_EXECUTION_TIMEOUT=1800000  # 30 minutes

# Check workflow status manually
{
  "name": "workflow-status-check",
  "arguments": {
    "workflowId": "your-workflow-id",
    "executionId": "execution-uuid"
  }
}

# Reduce status check interval for better monitoring
WORKFLOW_STATUS_CHECK_INTERVAL=2000

症状：ワークフローの実行がすぐに失敗します

診断手順：

1. 入力パラメーターをワークフローのスキーマと照合して検証します
2. ワークフローシステムが利用可能か確認します
3. API の認証情報と権限を確認します

解決方法：

# Enable parameter validation logging
LOG_LEVEL=debug

# Check parameter schema compliance
# Look for: "Parameter validation failed: 'dataset' is required"

# Test workflow system connectivity
# Use workflow-status-check with a known execution ID

パフォーマンスの問題

症状：サーバーの動作が遅くなる、または応答しなくなる

診断手順：

1. 同時実行数を確認する
2. メモリと CPU の使用状況を監視する
3. ワークフローの検出頻度を確認する

解決策：

# Reduce concurrent executions
WORKFLOW_MAX_CONCURRENT_EXECUTIONS=5

# Increase discovery interval to reduce API load
WORKFLOW_DISCOVERY_INTERVAL=1800000  # 30 minutes

# Disable automatic discovery if not needed
WORKFLOW_DISCOVERY_INTERVAL=0

# Use workflow filtering to reduce tool count
WORKFLOW_FILTER_PATTERNS=essential-*,critical-*

症状：API 呼び出しが過剰になり、レート制限が発生する

解決策：

# Increase status check interval
WORKFLOW_STATUS_CHECK_INTERVAL=10000  # 10 seconds

# Reduce discovery frequency
WORKFLOW_DISCOVERY_INTERVAL=3600000   # 1 hour

# Limit concurrent executions
WORKFLOW_MAX_CONCURRENT_EXECUTIONS=3

設定の問題

症状：ワークフローの設定エラーによりサーバーが起動しない

よくあるエラーと解決策：

# Error: "Workflow execution timeout must be at least 1000ms"
WORKFLOW_EXECUTION_TIMEOUT=30000  # Set to at least 1 second

# Error: "Status check interval must be at least 1000ms"
WORKFLOW_STATUS_CHECK_INTERVAL=2000  # Set to at least 1 second

# Error: "Maximum concurrent executions must be positive"
WORKFLOW_MAX_CONCURRENT_EXECUTIONS=5  # Set to positive number

# Error: "Discovery interval cannot exceed 24 hours"
WORKFLOW_DISCOVERY_INTERVAL=3600000   # Set to max 1 hour

統合の問題

症状：ワークフローがテストでは動作するが、本番環境では失敗する

診断チェックリスト：

1. 環境変数の違い
2. ネットワーク接続とファイアウォールのルール
3. API エンドポイントの可用性
4. リソース制限とタイムアウト

本番環境の設定レビュー：

# Ensure production-appropriate timeouts
WORKFLOW_EXECUTION_TIMEOUT=600000     # 10 minutes
WORKFLOW_STATUS_CHECK_INTERVAL=5000   # 5 seconds
WORKFLOW_DISCOVERY_INTERVAL=600000    # 10 minutes

# Set appropriate concurrency limits
WORKFLOW_MAX_CONCURRENT_EXECUTIONS=15

# Use production workflow filters
WORKFLOW_FILTER_PATTERNS=prod-*,live-*

# Enable appropriate logging
LOG_LEVEL=warn  # Reduce log noise in production

デバッグコマンド

デバッグを最大限に有効にする：

LOG_LEVEL=debug
WORKFLOWS_ENABLED=true
WORKFLOW_DISCOVERY_INTERVAL=60000
WORKFLOW_STATUS_CHECK_INTERVAL=2000
WORKFLOW_RETRY_ATTEMPTS=1

ワークフロー検出をテストする：

# Start server and look for these log messages:
# "Starting workflow discovery..."
# "Discovered X workflows"
# "Registered workflow tool: workflow-name"
# "Workflow discovery completed"

ワークフロー実行をテストする：

# Use a simple workflow first
{
  "name": "workflow-simple-test",
  "arguments": {
    "input": "test-value"
  }
}

# Monitor logs for:
# "Starting workflow execution: workflow-id"
# "Workflow status: RUNNING"
# "Workflow completed: execution-id"

ヘルプの利用

1. ログを確認する：デバッグログを有効にして、詳細なエラー情報を確認します
2. 設定を確認する：必要な環境変数がすべて設定されていることを確認します
3. 接続をテストする：ヘルスチェックと API ステータスのツールを使用します
4. API ドキュメントを確認する：エンドポイントのパスとパラメーターを確認します
5. ワークフローツールをテストする：複雑なワークフローの前に、シンプルなワークフローから始めます
6. リソースを監視する：ワークフローの実行中にメモリと CPU の使用状況を確認します
7. 問題を報告する：ログと設定の詳細を添えて、GitHub リポジトリに Issue を作成します

API リファレンス

サーバー設定

サーバーでは、次の設定オプションを使用できます。

interface ServerConfig {
  // Basic Configuration
  apiToken: string;           // Required: Simplified API token
  apiBaseUrl: string;         // Optional: API base URL
  logLevel: 'debug' | 'info' | 'warn' | 'error'; // Optional: Log level
  timeout: number;            // Optional: Request timeout in ms
  retryAttempts: number;      // Optional: Number of retry attempts
  retryDelay: number;         // Optional: Delay between retries in ms
  
  // Workflow Configuration
  workflowsEnabled: boolean;                    // Optional: Enable workflow tools
  workflowDiscoveryInterval: number;            // Optional: Auto-refresh interval (ms)
  workflowExecutionTimeout: number;             // Optional: Execution timeout (ms)
  workflowMaxConcurrentExecutions: number;      // Optional: Max concurrent executions
  workflowFilterPatterns: string[];             // Optional: Workflow name patterns
  workflowStatusCheckInterval: number;          // Optional: Status polling interval (ms)
  workflowRetryAttempts: number;                // Optional: Retry attempts for failures
}

ツールのレスポンス形式

すべてのツールは、次の形式でレスポンスを返します。

interface ToolResponse {
  content: Array<{
    type: 'text';
    text: string; // JSON string containing the actual response data
  }>;
}

成功レスポンス

{
  "success": true,
  "data": { /* response data */ },
  "message": "Operation completed successfully"
}

エラーレスポンス

{
  "success": false,
  "error": "Error description",
  "details": { /* additional error information */ }
}

コントリビューション

コントリビューションを歓迎します！詳細については、コントリビューションガイドをご覧ください。

開発環境のセットアップ

1. リポジトリをフォークします
2. フォークをクローンします：git clone https://github.com/your-username/simplified-mcp-server.git
3. 依存関係をインストールします：npm install
4. 機能ブランチを作成します：git checkout -b feature/your-feature
5. 変更を加えてテストを追加します
6. テストを実行します：npm test
7. プロジェクトをビルドします：npm run build
8. 変更をコミットします：git commit -m "Add your feature"
9. フォークにプッシュします：git push origin feature/your-feature
10. プルリクエストを作成します

ライセンス

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

サポート

• API ドキュメント：API ドキュメント
• ドキュメント：GitHub Wiki
• 問題：GitHub Issues
• ディスカッション：GitHub Discussions