Simplified MCP Server

简化版 MCP 服务

一个模型上下文协议（MCP）服务，可在 Claude、Cursor、Kiro（以及其他支持 MCP 的平台）与 Simplified 的 API 之间实现无缝集成。此服务让大模型能够通过标准化的 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 请求超时时间（毫秒）	30000	任何正数
RETRY_ATTEMPTS	重试次数	3	任何非负数
RETRY_DELAY	重试间隔（毫秒）	1000	任何正数

工作流工具配置

此服务支持动态工作流工具，可根据可用工作流自动发现并注册工具。此功能默认禁用，可通过环境变量启用。

变量	描述	默认值	范围/选项
WORKFLOWS_ENABLED	启用动态工作流工具	false	true、false
WORKFLOW_DISCOVERY_INTERVAL	自动刷新间隔（毫秒）	0（已禁用）	0-86400000（0 = 已禁用）
WORKFLOW_EXECUTION_TIMEOUT	执行超时时间（毫秒）	300000（5 分钟）	1000-3600000
WORKFLOW_MAX_CONCURRENT_EXECUTIONS	最大并发执行数	10	1-100
WORKFLOW_FILTER_PATTERNS	以逗号分隔的名称模式	``（无）	通配符模式
WORKFLOW_STATUS_CHECK_INTERVAL	状态轮询间隔（毫秒）	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 扩展：

扩展 -> 高级设置 -> 安装扩展...

选择 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/ 文件。

工具按组组织，每份规范对应一组：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

有两个可选变量用于设置默认工作区范围请求头；当工具调用未提供这些请求头时，将使用默认值：

变量	说明
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. 状态轮询：服务以至少 1000 毫秒的间隔轮询工作流状态
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	Reels 专属设置和动态分享
Pinterest	link、title、imageAlt	Pin 目标链接和无障碍设置
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
  }
}

动态工作流工具

每个发现的工作流都会成为一个独立的 MCP 工具，命名格式为 workflow-{workflow-name}。工具参数根据工作流的输入架构动态生成。

工作流工具示例：

• 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. 增大 WORKFLOW_DISCOVERY_INTERVAL，以减少 API 调用
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 仓库中创建问题，并附上日志和配置详情

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. Fork 此仓库
2. 克隆你的 Fork：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. 推送到你的 Fork：git push origin feature/your-feature
10. 创建 Pull Request

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

支持

• API 文档：API 文档
• 文档：GitHub Wiki
• 问题：GitHub Issues
• 讨论：GitHub Discussions