Weik.io Integration Expert: MCP Server

Weik.io 集成专家：MCP 服务

项目概览

此模型上下文协议（MCP）服务专为 Weik.io 集成平台设计，提供智能助手，引导开发者完成从规划、实施到测试和部署的完整集成生命周期。

Weik.io 是一个开源集成与自动化平台，采用基于 Agent 的架构，支持云端、本地部署和混合部署。它基于 Apache Camel 构建，并在此基础上扩展了多项专业功能，包括集成流、API 管理、托管文件传输、事件中心、实体存储和数据库变更跟踪。

该 MCP 服务提供工具和资源，使 AI 助手能够协助处理 Weik.io 集成任务，并访问 Weik.io 功能、Apache Camel 组件元数据和 Kamelet 信息。

配置

基于 Docker 的配置

{
  "mcpServers": {
    "weikio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network=host",
        "ghcr.io/weikio/mcp-server:latest"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

基于 NPX 的配置

{
  "mcpServers": {
    "weikio": {
      "command": "npx",
      "args": [
        "-y",
        "@weikio/mcp-server"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

MCP 工具实现

1. 规划工具

• get_supported_integration_types：获取受支持集成类型的信息（已实现）
• analyze_integration_requirements：确定最佳方案和技术（计划中）
• suggest_integration_pattern：根据需求推荐合适的模式（计划中）
• get_best_practices：获取特定集成类型的相关最佳实践（计划中）

2. 实施工具

• initialize_integration：使用指定名称初始化新的集成流（已实现）
• generate_camel_integration：生成 Camel YAML 流（计划中）
• generate_mft_configuration：生成用于文件操作的 MFT 配置（计划中）
• create_data_transformation：根据示例数据构建 JQ 或其他转换（计划中）
• validate_implementation：根据最佳实践检查实现（计划中）
• apply_best_practices：分析并根据最佳实践改进现有集成（计划中）
• get_best_practice：获取特定最佳实践的详细信息（计划中）
• check_compliance：根据最佳实践标准验证集成（计划中）

3. 测试与调试工具

• identify_test_parameters：确定测试所需的参数（计划中）
• generate_test_configuration：创建测试设置文件（计划中）
• create_test_data：生成用于测试的模拟数据（计划中）
• debug_transformation：交互式调试 JQ/转换（计划中）
• analyze_payload：检查任意位置的消息结构（计划中）
• trace_message_flow：可视化消息在集成中的传递路径（计划中）
• diagnose_error：分析错误并提出解决方案（计划中）

4. 外部工具集成

• setup_ngrok_tunnel：为本地端点配置并启动 ngrok 隧道（计划中）
• get_ngrok_url：获取当前的 ngrok 公网 URL，以用于集成（计划中）
• create_webhook_endpoint：生成用于测试的新 webhook.site 端点（计划中）
• retrieve_webhook_requests：获取收到的 webhook 负载以供分析（计划中）
• run_camel_jbang：执行 Camel 脚本以进行快速测试（计划中）

5. 本地 Weik.io 管理

• get_docker_compose：获取用于设置本地 Weik.io 实例的 Docker Compose 文件（已实现）
• start_local_weikio：使用 Docker Compose 启动本地 Weik.io（计划中）
• stop_local_weikio：停止正在运行的环境（计划中）
• restart_local_weikio：重启以快速刷新（计划中）
• get_weikio_status：执行简单的运行状况检查并报告状态（计划中）
• reset_local_weikio：将环境恢复到干净状态（计划中）

6. 配置文件管理

• list_profiles：列出所有 Weik.io 配置文件（已实现）
• add_profile：添加包含名称、URL 和 API 密钥的新 Weik.io 配置文件（已实现）

7. 发布工具

• push_integration：将集成推送到 Weik.io 实例（已实现）
• generate_push_commands：创建推送到 Weik.io 的命令（计划中）
• create_deployment_checklist：生成部署前的验证步骤（计划中）

技术概览

Apache Camel：

• 开源集成框架，实现企业集成模式
• 基于规则的路由和中介引擎，包含 300 多个组件
• 支持多种连接协议和数据格式
• 只需少量代码即可实现不同系统之间的复杂集成
• 提供 YAML DSL，用于声明式定义集成流

Weik.io：

• 基于 Apache Camel 构建的开源集成与自动化平台
• 基于 Agent 的架构，支持云端、本地和混合部署
• 通过以下专用功能扩展 Camel：
  • 集成流（系统间集成）
  • 内置网关的 API 管理
  • 托管文件传输（MFT）
  • 支持 CloudEvents 的事件中心
  • 实体存储（支持变更追踪的键值存储）
  • 数据库变更追踪
• 面向开发者的工具，支持 VS Code 集成和 CLI
• 满足企业需求，具备监控、可观测性和安全功能

当前状态

MCP 服务目前提供：

• Apache Camel 组件元数据
• Apache Camel Kamelet 元数据
• 基本的 Weik.io CLI 操作
• 集成类型决策支持
• Weik.io 配置文件管理
• 用于本地 Weik.io 实例的 Docker Compose 配置
• 集成流初始化
• 集成部署

集成流初始化

服务现在包含一个名为 initialize_integration 的工具，可用于创建新的集成流：

• 接受两个参数：
  • name：集成流名称（必须为小写，可包含连字符）
  • directory：集成流的创建目录（绝对路径）
• 在指定目录中创建一个以指定名称命名的新文件夹
• 在该文件夹中生成两个文件：
  • integration.camel.yaml：Apache Camel YAML 流定义
  • application.properties：流专用参数／属性／变量的配置

此工具可让 AI 助手帮助用户快速在首选位置创建并设置新的集成流。之后可根据用户的具体需求自定义该集成流。

使用示例：

// Using the MCP tool
initialize_integration(name: "hello-world", directory: "/path/to/your/project")

// Using the CLI directly
weikio integration init hello-world

集成部署

服务包含一个名为 push_integration 的工具，可将集成部署到 Weik.io 实例：

• 接受两个参数：
  • name：要推送的集成名称（文件夹名称）
  • directory：包含该集成的目录（绝对路径）
• 将集成推送到当前启用的 Weik.io 配置文件
• 验证集成是否存在以及是否包含所需文件

此工具可让 AI 助手在用户创建并自定义集成流后，帮助他们将集成流部署到 Weik.io 实例。

使用示例：

// Using the MCP tool
push_integration(name: "hello-world", directory: "/path/to/your/project")

// Using the CLI directly
weikio integration push hello-world

集成类型决策支持

服务器现在包含一个名为 get_supported_integration_types 的工具，可提供有关 Weik.io 支持的集成类型的详细信息：

1. 基于 Apache Camel 的集成流

   • 说明：一种灵活的集成框架，采用基于规则的路由和中介引擎来实现企业集成模式
   • 主要用例：系统间集成、基于 API 的集成、复杂数据转换等
   • 最适用于：复杂集成场景、需要数据转换的集成、基于 API 的集成等

2. 基于 RCLONE 的托管文件传输（MFT）

   • 说明：一种专用解决方案，用于在不同存储系统之间传输文件，并提供高级管理功能
   • 主要用例：在存储系统之间传输文件、文件同步、备份和归档等
   • 最适用于：在存储系统之间进行简单的文件传输、定期文件同步任务、备份和归档工作流等

借助此工具，AI 助手能够根据用户的具体需求，就应使用哪种集成类型做出明智建议。例如：

• 如果用户需要将文件从 SFTP 同步到 Azure Blob 存储，助手会推荐基于 RCLONE 的 MFT
• 如果用户需要集成 CRM 和 ERP 系统，并进行数据转换，助手会推荐基于 Apache Camel 的集成流

决策逻辑遵循一条简单规则：如果任务涉及在两个文件系统（SMB、SFTP、Azure Blob、S3、本地目录等）之间传输（复制、移动、同步）文件，请使用 MFT。否则，请使用基于 Apache Camel 的集成流。

增强目标

将服务器打造为全面的集成专家，使其能够：

1. 指导集成规划

   • 推荐合适的模式和方法
   • 针对不同集成场景运用最佳实践
   • 做出明智的技术决策（Camel YAML 与 Weik.io 专用功能之间的选择）

2. 协助实施

   • 生成正确的 Apache Camel YAML 语法
   • 创建数据转换（重点关注用于 JSON 的 JQ）
   • 支持 Camel 之外的 Weik.io 专用功能

3. 简化测试和调试

   • 确定不同集成类型所需的测试参数
   • 生成测试配置和示例数据
   • 为常见问题提供强大的调试工具
   • 协助排查数据转换问题
   • 支持详细检查消息在各集成节点之间的流转
   • 指导验证流程

4. 简化部署

   • 生成推送到 Weik.io 的正确命令
   • 提供部署验证指导

架构

知识管理系统

此增强功能引入了结构化知识系统：

1. YAML DSL 知识库

   • Apache Camel YAML 语法文档
   • 元素说明和语法规则
   • 示例仓库（从基础到高级）

2. 集成模式库

   • 常见 EIP 实现
   • 特定用例的模式
   • 按场景划分的最佳实践

3. 模板系统

   • 基于场景的模板
   • 渐进式复杂度选项
   • 可自定义参数

4. Weik.io 扩展知识库

   • MFT 功能和配置
   • 事件源文档
   • 变量支持
   • 实体存储使用模式
   • 数据库更改跟踪
   • 其他内置功能

5. 最佳实践框架

   • 设计时最佳实践
     • 使用 Weik.io Variables 配置属性占位符
     • 命名约定和结构
     • 错误处理模式
     • 安全实施指南
   • 运行时最佳实践
     • 用于 Webhook 集成的事件流
     • 监控钩子
     • 日志记录策略
     • 性能优化模式
   • 运维最佳实践
     • 部署策略
     • 配置管理
     • 版本控制方法

6. 调试与故障排除系统

   • 数据转换调试工具
   • 执行流程可视化
   • 错误模式识别与解决
   • 负载检查与验证

文件结构

weikio-server/
├── data/
│   ├── yaml-dsl/              # Apache Camel YAML DSL knowledge
│   │   ├── examples/          # Categorized examples
│   │   ├── elements/          # DSL element documentation
│   │   └── patterns/          # EIP implementation patterns
│   ├── templates/             # Reusable integration templates
│   │   ├── system-to-system/  # System integration templates
│   │   ├── data-processing/   # Data processing templates
│   │   └── api-based/         # API integration templates
│   ├── best-practices/        # Best practices documentation
│   │   ├── design/            # Design-time best practices
│   │   │   ├── property-placeholders.md
│   │   │   ├── naming-conventions.md
│   │   │   └── error-handling.md
│   │   ├── runtime/           # Runtime best practices
│   │   │   ├── event-streams.md
│   │   │   ├── monitoring.md
│   │   │   └── logging.md
│   │   └── operational/       # Operational best practices
│   │       ├── deployment.md
│   │       ├── configuration.md
│   │       └── versioning.md
│   ├── development-tools/     # External development tools
│   │   ├── ngrok/             # ngrok documentation and scripts
│   │   ├── webhook-site/      # webhook.site integration
│   │   ├── camel-jbang/       # Camel JBang scripts and examples
│   │   └── local-weikio/      # Local Weik.io environment
│   │       └── docker-compose.yml  # Docker Compose configuration
│   └── weikio/                # Weik.io-specific knowledge
│       ├── features/          # Built-in feature documentation
│       │   ├── mft/           # Managed File Transfer
│       │   ├── events/        # Event sources
│       │   ├── variables/     # Variables system
│       │   ├── entity-store/  # Key-value store
│       │   └── db-tracking/   # Database change tracking
│       └── best-practices/    # Weik.io-specific best practices
└── src/
    ├── integration-types-service.ts # Integration types information service
    ├── metadata-service.ts    # Apache Camel metadata service
    ├── yaml-dsl-service.ts    # YAML DSL knowledge service (planned)
    ├── template-service.ts    # Template management service (planned)
    ├── best-practices-service.ts # Best practices enforcement (planned)
    ├── dev-tools-service.ts   # Development tools integration (planned)
    └── local-weikio-service.ts # Local Weik.io management (planned)

实施路线图

阶段 1：Apache Camel YAML DSL 支持

1. 创建 YAML DSL 知识库

   • 从文档中提取并整理 DSL 元素
   • 编写语法规则和约束文档
   • 为元素添加元数据标签，以便搜索

2. 构建示例仓库

   • 开发展示核心概念的基础示例
   • 创建展示复杂模式的高级示例
   • 使用元数据为示例编制索引，以便高效检索

3. 实现集成模式库

   • 编写常见企业集成模式的文档
   • 为每种模式提供 YAML 实现
   • 创建针对特定上下文的变体

4. 开发模板系统

   • 为常见场景设计基础模板
   • 创建用于自定义的参数化系统
   • 在模板中加入文档

5. 添加核心 MCP 工具

   • learn_yaml_example：存储并为新示例编制索引
   • generate_camel_integration：根据需求创建 YAML
   • validate_yaml：验证语法和最佳实践
   • get_yaml_element_help：提供元素文档
   • list_integration_patterns：显示可用模式
   • get_template：检索集成模板

6. 开发调试功能

   • 创建数据转换调试工具
     • 输入/输出验证器
     • 转换步骤可视化
     • 架构合规性检查器
   • 实现常见错误解决模式
   • 设计负载检查工具
   • 构建执行流程跟踪功能

7. 建立最佳实践框架

   • 编写集成设计关键最佳实践的文档
   • 使用 Weik.io Variables 制定属性占位符标准
   • 开发用于 Webhook 集成的事件流模式
   • 将最佳实践强制执行机制集成到生成工具中
   • 创建验证规则以确保合规

阶段 2：Weik.io 功能支持

1. 开发 Weik.io 功能知识库

   • 记录 MFT 功能和配置
   • 为其他 Weik.io 功能创建结构化文档
   • 建立可扩展的格式，以便添加新功能

2. 增强模板系统

   • 添加 Weik.io 专用模板
   • 创建展示 Camel 与 Weik.io 集成的混合模板
   • 纳入功能选择最佳实践

3. 实现 Weik.io 专用工具

   • generate_mft_configuration：创建 MFT 配置
   • 为其他 Weik.io 功能提供工具（采用可扩展设计）

4. 添加测试和部署支持

   • 测试参数识别
   • 测试配置生成
   • 提供部署验证指南

可扩展机制

实现应优先考虑可扩展性，以支持未来增强：

1. 可插拔知识系统

   • 用于添加新知识的结构化文件格式
   • 支持不断演进的功能版本管理

2. 功能文档格式

   • 用于记录 Weik.io 功能的标准架构
   • 便于随着新功能开发完成而添加这些功能

3. 模板扩展 API

   • 添加新模板的明确约定
   • 参数定义标准

技术实现指南

知识库设计

1. 文件格式

   • 对结构化数据使用 JSON/YAML
   • 为每种知识类型维护清晰的架构
   • 包含丰富的元数据，以便筛选和搜索

2. 示例存储

   • 将示例存储为完整、有效的 YAML
   • 添加注释以辅助学习
   • 标记相关组件、模式和复杂度

服务实现

1. YAML DSL 服务

   • 提供索引和搜索功能
   • 实现针对 DSL 规则的验证
   • 支持针对各元素的上下文帮助

2. 模板服务

   • 支持参数替换
   • 支持按用例和复杂度筛选
   • 支持合并多个模板

最佳实践规范

1. 结构化文档格式

   • 基于 Markdown 的最佳实践文档
   • 适用性元数据（集成类型、组件）
   • 展示正确实现方式的代码示例
   • 应避免的常见反模式

2. 集成生成护栏

   • 默认在所有生成的代码中应用最佳实践
   • 确保模板配置符合标准
   • 自动实现属性占位符
   • 为 Webhook 场景生成事件流

3. 合规性检查

   • 用于验证最佳实践的静态分析规则
   • 可自定义的合规级别（必需与建议）
   • 提供详细报告和改进建议
   • 为不合规的实现提供修复建议

4. 可扩展机制

   • 添加新最佳实践的简易格式
   • 用于实践演进的版本标记
   • 过时实践的弃用机制

调试系统设计

1. 聚焦数据转换

   • 配备示例输入/输出的 JQ 测试环境
   • 逐步可视化转换过程
   • 识别常见错误模式
   • 针对预期格式进行架构验证

2. 消息流调试

   • 支持通过集成点进行跟踪
   • 提供每个步骤的负载检查
   • 识别潜在瓶颈和故障点

3. 错误解决模式

   • 维护常见错误及其解决方法的数据库
   • 通过模式匹配诊断错误
   • 根据错误特征提供修复建议

最佳实践示例

为展示最佳实践框架的详细程度，以下是两项关键实践的示例：

使用 Weik.io 变量的属性占位符

集成应使用 Weik.io 的 Variable 系统外部化所有配置，而不是将值硬编码：

# ❌ Incorrect: Hardcoded values
- route:
    from:
      uri: "sftp://ftp.example.com:22/incoming"
      parameters:
        username: "ftpuser"
        password: "secret123"

# ✅ Correct: Using Weik.io Variables
- route:
    from:
      uri: "sftp://{{vars.ftp.host}}:{{vars.ftp.port}}/incoming"
      parameters:
        username: "{{vars.ftp.username}}"
        password: "{{vars.ftp.password}}"

优点：

• 针对不同环境进行配置
• 提高安全性（代码中不包含密钥）
• 集中管理
• 无需重新部署即可在运行时重新配置

用于 Webhook 集成的事件流

所有 Webhook 风格的集成都应实现事件流，以便重放和检查：

# ✅ Recommended Pattern
- route:
    from:
      uri: "webhook://orders"
      steps:
        # Log incoming event to stream
        - to:
            uri: "stream:event"
            parameters:
              streamName: "webhook-orders"
              persistent: true
        # Continue with processing
        - process:
            # ... processing steps

优点：

• 能够重放事件以进行测试
• 检查负载以调试问题
• 记录收到的 Webhook 的审计跟踪
• 在处理失败时提供恢复机制

外部开发工具集成

MCP 服务可与常用开发和测试工具无缝集成：

ngrok

• 自动管理本地端点的隧道
• 配置自定义域名和身份验证
• 集成到 Webhook 测试工作流中

webhook.site

• 自动创建和管理端点
• 检查和分析负载
• 模拟响应，以模拟外部系统

Camel CLI (JBang)

• 无需设置项目即可快速测试组件
• 使用示例数据验证转换
• 通过最少的配置测试路由

这些工具直接集成到 MCP 服务的功能中，为开发者在整个集成生命周期中提供无缝体验。

本地 Weik.io 环境

MCP 服务可简化对本地 Weik.io 实例的管理：

Docker Compose 配置

MCP 服务包含一个名为 get_docker_compose 的工具，可提供现成的 Docker Compose 配置，用于运行本地 Weik.io 环境。该配置包括：

• 用于路由的 Traefik（可通过 http://weikio.localtest.me:8000 访问）
• 用于消息传递的 NATS
• Weik.io Backend（默认凭据为 [email protected]/password，API 密钥为 "api.key"）
• Weik.io UI
• Weik.io Agent
• API 管理

使用此配置的步骤：

1. 使用 get_docker_compose 获取 Docker Compose 文件
2. 将其保存到文件中（例如 docker-compose.yml）
3. 运行 docker-compose up -d 启动环境
4. 添加配置档案以连接本地实例：

   weikio profiles add "local" "http://backend.localtest.me:8000" "api.key"
   

5. 使用 weikio agents ls 验证连接

实例管理

• 一条命令即可启动完整的 Weik.io 环境
• 提供基本状态报告
• 提供简单的重置功能，便于进行干净的测试

开发集成

• 直接将集成部署到本地实例
• 使用隧道（ngrok）通过真实数据进行测试
• 在代码更改与测试之间快速迭代

这种简化方式专注于提高开发者的效率，只提供集成开发和测试所需的基本控制功能。

未来机会

1. 交互式学习

   • 为常见集成提供分步教程
   • 针对用户创建的集成提供反馈

2. 模式检测

   • 分析现有集成以识别模式
   • 根据最佳实践提出优化建议

3. 与 Weik.io 路线图集成

   • 在 Weik.io 发布新功能时提供支持
   • 与 Weik.io 产品演进保持一致

开发方法

本项目应采用迭代方式实施：

1. 从核心 YAML DSL 知识和简单示例入手
2. 添加集成模式和模板
3. 构建用于生成和验证的工具
4. 扩展 Weik.io 专属功能
5. 增强测试和部署支持

每次迭代都应提供独立价值，同时逐步实现完整愿景。

Docker 容器和 CI/CD

MCP 服务可以作为 Docker 容器运行，并通过 GitHub Actions 自动构建。

Docker 镜像

此 MCP 服务使用 Docker 容器化，便于在各种环境中部署和运行。Docker 镜像基于 Node.js Alpine 构建，占用空间小。

Docker 构建过程：

1. 安装 .NET 8 SDK 和 Weikio CLI
2. 将所有源文件复制到容器中
3. 安装所有依赖项（包括开发依赖项）
4. 构建 TypeScript 项目
5. 移除开发依赖项，以减小最终镜像体积
6. 设置入口点

Docker 镜像包含：

• Node.js 20（Alpine）
• .NET 8 SDK
• Weikio CLI（全局工具）

运行 Docker 容器

# Pull the latest image
docker pull ghcr.io/weikio/mcp-server:latest

# Run the container
docker run -it ghcr.io/weikio/mcp-server:latest

在本地构建

你也可以在本地构建并运行 Docker 镜像：

# Build the image
docker build -t weikio-server .

# Run the container
docker run -it weikio-server

NPM 包

此 MCP 服务也以 npm 包的形式提供，便于使用 npx。推送更改到 main 分支时，GitHub Actions 会自动将此包发布到 npm。

前置条件

使用 npm 包之前，请确保已安装以下内容：

1. Node.js（v20 或更高版本）
2. .NET 8 SDK - 安装说明
3. Weikio CLI - 使用以下命令安装：

   dotnet tool install weikio-cli --global --prerelease
   

确保所有工具都可通过 PATH 使用。

安装

无需安装即可通过 npx 直接使用此包：

npx @weikio/mcp-server

或者全局安装：

npm install -g @weikio/mcp-server

然后运行：

weikio-mcp-server