# Build and Test MCP Server for FastTransfer CLI Tool

## Context
FastTransfer is a command-line tool for efficient data transfer between various database systems. Documentation: https://aetperf.github.io/FastTransfer-Documentation/

Key capabilities:
- **Source databases**: ClickHouse, DuckDB, MySQL, Netezza, Oracle, PostgreSQL, SQL Server, SAP Hana, Teradata
- **Target databases**: ClickHouse, DuckDB, MySQL, Netezza, Oracle, PostgreSQL, SQL Server, SAP Hana, Teradata
- **Parallelism methods**: DataDriven, Ctid (PostgreSQL), Random, Rowid (Oracle), RangeId, Ntile, NZDataSlice (Netezza), None
- **Load modes**: Append, Truncate
- **Mapping**: Position-based or Name-based column mapping

## Objective
Create a complete, production-ready MCP server that:
1. Exposes FastTransfer functionality through MCP tools
2. **Implements user validation/approval before executing any commands**
3. Provides clear, helpful error messages
4. Handles all FastTransfer parameters intelligently
5. Includes comprehensive testing

## Requirements

### 1. Project Structure
```
fasttransfer-mcp/
├── src/
│   ├── __init__.py
│   ├── server.py              # Main MCP server
│   ├── fasttransfer.py        # FastTransfer command builder
│   └── validators.py          # Input validation
├── tests/
│   ├── test_server.py
│   └── test_command_builder.py
├── requirements.txt
├── README.md
└── .env.example
```

### 2. Core MCP Tools to Implement

#### Tool 1: `preview_transfer_command`
**Purpose**: Build and preview FastTransfer command WITHOUT executing
**Parameters**:
```json
{
  "source": {
    "type": "string (enum: mssql, pgsql, mysql, oracle, etc.)",
    "server": "string",
    "database": "string",
    "schema": "string (optional)",
    "table": "string (optional)",
    "query": "string (optional - SQL query instead of table)",
    "user": "string",
    "password": "string",
    "trusted_auth": "boolean (optional)"
  },
  "target": {
    "type": "string (enum: msbulk, pgcopy, mysqlbulk, orabulk, etc.)",
    "server": "string",
    "database": "string",
    "schema": "string",
    "table": "string",
    "user": "string",
    "password": "string",
    "trusted_auth": "boolean (optional)"
  },
  "options": {
    "method": "string (enum: DataDriven, Ctid, Random, Rowid, RangeId, Ntile, None)",
    "distribute_key_column": "string (optional)",
    "degree": "integer (default: -2)",
    "load_mode": "string (enum: Append, Truncate)",
    "batch_size": "integer (optional)",
    "map_method": "string (enum: Position, Name)",
    "run_id": "string (optional)"
  }
}
```
**Returns**: 
- Full FastTransfer command string
- Explanation of what the command will do
- Warning about any sensitive data in the command

#### Tool 2: `execute_transfer`
**Purpose**: Execute a previously previewed command
**Parameters**:
```json
{
  "command": "string (the exact command from preview_transfer_command)",
  "confirmation": "boolean (must be true)"
}
```
**Returns**: Execution results, logs, success/failure status

#### Tool 3: `validate_connection`
**Purpose**: Test database connectivity before transfer
**Parameters**:
```json
{
  "connection": {
    "type": "string",
    "server": "string",
    "database": "string",
    "user": "string",
    "password": "string"
  },
  "side": "string (enum: source, target)"
}
```
**Returns**: Connection test results

#### Tool 4: `list_supported_combinations`
**Purpose**: Show supported source → target combinations
**Returns**: Matrix of supported database pairs

#### Tool 5: `suggest_parallelism_method`
**Purpose**: Recommend best parallelism method based on source database and table
**Parameters**:
```json
{
  "source_type": "string",
  "has_numeric_key": "boolean",
  "has_identity_column": "boolean",
  "table_size_estimate": "string (small, medium, large)"
}
```
**Returns**: Recommended method with explanation

### 3. Safety and Validation Features

**CRITICAL REQUIREMENTS**:
- **Never execute commands without explicit user approval**
- **Always preview commands first** using `preview_transfer_command`
- **Mask passwords** in displayed commands (show as ******)
- **Validate all parameters** before building commands
- **Check FastTransfer binary exists** before attempting execution
- **Implement timeout protection** (default 30 minutes max)
- **Log all executions** with timestamps and results

### 4. Command Builder Logic

The `fasttransfer.py` module should:
- Build FastTransfer commands using **long parameter names** (--sourceserver, not -i)
- Handle optional parameters intelligently
- Escape special characters in passwords/queries
- Support both table-based and query-based transfers
- Validate parameter combinations (e.g., Ctid only works with PostgreSQL sources)

Example command structure:
```bash
./FastTransfer.exe \
  --sourceconnectiontype "pgsql" \
  --sourceserver "localhost:5432" \
  --sourceuser "myuser" \
  --sourcepassword "******" \
  --sourcedatabase "mydb" \
  --sourceschema "public" \
  --sourcetable "customers" \
  --targetconnectiontype "msbulk" \
  --targetserver "localhost" \
  --targetuser "sa" \
  --targetpassword "******" \
  --targetdatabase "TargetDB" \
  --targetschema "dbo" \
  --targettable "customers" \
  --method "RangeId" \
  --distributeKeyColumn "customer_id" \
  --degree -2 \
  --loadmode "Truncate" \
  --runid "transfer-20250413-001"
```

### 5. Configuration

**Environment Variables** (via .env):
```bash
FASTTRANSFER_PATH=/path/to/FastTransfer.exe
FASTTRANSFER_TIMEOUT=1800  # 30 minutes
FASTTRANSFER_LOG_DIR=./logs
```

**MCP Server Config** (~/.claude.json):
```json
{
  "mcpServers": {
    "fasttransfer": {
      "type": "stdio",
      "command": "python",
      "args": ["/absolute/path/to/fasttransfer-mcp/src/server.py"],
      "env": {
        "FASTTRANSFER_PATH": "/path/to/FastTransfer.exe"
      }
    }
  }
}
```

### 6. Testing Strategy

Create tests for:
1. **Command building** - Verify correct FastTransfer commands are generated
2. **Parameter validation** - Test invalid inputs are rejected
3. **Preview functionality** - Ensure commands display correctly with masked passwords
4. **Error handling** - Test missing binary, invalid connections, timeouts
5. **Integration test** - Test with actual FastTransfer binary (if available)

**Mock Testing Approach**:
- Mock subprocess calls to FastTransfer
- Test command structure without actual database connections
- Validate MCP protocol compliance

### 7. Documentation

**README.md should include**:
- Installation instructions
- Configuration steps
- Usage examples with Claude Code
- Security best practices
- Troubleshooting guide

**Example usage in Claude Code**:
```
User: "I need to copy the 'orders' table from my PostgreSQL database 
       (localhost:5432, db: sales_db) to SQL Server (localhost:1433, 
       db: warehouse). Use parallel transfer and truncate the target table."

Claude Code:
1. Calls preview_transfer_command
2. Shows user the exact command
3. Asks for confirmation
4. If confirmed, calls execute_transfer
5. Shows results
```

### 8. Implementation Guidelines

**Use these libraries**:
```txt
mcp>=0.9.0
python-dotenv>=1.0.0
pydantic>=2.0.0  # For input validation
```

**Code quality**:
- Type hints on all functions
- Comprehensive error handling
- Logging at appropriate levels
- Clear docstrings
- Follow PEP 8

**Security considerations**:
- Never log passwords in plain text
- Use environment variables for sensitive config
- Validate all user inputs
- Sanitize command-line parameters
- Implement execution timeouts

## Deliverables

1. **Fully functional MCP server** with all 5 tools implemented
2. **Comprehensive test suite** with >80% coverage
3. **Complete documentation** (README, code comments)
4. **Example configuration files** (.env.example, config.json example)
5. **Example usage scenarios** demonstrating the two-step approval process

## Testing Instructions

After building:

1. **Install the MCP server**:
   ```bash
   cd fasttransfer-mcp
   pip install -r requirements.txt
   ```

2. **Configure environment**:
   ```bash
   cp .env.example .env
   # Edit .env with your FastTransfer path
   ```

3. **Add to Claude Code**:
   Edit `~/.claude.json` with the config above

4. **Restart Claude Code**

5. **Test in Claude Code**:
   ```bash
   claude
   # Then run: /mcp
   # Should show "fasttransfer: connected"
   ```

6. **Try a preview**:
   ```
   "Can you preview a command to transfer data from PostgreSQL 
   (localhost, database: testdb, table: users) to SQL Server 
   (localhost, database: targetdb, table: users)? Use truncate mode."
   ```

7. **Verify the two-step process works**:
   - Command is previewed with masked passwords
   - Confirmation is required before execution
   - Results are clearly displayed

## Success Criteria

- ✅ All 5 MCP tools working correctly
- ✅ User approval required before ANY execution
- ✅ Passwords are masked in all displays
- ✅ Clear error messages for common issues
- ✅ Tests pass with good coverage
- ✅ Documentation is complete and clear
- ✅ Successfully tested with Claude Code

## Important Notes

- **NEVER execute FastTransfer without user confirmation**
- **Always preview first, execute second**
- **This is a security-critical tool** - handle credentials carefully
- **Test thoroughly** before using with production databases
- The FastTransfer binary must be obtained separately from Arpe.io

---

**START HERE**: Begin by creating the project structure, then implement the MCP server with the five tools, focusing first on `preview_transfer_command` and the safety mechanisms.

The fasttransfer binary is located in the fasttransfer subfolder