Weik.io Integration Expert: MCP Server

Project Overview

This Model Context Protocol (MCP) server is designed specifically for the Weik.io Integration Platform, providing an intelligent assistant that guides developers through the complete integration lifecycle from planning through implementation, testing, and deployment.

Weik.io is an open source integration and automation platform with agent-based architecture supporting cloud, on-premise, and hybrid deployments. It is built on Apache Camel and extends it with specialized capabilities including Integration Flows, API Management, Managed File Transfers, Event Hub, Entity Store, and Database change tracking.

The MCP server exposes tools and resources that enable AI assistants to help with Weik.io integration tasks, providing access to Weik.io functionality, Apache Camel component metadata, and Kamelet information.

Configuration

Docker-based Configuration

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

NPX-based Configuration

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

MCP Tools Implementation

1. Planning Tools

get_supported_integration_types: Get information about supported integration types (implemented)
analyze_integration_requirements: Determine optimal approach and technology (planned)
suggest_integration_pattern: Recommend appropriate pattern for requirements (planned)
get_best_practices: Retrieve relevant best practices for specific integration type (planned)

2. Implementation Tools

initialize_integration: Initialize a new integration flow with the specified name (implemented)
generate_camel_integration: Generate Camel YAML flow (planned)
generate_mft_configuration: Generate MFT config for file operations (planned)
create_data_transformation: Build JQ or other transformations based on sample data (planned)
validate_implementation: Check implementation against best practices (planned)
apply_best_practices: Analyze and enhance existing integration with best practices (planned)
get_best_practice: Retrieve detailed information about specific best practices (planned)
check_compliance: Validate integration against best practice standards (planned)

3. Testing & Debugging Tools

identify_test_parameters: Determine required parameters for testing (planned)
generate_test_configuration: Create test setup files (planned)
create_test_data: Generate mock data for testing (planned)
debug_transformation: Interactive JQ/transformation debugging (planned)
analyze_payload: Examine message structure at any point (planned)
trace_message_flow: Visualize message path through integration (planned)
diagnose_error: Analyze errors and suggest solutions (planned)

4. External Tool Integration

setup_ngrok_tunnel: Configure and start an ngrok tunnel for local endpoints (planned)
get_ngrok_url: Retrieve current ngrok public URL for use in integrations (planned)
create_webhook_endpoint: Generate new webhook.site endpoints for testing (planned)
retrieve_webhook_requests: Get received webhook payloads for analysis (planned)
run_camel_jbang: Execute Camel scripts for quick testing (planned)

5. Local Weik.io Management

get_docker_compose: Get a Docker Compose file for setting up a local Weik.io instance (implemented)
start_local_weikio: Start local Weik.io using Docker Compose (planned)
stop_local_weikio: Stop the running environment (planned)
restart_local_weikio: Restart for quick refresh (planned)
get_weikio_status: Simple health check and status reporting (planned)
reset_local_weikio: Return environment to clean state (planned)

6. Profile Management

list_profiles: List all Weik.io profiles (implemented)
add_profile: Add a new Weik.io profile with name, URL, and API key (implemented)

7. Publishing Tools

push_integration: Push an integration to a Weik.io instance (implemented)
generate_push_commands: Create commands to push to Weik.io (planned)
create_deployment_checklist: Generate pre-deployment verification steps (planned)

Technology Overview

Apache Camel:

Open source integration framework implementing Enterprise Integration Patterns
Rule-based routing and mediation engine with 300+ components
Supports multiple connection protocols and data formats
Enables complex integrations between disparate systems with minimal code
Provides YAML DSL for declarative integration flow definition

Weik.io:

Open source integration and automation platform built on Apache Camel
Agent-based architecture supporting cloud, on-premise, and hybrid deployments
Extends Camel with specialized capabilities including:
- Integration Flows (system-to-system integration)
- API Management with built-in gateway
- Managed File Transfers (MFTs)
- Event Hub with CloudEvents support
- Entity Store (key-value with change tracking)
- Database change tracking
Developer-friendly tools with VS Code integration and CLI
Enterprise-ready with monitoring, observability, and security features

Current State

The MCP server currently provides:

Apache Camel component metadata
Apache Camel Kamelet metadata
Basic Weik.io CLI operations
Integration type decision support
Weik.io profile management
Docker Compose configuration for local Weik.io instances
Integration flow initialization
Integration deployment

Integration Flow Initialization

The server now includes a tool called initialize_integration that allows creating a new integration flow:

Takes two parameters:
- name: Name of the integration flow (must be lowercase, can include hyphens)
- directory: Directory where the integration flow should be created (absolute path)
Creates a new folder with the specified name in the specified directory
Generates two files within the folder:
- integration.camel.yaml: Apache Camel YAML flow definition
- application.properties: Configuration for flow-specific parameters/properties/variables

This tool enables the AI assistant to help users create and set up new integration flows quickly in their preferred location. The integration flow can then be customized based on the user's specific requirements.

Example usage:

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

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

Integration Deployment

The server includes a tool called push_integration that allows deploying an integration to a Weik.io instance:

Takes two parameters:
- name: Name of the integration to push (folder name)
- directory: Directory containing the integration (absolute path)
Pushes the integration to the currently active Weik.io profile
Validates that the integration exists and contains the required files

This tool enables the AI assistant to help users deploy their integration flows to a Weik.io instance after they have been created and customized.

Example usage:

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

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

Integration Type Decision Support

The server now includes a tool called get_supported_integration_types that provides detailed information about the supported integration types in Weik.io:

Apache Camel Based Integration Flow
- Description: A flexible integration framework implementing Enterprise Integration Patterns with rule-based routing and mediation engine
- Main use cases: System-to-system integration, API-based integrations, complex data transformations, etc.
- Best suited for: Complex integration scenarios, integrations requiring data transformation, API-based integrations, etc.
RCLONE Based Managed File Transfer (MFT)
- Description: A specialized solution for transferring files between different storage systems with advanced management capabilities
- Main use cases: File transfers between storage systems, file synchronization, backup and archiving, etc.
- Best suited for: Simple file transfers between storage systems, regular file synchronization tasks, backup and archiving workflows, etc.

This tool enables the AI assistant to make informed recommendations about which integration type to use based on the user's specific requirements. For example:

If a user needs to sync files from SFTP to Azure Blob storage, the assistant will recommend RCLONE based MFT
If a user needs to integrate a CRM with an ERP system with data transformations, the assistant will recommend Apache Camel based Integration Flow

The decision logic follows a simple rule: If the task involves transferring files (copy, move, sync) between two file systems (SMB, SFTP, Azure Blob, S3, local directories, etc.), use MFT. Otherwise, use Apache Camel based Integration Flow.

Enhancement Goals

Transform the server into a comprehensive integration expert that can:

Guide integration planning
- Recommend appropriate patterns and approaches
- Apply best practices for different integration scenarios
- Make informed technology decisions (Camel YAML vs. specialized Weik.io features)
Assist with implementation
- Generate correct Apache Camel YAML syntax
- Create data transformations (with emphasis on JQ for JSON)
- Support specialized Weik.io features beyond Camel
Facilitate testing and debugging
- Identify required test parameters for different integration types
- Generate test configurations and sample data
- Provide robust debugging tools for common issues
- Assist with data transformation troubleshooting
- Enable detailed inspection of message flow through integration points
- Guide validation procedures
Streamline deployment
- Generate correct commands for pushing to Weik.io
- Provide deployment verification guidance

Architecture

Knowledge Management System

The enhancement introduces a structured knowledge system:

YAML DSL Knowledge Base
- Apache Camel YAML syntax documentation
- Element descriptions and syntax rules
- Example repository (basic to advanced)
Integration Patterns Library
- Common EIP implementations
- Use case specific patterns
- Best practices by scenario
Template System
- Scenario-based templates
- Progressive complexity options
- Customizable parameters
Weik.io Extensions Knowledge Base
- MFT capabilities and configurations
- Event sources documentation
- Variables support
- Entity store usage patterns
- Database change tracking
- Other built-in functionality
Best Practices Framework
- Design-time best practices
  - Property placeholder usage with Weik.io Variables
  - Naming conventions and structure
  - Error handling patterns
  - Security implementation guidelines
- Runtime best practices
  - Event streams for webhook integrations
  - Monitoring hooks
  - Logging strategies
  - Performance optimization patterns
- Operational best practices
  - Deployment strategies
  - Configuration management
  - Versioning approaches
Debugging & Troubleshooting System
- Data transformation debugging tools
- Execution flow visualization
- Error pattern recognition and resolution
- Payload inspection and validation

File Structure

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)

Implementation Roadmap

Phase 1: Apache Camel YAML DSL Support

Create YAML DSL Knowledge Base
- Extract and organize DSL elements from documentation
- Document syntax rules and constraints
- Tag elements with metadata for searchability
Build Example Repository
- Develop basic examples showcasing core concepts
- Create advanced examples demonstrating complex patterns
- Index examples with metadata for efficient retrieval
Implement Integration Pattern Library
- Document common Enterprise Integration Patterns
- Provide YAML implementations of each pattern
- Create context-specific variations
Develop Template System
- Design foundational templates for common scenarios
- Create parameterization system for customization
- Include documentation within templates
Add Core MCP Tools
- learn_yaml_example: Store and index new examples
- generate_camel_integration: Create YAML based on requirements
- validate_yaml: Verify syntax and best practices
- get_yaml_element_help: Provide element documentation
- list_integration_patterns: Show available patterns
- get_template: Retrieve integration templates
Develop Debugging Capabilities
- Create data transformation debugging tools
  - Input/output validators
  - Transformation step visualization
  - Schema compliance checkers
- Implement common error resolution patterns
- Design payload examination utilities
- Build execution flow tracing
Establish Best Practices Framework
- Document key best practices for integration design
- Create property placeholder standards with Weik.io Variables
- Develop event stream patterns for webhook integrations
- Build best practices enforcement into generation tools
- Create validation rules to ensure compliance

Phase 2: Weik.io Feature Support

Develop Weik.io Feature Knowledge Base
- Document MFT capabilities and configuration
- Create structured documentation for other Weik.io features
- Establish extensible format for adding new features
Enhance Template System
- Add Weik.io-specific templates
- Create hybrid templates showing Camel+Weik.io integration
- Include best practices for feature selection
Implement Weik.io-specific Tools
- generate_mft_configuration: Create MFT configurations
- Tools for other Weik.io features (extensible design)
Add Testing & Deployment Support
- Test parameter identification
- Test configuration generation
- Deployment validation guidance

Extensibility Mechanisms

The implementation should prioritize extensibility to allow future enhancements:

Pluggable Knowledge System
- Structured file format for adding new knowledge
- Versioning support for evolving capabilities
Feature Documentation Format
- Standard schema for documenting Weik.io features
- Easy addition of new features as they're developed
Template Extension API
- Clear conventions for adding new templates
- Parameter definition standards

Technical Implementation Guidelines

Knowledge Base Design

File Format
- Use JSON/YAML for structured data
- Maintain clear schemas for each knowledge type
- Include rich metadata for filtering and search
Example Storage
- Store examples as complete, valid YAML
- Annotate with comments for learning purposes
- Tag with relevant components, patterns, and complexity

Service Implementation

YAML DSL Service
- Provide indexing and search capabilities
- Implement validation against DSL rules
- Support contextual help for elements
Template Service
- Enable parameter substitution
- Provide filtering by use case and complexity
- Support merging of multiple templates

Best Practices Enforcement

Structured Documentation Format
- Markdown-based best practice documentation
- Metadata for applicability (integration type, components)
- Code examples showing correct implementation
- Common anti-patterns to avoid
Integration Generation Guardrails
- Default application of best practices in all generated code
- Template configurations conforming to standards
- Automatic property placeholder implementation
- Event stream generation for webhook scenarios
Compliance Checking
- Static analysis rules for best practice validation
- Customizable compliance levels (required vs. recommended)
- Detailed reporting with improvement suggestions
- Fix suggestions for non-compliant implementations
Extensibility Mechanism
- Simple format for adding new best practices
- Version tagging for practice evolution
- Deprecation mechanism for outdated practices

Debugging System Design

Data Transformation Focus
- JQ testing environment with sample input/output
- Step-by-step transformation visualization
- Common error pattern identification
- Schema validation against expected formats
Message Flow Debugging
- Enable tracing through integration points
- Provide payload inspection at each step
- Identify potential bottlenecks and failure points
Error Resolution Patterns
- Maintain database of common errors and resolutions
- Pattern matching for error diagnostics
- Suggested fixes based on error signatures

Example Best Practices

To illustrate the level of detail in the best practices framework, here are examples of two key practices:

Property Placeholders with Weik.io Variables

Integrations should externalize all configuration using Weik.io's Variable system rather than hardcoding values:

# ❌ 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}}"

Benefits:

Environment-specific configurations
Improved security (no secrets in code)
Centralized management
Runtime reconfiguration without redeployment

Event Streams for Webhook Integrations

All webhook-style integrations should implement event streams for replay and inspection:

# ✅ 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

Benefits:

Ability to replay events for testing
Inspection of payloads for debugging
Audit trail of received webhooks
Recovery mechanism in case of processing failures

External Developer Tools Integration

The MCP server provides seamless integration with popular development and testing tools:

ngrok

Automatic tunnel management for local endpoints
Configuration of custom domains and authentication
Integration with webhook testing workflows

webhook.site

Automated endpoint creation and management
Payload inspection and analysis
Response mocking for simulating external systems

Camel CLI (JBang)

Quick component testing without project setup
Transformation validation with sample data
Route testing with minimal configuration

These tools are integrated directly into the MCP server's capabilities, providing a seamless experience for developers throughout the integration lifecycle.

Local Weik.io Environment

The MCP server provides streamlined management of local Weik.io instances:

Docker Compose Configuration

The MCP server includes a tool called get_docker_compose that provides a ready-to-use Docker Compose configuration for running a local Weik.io environment. The configuration includes:

Traefik for routing (accessible at http://weikio.localtest.me:8000)
NATS for messaging
Weik.io Backend (with default credentials [email protected]/password and API key "api.key")
Weik.io UI
Weik.io Agent
API Management

To use this configuration:

Get the Docker Compose file with get_docker_compose
Save it to a file (e.g., docker-compose.yml)
Run docker-compose up -d to start the environment

Connect to the local instance by adding a profile:

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

Verify the connection with weikio agents ls

Instance Management

One-command startup of complete Weik.io environment
Basic status reporting
Simple reset functionality for clean testing

Development Integration

Deploy integrations directly to local instance
Test with real-world data using tunneling (ngrok)
Rapid iteration between code changes and testing

This simplified approach focuses on developer productivity by providing just the essential controls needed for integration development and testing.

Future Opportunities

Interactive Learning
- Step-by-step tutorials for common integrations
- Feedback on user-created integrations
Pattern Detection
- Analyze existing integrations to identify patterns
- Suggest optimizations based on best practices
Integration with Weik.io Roadmap
- Support for new Weik.io features as they're released
- Alignment with Weik.io product evolution

Development Approach

This project should be implemented with an iterative approach:

Start with core YAML DSL knowledge and simple examples
Add integration patterns and templates
Build tools for generation and validation
Extend with Weik.io-specific features
Enhance with testing and deployment support

Each iteration should deliver standalone value while building toward the complete vision.

Docker Container and CI/CD

The MCP server can be run as a Docker container, with automated builds via GitHub Actions.

Docker Image

The MCP server is containerized using Docker, making it easy to deploy and run in various environments. The Docker image is built on Node.js Alpine for a minimal footprint.

The Docker build process:

Installs .NET 8 SDK and Weikio CLI
Copies all source files into the container
Installs all dependencies (including dev dependencies)
Builds the TypeScript project
Prunes dev dependencies for a smaller final image
Sets up the entry point

The Docker image includes:

Node.js 20 (Alpine)
.NET 8 SDK
Weikio CLI (global tool)

Running the Docker Container

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

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

Building Locally

You can also build and run the Docker image locally:

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

# Run the container
docker run -it weikio-server

NPM Package

The MCP server is also available as an npm package, making it easy to use with npx. The package is automatically published to npm via GitHub Actions when changes are pushed to the main branch.

Prerequisites

Before using the npm package, ensure you have the following installed:

Node.js (v20 or later)
.NET 8 SDK - Installation instructions

Weikio CLI - Install with:

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

Ensure all tools are available in your PATH.

Installation

You can use the package directly with npx without installing it:

npx @weikio/mcp-server

Or install it globally:

npm install -g @weikio/mcp-server

Then run it with:

weikio-mcp-server

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.github/workflows		.github/workflows
metadata		metadata
src		src
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
NPM-PUBLISHING-GUIDE.md		NPM-PUBLISHING-GUIDE.md
README.md		README.md
mcp-settings-example.json		mcp-settings-example.json
package-lock.json		package-lock.json
package.json		package.json
test-components.json		test-components.json
tsconfig.json		tsconfig.json

weikio/mcp-server

Folders and files

Latest commit

History

Repository files navigation