BatchTicket(CLI: adt)은 Agent 워크플로우를 위한 결정적(deterministic) 구조화 데이터 트랜스듀서입니다. 생산 또는 배송 배치와 함께 이동하는 작은 티켓처럼, 각 실행은 버전이 지정된 계획과 실행이 무엇을 변경했는지에 대한 명시적 기록을 담고 있습니다. 이 기록은 매핑이 의미적으로 정확했다고 주장하지 않습니다.
이것은 jq나 SQL의 또 다른 방언이 아닙니다. DuckDB, JSON Schema, PyYAML 및 표준 파서들은 이미 확립된 실행 작업을 담당합니다. 이 프로젝트는 그들에 대한 Agent 계약을 담당합니다.
버전 0.2.0은 아직 출시되지 않은 소스 릴리스 후보입니다. 이 프로젝트는 Apache License 2.0에 따라 라이선스가 부여됩니다. 안정적인 기술 식별자는 agent-data-transformer, data-transformer, adt, 그리고 네 가지 data_* MCP 도구로 유지됩니다.
전체 페이로드를 반환하지 않고 JSON, JSONL, CSV, TSV, YAML 및 Parquet을 검사합니다.
JSON/YAML 봉투(envelope)에서 경계가 지정된 중첩 레코드 집합을 발견하고 해당 논리 필드를 프로파일링합니다.
소스 레코드 형태를 대상 JSON Schema와 비교하고, 구조적 매핑 후보만 표면화하며, 명시적으로 호환되는 매핑이 있어야만 실행 가능한 초안 계획을 생성합니다.
원시 코드, SQL, 셸, jq, 정규식 또는 템플릿 실행이 없는 안전한 변환 계획(Transformation Plan) v1.
필터(filter), 프로젝트(project), 드롭(drop), 이름 변경(rename), 정렬(sort), 제한(limit), 중복 제거(deduplicate), 형변환(cast), 파생(derive), 폭발(explode), 조인(join), 그룹(group), 피벗(pivot), 언피벗(unpivot), 평탄화(flatten), 비평탄화(unflatten) 및 트리 변이(tree mutation).
JSON Schema와 비-null, 고유(unique), 행 수(row-count), 필드 및 유형 검증(assertion).
스키마를 인식하는 키(keyed) 또는 무키(unkeyed) diff.
실제 대상 사전 점검(preflight), 단계적 원자 게시, 덮어쓰기 보호가 있는 예행 실행(dry-run).
누적 소스/바이트/행/항목/깊이/시간/RSS/임시 제한이 있는 전체 호출 워커 격리.
샘플, 형태, 실행 결과, diff, 검증 실패 및 오류를 포함한 완전한 직렬화 응답 전체에 대한 바이트 상한(byte ceiling).
하나의 엄격한 타입의 Plan v1 모델이 런타임 검증, 게시된 JSON Schema 및 실행 중인 MCP 스키마를 생성합니다.
CLI와 네 가지 작업 수준(task-level) MCP 도구를 위한 하나의 공유 코어.
Related MCP server: MCP Data Integration Server
개발 체크아웃:
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 mcp저장소, uv, Python 설치 또는 네트워크 연결이 런타임에 필요하지 않은 플랫폼별 플러그인을 빌드합니다:
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-local빌드는 dist/plugin/에 플러그인 디렉토리, .tar.gz 아카이브 및 SHA-256 체크섬을 생성합니다. 생성된 전체 디렉토리를 설치하거나 복사하십시오. 저장소 루트의 .mcp.json은 개발 구성이며, 생성된 플러그인의 .mcp.json은 번들된 실행으 직접 호출합니다. 생성된 로컬 마켓플레이스는 Codex가 해당 자체 포함 디렉토리를 가리키도록 합니다. --replace로 재빌드할 때는 삭제하거나 덮어쓰기 전에 심볼릭 링크된 출력 루트 또는 기존 생성 대상을 거부합니다.
생성된 자체 포함(self-contained) 번들은 현재 **로컬 검증 아티팩트(artifact)**이며, 공개 릴리스 자산이 아닙니다. 이 번들은 Python 런타임, Python 패키지 및 네이티브 라이브러리를 포함하며, 해당 서드 파티 라이선스 자료는 아직 아카이브에 포함되지 않았습니다. 플러그인 디렉토리, 아카이브 또는 체크섬을 GitHub Release에 업로드하지 마십시오. 이것은 Apache-2.0 소스 저장소를 게시하거나 사용하는 것을 제한하지 않습니다. 릴리스 체크리스트를 참조하십시오.
예제 변환은 두 레코드를 인라인으로 반환하며 execution_effects를 통해 입력 행 하나가 제거되었음을 보고합니다. 파일 출력은 output.path를 통해 선택적(opt-in)으로 제공되며, 기존 파일은 output.overwrite가 명시적으로 true일 때만 교체됩니다.
CLI 경로는 명시적인 사용자 경로이며 절대 경로일 수 있습니다. MCP 파일 경로는 더 좁은 기능입니다. 서버는 먼저 MCP 루트 프로토콜로 부여된 워크스페이스를 사용합니다. 단일 루트가 자동으로 선택되며 여러 루트가 부여된 경우, 도구의 선택적 workspace 필드에 해당 루트의 정확한 name을 전달하십시오. 루트를 지원하지 않는 호스트는 호환 부여로 명시적 ADT_WORKSPACE_ROOT를 전달할 수 있습니다. 도구 경로는 선택된 루트를 기준으로 유지되며 절대 경로, 상위 디렉터리, URI 및 심볼릭 링크 이탈은 거부됩니다. 인라인 전용 MCP 호출은 워크스페이스 부여 없이 가능합니다.
Codex CLI 0.148은 현재 MCP 루트를 로컬 플러그인 서버에 전달하지 않습니다. 콜드(cold) CLI 호스트 테스트를 위해 정확한 테스트 워크스페이스로 ADT_WORKSPACE_ROOT를 설정하고 Codex를 실행하십시오. 읽기 전용 도구는 approval=never로 실행할 수 있습니다. data_transform은 조건부 파일 출력 기능이 있으므로 특정 호출이 인라인으로 데이터를 반환하더라도 승인 가능한 호스트 정책이 필요합니다. 차단된 호출은 인가 결과일 뿐이며, 셸이나 모델 측 데이터 재작성으로 대체할 수 있는 권한이 아닙니다.
data_inspect는 선택적 target_schema와 mappings 객체를 받습니다. 구조적으로 증거를 기반으로 고유한 중첩 레코드 집합을 선택하고, 정확한 이름 또는 정규화된 이름 일치를 제안하며, 호환되지 않는, 누락된, 중복된, 생략된 또는 삭제된 필드를 보고할 수 있습니다. 퍼지 동의어, 캐스트 또는 기본값을 사용하지 않습니다. v1 어댑터는 최상위 레코드 필드를 매핑하며 객체 스키마 또는 items가 하나의 객체 스키마인 배열을 지원합니다. 구성/참조 스키마 및 모호한 레코드 집합은 명시적으로 해결되지 않은 상태로 남습니다.
모든 필수 필드에 명시적이고 호환 가능한 매핑이 있으면 adaptation.status는 ready가 되고 adaptation.draft_plan은 일상적인 Transformation Plan v1입니다. 그 계획을 data_transform을 통해 실행하십시오. 어댑터는 별도의 실행 경로나 다섯 번째 공개 도구를 만들지 않습니다.
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}]},
}
],
}
)공개 호출은 안정적인 error.code와 함께 status: ok, status: dry_run 또는 status: error를 반환합니다. 성공한 변환은 execution_effects 아래에서 런타임 관측 변경 사항을 노출합니다. 스택 트레이스 또는 DuckDB 내부를 누출하지 않습니다.
제품 모델, Transformation Plan v1 및 검토 계약을 참조하십시오. 기여는 CONTRIBUTING.md, 보안 보고서는 SECURITY.md 및 주요 변경 사항은 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.
Remote MCP: JSON repair, JSON Schema validation, JSON to TypeScript, CSV to JSON and JSON to CSV.
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
JSON Schema validator for API payloads via MCP: bounded checks and structured pass/fail errors.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
