Transform Rules MCP Server

Rulemorph 使用声明式 YAML/JSON 规则，将外部 API、CSV、JSON、YAML、TOML、XML、HTML、Markdown 和 Excel 中的数据转换为格式规范的 JSON。

无需为每个输入来源都编写新的自定义脚本，只需将转换逻辑保存在规则文件中。同一套规则可以通过 CLI 使用、嵌入 Rust、通过本地 UI/API 服务提供，或通过 MCP 提供给 AI 助手。

在浏览器中试用：playground.rulemorph.com

解决的问题

Rulemorph 将不断增长的转换代码转化为便于审查和版本管理的规则。

• 将供应商 API 响应规范化为内部架构
• 将 CSV / Excel 导入纳入 JSON 工作流
• 从 HTML 或 XML 中提取值，并使用相同的规则模型处理
• 以 YAML/JSON 的形式审查、替换和管理转换逻辑的版本
• 通过 CLI、本地 API 或 AI 助手重复使用同一转换逻辑

它并非用于替代可执行任意操作的应用程序代码、复杂的领域逻辑或长时间运行的工作流编排。对于这些情况，通常更适合使用常规应用程序代码或工作流引擎。

快速开始

将外部 API 响应中的 users 数组转换为应用程序所需的 JSON 格式。

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

运行

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

也可以将输入通过管道传给 transform：

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

输出

[{ "id": 1, "name": "Alice", "email": "[email protected]" }]

若要快速进行一次性转换而无需规则文件，请使用直接模式。

对 JSON 或临时 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"

如果需要小型输出对象且字段顺序很重要，请使用 -F/--field：

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 }

如果紧凑的嵌套目标映射更易于阅读，请使用 --output-map：

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 }

对于包含多条记录的直接输入，添加 --ndjson，即可每行输出一个 JSON 值：

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

直接模式也可以读取 CSV 或 Excel 文件。CSV 标题会根据 .csv 文件自动推断；对于无标题行的 CSV，请使用 -H/--headers。对于 Excel，请明确选择标题行 和数据范围：

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

选择哪个包

安装

CLI、服务和 MCP 服务的预编译二进制文件可从 GitHub Releases 获取。

CLI

brew install vinhphatfsg/tap/rulemorph

开发时，可从源代码构建：

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

UI / API 服务

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

完整的启动步骤请参阅 UI 服务指南。

MCP 服务

rulemorph-mcp 通过 Model Context Protocol 向 AI 助手提供 Rulemorph 功能。

• transform：转换数据
• validate_rules：验证规则
• generate_dto：生成 DTO
• analyze_input：概述输入结构

Claude Code 设置：

claude mcp add rulemorph -- rulemorph-mcp

主要功能

• 将 CSV / JSON / YAML / TOML / XML / HTML / Markdown / .xlsx Excel 规范化为 JSON 记录
• 使用 mappings 构建输出字段
• 使用 v2 管道表达式转换值：修剪、大小写转换、拼接、数值运算、查找和数组运算
• 使用 defs 定义规则局部自定义 OP，以复用类型化 v2 管道或映射主体
• 使用 sqrt、mod、pow、clamp 和 range 等数值辅助函数生成有界序列
• 使用 record_when、when 和 asserts 控制行为
• 使用 steps、branch 和 finalize 实现有序执行和输出数组处理
• 为 Rust、TypeScript、Python、Go、Java、Kotlin 和 Swift 生成推断的 DTO。显式 type 优先；动态或不安全的形状会回退为适用于 JSON 的类型。
• 检查内置和自定义 OP 执行的语义跟踪信息，而不改变转换输出
• 运行本地 UI/API 服务，或通过 MCP 提供相同的引擎

输入解析器旨在保持保守。HTML 解析不会执行 JavaScript 或获取 URL，Markdown 原始 HTML 仅作为源文本保留，Excel 解析不会执行宏或计算公式。为避免输入行为含糊不清或产生副作用，XML DTD/实体以及 JSON/YAML 重复键均会被拒绝。

规则结构

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

新规则文件应使用 version: 2。迁移期间仍接受 version: 1 规则文件，但验证和运行时入口会发出弃用警告。后续版本将先把 version: 1 规则文件改为需显式启用旧版选项才能使用，然后再移除此语法。

完整规则规范请参阅 Transformation Rules Spec。另有日文版本：Japanese。

DTO 生成

rulemorph generate -r rules.yaml -l typescript

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

支持的语言：rust、typescript、python、go、java、kotlin、swift

DTO 生成会优先采用显式映射类型，然后根据字面值和 v2 管道表达式推断简单标量、数组、映射和嵌套对象形状。如果形状是动态的，或过于宽泛而无法安全推断，生成的 DTO 将使用各语言对应的 JSON 回退类型。

库用法

[dependencies]
rulemorph = "0.3.4"

默认启用 html、excel 和 markdown 输入解析器。只需使用核心 CSV、JSON、YAML、TOML 和 XML 支持的库用户，可以禁用这些解析器以减少可选解析器依赖：

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

可通过 ["html"]、["excel"] 或 ["markdown"] 等功能显式重新启用解析器。 如果规则选择了已禁用的解析器，转换将以 invalid_input 失败（对于 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)?;

文档

• 文档索引
• Transformation Rules Spec / Japanese
• Endpoint Rules Spec
• Network Rules Spec
• UI Server Guide / Japanese
• UI Data Directory / Japanese