convez.ai
MCP ServerDados & AnalyticsIntermediário
vinhphatfsg

Rulemorph

vinhphatfsg/rulemorph

Transforme dados via regras YAML/JSON reutilizáveis

Ver no GitHub
BomPluginScore · de 0 a 100

Motor de transformação de dados declarativo baseado em YAML que converte CSV, JSON, XML, HTML e outros formatos em JSON estruturado sem necessidade de código customizado. Reutiliza as mesmas regras via CLI, API local, UI ou através de MCP para assistentes de IA.

Instalação

$npx convez-ai vinhphatfsg/rulemorph

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 1 mês
Versão
v0.3.4
Issues abertas
2
Contribuidores
2

Casos de uso

  • Normalizar respostas de APIs externas para seu schema interno
  • Importar e processar CSV/Excel em pipelines JSON
  • Extrair valores de HTML/XML com regras versionadas
  • Expor transformações a assistentes de IA via MCP

Veredito

Ferramenta sólida para casos de transformação de dados estruturada onde regras declarativas fazem sentido. MCP server bem posicionado para integração com Claude em pipelines de processamento de dados, mas não substitui lógica de negócio complexa ou orquestração de workflows.

README

A tradução para o português deste README ainda está na fila.

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

GoalUse
Try rules without installing anythingRulemorph Playground
File transforms, DTO generation, CI validationrulemorph CLI
Embed transformations in a Rust applicationrulemorph crate
Run the local UI or YAML-defined APIsrulemorph-server
Use transforms, validation, and DTO generation from an AI assistantrulemorph-mcp

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"]

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

Ver o original no GitHub

Bom para

Relacionados