fasttransfer-mcp 0.1.0__tar.gz

fasttransfer_mcp-0.1.0/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:fasttransfer.arpe.io)",
+      "Bash(/home/francois/Workspace/fasttransfer-mcp/fasttransfer/FastTransfer:*)",
+      "Bash(find:*)",
+      "Bash(/home/francois/Workspace/FastTransfer/latest/FastTransfer:*)",
+      "Bash(python -m pytest tests/ -v)",
+      "Bash(pip show:*)",
+      "Bash(pip install build)",
+      "Bash(python -m build:*)",
+      "Bash(python:*)",
+      "Bash(pip install:*)"
+    ]
+  }
+}

fasttransfer_mcp-0.1.0/.env.example

@@ -0,0 +1,17 @@
+# FastTransfer MCP Server Configuration
+
+# Path to FastTransfer binary
+# Default: ./fasttransfer/FastTransfer
+FASTTRANSFER_PATH=./fasttransfer/FastTransfer
+
+# Maximum execution timeout in seconds
+# Default: 1800 (30 minutes)
+FASTTRANSFER_TIMEOUT=1800
+
+# Directory for execution logs
+# Default: ./logs
+FASTTRANSFER_LOG_DIR=./logs
+
+# Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+# Default: INFO
+LOG_LEVEL=INFO

fasttransfer_mcp-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+ENV/
+env/
+
+# Environment variables
+.env
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Logs
+logs/
+*.log
+
+# OS
+.DS_Store
+Thumbs.db

fasttransfer_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to the FastTransfer MCP Server will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-20
+
+### Added
+
+- MCP server with six tools: `preview_transfer_command`, `execute_transfer`, `validate_connection`, `list_supported_combinations`, `suggest_parallelism_method`, `get_version`
+- Version detection module (`src/version.py`) with static capability registry for FastTransfer v0.16.0.0
+  - `FastTransferVersion` dataclass with comparison operators
+  - `VersionDetector` with subprocess-based detection, caching, and graceful fallback
+  - `VersionCapabilities` registry mapping versions to supported types and feature flags
+- 16 source connection types: `clickhouse`, `duckdb`, `duckdbstream`, `hana`, `mssql`, `msoledbsql`, `mysql`, `nzoledb`, `nzsql`, `nzbulk`, `odbc`, `oledb`, `oraodp`, `pgcopy`, `pgsql`, `teradata`
+- 11 target connection types: `clickhousebulk`, `duckdb`, `hanabulk`, `msbulk`, `mysqlbulk`, `nzbulk`, `orabulk`, `oradirect`, `pgcopy`, `pgsql`, `teradata`
+- 9 parallelism methods: `Ctid`, `DataDriven`, `Ntile`, `NZDataSlice`, `None`, `Physloc`, `Random`, `RangeId`, `Rowid`
+- Flexible connection configuration: `server` (optional), `connect_string`, `dsn`, `provider`, `file_input`, `trusted_auth`
+- Mutual exclusivity validation for connection parameters
+- Transfer options: `data_driven_query`, `use_work_tables`, `settings_file`, `log_level`, `no_banner`, `license_path`
+- `LogLevel` enum: `error`, `warning`, `information`, `debug`, `fatal`
+- Physloc method validation (SQL Server sources only)
+- Password and connection string masking in command output
+- DuckDB Stream file import as a source category
+- Parallelism suggestion engine with Physloc recommendation for SQL Server without numeric key
+- 122 tests across three test modules

fasttransfer_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arpe.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fasttransfer_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: fasttransfer-mcp
+Version: 0.1.0
+Summary: A Model Context Protocol (MCP) server for FastTransfer, enabling efficient data transfer between database systems.
+Project-URL: Homepage, https://aetperf.github.io/FastTransfer-Documentation/
+Project-URL: Repository, https://github.com/aetperf/fasttransfer-mcp
+Project-URL: Issues, https://github.com/aetperf/fasttransfer-mcp/issues
+Author: Arpe.io
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data-transfer,database,etl,fasttransfer,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.11.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# FastTransfer MCP Server
+
+<!-- mcp-name: io.github.aetperf/fasttransfer-mcp -->
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes [FastTransfer](https://aetperf.github.io/FastTransfer-Documentation/) functionality for efficient data transfer between various database systems.
+
+## Overview
+
+FastTransfer is a high-performance CLI tool for transferring data between databases. This MCP server wraps FastTransfer functionality and provides:
+
+- **Safety-first approach**: Preview commands before execution with user confirmation required
+- **Password masking**: Credentials and connection strings are never displayed in logs or output
+- **Intelligent validation**: Parameter validation with database-specific compatibility checks
+- **Smart suggestions**: Automatic parallelism method recommendations
+- **Version detection**: Automatic binary version detection with capability registry
+- **Comprehensive logging**: Full execution logs with timestamps and results
+
+## MCP Tools
+
+### 1. `preview_transfer_command`
+Build and preview a FastTransfer command WITHOUT executing it. Shows the exact command with passwords masked. Always use this first.
+
+### 2. `execute_transfer`
+Execute a previously previewed command. Requires `confirmation: true` as a safety mechanism.
+
+### 3. `validate_connection`
+Validate database connection parameters (parameter check only, does not test actual connectivity).
+
+### 4. `list_supported_combinations`
+List all supported source-to-target database combinations.
+
+### 5. `suggest_parallelism_method`
+Recommend the optimal parallelism method based on source database type and table characteristics.
+
+### 6. `get_version`
+Report the detected FastTransfer binary version, supported types, and feature flags.
+
+## Parallelism Methods
+
+| Method | Best For | Requires Key |
+|--------|----------|:------------:|
+| `Ctid` | PostgreSQL sources | No |
+| `Rowid` | Oracle sources | No |
+| `Physloc` | SQL Server sources without numeric key | No |
+| `NZDataSlice` | Netezza sources | No |
+| `RangeId` | Large tables with numeric key | Yes |
+| `Random` | Tables with evenly distributed numeric key | Yes |
+| `DataDriven` | Any column type, distinct values | Yes |
+| `Ntile` | Even distribution across workers | Yes |
+| `None` | Small tables or troubleshooting | No |
+
+## Installation
+
+### Prerequisites
+
+- Python 3.10 or higher
+- FastTransfer binary v0.16+ (obtain from [Arpe.io](https://arpe.io))
+- Claude Code or another MCP client
+
+### Setup
+
+1. **Clone or download this repository**:
+   ```bash
+   cd /path/to/fasttransfer-mcp
+   ```
+
+2. **Install Python dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Configure environment**:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your FastTransfer path
+   ```
+
+4. **Add to Claude Code configuration** (`~/.claude.json`):
+   ```json
+   {
+     "mcpServers": {
+       "fasttransfer": {
+         "type": "stdio",
+         "command": "python",
+         "args": ["/absolute/path/to/fasttransfer-mcp/src/server.py"],
+         "env": {
+           "FASTTRANSFER_PATH": "/absolute/path/to/fasttransfer/FastTransfer"
+         }
+       }
+     }
+   }
+   ```
+
+5. **Restart Claude Code** to load the MCP server.
+
+6. **Verify installation**:
+   ```
+   # In Claude Code, run:
+   /mcp
+   # You should see "fasttransfer: connected"
+   ```
+
+## Configuration
+
+### Environment Variables
+
+Edit `.env` to configure:
+
+```bash
+# Path to FastTransfer binary (required)
+FASTTRANSFER_PATH=./fasttransfer/FastTransfer
+
+# Execution timeout in seconds (default: 1800 = 30 minutes)
+FASTTRANSFER_TIMEOUT=1800
+
+# Log directory (default: ./logs)
+FASTTRANSFER_LOG_DIR=./logs
+
+# Log level (default: INFO)
+LOG_LEVEL=INFO
+```
+
+## Connection Options
+
+The server supports multiple ways to authenticate and connect:
+
+| Parameter | Description |
+|-----------|-------------|
+| `server` | Host:port or host\instance (optional with `connect_string` or `dsn`) |
+| `user` / `password` | Standard credentials |
+| `trusted_auth` | Windows trusted authentication |
+| `connect_string` | Full connection string (excludes server/user/password/dsn) |
+| `dsn` | ODBC DSN name (excludes server/provider) |
+| `provider` | OleDB provider name |
+| `file_input` | File path for data input (source only, excludes query) |
+
+## Transfer Options
+
+| Option | CLI Flag | Description |
+|--------|----------|-------------|
+| `method` | `--method` | Parallelism method |
+| `distribute_key_column` | `--distributeKeyColumn` | Column for data distribution |
+| `degree` | `--degree` | Parallelism degree (0=auto, >0=fixed, <0=CPU adaptive) |
+| `load_mode` | `--loadmode` | Append or Truncate |
+| `batch_size` | `--batchsize` | Batch size for bulk operations |
+| `map_method` | `--mapmethod` | Column mapping: Position or Name |
+| `run_id` | `--runid` | Run ID for logging |
+| `data_driven_query` | `--datadrivenquery` | Custom SQL for DataDriven method |
+| `use_work_tables` | `--useworktables` | Intermediate work tables for CCI |
+| `settings_file` | `--settingsfile` | Custom settings JSON file |
+| `log_level` | `--loglevel` | Override log level (error/warning/information/debug/fatal) |
+| `no_banner` | `--nobanner` | Suppress banner output |
+| `license_path` | `--license` | License file path or URL |
+
+## Usage Examples
+
+### PostgreSQL to SQL Server Transfer
+
+```
+User: "Copy the 'orders' table from PostgreSQL (localhost:5432, database: sales_db,
+       schema: public) to SQL Server (localhost:1433, database: warehouse, schema: dbo).
+       Use parallel transfer and truncate the target first."
+
+Claude Code will:
+1. Call suggest_parallelism_method to recommend Ctid for PostgreSQL
+2. Call preview_transfer_command with your parameters
+3. Show the command with masked passwords
+4. Explain what will happen
+5. Ask for confirmation
+6. Execute with execute_transfer when you approve
+```
+
+### File Import via DuckDB Stream
+
+```
+User: "Import /data/export.parquet into the SQL Server 'staging' table
+       using DuckDB stream."
+
+Claude Code will use duckdbstream source type with file_input parameter.
+```
+
+### Check Version and Capabilities
+
+```
+User: "What version of FastTransfer is installed?"
+
+Claude Code will call get_version and display the detected version,
+supported source/target types, and available features.
+```
+
+## Two-Step Safety Process
+
+This server implements a mandatory two-step process:
+
+1. **Preview** - Always use `preview_transfer_command` first
+2. **Execute** - Use `execute_transfer` with `confirmation: true`
+
+You cannot execute without previewing first and confirming.
+
+## Security
+
+- Passwords and connection strings are masked in all output and logs
+- Sensitive flags masked: `--sourcepassword`, `--targetpassword`, `--sourceconnectstring`, `--targetconnectstring`, `-x`, `-X`, `-g`, `-G`
+- Use environment variables for sensitive configuration
+- Review commands carefully before executing
+- Use minimum required database permissions
+
+## Testing
+
+Run the test suite:
+
+```bash
+# Run all tests
+python -m pytest tests/ -v
+
+# Run with coverage
+python -m pytest tests/ --cov=src --cov-report=html
+```
+
+## Project Structure
+
+```
+fasttransfer-mcp/
+  src/
+    __init__.py
+    server.py          # MCP server (tool definitions, handlers)
+    fasttransfer.py    # Command builder, executor, suggestions
+    validators.py      # Pydantic models, enums, validation
+    version.py         # Version detection and capabilities registry
+  tests/
+    __init__.py
+    test_command_builder.py
+    test_validators.py
+    test_version.py
+  .env.example
+  requirements.txt
+  CHANGELOG.md
+  README.md
+```
+
+## License
+
+This MCP server wrapper is provided as-is. FastTransfer itself is a separate product from Arpe.io.
+
+## Related Links
+
+- [FastTransfer Documentation](https://aetperf.github.io/FastTransfer-Documentation/)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Claude Code](https://claude.com/claude-code)

fasttransfer_mcp-0.1.0/README.md

@@ -0,0 +1,249 @@
+# FastTransfer MCP Server
+
+<!-- mcp-name: io.github.aetperf/fasttransfer-mcp -->
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes [FastTransfer](https://aetperf.github.io/FastTransfer-Documentation/) functionality for efficient data transfer between various database systems.
+
+## Overview
+
+FastTransfer is a high-performance CLI tool for transferring data between databases. This MCP server wraps FastTransfer functionality and provides:
+
+- **Safety-first approach**: Preview commands before execution with user confirmation required
+- **Password masking**: Credentials and connection strings are never displayed in logs or output
+- **Intelligent validation**: Parameter validation with database-specific compatibility checks
+- **Smart suggestions**: Automatic parallelism method recommendations
+- **Version detection**: Automatic binary version detection with capability registry
+- **Comprehensive logging**: Full execution logs with timestamps and results
+
+## MCP Tools
+
+### 1. `preview_transfer_command`
+Build and preview a FastTransfer command WITHOUT executing it. Shows the exact command with passwords masked. Always use this first.
+
+### 2. `execute_transfer`
+Execute a previously previewed command. Requires `confirmation: true` as a safety mechanism.
+
+### 3. `validate_connection`
+Validate database connection parameters (parameter check only, does not test actual connectivity).
+
+### 4. `list_supported_combinations`
+List all supported source-to-target database combinations.
+
+### 5. `suggest_parallelism_method`
+Recommend the optimal parallelism method based on source database type and table characteristics.
+
+### 6. `get_version`
+Report the detected FastTransfer binary version, supported types, and feature flags.
+
+## Parallelism Methods
+
+| Method | Best For | Requires Key |
+|--------|----------|:------------:|
+| `Ctid` | PostgreSQL sources | No |
+| `Rowid` | Oracle sources | No |
+| `Physloc` | SQL Server sources without numeric key | No |
+| `NZDataSlice` | Netezza sources | No |
+| `RangeId` | Large tables with numeric key | Yes |
+| `Random` | Tables with evenly distributed numeric key | Yes |
+| `DataDriven` | Any column type, distinct values | Yes |
+| `Ntile` | Even distribution across workers | Yes |
+| `None` | Small tables or troubleshooting | No |
+
+## Installation
+
+### Prerequisites
+
+- Python 3.10 or higher
+- FastTransfer binary v0.16+ (obtain from [Arpe.io](https://arpe.io))
+- Claude Code or another MCP client
+
+### Setup
+
+1. **Clone or download this repository**:
+   ```bash
+   cd /path/to/fasttransfer-mcp
+   ```
+
+2. **Install Python dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Configure environment**:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your FastTransfer path
+   ```
+
+4. **Add to Claude Code configuration** (`~/.claude.json`):
+   ```json
+   {
+     "mcpServers": {
+       "fasttransfer": {
+         "type": "stdio",
+         "command": "python",
+         "args": ["/absolute/path/to/fasttransfer-mcp/src/server.py"],
+         "env": {
+           "FASTTRANSFER_PATH": "/absolute/path/to/fasttransfer/FastTransfer"
+         }
+       }
+     }
+   }
+   ```
+
+5. **Restart Claude Code** to load the MCP server.
+
+6. **Verify installation**:
+   ```
+   # In Claude Code, run:
+   /mcp
+   # You should see "fasttransfer: connected"
+   ```
+
+## Configuration
+
+### Environment Variables
+
+Edit `.env` to configure:
+
+```bash
+# Path to FastTransfer binary (required)
+FASTTRANSFER_PATH=./fasttransfer/FastTransfer
+
+# Execution timeout in seconds (default: 1800 = 30 minutes)
+FASTTRANSFER_TIMEOUT=1800
+
+# Log directory (default: ./logs)
+FASTTRANSFER_LOG_DIR=./logs
+
+# Log level (default: INFO)
+LOG_LEVEL=INFO
+```
+
+## Connection Options
+
+The server supports multiple ways to authenticate and connect:
+
+| Parameter | Description |
+|-----------|-------------|
+| `server` | Host:port or host\instance (optional with `connect_string` or `dsn`) |
+| `user` / `password` | Standard credentials |
+| `trusted_auth` | Windows trusted authentication |
+| `connect_string` | Full connection string (excludes server/user/password/dsn) |
+| `dsn` | ODBC DSN name (excludes server/provider) |
+| `provider` | OleDB provider name |
+| `file_input` | File path for data input (source only, excludes query) |
+
+## Transfer Options
+
+| Option | CLI Flag | Description |
+|--------|----------|-------------|
+| `method` | `--method` | Parallelism method |
+| `distribute_key_column` | `--distributeKeyColumn` | Column for data distribution |
+| `degree` | `--degree` | Parallelism degree (0=auto, >0=fixed, <0=CPU adaptive) |
+| `load_mode` | `--loadmode` | Append or Truncate |
+| `batch_size` | `--batchsize` | Batch size for bulk operations |
+| `map_method` | `--mapmethod` | Column mapping: Position or Name |
+| `run_id` | `--runid` | Run ID for logging |
+| `data_driven_query` | `--datadrivenquery` | Custom SQL for DataDriven method |
+| `use_work_tables` | `--useworktables` | Intermediate work tables for CCI |
+| `settings_file` | `--settingsfile` | Custom settings JSON file |
+| `log_level` | `--loglevel` | Override log level (error/warning/information/debug/fatal) |
+| `no_banner` | `--nobanner` | Suppress banner output |
+| `license_path` | `--license` | License file path or URL |
+
+## Usage Examples
+
+### PostgreSQL to SQL Server Transfer
+
+```
+User: "Copy the 'orders' table from PostgreSQL (localhost:5432, database: sales_db,
+       schema: public) to SQL Server (localhost:1433, database: warehouse, schema: dbo).
+       Use parallel transfer and truncate the target first."
+
+Claude Code will:
+1. Call suggest_parallelism_method to recommend Ctid for PostgreSQL
+2. Call preview_transfer_command with your parameters
+3. Show the command with masked passwords
+4. Explain what will happen
+5. Ask for confirmation
+6. Execute with execute_transfer when you approve
+```
+
+### File Import via DuckDB Stream
+
+```
+User: "Import /data/export.parquet into the SQL Server 'staging' table
+       using DuckDB stream."
+
+Claude Code will use duckdbstream source type with file_input parameter.
+```
+
+### Check Version and Capabilities
+
+```
+User: "What version of FastTransfer is installed?"
+
+Claude Code will call get_version and display the detected version,
+supported source/target types, and available features.
+```
+
+## Two-Step Safety Process
+
+This server implements a mandatory two-step process:
+
+1. **Preview** - Always use `preview_transfer_command` first
+2. **Execute** - Use `execute_transfer` with `confirmation: true`
+
+You cannot execute without previewing first and confirming.
+
+## Security
+
+- Passwords and connection strings are masked in all output and logs
+- Sensitive flags masked: `--sourcepassword`, `--targetpassword`, `--sourceconnectstring`, `--targetconnectstring`, `-x`, `-X`, `-g`, `-G`
+- Use environment variables for sensitive configuration
+- Review commands carefully before executing
+- Use minimum required database permissions
+
+## Testing
+
+Run the test suite:
+
+```bash
+# Run all tests
+python -m pytest tests/ -v
+
+# Run with coverage
+python -m pytest tests/ --cov=src --cov-report=html
+```
+
+## Project Structure
+
+```
+fasttransfer-mcp/
+  src/
+    __init__.py
+    server.py          # MCP server (tool definitions, handlers)
+    fasttransfer.py    # Command builder, executor, suggestions
+    validators.py      # Pydantic models, enums, validation
+    version.py         # Version detection and capabilities registry
+  tests/
+    __init__.py
+    test_command_builder.py
+    test_validators.py
+    test_version.py
+  .env.example
+  requirements.txt
+  CHANGELOG.md
+  README.md
+```
+
+## License
+
+This MCP server wrapper is provided as-is. FastTransfer itself is a separate product from Arpe.io.
+
+## Related Links
+
+- [FastTransfer Documentation](https://aetperf.github.io/FastTransfer-Documentation/)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Claude Code](https://claude.com/claude-code)