@prefixcheck/edi-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PrefixCheck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @prefixcheck/edi-mcp
+
+MCP server exposing operator-grade EDIFACT **CODECO** + **COPRAR** tooling to any MCP client (Claude Desktop, Cursor, Cline, Continue, Claude Code).
+
+```bash
+npx -y @prefixcheck/edi-mcp
+```
+
+---
+
+## What it does
+
+Drops EDI parsing, SMDG validation, ISO 6346 check-digit verification, UN/LOCODE extraction, and COPRAR ↔ CODECO reconciliation directly into your AI workflow. Now you can paste a broken EDIFACT message into Claude/Cursor and ask "what's wrong with this?" — and get a real, operator-grade answer.
+
+---
+
+## Quick install · Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "prefixcheck-edi": {
+      "command": "npx",
+      "args": ["-y", "@prefixcheck/edi-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The 9 EDI tools become available.
+
+## Quick install · Cursor
+
+Add to `.cursor/mcp.json` (per-project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "prefixcheck-edi": {
+      "command": "npx",
+      "args": ["-y", "@prefixcheck/edi-mcp"]
+    }
+  }
+}
+```
+
+## Quick install · Cline / Continue
+
+Same `mcpServers` shape — both clients use the standard MCP configuration format.
+
+---
+
+## Tools (9)
+
+| Tool                        | Returns                                                    |
+| --------------------------- | ---------------------------------------------------------- |
+| `parse_message`             | Full ParsedMessage structure for a CODECO/COPRAR text      |
+| `diagnose_message`          | All 11 SMDG-grade diagnostic findings                      |
+| `reconcile_messages`        | COPRAR ↔ CODECO field-level diff report (8 fields)         |
+| `validate_container_number` | ISO 6346 check digit (true/false + computed value)         |
+| `decode_size_type`          | 4-character ISO size-type → operator-readable English      |
+| `lookup_code`               | Any of 21 code-list values → English (DTM/LOC/EQD/NAD/...) |
+| `segment_info`              | Operator-grade name + brief for any 3-letter segment tag   |
+| `extract_containers`        | All ISO 6346 container numbers from a message              |
+| `extract_locodes`           | All UN/LOCODE values from LOC segments                     |
+
+## Resources (6)
+
+| URI                   | Type | Content                                                               |
+| --------------------- | ---- | --------------------------------------------------------------------- |
+| `edi://schema/codeco` | json | CODECO message metadata (purpose, BGM codes, required segments)       |
+| `edi://schema/coprar` | json | COPRAR message metadata                                               |
+| `edi://sample/codeco` | text | Real-shape SMDG D.00B CODECO sample message                           |
+| `edi://sample/coprar` | text | Real-shape SMDG D.00B COPRAR sample (matched pair with CODECO sample) |
+| `edi://segments`      | json | Full 32-segment dictionary                                            |
+| `edi://codes`         | json | All 21 code lists with codes + English decodes                        |
+
+---
+
+## What you can do with it
+
+**Depot dispatcher**: paste a CODECO into Claude, ask "what's wrong?" → tool runs `diagnose_message`, returns the failing rule (bad check digit, wrong DTM format, missing NAD+CF, etc.) with the exact segment that triggered it.
+
+**Developer debugging**: paste a COPRAR your partner rejected → tool surfaces every SMDG validation failure with the rule that caught it.
+
+**Reconciliation**: "here's the COPRAR I sent and the CODECO I got back — do they match?" → tool runs `reconcile_messages`, returns container-by-container field diffs (size-type, full/empty, POL, POD, booking, gross weight ±2%, VGM ±5%, reefer temp ±1°C).
+
+**Reference**: "what does EQD position 5 mean?" → tool reads `edi://segments` + `edi://codes` resources.
+
+**Training**: junior operator pastes a message → AI walks through each segment using `segment_info` + `lookup_code`.
+
+---
+
+## Built on
+
+- [`@prefixcheck/edi`](https://www.npmjs.com/package/@prefixcheck/edi) — the underlying TS library
+- [UN/EDIFACT D.00B](https://service.unece.org/trade/untdid/d00b/) — directory
+- [SMDG](https://smdg.org/) — 2.1.3 ST VGM CODECO + COPRAR Implementation Guides
+- Operator guides from DAKOSY (Hamburg), Valenciaport PCS, Transnet, EPB Bilbao
+
+Companion surfaces:
+
+- **In-browser tool**: [prefixcheck.com/container-edi/](https://prefixcheck.com/container-edi/)
+- **Public HTTP API**: `POST /api/edi/decode` + `POST /api/edi/reconcile` at prefixcheck.com
+- **Embeddable widget**: `<iframe src="https://prefixcheck.com/embed/edi/">`
+- **npm library**: `npm install @prefixcheck/edi`
+- **MCP server**: this package
+
+---
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+/**
+ * @prefixcheck/edi-mcp
+ *
+ * MCP server exposing operator-grade EDIFACT CODECO + COPRAR
+ * tooling to any MCP client (Claude Desktop, Cursor, Cline,
+ * Continue, Claude Code, etc.).
+ *
+ * Wraps the same parser + schemas that power:
+ *   - https://prefixcheck.com/container-edi/    (in-browser tool)
+ *   - https://prefixcheck.com/api/edi/decode    (HTTP API)
+ *   - @prefixcheck/edi                          (npm library)
+ *
+ * Nine tools + six resources. Pure stdio MCP — no HTTP server,
+ * no auth, no state.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { parse, extractContainerNumbers, extractUNLocodes } from "./parser.js";
+import { CODECO, COPRAR, CODE_LISTS, SEGMENTS, decodeISOSizeType, detectMessageType, diagnoseSingle, lookup, reconcile, segmentInfo, validateCheckDigit, } from "./schemas.js";
+import { SAMPLE_CODECO, SAMPLE_COPRAR } from "./samples.js";
+// -------------------------------------------------------------
+// Server setup
+// -------------------------------------------------------------
+const SERVER_NAME = "prefixcheck-edi-mcp";
+const SERVER_VERSION = "0.1.0";
+const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {}, resources: {} } });
+const TOOLS = [
+    {
+        name: "parse_message",
+        description: "Tokenize a raw EDIFACT CODECO or COPRAR message into structured segments + envelope metadata. Handles UNA delimiter overrides, UNB/UNZ + UNH/UNT envelopes, and release-character escapes. Returns the full ParsedMessage structure.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                text: { type: "string", description: "Raw EDIFACT message text." },
+            },
+            required: ["text"],
+        },
+    },
+    {
+        name: "diagnose_message",
+        description: "Parse a CODECO or COPRAR message and run all 11 SMDG-grade diagnostic rules against it. Returns the list of findings (errors + warnings + info). Empty list = clean message.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                text: { type: "string", description: "Raw EDIFACT message text." },
+            },
+            required: ["text"],
+        },
+    },
+    {
+        name: "reconcile_messages",
+        description: "Cross-message reconciliation between a COPRAR (carrier → terminal load list) and its matching CODECO (terminal → carrier gate report). Returns container-by-container field-level diff report. Tolerances: gross weight ±2%, VGM ±5%, reefer temp ±1°C.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                coprar: { type: "string", description: "Raw EDIFACT COPRAR text." },
+                codeco: { type: "string", description: "Raw EDIFACT CODECO text." },
+            },
+            required: ["coprar", "codeco"],
+        },
+    },
+    {
+        name: "validate_container_number",
+        description: "Validate an ISO 6346 container number's check digit (mod-11 weighted-letter algorithm). Returns { valid: boolean, code, computed_check_digit }.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                code: {
+                    type: "string",
+                    description: "11-character container number (e.g. 'MSCU1234566').",
+                },
+            },
+            required: ["code"],
+        },
+    },
+    {
+        name: "decode_size_type",
+        description: "Decode a 4-character ISO 6346 size-type code (e.g. '45R1') into operator-readable parts: size, type, height/variant, variant digit.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                code: { type: "string", description: "4-character ISO 6346 size-type code." },
+            },
+            required: ["code"],
+        },
+    },
+    {
+        name: "lookup_code",
+        description: "Decode any code-list value to plain English. Lists available: BGM.docname, BGM.function, DTM.qualifier, DTM.format, LOC.qualifier, EQD.type, EQD.supplier, EQD.fullEmpty, STS.code, RFF.qualifier, NAD.party, MEA.qualifier, MEA.unit, VGM.method, HAN.code, SEL.party, FTX.qualifier, TDT.mode, TDT.idCodeList, CNT.qualifier, UNB.syntax.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                list_name: { type: "string", description: "Code list name (e.g. 'DTM.qualifier')." },
+                code: { type: "string", description: "Code value (e.g. '137')." },
+            },
+            required: ["list_name", "code"],
+        },
+    },
+    {
+        name: "segment_info",
+        description: "Get the operator-grade English name + brief explanation for a 3-letter EDIFACT segment tag (e.g. 'EQD', 'LOC', 'TDT').",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tag: { type: "string", description: "3-letter segment tag." },
+            },
+            required: ["tag"],
+        },
+    },
+    {
+        name: "extract_containers",
+        description: "Extract every ISO 6346-shaped container number (4 letters + 7 digits) from anywhere in an EDIFACT message. Returns deduplicated list.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                text: { type: "string", description: "Raw EDIFACT message text." },
+            },
+            required: ["text"],
+        },
+    },
+    {
+        name: "extract_locodes",
+        description: "Extract every 5-character UN/LOCODE (2-letter country + 3-char place) from LOC segments in an EDIFACT message. Returns deduplicated list.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                text: { type: "string", description: "Raw EDIFACT message text." },
+            },
+            required: ["text"],
+        },
+    },
+];
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const a = (args || {});
+    try {
+        switch (name) {
+            case "parse_message": {
+                const text = String(a.text || "");
+                const parsed = parse(text);
+                return jsonResult({
+                    message_type: detectMessageType(parsed),
+                    interchange: parsed.interchange,
+                    message: parsed.message,
+                    segments: parsed.segments,
+                    delimiters: parsed.delimiters,
+                    envelope_warnings: parsed.envelopeWarnings,
+                });
+            }
+            case "diagnose_message": {
+                const text = String(a.text || "");
+                const parsed = parse(text);
+                const diagnostics = diagnoseSingle(parsed);
+                return jsonResult({
+                    message_type: detectMessageType(parsed),
+                    diagnostics,
+                    counts: {
+                        errors: diagnostics.filter((d) => d.level === "error").length,
+                        warnings: diagnostics.filter((d) => d.level === "warn").length,
+                        infos: diagnostics.filter((d) => d.level === "info").length,
+                    },
+                });
+            }
+            case "reconcile_messages": {
+                const coprar = parse(String(a.coprar || ""));
+                const codeco = parse(String(a.codeco || ""));
+                return jsonResult({
+                    report: reconcile(coprar, codeco),
+                    coprar_warnings: coprar.envelopeWarnings,
+                    codeco_warnings: codeco.envelopeWarnings,
+                });
+            }
+            case "validate_container_number": {
+                const code = String(a.code || "");
+                const valid = validateCheckDigit(code);
+                return jsonResult({ code, valid });
+            }
+            case "decode_size_type": {
+                const code = String(a.code || "");
+                const decoded = decodeISOSizeType(code);
+                return jsonResult({ code, decoded });
+            }
+            case "lookup_code": {
+                const list_name = String(a.list_name || "");
+                const code = String(a.code || "");
+                const decoded = lookup(list_name, code);
+                return jsonResult({ list_name, code, decoded });
+            }
+            case "segment_info": {
+                const tag = String(a.tag || "").toUpperCase();
+                return jsonResult({ tag, ...segmentInfo(tag) });
+            }
+            case "extract_containers": {
+                const parsed = parse(String(a.text || ""));
+                return jsonResult({ container_numbers: extractContainerNumbers(parsed) });
+            }
+            case "extract_locodes": {
+                const parsed = parse(String(a.text || ""));
+                return jsonResult({ un_locodes: extractUNLocodes(parsed) });
+            }
+            default:
+                return jsonResult({ error: `Unknown tool: ${name}` }, true);
+        }
+    }
+    catch (err) {
+        return jsonResult({ error: err instanceof Error ? err.message : "Unknown error", tool: name }, true);
+    }
+});
+function jsonResult(payload, isError = false) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+// -------------------------------------------------------------
+// Resources
+// -------------------------------------------------------------
+const RESOURCES = [
+    {
+        uri: "edi://schema/codeco",
+        name: "CODECO schema",
+        description: "CODECO message metadata: name, longName, purpose, BGM codes, required segments.",
+        mimeType: "application/json",
+    },
+    {
+        uri: "edi://schema/coprar",
+        name: "COPRAR schema",
+        description: "COPRAR message metadata: name, longName, purpose, BGM codes, required segments.",
+        mimeType: "application/json",
+    },
+    {
+        uri: "edi://sample/codeco",
+        name: "CODECO sample",
+        description: "Real-shape SMDG D.00B CODECO sample message (gate-in, terminal → carrier, MSCU1234566 full 40HC NLRTM → USNYC).",
+        mimeType: "text/plain",
+    },
+    {
+        uri: "edi://sample/coprar",
+        name: "COPRAR sample",
+        description: "Real-shape SMDG D.00B COPRAR Load sample message (carrier → terminal, 3 containers including 1 reefer, matched-pair with the CODECO sample on MSCU1234566).",
+        mimeType: "text/plain",
+    },
+    {
+        uri: "edi://segments",
+        name: "Segment dictionary",
+        description: "Full 32-segment dictionary with operator-grade name + brief for every common CODECO/COPRAR segment.",
+        mimeType: "application/json",
+    },
+    {
+        uri: "edi://codes",
+        name: "Code lists index",
+        description: "Index of all 21 code lists available via lookup_code. Each list has 5-40 codes with English decodes.",
+        mimeType: "application/json",
+    },
+];
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: RESOURCES }));
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    switch (uri) {
+        case "edi://schema/codeco":
+            return {
+                contents: [{ uri, mimeType: "application/json", text: JSON.stringify(CODECO, null, 2) }],
+            };
+        case "edi://schema/coprar":
+            return {
+                contents: [{ uri, mimeType: "application/json", text: JSON.stringify(COPRAR, null, 2) }],
+            };
+        case "edi://sample/codeco":
+            return { contents: [{ uri, mimeType: "text/plain", text: SAMPLE_CODECO }] };
+        case "edi://sample/coprar":
+            return { contents: [{ uri, mimeType: "text/plain", text: SAMPLE_COPRAR }] };
+        case "edi://segments":
+            return {
+                contents: [{ uri, mimeType: "application/json", text: JSON.stringify(SEGMENTS, null, 2) }],
+            };
+        case "edi://codes": {
+            const index = Object.fromEntries(Object.entries(CODE_LISTS).map(([k, v]) => [
+                k,
+                { code_count: Object.keys(v).length, codes: v },
+            ]));
+            return {
+                contents: [{ uri, mimeType: "application/json", text: JSON.stringify(index, null, 2) }],
+            };
+        }
+        default:
+            throw new Error(`Unknown resource: ${uri}`);
+    }
+});
+// -------------------------------------------------------------
+// Boot
+// -------------------------------------------------------------
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write(`${SERVER_NAME} v${SERVER_VERSION} ready · 9 tools · 6 resources\n`);
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/parser.js

@@ -0,0 +1,246 @@
+// ============================================================
+// @prefixcheck/edi · EDIFACT tokenizer + envelope handling
+//
+// Universal layer that turns raw EDIFACT text into a structured
+// object tree. The schema layer (CODECO/COPRAR validation) runs
+// on top of this and is loaded separately so new message types
+// can be added without touching the parser.
+//
+// EDIFACT delimiter conventions:
+//   element separator    default '+'
+//   composite separator  default ':'
+//   segment terminator   default "'"
+//   release character    default '?'  (escapes the next char)
+//   decimal              default '.'  (or ',')
+//   repetition           default '*'
+//
+// The optional UNA segment at the start of an interchange overrides
+// the defaults. Format: `UNA:+.? '` — exactly 6 single-character
+// overrides in the order: composite, element, decimal, release,
+// repetition, segment.
+// ============================================================
+export const DEFAULT_DELIMITERS = Object.freeze({
+    element: "+",
+    composite: ":",
+    segment: "'",
+    release: "?",
+    decimal: ".",
+    repetition: "*",
+});
+function parseUNA(raw) {
+    if (raw.length < 9 || raw.slice(0, 3) !== "UNA") {
+        return { delimiters: { ...DEFAULT_DELIMITERS }, rest: raw };
+    }
+    const spec = raw.slice(3, 9);
+    return {
+        delimiters: {
+            composite: spec[0],
+            element: spec[1],
+            decimal: spec[2],
+            release: spec[3],
+            repetition: spec[4],
+            segment: spec[5],
+        },
+        rest: raw.slice(9),
+    };
+}
+/**
+ * Split text by an unescaped delimiter character. A delimiter preceded
+ * by the release character (default `?`) is a literal, not a delimiter.
+ *
+ * Note: this function PRESERVES release-character escape sequences in
+ * the output. The escape (`?X`) stays as `?X` so that downstream splits
+ * (e.g., element → composite → sub-element) can also honour escapes.
+ * The final value layer strips escapes with `unescape()`.
+ */
+function splitUnescaped(text, delim, release) {
+    const parts = [];
+    let buf = "";
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (c === release && i + 1 < text.length) {
+            buf += c + text[i + 1];
+            i++;
+            continue;
+        }
+        if (c === delim) {
+            parts.push(buf);
+            buf = "";
+            continue;
+        }
+        buf += c;
+    }
+    parts.push(buf);
+    return parts;
+}
+/**
+ * Strip release-character escape sequences from a sub-element value.
+ * Called only at the leaf layer, after all splitting is done.
+ */
+function unescape(text, release) {
+    let out = "";
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] === release && i + 1 < text.length) {
+            out += text[i + 1];
+            i++;
+        }
+        else {
+            out += text[i];
+        }
+    }
+    return out;
+}
+/**
+ * Strip whitespace following each segment terminator without touching
+ * content inside segments. Human-readable transmission commonly
+ * inserts `\r\n` after each terminator; not part of the standard
+ * but ubiquitous in archived files and operator pastes.
+ */
+function normalizeWhitespace(text, segDelim) {
+    let out = "";
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        out += c;
+        if (c === segDelim) {
+            while (i + 1 < text.length && /\s/.test(text[i + 1]))
+                i++;
+        }
+    }
+    return out;
+}
+function extractEnvelopes(segments) {
+    let interchange = null;
+    let message = null;
+    const warnings = [];
+    const first = segments[0];
+    const last = segments[segments.length - 1];
+    if (first && first.tag === "UNB") {
+        interchange = {
+            syntaxId: (first.elements[0] || [])[0] || "",
+            syntaxVer: (first.elements[0] || [])[1] || "",
+            sender: (first.elements[1] || [])[0] || "",
+            senderQual: (first.elements[1] || [])[1] || "",
+            recipient: (first.elements[2] || [])[0] || "",
+            recipQual: (first.elements[2] || [])[1] || "",
+            dateTime: (first.elements[3] || []).join(":") || "",
+            controlRef: (first.elements[4] || [])[0] || "",
+        };
+        if (!last || last.tag !== "UNZ") {
+            warnings.push("UNB interchange header found but no UNZ trailer.");
+        }
+    }
+    for (let i = 0; i < segments.length; i++) {
+        if (segments[i].tag === "UNH") {
+            const unh = segments[i];
+            message = {
+                controlRef: (unh.elements[0] || [])[0] || "",
+                type: (unh.elements[1] || [])[0] || "",
+                version: (unh.elements[1] || [])[1] || "",
+                release: (unh.elements[1] || [])[2] || "",
+                agency: (unh.elements[1] || [])[3] || "",
+                assocCode: (unh.elements[1] || [])[4] || "",
+            };
+            break;
+        }
+    }
+    if (!message) {
+        warnings.push("No UNH message header found. Parsed as raw segment body.");
+    }
+    return { interchange, message, envelopeWarnings: warnings };
+}
+/**
+ * Tokenize a raw EDIFACT string into structured form.
+ *
+ * Accepts any of:
+ * - bare message body (UNH ... UNT)
+ * - full interchange (optional UNA, UNB ... UNZ wrapping one or more messages)
+ * - whitespace-separated segments (newlines between `'` terminators)
+ *
+ * @example
+ * ```ts
+ * import { parse } from "@prefixcheck/edi";
+ * const parsed = parse("UNH+1+CODECO:D:00B:UN:SMDG21'BGM+34+REF+9'...");
+ * console.log(parsed.message?.type); // "CODECO"
+ * ```
+ */
+export function parse(rawInput) {
+    if (!rawInput || typeof rawInput !== "string") {
+        return {
+            interchange: null,
+            message: null,
+            segments: [],
+            delimiters: { ...DEFAULT_DELIMITERS },
+            envelopeWarnings: ["Empty input."],
+        };
+    }
+    // Strip BOM + outer whitespace
+    const trimmed = rawInput.replace(/^/, "").trim();
+    const unaResult = parseUNA(trimmed);
+    const delim = unaResult.delimiters;
+    const body = normalizeWhitespace(unaResult.rest, delim.segment);
+    const rawSegments = splitUnescaped(body, delim.segment, delim.release);
+    const segments = [];
+    let bodyIndex = 0;
+    for (let s = 0; s < rawSegments.length; s++) {
+        const segText = rawSegments[s].trim();
+        if (!segText)
+            continue;
+        const elements = splitUnescaped(segText, delim.element, delim.release);
+        const tagRaw = elements.shift() || "";
+        const tag = unescape(tagRaw, delim.release);
+        // Composite split → unescape each leaf sub-element value.
+        const composed = elements.map((el) => splitUnescaped(el, delim.composite, delim.release).map((v) => unescape(v, delim.release)));
+        segments.push({
+            tag,
+            index: bodyIndex++,
+            elements: composed,
+            raw: unescape(segText, delim.release),
+        });
+    }
+    const env = extractEnvelopes(segments);
+    return {
+        interchange: env.interchange,
+        message: env.message,
+        segments,
+        delimiters: delim,
+        envelopeWarnings: env.envelopeWarnings,
+    };
+}
+/**
+ * Extract every ISO 6346-shaped container number (4 letters + 7 digits)
+ * found anywhere in the parsed message. Useful for cross-referencing
+ * to a registry or driving downstream linking.
+ */
+export function extractContainerNumbers(parsed) {
+    const pattern = /\b[A-Z]{4}\d{7}\b/g;
+    const seen = new Set();
+    const out = [];
+    for (const seg of parsed.segments) {
+        const matches = seg.raw.match(pattern) || [];
+        for (const m of matches) {
+            if (!seen.has(m)) {
+                seen.add(m);
+                out.push(m);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Extract every UN/LOCODE-shaped token (5 chars: 2-letter country
+ * code + 3-letter/digit location code) from LOC segments specifically.
+ */
+export function extractUNLocodes(parsed) {
+    const seen = new Set();
+    const out = [];
+    for (const seg of parsed.segments) {
+        if (seg.tag !== "LOC")
+            continue;
+        const place = (seg.elements[1] || [])[0];
+        if (place && /^[A-Z]{2}[A-Z0-9]{3}$/.test(place) && !seen.has(place)) {
+            seen.add(place);
+            out.push(place);
+        }
+    }
+    return out;
+}