@mcpworkflow/plugin-sdk

MCP Workflow Plugin SDK - 用于开发工作流节点插件的开发工具包

简介

这是一个用于开发 MCP Workflow 节点插件的 SDK，提供了完整的类型定义、Canvas 绘制工具和通用组件，帮助开发者快速创建自定义的工作流节点。

特性

• 🎨 Canvas 绘制工具 - 提供丰富的 Canvas 绘制辅助函数
• 📝 完整类型定义 - TypeScript 类型支持，提供良好的开发体验
• 🧩 通用组件 - 预制的配置面板组件，快速构建节点配置界面
• 🔧 工具函数 - 常用的工具函数和验证逻辑
• 🎯 插件化架构 - 支持独立开发、打包和发布的插件系统

安装

npm install @mcpworkflow/plugin-sdk
# 或
yarn add @mcpworkflow/plugin-sdk
# 或
pnpm add @mcpworkflow/plugin-sdk

快速开始

1. 创建基本插件

import { WorkflowNodePlugin, PluginManifest } from '@mcpworkflow/plugin-sdk';

// 定义插件清单
const manifest: PluginManifest = {
  id: 'my-custom-node',
  name: '我的自定义节点',
  version: '1.0.0',
  description: '这是一个自定义节点示例',
  author: 'Your Name',
  category: 'custom',
  icon: '🔧',
  tags: ['custom', 'example']
};

// 实现插件
const plugin: WorkflowNodePlugin = {
  manifest,
  
  // 配置模式
  getConfigSchema: () => ({
    title: '节点配置',
    properties: {
      message: {
        key: 'message',
        type: 'string',
        label: '消息内容',
        required: true,
        placeholder: '请输入消息内容'
      }
    }
  }),
  
  // 端口定义
  getPortDefinitions: () => ({
    inputs: [
      {
        id: 'input',
        name: '输入',
        type: 'string',
        required: true
      }
    ],
    outputs: [
      {
        id: 'output',
        name: '输出',
        type: 'string'
      }
    ]
  }),
  
  // 节点渲染
  render: (ctx, node, options) => {
    const { canvas, theme } = options;
    
    // 绘制节点背景
    canvas.drawShape('rect', node.x, node.y, node.width, node.height, {
      fill: true,
      fillColor: theme.colors.node.background,
      stroke: true,
      strokeColor: theme.colors.node.border,
      radius: theme.sizes.borderRadius
    });
    
    // 绘制节点标题
    canvas.drawTextWithOptions(
      node.name,
      node.x + 10,
      node.y + 20,
      {
        font: theme.fonts.header,
        color: theme.colors.node.text
      }
    );
    
    return {
      clickAreas: [],
      hoverAreas: []
    };
  },
  
  // 节点执行
  execute: async (inputs, config, context) => {
    const inputValue = inputs.input;
    const message = config.message || 'Hello';
    
    return {
      success: true,
      outputs: {
        output: `${message}: ${inputValue}`
      }
    };
  },
  
  // 配置验证
  validateConfig: (config) => {
    const errors: string[] = [];
    
    if (!config.message) {
      errors.push('消息内容不能为空');
    }
    
    return {
      valid: errors.length === 0,
      errors,
      warnings: []
    };
  }
};

export default plugin;

2. 使用 Canvas 绘制工具

import { CanvasHelper, defaultTheme } from '@mcpworkflow/plugin-sdk';

// 创建 Canvas 辅助工具
const canvas = new CanvasHelper(ctx, defaultTheme);

// 绘制圆角矩形
canvas.drawRoundedRect(10, 10, 100, 60, 8);

// 绘制文本
canvas.drawTextWithOptions('Hello World', 20, 30, {
  font: '14px Arial',
  color: '#333',
  align: 'left'
});

// 绘制端口
canvas.drawPort(5, 25, 'input', {
  radius: 6,
  connected: true
});

// 绘制连接线
canvas.drawConnection(15, 25, 85, 25, {
  strokeColor: '#1890ff',
  curved: true
});

3. 使用配置面板组件

import React from 'react';
import { ConfigPanel } from '@mcpworkflow/plugin-sdk';

const MyNodeConfig = () => {
  const [config, setConfig] = useState({});
  
  const schema = {
    title: '节点配置',
    properties: {
      name: {
        key: 'name',
        type: 'string',
        label: '节点名称',
        required: true
      },
      count: {
        key: 'count',
        type: 'number',
        label: '数量',
        min: 1,
        max: 100
      },
      enabled: {
        key: 'enabled',
        type: 'boolean',
        label: '启用'
      }
    }
  };
  
  return (
    <ConfigPanel
      config={config}
      schema={schema}
      onChange={setConfig}
    />
  );
};

API 文档

核心接口

WorkflowNodePlugin

插件的主要接口，定义了插件的所有行为：

interface WorkflowNodePlugin {
  manifest: PluginManifest;                    // 插件清单
  getConfigSchema(): ConfigSchema;             // 获取配置模式
  getPortDefinitions(): PortDefinitions;      // 获取端口定义
  render(ctx: PluginContext, node: WorkflowNode, options: RenderOptions): RenderResult;
  execute(inputs: ExecutionInput, config: any, context: ExecutionContext): Promise<ExecutionOutput>;
  validateConfig?(config: any): ValidationResult;
  onConfigChange?(config: any, context: PluginContext): void;
  onMount?(context: PluginContext): void;
  onUnmount?(context: PluginContext): void;
}

CanvasHelper

Canvas 绘制辅助类，提供丰富的绘制方法：

class CanvasHelper {
  // 绘制形状
  drawShape(type: 'rect' | 'circle' | 'ellipse', x: number, y: number, width: number, height: number, options?: ShapeDrawOptions): void;
  
  // 绘制文本
  drawTextWithOptions(text: string, x: number, y: number, options?: TextDrawOptions): void;
  
  // 绘制端口
  drawPort(x: number, y: number, type: 'input' | 'output', options?: PortDrawOptions): void;
  
  // 绘制连接线
  drawConnection(startX: number, startY: number, endX: number, endY: number, options?: ConnectionDrawOptions): void;
  
  // 更多方法...
}

工具函数

import { utils } from '@mcpworkflow/plugin-sdk';

// 生成唯一ID
const id = utils.generateId();

// 深度克隆
const cloned = utils.deepClone(originalObject);

// 防抖
const debouncedFn = utils.debounce(myFunction, 300);

// 验证配置
const result = utils.validateConfig(config, schema);

开发指南

插件开发流程

1. 创建插件项目

   mkdir my-workflow-plugin
   cd my-workflow-plugin
   npm init -y
   npm install @mcpworkflow/plugin-sdk

2. 实现插件接口

   • 定义插件清单 (manifest)
   • 实现配置模式 (config schema)
   • 实现渲染逻辑 (render)
   • 实现执行逻辑 (execute)

3. 测试插件

   • 编写单元测试
   • 在开发环境中测试

4. 打包发布

   npm run build
   npm publish

最佳实践

1. 性能优化

   • 避免在 render 方法中进行复杂计算
   • 使用防抖和节流优化频繁操作
   • 合理使用 Canvas 缓存

2. 用户体验

   • 提供清晰的配置界面
   • 添加适当的验证和错误提示
   • 支持键盘快捷键

3. 兼容性

   • 遵循语义化版本规范
   • 保持向后兼容性
   • 提供迁移指南

示例插件

查看 examples 目录中的示例插件：

• 文件输入插件
• HTTP 请求插件
• 数据转换插件

更新 npm 包

patch：补丁号，修复bug，小变动，如 v1.0.0->v1.0.1

npm version patch

minor：次版本号，增加新功能，如 v1.0.0->v1.1.0

npm version minor

major：主版本号，不兼容的修改，如 v1.0.0->v2.0.0

npm version major

重新发布

npm publish

贡献

欢迎贡献代码！请阅读 贡献指南 了解详细信息。

许可证

MIT License - 查看 LICENSE 文件了解详细信息。

更新日志

查看 CHANGELOG.md 了解版本更新信息。