This server provides read-only inspection, schema-aware transformation, validation, and diffing of structured data through four MCP tools.
data_inspect: Inspect JSON, JSONL, CSV, TSV, YAML, or Parquet shape, types, counts, and samples; discover nested record sets; and optionally compare fields against a target JSON Schema to emit a draft Transformation Plan when explicit mappings are supplied.
data_transform: Execute safe Transformation Plan v1 operations such as filter, project, drop, rename, sort, limit, dedupe, cast, derive, explode, join, group, pivot/unpivot, flatten/unflatten, set/delete/merge, with dry-run, optional file output, overwrite protection, and execution effects reporting.
data_validate: Validate existing structured data against JSON Schema and deterministic assertions (non-null, unique, row-count, field-exists, type), returning valid true/false without rewriting the source.
data_diff: Compare two structured datasets by schema and rows, optionally using key fields, and return compact added/removed/changed counts and samples.
Safety and limits: Worker isolation, response byte ceilings, source/row/depth/time/memory/temp limits, workspace-granted paths with escape rejection, inline sources without workspace grants, and no raw code, SQL, regex, or template execution.
Enables inspection, transformation, validation, and diffing of YAML data using the same deterministic plan and assertion model as the other supported formats.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@data-transformer transform users.csv by dropping the email column and sorting by last name"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
BatchTicket (CLI: adt) is a deterministic structured-data transducer for Agent workflows. Like the small ticket that travels with a production or shipping batch, each run carries a versioned plan and an explicit account of what execution changed. That account does not claim the mapping was semantically correct.
It is not another jq or SQL dialect. DuckDB, JSON Schema, PyYAML, and standard parsers own established execution work. This project owns the Agent contract around them.
Version 0.2.0 is an unreleased source release candidate. The project is licensed under the
Apache License 2.0. The stable technical identifiers remain
agent-data-transformer, data-transformer, adt, and the four data_* MCP tools.
Inspect JSON, JSONL, CSV, TSV, YAML, and Parquet without returning full payloads.
Discover bounded nested record sets in JSON/YAML envelopes and profile their logical fields.
Compare a source record shape with a target JSON Schema, surface only structural mapping candidates, and emit an executable draft plan only after explicit compatible mappings.
Safe Transformation Plan v1 with no raw code, SQL, shell, jq, regex, or template execution.
Filter, project, drop, rename, sort, limit, deduplicate, cast, derive, explode, join, group, pivot, unpivot, flatten, unflatten, and tree mutation.
JSON Schema plus non-null, unique, row-count, field, and type assertions.
Schema-aware keyed or unkeyed diff.
Dry-run with real destination preflight, staged atomic publication, and overwrite protection.
Whole-call worker isolation with cumulative source/byte/row/item/depth/time/RSS/temp limits.
A byte ceiling over the complete serialized response, including samples, shapes, execution effects, diffs, validation failures, and errors.
One strict typed Plan v1 model generates runtime validation, the published JSON Schema, and the live MCP schema.
One shared core with CLI and four task-level MCP tools.
Related MCP server: Trace MCP
Development checkout:
git clone https://github.com/tetracoralla/BatchTicket.git
cd BatchTicket
uv sync --frozen --extra dev
uv run adt inspect examples/users.json --select 'data.users[*]'
uv run adt inspect examples/users.json --select 'data.users[*]' \
--target-schema target.schema.json --mappings mappings.json
uv run adt transform examples/adults.plan.yaml
uv run adt transform examples/adults.plan.yaml --dry-run
uv run adt validate examples/users.json --select 'data.users[*]' \
--assertions examples/users.assertions.json
ADT_WORKSPACE_ROOT=/absolute/granted/workspace uv run adt mcpBuild a platform-specific plugin that does not need the repository, uv, a Python
installation, or a network connection at runtime:
uv run python scripts/build_plugin.py
uv run python scripts/probe_plugin.py \
dist/plugin/data-transformer-0.2.0-darwin-arm64
codex plugin marketplace add dist/plugin
codex plugin add data-transformer@data-transformer-localThe build produces a plugin directory, a .tar.gz archive, and a SHA-256 checksum in
dist/plugin/. Install or copy the complete generated directory; the repository-root
.mcp.json is development configuration, while the generated plugin's .mcp.json invokes
its bundled executable directly. The generated local marketplace points Codex at that
self-contained directory. Rebuilding with --replace refuses symlinked output roots or
generated targets before deleting or overwriting anything.
Each generated bundle contains legal/THIRD_PARTY_NOTICES.md, the copied license texts under
legal/licenses/, and legal/sbom.cdx.json. The inventory is built from the locked runtime
dependency closure plus the incorporated CPython runtime and PyInstaller bootloader; it is checked
again from the archive by the plugin test path. The archive is stable for the same source, lock,
and build environment, so its companion SHA-256 file identifies the exact generated bundle.
This local macOS arm64 artifact is not a publication action. A GitHub Release upload, code-signing or notarization decision still requires separate authorization; see the release checklist.
The example transformation returns two records inline and reports through execution_effects that one input row was removed. File output is opt-in through output.path; existing files are never replaced unless output.overwrite is explicitly true.
CLI paths are explicit user paths and may be absolute. MCP file paths are a narrower
capability: the server first uses workspaces granted through the MCP roots protocol. A
single root is selected automatically; when several roots are granted, pass their exact
root name in the tool's optional workspace field. Hosts without roots support may pass
an explicit ADT_WORKSPACE_ROOT as a compatibility grant. Tool paths remain relative to
the selected root, and absolute, parent, URI, and symlink escapes are rejected. Inline-only
MCP calls do not require a workspace grant.
Codex CLI 0.148 does not currently pass MCP roots to local plugin servers. For a cold CLI
host test, launch Codex with ADT_WORKSPACE_ROOT set to the exact test workspace. Read-only
tools can run under approval=never; data_transform has conditional file-output
capability and therefore requires an approval-capable host policy even when a particular
call returns data inline. A blocked call is an authorization result, not permission to
fall back to shell or model-side data rewriting.
data_inspect accepts an optional target_schema and mappings object. It can select a
unique nested record set by structural evidence, suggest exact or normalized-name matches,
and report incompatible, missing, duplicated, omitted, or dropped fields. It does not use
fuzzy synonyms, casts, or defaults. The v1 adapter maps top-level record fields and supports
an object schema or an array whose items is one object schema. Composed/reference schemas
and ambiguous record sets remain explicitly unresolved.
When every required field has an explicit compatible mapping,
adaptation.status is ready and adaptation.draft_plan is a normal Transformation Plan
v1. Run that plan through data_transform; the adapter does not create a separate execution
path or fifth public tool.
capabilities/provider.json binds the read-only data_inspect and
data_validate core paths to
org.openadam.structured-data.analyze@0.1.0. The JSONL adapter validates the
portable request, preserves the same restricted workspace and isolated worker,
and projects provider results into the canonical shape and validation
contracts. A failed content constraint remains a successful result with
valid=false; malformed constraints and execution failures use stable
Capability errors.
The v0.2 Provider Manifest declares canonical JSONL adapter targets for
inspect and validate separately from the public FastMCP tool targets. Its
executable transport schema probe introspects the current data_inspect and
data_validate tool schemas, keeping canonical adapter and live transport
conformance as separate evidence lanes.
Installed source wheels expose adt-capability and
adt-transport-schema-probe. Their canonical schemas are package resources,
so neither command depends on a repository checkout or a sibling Procedure.
The self-contained plugin exposes the same two interfaces through the
runtime/adt-capability and runtime/adt-transport-schema-probe launchers,
which reuse one frozen runtime, and ships a release-bound Provider Manifest plus canonical
schemas. Installed Hosts can therefore use the Capability without a source
checkout, Python environment, package manager, or network access.
from data_transformer import DataTransformer
result = DataTransformer().transform(
{
"version": "1",
"sources": {"rows": {"inline": [{"x": 2}, {"x": 4}]}},
"steps": [
{
"op": "derive",
"field": "doubled",
"expr": {"multiply": [{"field": "x"}, {"value": 2}]},
}
],
}
)Public calls return status: ok, status: dry_run, or status: error with a stable error.code. Successful transformations expose runtime-observed changes under execution_effects; they do not leak stack traces or DuckDB internals.
See the product model, Transformation Plan v1, and the review contract. Contributions are described in CONTRIBUTING.md, security reports in SECURITY.md, and notable changes in CHANGELOG.md.
Compare two structured datasets by schema and rows, optionally using stable key fields. Returns compact added, removed, and changed counts and samples.
| Name | Required | Description | Default |
|---|---|---|---|
| left | Yes | ||
| right | Yes | ||
| limits | No | ||
| workspace | No | ||
| key_fields | No | ||
| sample_rows | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about the output being 'compact' and that it 'returns added, removed, and changed counts and samples', which goes beyond annotations. There is no contradiction, and the description adds value by clarifying the behavioral output characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the purpose and includes the key optional parameter (key fields) and the output nature. Every phrase earns its place, with no redundancy or fluff. This is ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters including complex source objects (PathSource/InlineSource) and a limits model, but the description does not mention that sources can be paths or inline, nor the limits concept. However, the schema provides rich detail on these, and the output is described. Given no output schema, the description covers the return format adequately. The main gap is not explaining how sources are specified, but the schema covers that, so a moderate score is fair.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description explicitly mentions 'stable key fields' matching the key_fields parameter and 'compact counts and samples' relating to sample_rows. However, it does not explain the left/right source objects, limits, or workspace parameters. The description adds some meaning but not enough to fully compensate for low coverage; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Compare two structured datasets by schema and rows' with 'optional stable key fields', and specifies the output as 'compact added, removed, and changed counts and samples'. This is a specific verb+resource combination that distinguishes it from siblings like data_transform (transforms), data_inspect (inspects), and data_validate (validates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when two datasets need comparison, but it does not explicitly mention when not to use it or name alternatives. Sibling tools are obvious from their names, but the description could have added context about when to choose this over data_inspect or data_validate. Still, the purpose is clear enough that a moderate score is warranted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect JSON, JSONL, CSV, TSV, YAML, or Parquet shape, types, counts, and a small sample without returning the full payload. Use for 'what fields are in this data?' or unknown tool output. Optionally compare record fields with target_schema and return deterministic mapping candidates; a draft plan is returned only after explicit mappings are supplied. One successful call is sufficient for its recorded observations; never repeat the same arguments to confirm it.
| Name | Required | Description | Default |
|---|---|---|---|
| limits | No | ||
| source | Yes | ||
| mappings | No | ||
| workspace | No | ||
| sample_rows | No | ||
| target_schema | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the read-only/idempotent annotations by adding key behavioral details: no full payload returned, deterministic mapping candidates, draft plans only after explicit mappings, and a note that one successful call is sufficient for observations. These are meaningful traits not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with the core purpose, and every sentence adds valuable context: formats, outputs, use cases, optional mapping behavior, and idempotence caution. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's main purpose, use cases, and special behaviors well. It lacks detail on certain parameters (limits, workspace) and the two source variants, but for a read-only inspection tool with clear annotations, the provided context is sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It meaningfully explains target_schema and mappings, and implies sample behavior via 'small sample,' but it leaves limits, workspace, and source structure (path vs inline) undocumented. This is a partial but not full compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool inspects multiple data formats (JSON, JSONL, CSV, TSV, YAML, Parquet) and returns shape, types, counts, and a small sample without returning the full payload. It also clearly distinguishes itself from sibling tools by specifying its use case: 'what fields are in this data?' or unknown tool output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance ('Use for...') and a strong behavioral instruction ('never repeat the same arguments to confirm it'). While it doesn't explicitly name alternative sibling tools as exclusions, the use case framing makes it clear when inspection is appropriate versus transform/validate/diff.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transform or rewrite records: reshape, filter, join, aggregate, cast, flatten, or convert structured data with Transformation Plan v1. Do not use this tool for a validation-only request such as checking non-null or unique fields; use data_validate. Known transformation shape: {"version":"1","sources":{"input":{"path":"users.json","select":"data.users[*]"}},"steps":[{"id":"filtered","op":"filter","source":"input","where":{"field":"age","gte":18}},{"op":"select","source":"filtered","fields":[{"field":"userId","as":"id"}]}],"return":{"mode":"auto"}}. Omit workspace with ADT_WORKSPACE_ROOT; otherwise it is an exact granted root name, never a path. Returns a compact sample and explicit execution effects; large results require output.path.
| Name | Required | Description | Default |
|---|---|---|---|
| plan | Yes | ||
| dry_run | No | ||
| workspace | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), so the description's job is to add value beyond them. It does: it discloses that the tool 'Returns a compact sample and explicit execution effects,' warns that 'large results require output.path,' and explains workspace variable behavior (ADT_WORKSPACE_ROOT). Crucially, the description is consistent with the annotations—the described rewrite/transform behavior aligns with destructiveHint=true, so there's no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but justifiably so given the tool's complexity—a full transformation DSL. It front-loads the purpose, uses a crisp exclusion, and packs workspace semantics and return behavior into tight sentences. The embedded JSON example is bulky but earns its place. It loses one point for the dense JSON blob being potentially hard to scan, but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 top-level params, a huge nested schema (19 step types, multiple assertion types), and no output schema, the description covers the most critical gaps: workspace pathing rules, large-result handling (output.path), the full plan shape, and the validation sibling's boundary. It's slightly shy of a 5 because the 'compact sample and explicit execution effects' return semantics are never detailed, and error/limit behaviors aren't addressed—leaving some burden on the agent despite the otherwise strong guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate, and it does extensively: it embeds a complete Transformation Plan v1 JSON example showing versions, sources with path/select, steps (filter with condition, select with aliases), and return mode. It also explicitly documents the workspace parameter semantics and the output.path behavior for large results. This is exactly the burden-shifting the rubric requires when the schema provides no narrative.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb phrase — 'Transform or rewrite records: reshape, filter, join, aggregate, cast, flatten, or convert structured data with Transformation Plan v1' — clearly naming the resource (Transformation Plan v1) and listing concrete operations. It differentiates from siblings by explicitly excluding validation tasks ('Do not use this tool for a validation-only request'). This is a strong purpose statement for a tool whose name alone would be ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit when-not-to-use directive with a named alternative: 'Do not use this tool for a validation-only request such as checking non-null or unique fields; use data_validate.' It also provides workspace usage guidance ('Omit workspace with ADT_WORKSPACE_ROOT; otherwise it is an exact granted root name, never a path') and large-result handling. This matches the exemplar behavior in the rubric—clear exclusion plus named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate or check requirements on existing structured data (校验/检查非空、唯一、类型、字段或行数); choose data_validate, not data_transform, for validation-only requests. It accepts JSON Schema and deterministic assertions and returns valid true or false without rewriting the source. Known validation shape: {"source":{"path":"users.json","select":"data.users[*]"},"assertions":[{"type":"not_null","field":"userId"},{"type":"unique","field":"userId"}]}.
| Name | Required | Description | Default |
|---|---|---|---|
| limits | No | ||
| schema | No | ||
| source | Yes | ||
| workspace | No | ||
| assertions | No | ||
| sample_rows | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful context by stating it 'returns valid true or false without rewriting the source' and that assertions are deterministic, reinforcing that validation has no side effects. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and usage guidance, and the three sentences are efficient. The JSON shape example is practical and earns its place, though it slightly lengthens the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 6-parameter tool with no output schema, the description covers the main purpose, sibling differentiation, side-effect-free behavior, and return type. Yet optional parameters like limits, workspace, and sample_rows are not addressed, so the description is not fully complete despite the rich input schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It provides a concrete validation shape for source and assertions, and enumerates assertion type names, giving real semantic value for the core parameters. However, other parameters such as limits, workspace, and sample_rows are not described, leaving clear gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Validate or check requirements') and clearly identifies the resource ('existing structured data'). It enumerates supported check types (non-null, unique, type, field, row count) and explicitly distinguishes from a sibling tool ('choose data_validate, not data_transform'), which is strong differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit usage rule: 'choose data_validate, not data_transform, for validation-only requests.' This named alternative and clear when/when-not guidance meets the highest bar, even though it does not mention data_inspect or data_diff.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0data_diffdata_inspectdata_transformdata_validateScored across 4 tools
Each tool occupies a cleanly separated role: observe (inspect), modify (transform), check (validate), and compare (diff). The overlap risk between transform and validate is explicitly addressed with cross-references steering agents to the right tool. No ambiguity remains after reading the descriptions.
All tools follow the exact data_<verb> pattern in snake_case with uniform imperative verbs: transform, inspect, validate, diff. The convention is fully predictable with zero deviation.
At 4 tools, the surface is tightly scoped with no bloat, comfortably within the ideal range for a focused data utility. Every tool earns its place within the read/validate/write/compare lifecycle.
Core workflows are fully covered: reading, transforming/writing output, validating, and diffing data, with output paths already handled by the transform tool. Minor gaps like an explicit export/delete or data source listing tool prevent a perfect score, but agents can accomplish all primary tasks.
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Monitor MCP servers, API contracts and AI outputs for schema drift. Alerts on breaking changes.
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
