Rulemorph MCP Server README

Rulemorph transforms data from external APIs, CSV, JSON, YAML, TOML, XML, HTML, Markdown, and Excel into predictable JSON using declarative YAML/JSON rules.

Instead of adding another custom script for every input source, you can keep transformation behavior in rule files. The same rules can be reused from the CLI, embedded in Rust, served through a local UI/API server, or exposed to AI assistants through MCP.

Try it in your browser: playground.rulemorph.com

What It Solves

Rulemorph moves growing transformation code into reviewable, versioned rules.

• Normalize vendor API responses into your internal schema
• Bring CSV / Excel imports into a JSON pipeline
• Extract values from HTML or XML and process them with the same rule model
• Review, replace, and version transformation behavior as YAML/JSON
• Reuse the same transformation from the CLI, a local API, or an AI assistant

It is not meant to replace application code for arbitrary execution, complex domain logic, or long-running workflow orchestration. For those cases, normal application code or a workflow engine is usually a better fit.

Quick Start

Transform a users array from an external API response into the JSON shape your application expects.

rules.yaml

version: 2
input:
  format: json
  json:
    records_path: "users"
mappings:
  - target: "id"
    source: "user_id"
  - target: "name"
    expr: ["@input.full_name", trim]
  - target: "email"
    expr: ["@input.username", concat: ["lit:@example.com"]]

input.json

{ "users": [{ "user_id": 1, "full_name": " Alice ", "username": "alice" }] }

Run

rulemorph transform -r rules.yaml -i input.json

You can also pipe input to transform:

cat input.json | rulemorph transform -r rules.yaml
cat input.json | rulemorph transform -r rules.yaml -i -

Output

[{ "id": 1, "name": "Alice", "email": "alice@example.com" }]

For quick one-off transformations without a rule file, use direct mode.

Evaluate a single expression against JSON or ad-hoc CSV:

echo '{ "test": 1 }' | rulemorph -rule '@input.test'
echo '{ "a": 1, "b": 2 }' | rulemorph --rule '["@input.a", {"+": ["@input.b"]}]'
echo 'a,test,1' | rulemorph -rule '@input.0'
echo 'a,test,1' | rulemorph -H 'id,name,age' -rule '@input.id'

1
3
"a"
"a"

Use -F/--field when you want a small output object and field order matters:

echo 'u1,Alice,42' | rulemorph -H 'id,name,age' \
  -F id='@input.id' \
  -F name='["@input.name","trim","uppercase"]' \
  -F age='["@input.age","int"]'

{ "id": "u1", "name": "ALICE", "age": 42 }

Use --output-map when a compact nested target map is easier to read:

echo 'u1,Alice,42' | rulemorph -H 'id,name,age' \
  --output-map '{"user.id":"@input.id","user.name":["@input.name","trim"],"age":["@input.age","int"]}'

{ "user": { "id": "u1", "name": "Alice" }, "age": 42 }

For multi-record direct input, add --ndjson to emit one JSON value per line:

printf 'u1,Alice,42\nu2,Bob,7\n' | rulemorph --ndjson -H 'id,name,age' \
  --output-map '{"id":"@input.id","age":["@input.age","int"]}'

{"age":42,"id":"u1"}
{"age":7,"id":"u2"}

Direct mode can also read CSV or Excel files. CSV headers are inferred from .csv files; use -H/--headers for headerless CSV. For Excel, select the header row and data range explicitly:

rulemorph --rule '@input.id' -i users.csv
rulemorph -H 'id,name,age' --rule '@input.id' -i headerless-users.csv
rulemorph --rule '@input.id' -i users.xlsx --excel-header-row 1 --excel-data-range A2:D20

"u1"
"u1"
["u1","u2"]

Which Package To Use

Installation

Prebuilt binaries for the CLI, server, and MCP server are available from GitHub Releases.

CLI

brew install vinhphatfsg/tap/rulemorph

Build from source for development:

cargo build -p rulemorph_cli --release
./target/release/rulemorph --help

UI / API Server

brew install vinhphatfsg/tap/rulemorph-server
rulemorph-server --rules-dir ./api_rules --api-mode rules

For full startup steps, see the UI Server Guide.

MCP Server

rulemorph-mcp exposes Rulemorph capabilities to AI assistants through the Model Context Protocol.

• transform: transform data
• validate_rules: validate rules
• generate_dto: generate DTOs
• analyze_input: summarize input structure

Claude Code setup:

claude mcp add rulemorph -- rulemorph-mcp

Key Features

• Normalize CSV / JSON / YAML / TOML / XML / HTML / Markdown / .xlsx Excel into JSON records
• Build output fields with mappings
• Transform values with v2 pipe expressions: trim, case conversion, concatenation, numeric operations, lookups, and array operations
• Define rule-local custom OPs with defs to reuse typed v2 pipes or mapping bodies
• Use numeric helpers such as sqrt, mod, pow, clamp, and range for bounded generated sequences
• Control behavior with record_when, when, and asserts
• Use steps, branch, and finalize for ordered execution and output-array processing
• Generate inferred DTOs for Rust, TypeScript, Python, Go, Java, Kotlin, and Swift. Explicit type wins; dynamic or unsafe shapes fall back to JSON-friendly types.
• Inspect semantic traces for built-in and custom OP execution without changing transform output
• Run a local UI/API server or expose the same engine through MCP

Input parsers are designed to be conservative. HTML parsing does not execute JavaScript or fetch URLs, Markdown raw HTML is preserved only as source text, and Excel parsing does not execute macros or evaluate formulas. XML DTD/entities and JSON/YAML duplicate keys are rejected to avoid ambiguous or side-effectful input behavior.

Rule Structure

version: 2
input:
  format: json # csv | json | yaml | toml | xml | html | markdown | excel
  json:
    records_path: "items"
mappings:
  - target: "output.field"
    source: "input.field"
    type: string
    when:
      eq: ["@input.status", "active"]

New rule files should use version: 2. version: 1 rule files are still accepted during migration, but validation and runtime entry points emit a deprecation warning. A later release will move version: 1 rule files behind an explicit legacy opt-in before removing that syntax.

For the full rule specification, see Transformation Rules Spec. The Japanese version is also available in Japanese.

DTO Generation

rulemorph generate -r rules.yaml -l typescript

export interface Record {
  id: number;
  name: string;
  email: string;
}

Supported languages: rust, typescript, python, go, java, kotlin, swift

DTO generation uses explicit mapping types first, then infers simple scalar, array, map, and nested object shapes from literals and v2 pipe expressions. If a shape is dynamic or too broad to infer safely, the generated DTO uses each language's JSON fallback type.

Library Usage

[dependencies]
rulemorph = "0.3.4"

The html, excel, and markdown input parsers are enabled by default. Library users that only need core CSV, JSON, YAML, TOML, and XML support can disable them to reduce optional parser dependencies:

[dependencies]
rulemorph = { version = "0.3.4", default-features = false }

Re-enable parsers explicitly with features such as ["html"], ["excel"], or ["markdown"]. If a disabled parser is selected by a rule, transformation fails with invalid_input (for Markdown: input format markdown is not enabled in this build).

use rulemorph::{parse_rule_file, transform};

let rule = parse_rule_file(&std::fs::read_to_string("rules.yaml")?)?;
let input = std::fs::read_to_string("input.json")?;
let output = transform(&rule, &input, None)?;

Documentation

• Documentation index
• Transformation Rules Spec / Japanese
• Endpoint Rules Spec
• Network Rules Spec
• UI Server Guide / Japanese
• UI Data Directory / Japanese