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

```python
# 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
```python
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
```python
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**
```python
# 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**
```python
# 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**
```python
# Check workflow status
status = await bulk_operations_get_workflow_status(
    workflow_id=workflow_id,
    include_operation_details=True
)
```

## 🔧 Advanced Features

### Dependency Management
```python
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
```python
# 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
```python
workflows = await bulk_operations_list_workflows()
print(f"Total workflows: {workflows['total_workflows']}")
```

### Security Status
```python
status = await security_manager_security_status()
print(f"Protection level: {status['safety_summary']['protection_level']}")
```

### Tool Visibility
```python
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

```python
# 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.