---
name: v2-compat
description: "V2 backward compatibility layer mapping underscore-based MCP tool names to V3 slash-based implementations with parameter translation"
metadata:
  openclaw:
    emoji: "🔀"
---

# V2 Compat — Backward Compatibility Tool Layer

Provides backward compatibility with V2 MCP tool naming conventions. Maps V2 underscore-based tool names (e.g., `swarm_init`) to V3 slash-based implementations (e.g., `swarm/init`) with automatic parameter translation between the two APIs.

## Purpose

Ensures existing V2 integrations and scripts continue to work after the V3 migration. All V2 tools are marked as deprecated and delegate to V3 handlers internally, translating input parameters and response formats as needed.

## Source Location

`/tmp/ruflo/v3/mcp/tools/v2-compat-tools.ts`

## Tool Mapping

### Swarm Tools

| V2 Tool | V3 Tool | Description |
|---------|---------|-------------|
| `swarm_init` | `swarm/init` | Initialize swarm with topology |
| `swarm_status` | `swarm/status` | Get swarm status and metrics |
| `swarm_monitor` | `swarm/status` (with metrics) | Monitor swarm activity |

### Agent Tools

| V2 Tool | V3 Tool | Description |
|---------|---------|-------------|
| `agent_spawn` | `agent/spawn` | Spawn new agent |
| `agent_list` | `agent/list` | List active agents |
| `agent_metrics` | `agent/status` + `system/metrics` | Agent performance metrics |

### Task Tools

| V2 Tool | V3 Tool | Description |
|---------|---------|-------------|
| `task_orchestrate` | `tasks/create` | Orchestrate task across swarm |
| `task_status` | `tasks/status` / `tasks/list` | Check task progress |
| `task_results` | `tasks/results` | Retrieve completed task results |

### Memory Tools

| V2 Tool | V3 Tool | Description |
|---------|---------|-------------|
| `memory_usage` | `memory/store`, `memory/search`, `memory/list` | All memory operations |

### System Tools

| V2 Tool | V3 Tool | Description |
|---------|---------|-------------|
| `neural_status` | `system/status` | System health |
| `neural_train` | `hooks/pretrain` | Train intelligence |
| `neural_patterns` | `hooks/metrics` | Pattern metrics |
| `benchmark_run` | `system/metrics` | Run benchmarks |
| `features_detect` | `system/info` | Feature detection |

## Parameter Translation Details

### swarm_init -> swarm/init

```
V2 Input:                         V3 Input:
{                                 {
  topology: string,                 topology: string,
  maxAgents: number,    -->         maxAgents: number,
  strategy: string                  config: {
}                                     loadBalancing: strategy === 'balanced',
                                      autoScaling: strategy === 'adaptive'
                                    }
                                  }
```

### swarm_status -> swarm/status

```
V2 Input:                         V3 Input:
{                                 {
  detailed: boolean,    -->         includeAgents: detailed || verbose,
  verbose: boolean                  includeMetrics: detailed || verbose,
}                                   includeTopology: verbose
                                  }
```

### agent_spawn -> agent/spawn

```
V2 Input:                         V3 Input:
{                                 {
  type: string,         -->         agentType: type,
  name: string,                     id: name,
  capabilities: string[]            config: { capabilities },
}                                   priority: 'normal'
                                  }
```

### agent_list -> agent/list

```
V2 Input:                         V3 Input:
{                                 {
  filter: "all"|"active"|           status: filterMap[filter]
          "idle"|"busy"   -->     }
}
// "busy" maps to "active" in V3
```

### task_orchestrate -> tasks/create

```
V2 Input:                         V3 Input:
{                                 {
  task: string,         -->         name: task,
  strategy: string,                 description: task,
  priority: string,                 type: 'orchestration',
  maxAgents: number                 priority: priority,
}                                   config: { strategy, maxAgents }
                                  }
```

### memory_usage -> memory/* (action-based routing)

The `memory_usage` tool routes to different V3 tools based on the `action` parameter:

| V2 action | V3 Tool | Behavior |
|-----------|---------|----------|
| `store` | `memory/store` | Stores with namespace-prefixed key |
| `retrieve` | `memory/search` | Searches with limit: 1 |
| `delete` | `memory/store` | Stores null with deleted: true metadata |
| `list` | `memory/list` | Lists by namespace |

## Tool Metadata

All V2 compatibility tools share these properties:

```typescript
{
  category: 'v2-compat',
  tags: ['v2', ...],
  version: '2.0.0',
  deprecated: true      // Marked deprecated in all definitions
}
```

## V3 Import Dependencies

The compatibility layer imports handlers from these V3 tool modules:

- `swarm-tools.js` -- initSwarmTool, swarmStatusTool
- `agent-tools.js` -- spawnAgentTool, listAgentsTool, agentStatusTool
- `task-tools.js` -- createTaskTool, taskStatusTool, taskResultsTool, listTasksTool
- `memory-tools.js` -- storeMemoryTool, searchMemoryTool, listMemoryTool
- `system-tools.js` -- systemStatusTool, systemMetricsTool, systemInfoTool
- `hooks-tools.js` -- pretrainTool, metricsTool

## Migration Guide

To migrate from V2 to V3 tools:

1. Replace underscore naming with slash naming: `swarm_init` -> `swarm/init`
2. Update parameter names per the translation tables above
3. Remove `verbose`/`detailed` flags; use explicit `includeAgents`, `includeMetrics`, `includeTopology`
4. Replace `memory_usage` action-based routing with direct tool calls to `memory/store`, `memory/search`, `memory/list`
5. Replace `neural_*` tools with `system/*` and `hooks/*` equivalents