enhanced-mcp-tools/examples/BULK_OPERATIONS_INTEGRATION_GUIDE.md

BulkToolCaller Integration Guide

Overview

The BulkToolCaller has been successfully integrated with your Enhanced MCP Tools server, providing powerful workflow orchestration and batch operations while maintaining the SACRED TRUST safety framework.

🎯 Key Features

1. Workflow Orchestration

• Dependency Management: Define operation dependencies for staged execution
• Multiple Execution Modes: Sequential, parallel, staged, and interactive modes
• Progress Monitoring: Real-time progress tracking and status updates

2. Security Integration

• SecurityManager Integration: Seamless integration with existing security controls
• Progressive Tool Disclosure: Respects security levels (SAFE/CAUTION/DESTRUCTIVE)
• Safety Confirmations: Required confirmations for destructive operations

3. Safety Features

• Comprehensive Dry Run: Validate workflows before execution
• Backup Creation: Automatic backup for destructive operations
• Error Handling: Robust error handling with detailed reporting
• Rollback Capabilities: Reverse operations where possible

🚀 Quick Start

Basic Usage

# 1. Create a workflow
await bulk_operations_create_bulk_workflow(
    name="Code Analysis",
    description="Comprehensive code analysis",
    operations=[
        {
            "id": "git_check",
            "tool_name": "git_status",
            "arguments": {"path": "/project"},
            "description": "Check Git status",
            "security_level": "safe"
        },
        {
            "id": "security_scan",
            "tool_name": "search_analysis_security_pattern_scan",
            "arguments": {"path": "/project", "scan_types": ["secrets"]},
            "description": "Security scan",
            "security_level": "safe",
            "depends_on": ["git_check"]
        }
    ],
    mode="staged"
)

# 2. Validate with dry run (ALWAYS DO THIS FIRST)
await bulk_operations_dry_run_bulk_workflow(workflow_id="<workflow-id>")

# 3. Execute safely
await bulk_operations_execute_bulk_workflow(
    workflow_id="<workflow-id>",
    dry_run=False,
    confirm_destructive=True  # Required for destructive operations
)

🛡️ Security Levels

🟢 SAFE (Always Available)

• Read-only operations
• Information gathering
• Status checks
• Examples: git_status, file_analysis, security_scans

🟡 CAUTION (Normal Mode)

• Reversible modifications
• Create/backup operations
• Examples: file_backups, code_formatting, test_execution

🔴 DESTRUCTIVE (Requires Explicit Enablement)

• Irreversible operations
• Data deletion/modification
• Examples: file_deletion, bulk_modifications

📋 Available Tools

The BulkToolCaller integrates with these Enhanced MCP Tools modules:

File Operations

• file_ops_read_file - Read file contents
• file_ops_write_file - Write file contents (CAUTION)
• file_ops_create_backup - Create file backups (CAUTION)
• file_ops_analyze_file_complexity - Analyze code complexity
• file_ops_auto_fix_issues - Auto-fix code issues (CAUTION)

Git Operations

• git_status - Check repository status
• git_commit - Commit changes (CAUTION)
• git_create_branch - Create Git branch (CAUTION)

Search & Analysis

• search_analysis_advanced_search - Advanced text search
• search_analysis_security_pattern_scan - Security vulnerability scan

Development Workflow

• dev_workflow_run_tests - Execute test suites
• dev_workflow_analyze_dependencies - Dependency analysis
• dev_workflow_lint_code - Code linting

Archive Operations

• archive_create_backup - Create archive backups (CAUTION)
• archive_extract - Extract archives (CAUTION)

🎨 Workflow Templates

1. Code Analysis Workflow

await bulk_operations_create_code_analysis_workflow(
    name="Project Analysis",
    target_path="/path/to/project",
    include_patterns=["*.py", "*.js", "*.ts"],
    exclude_patterns=["node_modules/*", "*.min.js"]
)

2. Fix and Test Workflow

await bulk_operations_create_fix_and_test_workflow(
    name="Auto Fix",
    target_files=["/path/to/file1.py", "/path/to/file2.py"],
    backup_enabled=True,
    run_tests=True
)

🛡️ Safety Workflow

SACRED TRUST Protocol

1. 🧪 ALWAYS DRY RUN FIRST

# Validate before execution
dry_run_result = await bulk_operations_dry_run_bulk_workflow(workflow_id)
if not dry_run_result.get("ready_for_execution"):
    print("❌ Workflow has safety issues - do not proceed")

2. 🔒 ENABLE DESTRUCTIVE TOOLS ONLY WHEN NEEDED

# Enable destructive tools with confirmation
await security_manager_enable_destructive_tools(
    enabled=True,
    confirm_destructive=True
)

# Execute workflow
await bulk_operations_execute_bulk_workflow(
    workflow_id=workflow_id,
    dry_run=False,
    confirm_destructive=True
)

# Disable destructive tools after use
await security_manager_enable_destructive_tools(
    enabled=False,
    confirm_destructive=False
)

3. 📊 MONITOR PROGRESS

# Check workflow status
status = await bulk_operations_get_workflow_status(
    workflow_id=workflow_id,
    include_operation_details=True
)

🔧 Advanced Features

Dependency Management

operations = [
    {
        "id": "setup",
        "tool_name": "git_status",
        "arguments": {"path": "/project"}
    },
    {
        "id": "backup",
        "tool_name": "archive_create_backup",
        "arguments": {"source_paths": ["/project"]},
        "depends_on": ["setup"]  # Runs after setup
    },
    {
        "id": "test",
        "tool_name": "dev_workflow_run_tests",
        "arguments": {"test_type": "unit"},
        "depends_on": ["backup"]  # Runs after backup
    }
]

Execution Modes

• Sequential: Operations run one after another
• Parallel: Independent operations run simultaneously
• Staged: Dependency-aware execution in stages
• Interactive: Prompt for confirmation between steps

Error Handling

# Continue execution even if some operations fail
await bulk_operations_execute_bulk_workflow(
    workflow_id=workflow_id,
    continue_on_error=True
)

# Rollback completed workflow (where possible)
await bulk_operations_rollback_workflow(
    workflow_id=workflow_id,
    confirm_rollback=True
)

📈 Monitoring & Management

List All Workflows

workflows = await bulk_operations_list_workflows()
print(f"Total workflows: {workflows['total_workflows']}")

Security Status

status = await security_manager_security_status()
print(f"Protection level: {status['safety_summary']['protection_level']}")

Tool Visibility

tools = await security_manager_list_tools_by_security()
print(f"Visible tools: {tools['visible_tools']}")
print(f"Hidden tools: {tools['hidden_tools']}")

⚠️ Important Safety Reminders

1. ALWAYS run dry run validation first
2. Enable destructive tools only when necessary
3. Create backups before destructive operations
4. Monitor execution progress
5. Disable destructive tools after use
6. Test workflows on non-critical data first
7. Have rollback plans ready

🎯 Example: Complete Workflow

# 1. Check security status
security_status = await security_manager_security_status()

# 2. Create workflow
workflow = await bulk_operations_create_code_analysis_workflow(
    name="Security Audit",
    target_path="/my/project"
)

# 3. Validate with dry run
dry_run = await bulk_operations_dry_run_bulk_workflow(workflow["workflow_id"])

# 4. Execute if safe
if dry_run.get("ready_for_execution"):
    result = await bulk_operations_execute_bulk_workflow(
        workflow_id=workflow["workflow_id"],
        dry_run=False
    )
    print(f"✅ Workflow completed: {result['completed_operations']} operations")
else:
    print("❌ Workflow failed validation")

🔗 Integration Points

The BulkToolCaller integrates with:

• SecurityManager: For safety controls and tool visibility
• ComponentService: For progressive tool disclosure
• All tool modules: As registered executors
• Enhanced MCPBase: For consistent architecture

🎉 Benefits

1. Powerful Automation: Orchestrate complex multi-step workflows
2. Safety First: Built-in safety controls and validation
3. Flexible Execution: Multiple modes for different scenarios
4. Error Recovery: Comprehensive error handling and rollback
5. Security Integration: Seamless integration with existing security framework
6. Progress Monitoring: Real-time status and progress tracking

The BulkToolCaller transforms your Enhanced MCP Tools into a powerful workflow orchestration platform while maintaining the highest safety standards through the SACRED TRUST framework.