Work in Progress

Documentation

Learn how to use Transmute to transform your data. From getting started to advanced TXL patterns.

Welcome to Transmute

Transmute is a data transformation ecosystem built on TXL, a transformation language designed for readability and precision. Whether you're migrating data between formats, normalizing fields, or reshaping complex nested structures, Transmute provides the tools you need.

What can you do with Transmute?

  • Transform data between formats (CSV, JSON, XML, and more)
  • Normalize and clean data across large datasets
  • Build repeatable transformation pipelines
  • Version and review your transformations with TXL
  • Integrate directly into your applications via API

The Transmute Ecosystem

All tools speak the same TXL language and work together seamlessly:

Studio (TXM)

Visual schema mapping editor. Infer schemas, wire fields, and progressively work from simple to complex.

CLI (TXD)

Transform data via command line. Pipe in/out and compose multi-step pipelines.

API

REST API with generated clients. Integrate transformation into any application.

Editor (TXE)

Fix data issues directly. Open failed rows and resolve interactively.

MCP

Hosted Model Context Protocol server. Let an AI agent call transformation tools directly - see the MCP reference below.

Next Steps

Start with the Quick Start guide to begin your first transformation, explore the TXL Language documentation, or invoke Transmute through its API below.

Invoke Transmute through the API

The API uses JSON for mapping operations and multipart form data for file uploads. Its machine-readable contract is published at /openapi.json; the versioned /openapi/v1.json route remains available for compatibility.

Open Swagger UI
Run these PowerShell examples from the repository root. They use the included sample mapping and data. For local development, start Transmute first with .\start.ps1 start -App all -NoBrowser.

1. Check the service and contract

Set the local API address, verify health, and inspect the published OpenAPI document.

$baseUrl = "http://127.0.0.1:5000"

Invoke-RestMethod "$baseUrl/health"
Invoke-RestMethod "$baseUrl/openapi.json" | Select-Object openapi, info

2. Create a mapping

Create a server-side mapping from the repository's sample TXL file. Keep the returned ID for subsequent calls.

$mappingSource = [System.IO.File]::ReadAllText(
  (Resolve-Path "samples/mappings/orders.txl.md")
)

$createBody = @{
  name = "Orders API example"
  markdownSource = $mappingSource
} | ConvertTo-Json

$mapping = Invoke-RestMethod `
  -Method Post `
  -Uri "$baseUrl/api/v1/mappings" `
  -ContentType "application/json" `
  -Body $createBody

$mapping.id

3. Validate and preview

Validate the stored TXL, then preview it against an in-memory row before uploading a complete file.

$mappingId = $mapping.id

$validation = Invoke-RestMethod `
  -Method Post `
  -Uri "$baseUrl/api/v1/mappings/$mappingId/validate"
$validation

$previewBody = @{
  sampleRows = @(
    @{ order_id = "ORD-2001"; amount = "149.90"; placed_at = "2026-07-03" }
  )
  maxRows = 10
} | ConvertTo-Json -Depth 10

Invoke-RestMethod `
  -Method Post `
  -Uri "$baseUrl/api/v1/mappings/$mappingId/preview" `
  -ContentType "application/json" `
  -Body $previewBody

4. Transform a file

Create a valid four-row input from the sample CSV, upload it as multipart form data, and save the transformed response. The full sample intentionally includes one malformed amount for TXE repair testing. curl.exe explicitly selects the native curl binary in PowerShell.

New-Item -ItemType Directory -Path "output" -Force | Out-Null
Get-Content "samples/in/orders.csv" |
  Select-Object -First 5 |
  Set-Content "output/orders-api-input.csv"

curl.exe --fail-with-body `
  -X POST `
  -F "file=@output/orders-api-input.csv" `
  -o "output/orders-api.json" `
  "$baseUrl/api/v1/mappings/$mappingId/run"

Get-Content "output/orders-api.json"

Call the hosted API

For the deployed service, replace http://127.0.0.1:5000 with https://transmute.online. Before production integration, generate a client or inspect request and response schemas in the OpenAPI specification.

Connect an AI agent via MCP

Transmute runs a hosted Model Context Protocol server at https://transmute.online/mcp (Streamable HTTP transport). Point any MCP client at it and your agent gets four tools instead of hand-writing conversion code:

  • validate_txl - validate a TXL mapping document.
  • transform - run a TXL mapping over CSV/TSV/JSON/JSONL/NDJSON/XML/HTML input and return the result.
  • generate_txl - generate a TXL mapping from a destination schema, using an AI provider.
  • infer_schema - infer a destination schema from a source schema/samples and instructions, using an AI provider.
validate_txl and transform need no credentials - the endpoint accepts unauthenticated calls. generate_txl and infer_schema call out to an AI provider on your behalf, so pass your own provider, model and apiKey arguments per call; Transmute never stores that key. Mappings with custom ops (customOps) aren't accepted on this hosted endpoint - see the local MCP install, coming soon, for those.

1. Set up your agent

Pick your client below - each tab shows a one-line install and a manual config alternative.

Option A - one command

Run once in your terminal and the server is registered for your user:

claude mcp add --transport http transmute https://transmute.online/mcp

Option B - project config

Commit a .mcp.json at the repository root to share the server with everyone working in the repo:

{
  "mcpServers": {
    "transmute": {
      "type": "http",
      "url": "https://transmute.online/mcp"
    }
  }
}

2. Try it

Ask your agent to validate or transform the repository's sample mapping - e.g. "use the transmute MCP server to validate samples/mappings/orders.txl.md" - and it will call validate_txl directly instead of writing a script to check it.