ebcdicjp-mcp
This MCP server lets AI agents inspect, read, write, and troubleshoot Japanese mainframe EBCDIC data and COBOL copybooks.
Parse a COBOL copybook and list every field with byte position, length, and type via
describe_layout.Decode fixed-length or RDW variable-length EBCDIC data files using a copybook via
read_records, returning nested JSON records plus issues such as gaiji, broken SO/SI, and invalid numbers.Build fixed-length EBCDIC test data from JSON records via
write_records, reporting characters that will not round-trip.Decode hex bytes as Japanese EBCDIC via
decode_bytes, including problem reporting.Encode text to Japanese EBCDIC hex via
encode_text, listing unencodable or one-way characters.Detect whether a data file is IBM930 or IBM939 via
detect_codepage.Support IBM930/IBM939 kana and kanji, COBOL PIC X/N/G/9/S9/V, COMP-3, COMP, zoned decimal, OCCURS, REDEFINES, and FILLER.
Report code page, RDW, and copybook encoding assumptions in notes instead of silently guessing.
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., "@ebcdicjp-mcp show me the layout of CUSTMAST.cpy and read the first 5 records in CUST.dat"
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.

kanjiframe
メインフレームの日本語データ(EBCDIC のカナ・漢字、COBOL のレコード)を、開発PCや AI エージェントから読み書きするツール。 Python 標準ライブラリだけで動きます(依存ゼロ)。旧名は ebcdicjp です。
kanjiframe reads and writes Japanese mainframe data — EBCDIC IBM930/939 kana and kanji with SO/SI, COBOL copybook layouts, packed and zoned decimals — with zero dependencies. CLI, Python codecs and an MCP server for AI agents.
なぜ
メインフレームの移行・保守では、本番から抜いた固定長データ(コピーブック付き)を開発PCで確かめたい場面がよくあります。
でも、Python の標準ライブラリには日本語 EBCDIC(IBM930 / IBM939)のコーデックがありません(cp930 は LookupError)。
欧米向けの手順(cp037)では、漢字の SO/SI やカナ/英小文字の違いを扱えず、変換は商用製品に頼ることになります。
Related MCP server: agent-tool
できること
$ kanjiframe layout CUSTMAST.cpy
CUST-REC length=224
1 10 zoned CUST-REC.CUST-NO 9(10)
11 30 text CUST-REC.CUST-KANA X(30)
41 40 dbcs CUST-REC.CUST-KANJI N(20)
89 8 packed V2 CUST-REC.BALANCE S9(13)V99
...
$ kanjiframe view CUST.dat -c CUSTMAST.cpy --format md --use ADDR-JP
note: code page: IBM930 (IBM939 would read 30 bytes as lowercase letters with only 17% vowels — ...)
## record 1
| CUST-KANJI | 山田太郎 |
| BALANCE | 1234567.89 |
| ADDR-JP.ADDR-REST | 千代田区丸の内1−1−1 |
...
$ kanjiframe check EMPMAST.dat -c EMPMAST.cpy --key EMP-ID
note: copybook is not UTF-8; read it as Shift_JIS (cp932)
note: assumed RDW variable-length records (6 records): ...
record 3 EMP-ID=E0000003 EMP-REC.ALLOWANCES(1).ALLOW-NAME pos 92 [0E 46 50 ...] bad-shift: ... (missing SI)
record 4 EMP-ID=E0000004 EMP-REC.EMP-NAME-KANJI pos 13 [... 69 41 ...] gaiji: user-defined character (外字) 6941
record 6 EMP-ID=E0000006 EMP-REC.DEPT-CD pos 79 [C1 F1 C2 F2] bad-number: byte 1 of the field (C1) is not a digitコーデック:IBM930(カナ)・IBM939(英小文字)。SO(0E)/SI(0F) で切り替わる漢字、PIC N(SO/SI なしの2バイト)。
b"...".decode("ibm930")のように Python のcodecsからも使えます。数値:パック10進(COMP-3)、ゾーン10進(符号付き・SIGN SEPARATE)、バイナリ(COMP)。金額は Decimal で桁を落としません。
コピーブック:PIC X / N / G / 9 / S9 / V、COMP-3 / COMP / BINARY / DISPLAY-1、OCCURS(DEPENDING ON は最大で配置)、REDEFINES、FILLER、固定形式(1〜6桁目の連番・7桁目のコメント)。
問題の場所を示す:読めないバイト、外字、SO/SI の崩れ、数字でないパック10進などを「項目のパス(OCCURS の何番目かも)・バイト位置(1始まり)・実際のバイト」で報告します。黙って置き換えません。
checkでファイル全体の問題を社員番号などのキー付きで一覧できます。決めつけずに推定する:コードページ(IBM930/939)、RDW の有無、コピーブックの文字コード(UTF-8/Shift_JIS)はデータから判定し、何を仮定したかを
note:で必ず表示します。英小文字が無くても、半角カナの読み方の崩れ(tユn゙のように英小文字とカナが混ざる)で見分けます。それでも決められないときは「code page UNCERTAIN」と出し、終了コード1にします。戻らない文字を知らせる:「〜」(U+301C) は 43A1 に変換され、読み戻すと「~」(U+FF5E) になります。こうした文字(IBM930 で53種、IBM939 で54種)を書き込み時に報告します。
テストデータを作る:JSON から固定長の EBCDIC ファイルを作ります(
encode)。AI エージェントから使う:MCP サーバー(
describe_layout/read_records/write_records/decode_bytes/encode_text/detect_codepage)。
正しさの確かめ方
変換表は JDK(Java)の x-IBM930 / x-IBM939 から生成し(tools/GenTables.java)、テストで次を突き合わせています。
2バイトの全コード(各 11,635 個)が JDK と同じ文字になること
漢字・カナ・英数・半角カナを混ぜたランダムな 1,200 個の文字列が、JDK と同じバイト列(SO/SI の位置を含む)になること
Java で独立に作ったデータファイル(
tools/MakeSample.java)を正しく読めること
java が入っていればこの突き合わせも実行されます。
インストールと使い方
pip install git+https://github.com/yukijames25/kanjiframe
kanjiframe layout CUSTMAST.cpy # 項目の位置と長さ
kanjiframe view CUST.dat -c CUSTMAST.cpy -n 5 # JSONL(--format csv / md も可)
kanjiframe check CUST.dat -c CUSTMAST.cpy --key CUST-NO # 全件の問題を1行ずつ(キー付き)
kanjiframe dump CUST.dat -c CUSTMAST.cpy --skip 4 -n 1 # 5件目の項目ごとの16進と値(文字化けの調査)
kanjiframe detect CUST.dat -c CUSTMAST.cpy # IBM930 と IBM939 のどちらか
kanjiframe encode records.jsonl -c CUSTMAST.cpy -o TEST.dat --codepage ibm930 # テストデータを作る
kanjiframe text --encode "山田〜" # 文字列 → 16進(戻らない文字も表示)
kanjiframe text 0E 45 65 45 63 0F # 16進 → 文字列(930 と 939 で違えば両方)--codepage ibm930|ibm939:推定を上書きするとき(読むときの既定は auto。encodeでは必ず指定)--rdw/--no-rdw:可変長(各レコードの先頭に4バイトの RDW)かどうか。既定はファイルから判定--use ADDR-JP:REDEFINES のどの読み方を使うか(どちらで読んでも文字として成り立つことがあるため、レコード種別の規則を知っている人が指定します)--use HOJIN-DETAIL:TOR-KBN=1 --use KOJIN-DETAIL:TOR-KBN=2:法人と個人のようにレコード区分で読み方が変わるファイルを、1回で正しく読む(値はカンマで複数可。どの規則にも当たらない区分はno-ruleとして報告)--copybook-encoding cp932:コピーブックの文字コード(既定 auto:UTF-8、だめなら Shift_JIS)
Claude Code から使う
claude mcp add kanjiframe -- kanjiframe-mcp.claude/skills/kanjiframe/ に、エージェント向けの手順(スキル)があります。
終了コード:0 = 問題なし、1 = 問題あり(またはコードページを決められない)、2 = エラー(ファイルが無い、コピーブックが読めないなど)。
view / check の最後の行が件数のまとめです。数値項目が空白(blank)のものは問題とは別に数えます。
制限
対応する文字コードは IBM930 / IBM939(日本語 EBCDIC の代表的な2つ)です。KEIS(日立)・JEF(富士通)は、仕様を確かめてから対応予定です。
外字(ユーザー定義領域 6941〜7FFE)は、各社の外字表が無いと何の字か分かりません。値には「〓」を出し、問題(kind
gaiji、コード付き)として報告します。Python からkeep_gaiji=Trueで読むと私用領域(U+E000〜)の文字のまま受け取れます。COMP-1 / COMP-2(浮動小数点)、SIGN の符号位置が特殊なもの、RENAMES(66 レベル)は未対応です。
REDEFINES は、どちらの読み方も表示し、片方だけが正しく読めるときはもう片方を「alternative」として目立たなくします。どちらも文字として読めてしまう場合は
--useで指定してください。読めなかった値は、JSON では null、CSV と Markdown では
#ERRになります(空の項目と区別するため)。
開発
python -m unittest discover -s tests # java があれば JDK との突き合わせも
java tools/GenTables.java local && python tools/build_tables.py local # 変換表の再生成
java tools/MakeSample.java tests/data/custmast_930.dat # サンプルデータの再生成選んだ理由と調査は docs/RESEARCH.md。
License: MIT
Available Tools
6 toolsdecode_bytesB
Decode hex bytes (e.g. from a hex dump or an error message) as Japanese EBCDIC, with problems listed.
Inputs: hex (required), codepage, dbcs_only.
describe_layoutB
Parse a COBOL copybook and list every field with its byte position, length and type (text = PIC X with SO/SI kanji, dbcs = PIC N, zoned, packed = COMP-3, binary = COMP).
Inputs: copybook (required), record, copybook_encoding.
detect_codepageA
Guess whether a data file is IBM930 or IBM939 (says 'ambiguous' with both previews when it can't tell).
Inputs: path (required), copybook, copybook_encoding.
encode_textB
Encode text to Japanese EBCDIC hex (SO/SI added around kanji). Lists unencodable and one-way characters.
Inputs: text (required), codepage, dbcs_only.
read_recordsA
Decode records of a Japanese mainframe data file (fixed-length, or variable with RDW) using a copybook. Returns nested JSON per record plus issues located by field path and byte offset (pos is 1-based): unmapped bytes, 外字 (gaiji, shown as 〓), broken SO/SI, invalid packed/zoned numbers. Code page and RDW are detected unless given; read the notes. Read a few records first (limit).
Inputs: path (required), copybook (required), rdw, use, +6 more.
write_recordsA
Build a fixed-length EBCDIC file (test data) from JSON records shaped like read_records output. Missing fields are spaces / zero. Reports characters that will not read back the same (〜 → ~).
Inputs: records (required), codepage (required), copybook (required), output_path (required), +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct primary action: copybook introspection, hex decoding, file reading, file writing, text encoding, and codepage detection. There is mild overlap between decode_bytes and read_records (both decode EBCDIC bytes) and between encode_text and write_records (both encode to EBCDIC), but descriptions make the intended scope clear.
All six tools use a consistent snake_case verb_noun pattern: describe_layout, decode_bytes, read_records, write_records, encode_text, detect_codepage. No mixed conventions or ambiguous abbreviations.
Six tools is well-scoped for a specialized Japanese EBCDIC/copybook utility server. Each tool covers a distinct part of the workflow without obvious redundancy or missing bulk operations.
The surface covers copybook parsing, record reading/writing, hex decoding, text encoding, and codepage detection, which are the core operations for this domain. A dedicated decode_text operation or copybook validation tool would improve symmetry, but the existing tools allow agents to complete the main workflows.
Maintenance
Related MCP Connectors
Japan data tools for AI agents: calendar (rokuyo), address, name splitting, corporate number lookup
Pay-per-call document and web tools for AI agents: PDF parsing and OCR (Japanese-strong), web and structured extraction, invoice verification, company profiles and PDF utilities. x402 (USDC on Base), no API key; failed calls are never charged.
300+ deterministic data utilities for AI agents: validate, normalize, parse, match, redact.
Japanese business days, holiday checks and invoice due dates for your AI agent.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to discover, execute, and validate CyberChef operations for data encoding, decoding, encryption, and transformation tasks. Provides structured access to CyberChef's extensive catalog of data manipulation tools through natural language interactions.-
- AlicenseAqualityBmaintenanceEncoding-aware, indentation-smart file tools for AI coding agents. 20+ tools including read/edit with automatic encoding detection, smart indentation conversion, SSH, SFTP, process management, and system utilities.1126MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to automate reverse engineering and binary analysis by running scripts, retrieving metadata, searching values, text, and byte sequences, and reading disassembly.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to inspect, edit, and analyze Dreamcast VMU save images through MCP tools, including named-field modification with automatic checksum/CRC updates and diff-based discovery of save structure.MIT