@datanimbus/dnio-mcp 1.0.0

package/src/tools/data-formats.js

@@ -0,0 +1,806 @@
+'use strict';
+
+const crypto = require('crypto');
+const {z} = require('zod');
+const {toolError} = require('./_helpers');
+
+// ─── Mapping tables (per spec §4, §5, §6) ───────────────────────────────────
+
+const FORMAT_TYPE_MAP = {
+    JSON: 'JSON',
+    XML: 'XML',
+    XLS: 'XLS',
+    XLSX: 'XLSX',
+    FIXED: 'FLATFILE',
+    FLATFILE: 'FLATFILE',
+    TXT: 'TXT',
+    CSV: 'CSV',
+    DELIMITER: 'DELIMITER'
+};
+
+const FORMATS_WITH_SUBTYPE = new Set(['FLATFILE', 'TXT', 'CSV', 'DELIMITER']);
+const FORMATS_NESTING = new Set(['JSON', 'XML']);
+
+const TYPE_MAP = {
+    Text: 'String', text: 'String', String: 'String', string: 'String',
+    Number: 'Number', number: 'Number',
+    Boolean: 'Boolean', boolean: 'Boolean', 'True/False': 'Boolean',
+    Date: 'Date', date: 'Date',
+    Group: 'Object', group: 'Object', Object: 'Object', object: 'Object',
+    Collection: 'Array', collection: 'Array', Array: 'Array', array: 'Array'
+};
+
+const PRIMITIVE_TYPES = new Set(['String', 'Number', 'Boolean', 'Date']);
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function _uuid() {
+    return crypto.randomUUID();
+}
+
+function _resolveFormatType(input) {
+    if (!input) throw new Error('formatType required');
+    const mapped = FORMAT_TYPE_MAP[String(input).toUpperCase()] || FORMAT_TYPE_MAP[input];
+    if (!mapped) throw new Error(`Unknown formatType '${input}'. Allowed: ${Object.keys(FORMAT_TYPE_MAP).join(', ')}`);
+    return mapped;
+}
+
+function _resolveSubType(formatType, requested) {
+    // JSON/XML/XLS/XLSX → always 'flat'.
+    if (!FORMATS_WITH_SUBTYPE.has(formatType)) return 'flat';
+    // FLATFILE/TXT/CSV/DELIMITER → user picks.
+    const sub = requested || 'flat';
+    if (sub !== 'flat' && sub !== 'HRSF') {
+        throw new Error(`subType for ${formatType} must be 'flat' or 'HRSF', got '${sub}'`);
+    }
+    return sub;
+}
+
+function _resolveType(input) {
+    const mapped = TYPE_MAP[input];
+    if (!mapped) throw new Error(`Unknown type '${input}'. Allowed: ${Object.keys(TYPE_MAP).join(', ')}`);
+    return mapped;
+}
+
+function _allowedForFormat(formatType) {
+    if (FORMATS_NESTING.has(formatType)) return new Set(['String', 'Number', 'Boolean', 'Date', 'Object', 'Array']);
+    return PRIMITIVE_TYPES;
+}
+
+function _splitDataPath(dataPath) {
+    if (!dataPath) return [];
+    return String(dataPath).replace(/\[#\]/g, '.[#]').split('.').filter(Boolean);
+}
+
+// Walk path like 'cars[#].model.year' → [cars, _self, model, year] node.
+// '[#]' segment maps to the '_self' child of the preceding Array.
+function _findNodeByPath(definition, dataPath) {
+    if (!dataPath) return {definition, node: null}; // root
+    const segs = _splitDataPath(dataPath);
+    let parentDef = definition;
+    let current = null;
+    for (const seg of segs) {
+        const matchKey = seg === '[#]' ? '_self' : seg;
+        const child = (parentDef || []).find(n => n.key === matchKey);
+        if (!child) return null;
+        current = child;
+        parentDef = child.definition || [];
+    }
+    return {node: current, parentDefinition: parentDef};
+}
+
+// Locate the parent's definition[] for inserting/removing a node at the given path.
+function _findParentDefinition(definition, dataPath) {
+    if (!dataPath) return definition; // insert at root
+    const segs = _splitDataPath(dataPath);
+    let parentDef = definition;
+    let node = null;
+    for (const seg of segs) {
+        const matchKey = seg === '[#]' ? '_self' : seg;
+        node = (parentDef || []).find(n => n.key === matchKey);
+        if (!node) return null;
+        parentDef = node.definition || (node.definition = []);
+    }
+    return parentDef;
+}
+
+// Recompute every node's properties.dataPath / dataPathSegs + root attributeCount.
+// Spec §9: append `key` for normal step; append '[#]' when entering Array's _self.
+function _annotatePaths(definition, parentSegs) {
+    const segs = parentSegs || [];
+    for (const node of (definition || [])) {
+        const isSelf = node.key === '_self';
+        const myPathSegs = isSelf ? [...segs, '[#]'] : [...segs, node.key];
+        const dataPath = myPathSegs.join('.').replace(/\.\[#\]/g, '[#]');
+        node.properties = node.properties || {};
+        node.properties.dataPath = dataPath;
+        node.properties.dataPathSegs = myPathSegs;
+        if (Array.isArray(node.definition)) {
+            _annotatePaths(node.definition, myPathSegs);
+        }
+    }
+}
+
+// ─── Attribute builder (simple LLM-friendly input → DNIO attribute node) ────
+
+const VARIANT_FLAGS = {
+    longText:     {richText: true},
+    richText:     {richText: true},
+    email:        {email: true},
+    currency:     {currency: true}, // §13 verify
+    date:         {dateType: 'date'},
+    datetime:     {dateType: 'datetime-local'}
+};
+
+// Per-format property defaults (spec §8). Always include fieldLength/paddingChar/paddingPosition.
+function _defaultProperties(name, storedType) {
+    return {
+        name: name || '',
+        _typeChanged: storedType,
+        default: null,
+        fieldLength: 10,
+        paddingChar: ' ',
+        paddingPosition: 'suffix'
+    };
+}
+
+/**
+ * Build a DNIO attribute node from a simple LLM-friendly spec.
+ *
+ * Spec shape:
+ *   {
+ *     key: 'firstName',                 // required
+ *     type: 'Text|Number|Boolean|Date|Group|Collection' (or stored equivalents),
+ *     name?: 'FIRST_NAME',              // display name; defaults to key.toUpperCase()
+ *     variant?: 'longText'|'richText'|'email'|'currency'|'date'|'datetime',
+ *     enum?: [...],                     // for listOfValues/listOfNumber
+ *     precision?: number,               // Number
+ *     required?: boolean,               // CSV/DELIMITER
+ *     fieldNumber?: number,             // CSV/DELIMITER
+ *     mask?: 'all'|'data'|'disable'|boolean,
+ *     pattern?, minLength?, maxLength?,
+ *     fieldLength?, paddingChar?, paddingPosition?,
+ *     _description?,
+ *     children?: [<spec>...],           // Group → nested defs
+ *     itemType?: 'Text'|...|'Group',    // Collection child type (defaults to 'Group')
+ *   }
+ */
+function _buildAttribute(spec, formatType) {
+    if (!spec || !spec.key) throw new Error('attribute spec needs `key`');
+    const allowed = _allowedForFormat(formatType);
+
+    let storedType;
+    let isCollection = false;
+    let isGroup = false;
+    if (spec.type === 'Collection' || spec.type === 'Array' || spec.type === 'array' || spec.type === 'collection') {
+        storedType = 'Array';
+        isCollection = true;
+    } else if (spec.type === 'Group' || spec.type === 'Object' || spec.type === 'group' || spec.type === 'object') {
+        storedType = 'Object';
+        isGroup = true;
+    } else {
+        storedType = _resolveType(spec.type);
+    }
+
+    if (!allowed.has(storedType)) {
+        throw new Error(`Type '${storedType}' not allowed for formatType '${formatType}' (allowed: ${[...allowed].join(', ')})`);
+    }
+
+    const props = _defaultProperties(spec.name || spec.key.toUpperCase(), storedType);
+
+    // Variant flags (primitives only).
+    if (spec.variant) {
+        const flag = VARIANT_FLAGS[spec.variant];
+        if (!flag) throw new Error(`Unknown variant '${spec.variant}'`);
+        Object.assign(props, flag);
+    }
+    if (Array.isArray(spec.enum)) props.enum = spec.enum;
+    if (typeof spec.precision === 'number') props.precision = spec.precision;
+    if (typeof spec.required === 'boolean') props.required = spec.required;
+    if (typeof spec.fieldNumber === 'number') props.fieldNumber = spec.fieldNumber;
+    if (spec.mask !== undefined) props.mask = spec.mask;
+    if (spec.pattern) props.pattern = spec.pattern;
+    if (typeof spec.minLength === 'number') props.minLength = spec.minLength;
+    if (typeof spec.maxLength === 'number') props.maxLength = spec.maxLength;
+    if (typeof spec.fieldLength === 'number') props.fieldLength = spec.fieldLength;
+    if (spec.paddingChar !== undefined) props.paddingChar = spec.paddingChar;
+    if (spec.paddingPosition) props.paddingPosition = spec.paddingPosition;
+    if (spec.description) props._description = spec.description;
+
+    const node = {
+        _fieldId: _uuid(),
+        key: spec.key,
+        type: storedType,
+        properties: props
+    };
+
+    if (isGroup) {
+        node.definition = (spec.children || []).map(c => _buildAttribute(c, formatType));
+    } else if (isCollection) {
+        // Always wrap children in a `_self` entry per §6.
+        const itemType = spec.itemType || (Array.isArray(spec.children) && spec.children.length > 0 ? 'Group' : 'String');
+        const isSelfPrimitive = !(itemType === 'Group' || itemType === 'Object');
+        let selfStored;
+        try {
+            selfStored = isSelfPrimitive ? _resolveType(itemType) : 'Object';
+        } catch (e) {
+            selfStored = 'Object';
+        }
+        const selfProps = _defaultProperties('', selfStored);
+        const selfNode = {
+            _fieldId: _uuid(),
+            key: '_self',
+            type: selfStored,
+            properties: selfProps
+        };
+        if (selfStored === 'Object') {
+            selfNode.definition = (spec.children || []).map(c => _buildAttribute(c, formatType));
+        }
+        node.definition = [selfNode];
+    }
+
+    return node;
+}
+
+// HRSF rigid skeleton per §4. Optional `sections` populates each section with primitives.
+//
+// sections shape:
+//   { header?: [<spec>, ...], records?: [<spec>, ...], footer?: [<spec>, ...] }
+// Each spec uses the same shape as _buildAttribute. HRSF only allows primitives inside
+// sections — Group/Collection are rejected at build time.
+function _buildHrsfSkeleton(formatType, sections) {
+    const s = sections || {};
+
+    const buildPrimitives = (specs, sectionLabel) => {
+        if (!Array.isArray(specs)) return [];
+        return specs.map((spec) => {
+            const node = _buildAttribute(spec, formatType);
+            if (!PRIMITIVE_TYPES.has(node.type)) {
+                throw new Error(`HRSF ${sectionLabel} only allows primitives, got '${node.type}' on '${node.key}'`);
+            }
+            return node;
+        });
+    };
+
+    const header = {
+        _fieldId: _uuid(),
+        key: 'Header',
+        type: 'Object',
+        definition: buildPrimitives(s.header, 'Header'),
+        properties: _defaultProperties('HEADER', 'Object')
+    };
+    const recordsSelf = {
+        _fieldId: _uuid(),
+        key: '_self',
+        type: 'Object',
+        definition: buildPrimitives(s.records, 'Records._self'),
+        properties: _defaultProperties('', 'Object')
+    };
+    const records = {
+        _fieldId: _uuid(),
+        key: 'Records',
+        type: 'Array',
+        definition: [recordsSelf],
+        properties: _defaultProperties('RECORDS', 'Array')
+    };
+    const footer = {
+        _fieldId: _uuid(),
+        key: 'Footer',
+        type: 'Object',
+        definition: buildPrimitives(s.footer, 'Footer'),
+        properties: _defaultProperties('FOOTER', 'Object')
+    };
+    return [header, records, footer];
+}
+
+// ─── Pre-PUT validation (spec §11.9) ────────────────────────────────────────
+
+function _validateRoot(doc) {
+    if (doc.type !== 'Object') throw new Error('root type must be "Object"');
+
+    // HRSF root has its own contract: exactly [Header(Object), Records(Array), Footer(Object)].
+    // Sections themselves use Object/Array even though FLATFILE/CSV/etc. would otherwise
+    // restrict root types to primitives — so handle HRSF before the format-allowed check.
+    if (doc.subType === 'HRSF') {
+        const keys = (doc.definition || []).map(n => n.key);
+        if (keys.length !== 3 || keys[0] !== 'Header' || keys[1] !== 'Records' || keys[2] !== 'Footer') {
+            throw new Error('HRSF skeleton must be exactly [Header, Records, Footer] in that order');
+        }
+        const [header, records, footer] = doc.definition;
+        if (header.type !== 'Object') throw new Error('HRSF Header must be Object');
+        if (footer.type !== 'Object') throw new Error('HRSF Footer must be Object');
+        if (records.type !== 'Array' || !Array.isArray(records.definition) || records.definition[0]?.key !== '_self' || records.definition[0].type !== 'Object') {
+            throw new Error('HRSF Records must be Array with _self Object wrapper');
+        }
+        for (const section of doc.definition) {
+            _walkValidate(section, doc.formatType, doc.subType);
+        }
+        return;
+    }
+
+    const allowed = _allowedForFormat(doc.formatType);
+    const seen = new Set();
+    for (const node of (doc.definition || [])) {
+        if (!allowed.has(node.type)) {
+            throw new Error(`Type '${node.type}' on '${node.key}' not allowed for formatType '${doc.formatType}'`);
+        }
+        if (seen.has(node.key)) throw new Error(`duplicate key '${node.key}' at root`);
+        seen.add(node.key);
+        _walkValidate(node, doc.formatType, doc.subType);
+    }
+}
+
+function _walkValidate(node, formatType, subType) {
+    if (node.type === 'Array') {
+        if (!Array.isArray(node.definition) || node.definition.length === 0 || node.definition[0].key !== '_self') {
+            throw new Error(`Array '${node.key}' must have a _self wrapper child`);
+        }
+        const self = node.definition[0];
+        // HRSF: only primitives inside sections.
+        if (subType === 'HRSF' && self.type === 'Object') {
+            for (const child of (self.definition || [])) {
+                if (!PRIMITIVE_TYPES.has(child.type)) {
+                    throw new Error(`HRSF Records._self only allows primitives, got '${child.type}' on '${child.key}'`);
+                }
+            }
+        }
+        if (Array.isArray(self.definition)) {
+            const seen = new Set();
+            for (const child of self.definition) {
+                if (seen.has(child.key)) throw new Error(`duplicate key '${child.key}' inside ${node.key}._self`);
+                seen.add(child.key);
+                _walkValidate(child, formatType, subType);
+            }
+        }
+    } else if (node.type === 'Object' && Array.isArray(node.definition)) {
+        const seen = new Set();
+        for (const child of node.definition) {
+            if (subType === 'HRSF' && (node.key === 'Header' || node.key === 'Footer') && !PRIMITIVE_TYPES.has(child.type)) {
+                throw new Error(`HRSF ${node.key} only allows primitives, got '${child.type}' on '${child.key}'`);
+            }
+            if (seen.has(child.key)) throw new Error(`duplicate key '${child.key}' inside ${node.key}`);
+            seen.add(child.key);
+            _walkValidate(child, formatType, subType);
+        }
+    }
+}
+
+// ─── Tool registrations ─────────────────────────────────────────────────────
+
+module.exports = function registerDataFormatsTools({server, dnioClient, registry, userContext}) {
+    const requireApp = () => {
+        if (!registry.selectedApp) {
+            return {content: [{type: 'text', text: 'No app selected. Use list_apps → select_app first.'}], isError: true};
+        }
+        return null;
+    };
+
+    server.registerTool(
+        'list_data_formats',
+        {
+            title: 'List Data Formats',
+            description: `List Data Formats in the selected app.
+
+Args:
+  - filter (optional): JSON string, extra filter merged onto {app}.
+  - select (optional): comma-separated fields.
+  - count  (optional, default -1): max items.
+  - page   (optional, default 1).`,
+            inputSchema: {
+                filter: z.string().optional(),
+                select: z.string().optional(),
+                count: z.number().int().optional(),
+                page: z.number().int().optional()
+            },
+            annotations: {readOnlyHint: true, idempotentHint: true}
+        },
+        async (params) => {
+            const guard = requireApp();
+            if (guard) return guard;
+            try {
+                dnioClient.setToken(userContext.token);
+                const filter = params.filter ? JSON.parse(params.filter) : undefined;
+                const result = await dnioClient.dataFormats.list(registry.selectedApp, {
+                    filter,
+                    select: params.select,
+                    count: params.count,
+                    page: params.page
+                });
+                return {content: [{type: 'text', text: JSON.stringify(result, null, 2)}]};
+            } catch (error) {
+                return toolError('Failed to list data formats', error);
+            }
+        }
+    );
+
+    server.registerTool(
+        'get_data_format',
+        {
+            title: 'Get Data Format',
+            description: 'Fetch a Data Format by id (e.g. "DF6482").',
+            inputSchema: {id: z.string().min(1)},
+            annotations: {readOnlyHint: true, idempotentHint: true}
+        },
+        async (params) => {
+            const guard = requireApp();
+            if (guard) return guard;
+            try {
+                dnioClient.setToken(userContext.token);
+                const result = await dnioClient.dataFormats.get(registry.selectedApp, params.id);
+                return {content: [{type: 'text', text: JSON.stringify(result, null, 2)}]};
+            } catch (error) {
+                return toolError(`Failed to get data format ${params.id}`, error);
+            }
+        }
+    );
+
+    server.registerTool(
+        'create_data_format',
+        {
+            title: 'Create Data Format',
+            description: `Create a Data Format in two steps automatically: POST shell → PUT populated definition.
+
+UI label → stored formatType: JSON→JSON, XML→XML, XLS→XLS, XLSX→XLSX, FIXED→FLATFILE, TXT→TXT, CSV→CSV, DELIMITER→DELIMITER.
+subType: JSON/XML/XLS/XLSX always 'flat'. FLATFILE/TXT/CSV/DELIMITER accept 'flat' or 'HRSF'.
+HRSF: rigid 3-section skeleton (Header/Records/Footer) — auto-generated when subType='HRSF'. The 'definition' arg is ignored for HRSF; pass section fields via 'hrsfSections' instead. Header/Records/Footer accept primitives only (Text/Number/Boolean/Date).
+
+Attribute spec (per node, recursive — pass via 'definition'):
+  { key, type: 'Text|Number|Boolean|Date|Group|Collection',
+    name?, variant?: 'longText|richText|email|currency|date|datetime',
+    enum?, precision?, required?, fieldNumber?, mask?,
+    pattern?, minLength?, maxLength?,
+    fieldLength?, paddingChar?, paddingPosition?, description?,
+    children?: [<spec>...],            // for Group
+    itemType?: 'Text|...|Group', children?: [<spec>...] // for Collection
+  }
+
+Args:
+  - name (required)
+  - formatType (required): JSON|XML|XLS|XLSX|FIXED|TXT|CSV|DELIMITER
+  - subType (optional): flat|HRSF (only for FIXED/TXT/CSV/DELIMITER)
+  - description, character, lineSeparator, excelType, strictValidation (all optional)
+  - definition (optional JSON string): array of attribute specs (flat formats only).
+  - hrsfSections (optional JSON string): for subType=HRSF — populates the rigid skeleton's sections.
+        Shape: { "header": [<spec>,...], "records": [<spec>,...], "footer": [<spec>,...] }
+        Each spec is the same shape as 'definition' entries, BUT must be primitives only
+        (Text/Number/Boolean/Date — no Group/Collection inside HRSF sections).
+        Omit to create an empty skeleton; you can later use add_attribute with parentPath
+        'Header', 'Records[#]', or 'Footer' to populate it.`,
+            inputSchema: {
+                name: z.string().min(1),
+                formatType: z.string().min(1),
+                subType: z.enum(['flat', 'HRSF']).optional(),
+                description: z.string().optional(),
+                character: z.string().optional(),
+                lineSeparator: z.string().optional(),
+                excelType: z.enum(['xls', 'xlsx']).optional(),
+                strictValidation: z.boolean().optional(),
+                definition: z.string().optional(),
+                hrsfSections: z.string().optional()
+            },
+            annotations: {destructiveHint: false, idempotentHint: false}
+        },
+        async (params) => {
+            const guard = requireApp();
+            if (guard) return guard;
+            try {
+                const app = registry.selectedApp;
+                const formatType = _resolveFormatType(params.formatType);
+                const subType = _resolveSubType(formatType, params.subType);
+
+                dnioClient.setToken(userContext.token);
+
+                // Step 1: POST shell with empty definition.
+                const shell = {
+                    name: params.name,
+                    description: params.description ?? null,
+                    strictValidation: params.strictValidation ?? null,
+                    type: 'Object',
+                    formatType,
+                    subType,
+                    character: params.character ?? ',',
+                    excelType: params.excelType ?? 'xls',
+                    lineSeparator: params.lineSeparator ?? '\\n',
+                    app,
+                    definition: []
+                };
+                const created = await dnioClient.dataFormats.create(app, shell);
+                if (!created || !created._id) {
+                    return toolError('Create returned no _id', new Error(JSON.stringify(created)));
+                }
+
+                // Step 2: build definition, validate, PUT.
+                let definition;
+                if (subType === 'HRSF') {
+                    let sections;
+                    if (params.hrsfSections) {
+                        try {
+                            sections = JSON.parse(params.hrsfSections);
+                        } catch (e) {
+                            return toolError('hrsfSections is not valid JSON', e);
+                        }
+                        if (!sections || typeof sections !== 'object' || Array.isArray(sections)) {
+                            return toolError('hrsfSections must be an object with header/records/footer arrays', new Error(''));
+                        }
+                    }
+                    try {
+                        definition = _buildHrsfSkeleton(formatType, sections);
+                    } catch (e) {
+                        return toolError('Failed to build HRSF skeleton', e);
+                    }
+                } else if (params.definition) {
+                    let specs;
+                    try {
+                        specs = JSON.parse(params.definition);
+                    } catch (e) {
+                        return toolError('definition is not valid JSON', e);
+                    }
+                    if (!Array.isArray(specs)) {
+                        return toolError('definition must be a JSON array of attribute specs', new Error(''));
+                    }
+                    definition = specs.map(s => _buildAttribute(s, formatType));
+                } else {
+                    definition = [];
+                }
+
+                const populated = {...created, definition};
+                _annotatePaths(populated.definition, []);
+                populated.attributeCount = populated.definition.length;
+                _validateRoot(populated);
+
+                const final = await dnioClient.dataFormats.update(app, created._id, populated);
+                return {content: [{type: 'text', text: JSON.stringify({
+                    dataFormatId: final._id,
+                    formatType: final.formatType,
+                    subType: final.subType,
+                    attributeCount: final.attributeCount,
+                    dataFormat: final
+                }, null, 2)}]};
+            } catch (error) {
+                return toolError('Failed to create data format', error);
+            }
+        }
+    );
+
+    server.registerTool(
+        'update_data_format',
+        {
+            title: 'Update Data Format',
+            description: `Replace a Data Format document. Send the FULL doc — partial PUT not supported.
+
+Use this when you have the entire mutated doc ready (e.g. from get_data_format). For attribute-only changes, prefer add_attribute / update_attribute / remove_attribute.
+
+Args:
+  - id (required)
+  - data (required, JSON string): full document.`,
+            inputSchema: {
+                id: z.string().min(1),
+                data: z.string().min(2)
+            },
+            annotations: {destructiveHint: true, idempotentHint: false}
+        },
+        async (params) => {
+            const guard = requireApp();
+            if (guard) return guard;
+            try {
+                const payload = JSON.parse(params.data);
+                payload.app = registry.selectedApp;
+                _annotatePaths(payload.definition || [], []);
+                payload.attributeCount = (payload.definition || []).length;
+                _validateRoot(payload);
+                dnioClient.setToken(userContext.token);
+                const result = await dnioClient.dataFormats.update(registry.selectedApp, params.id, payload);
+                return {content: [{type: 'text', text: JSON.stringify(result, null, 2)}]};
+            } catch (error) {
+                return toolError(`Failed to update data format ${params.id}`, error);
+            }
+        }
+    );
+
+    server.registerTool(
+        'delete_data_format',
+        {
+            title: 'Delete Data Format',
+            description: 'Soft-delete a Data Format by id.',
+            inputSchema: {id: z.string().min(1)},
+            annotations: {destructiveHint: true, idempotentHint: false}
+        },
+        async (params) => {
+            const guard = requireApp();
+            if (guard) return guard;
+            try {
+                dnioClient.setToken(userContext.token);
+                const result = await dnioClient.dataFormats.delete(registry.selectedApp, params.id);
+                return {content: [{type: 'text', text: JSON.stringify({id: params.id, action: 'deleted', result}, null, 2)}]};
+            } catch (error) {
+                return toolError(`Failed to delete data format ${params.id}`, error);
+            }
+        }
+    );
+
+    server.registerTool(
+        'add_attribute',
+        {
+            title: 'Add Attribute to Data Format',
+            description: `Insert an attribute at a parent dataPath. Fetches the current doc, mutates definition[], PUTs the full doc back.
+
+Args:
+  - id (required): Data Format id.
+  - parentPath (optional): dataPath of the parent Group/Array (e.g. 'address' or 'cars[#]'). Omit/empty to insert at root.
+  - attribute (required, JSON string): attribute spec — same shape as create_data_format.definition entries.`,
+            inputSchema: {
+                id: z.string().min(1),
+                parentPath: z.string().optional(),
+                attribute: z.string().min(2)
+            },
+            annotations: {destructiveHint: false, idempotentHint: false}
+        },
+        async (params) => {
+            const guard = requireApp();
+            if (guard) return guard;
+            try {
+                const app = registry.selectedApp;
+                dnioClient.setToken(userContext.token);
+                const doc = await dnioClient.dataFormats.get(app, params.id);
+                if (!doc || !doc.formatType) return toolError('Failed to fetch data format for edit', new Error('missing formatType'));
+
+                const spec = JSON.parse(params.attribute);
+                const newNode = _buildAttribute(spec, doc.formatType);
+
+                const targetDef = _findParentDefinition(doc.definition || (doc.definition = []), params.parentPath || '');
+                if (!targetDef) {
+                    return toolError(`parentPath '${params.parentPath}' not found in data format`, new Error(''));
+                }
+                if (targetDef.some(n => n.key === newNode.key)) {
+                    return toolError(`duplicate key '${newNode.key}' at parent '${params.parentPath || '(root)'}'`, new Error(''));
+                }
+                targetDef.push(newNode);
+
+                _annotatePaths(doc.definition, []);
+                doc.attributeCount = doc.definition.length;
+                doc.app = app;
+                _validateRoot(doc);
+
+                const updated = await dnioClient.dataFormats.update(app, params.id, doc);
+                return {content: [{type: 'text', text: JSON.stringify({
+                    addedKey: newNode.key,
+                    addedDataPath: newNode.properties.dataPath,
+                    dataFormat: updated
+                }, null, 2)}]};
+            } catch (error) {
+                return toolError(`Failed to add attribute to ${params.id}`, error);
+            }
+        }
+    );
+
+    server.registerTool(
+        'update_attribute',
+        {
+            title: 'Update Attribute in Data Format',
+            description: `Edit an existing attribute identified by dataPath. Fetches → mutates → PUTs.
+
+Pass only the fields to change in 'patch'. Properties merge onto existing properties; nested 'children' (for Group/Collection) replace the existing definition entirely.
+
+Args:
+  - id (required)
+  - dataPath (required): e.g. 'firstName' or 'address.pin' or 'cars[#].model'.
+  - patch (required, JSON string): partial spec (any of name, variant, enum, precision, required, fieldNumber, mask, pattern, minLength, maxLength, fieldLength, paddingChar, paddingPosition, description, children, itemType).`,
+            inputSchema: {
+                id: z.string().min(1),
+                dataPath: z.string().min(1),
+                patch: z.string().min(2)
+            },
+            annotations: {destructiveHint: false, idempotentHint: true}
+        },
+        async (params) => {
+            const guard = requireApp();
+            if (guard) return guard;
+            try {
+                const app = registry.selectedApp;
+                dnioClient.setToken(userContext.token);
+                const doc = await dnioClient.dataFormats.get(app, params.id);
+                if (!doc) return toolError('Failed to fetch data format for edit', new Error('not found'));
+
+                const found = _findNodeByPath(doc.definition || [], params.dataPath);
+                if (!found || !found.node) return toolError(`dataPath '${params.dataPath}' not found`, new Error(''));
+                const node = found.node;
+
+                const patch = JSON.parse(params.patch);
+                node.properties = node.properties || {};
+
+                if (patch.name) node.properties.name = patch.name;
+                if (patch.variant) {
+                    const flag = VARIANT_FLAGS[patch.variant];
+                    if (!flag) return toolError(`Unknown variant '${patch.variant}'`, new Error(''));
+                    Object.assign(node.properties, flag);
+                }
+                for (const k of ['enum', 'precision', 'required', 'fieldNumber', 'mask', 'pattern', 'minLength', 'maxLength', 'fieldLength', 'paddingChar', 'paddingPosition', 'default']) {
+                    if (k in patch) node.properties[k] = patch[k];
+                }
+                // Description stored under `_description` per platform schema (not `description`).
+                if ('description' in patch) node.properties._description = patch.description;
+                if (patch.children && (node.type === 'Object' || (node.type === 'Array' && node.definition?.[0]?.type === 'Object'))) {
+                    const built = patch.children.map(c => _buildAttribute(c, doc.formatType));
+                    if (node.type === 'Object') node.definition = built;
+                    else node.definition[0].definition = built;
+                }
+
+                _annotatePaths(doc.definition, []);
+                doc.attributeCount = doc.definition.length;
+                doc.app = app;
+                _validateRoot(doc);
+
+                const updated = await dnioClient.dataFormats.update(app, params.id, doc);
+                return {content: [{type: 'text', text: JSON.stringify({
+                    updatedDataPath: params.dataPath,
+                    dataFormat: updated
+                }, null, 2)}]};
+            } catch (error) {
+                return toolError(`Failed to update attribute ${params.dataPath} in ${params.id}`, error);
+            }
+        }
+    );
+
+    server.registerTool(
+        'remove_attribute',
+        {
+            title: 'Remove Attribute from Data Format',
+            description: `⚠️ Destructive. Delete an attribute identified by dataPath. Fetches → mutates → PUTs.
+
+Refuses to remove HRSF skeleton sections (Header/Records/Footer at root).
+
+Args:
+  - id (required)
+  - dataPath (required)`,
+            inputSchema: {
+                id: z.string().min(1),
+                dataPath: z.string().min(1)
+            },
+            annotations: {destructiveHint: true, idempotentHint: false}
+        },
+        async (params) => {
+            const guard = requireApp();
+            if (guard) return guard;
+            try {
+                const app = registry.selectedApp;
+                dnioClient.setToken(userContext.token);
+                const doc = await dnioClient.dataFormats.get(app, params.id);
+                if (!doc) return toolError('Failed to fetch data format for edit', new Error('not found'));
+
+                if (doc.subType === 'HRSF') {
+                    const top = _splitDataPath(params.dataPath)[0];
+                    if (top === 'Header' || top === 'Records' || top === 'Footer') {
+                        if (_splitDataPath(params.dataPath).length === 1) {
+                            return toolError('Cannot remove HRSF skeleton section. Edit its children instead.', new Error(''));
+                        }
+                    }
+                }
+
+                const segs = _splitDataPath(params.dataPath);
+                if (segs.length === 0) return toolError('dataPath required', new Error(''));
+                const lastSeg = segs[segs.length - 1];
+                const parentPath = segs.slice(0, -1).join('.').replace(/\.\[#\]/g, '[#]');
+                const parentDef = _findParentDefinition(doc.definition || [], parentPath);
+                if (!parentDef) return toolError(`parent of '${params.dataPath}' not found`, new Error(''));
+
+                const matchKey = lastSeg === '[#]' ? '_self' : lastSeg;
+                const idx = parentDef.findIndex(n => n.key === matchKey);
+                if (idx < 0) return toolError(`'${params.dataPath}' not found`, new Error(''));
+                parentDef.splice(idx, 1);
+
+                _annotatePaths(doc.definition, []);
+                doc.attributeCount = doc.definition.length;
+                doc.app = app;
+                _validateRoot(doc);
+
+                const updated = await dnioClient.dataFormats.update(app, params.id, doc);
+                return {content: [{type: 'text', text: JSON.stringify({
+                    removedDataPath: params.dataPath,
+                    dataFormat: updated
+                }, null, 2)}]};
+            } catch (error) {
+                return toolError(`Failed to remove attribute ${params.dataPath} from ${params.id}`, error);
+            }
+        }
+    );
+};