@datanimbus/dnio-mcp 1.0.0

package/src/tools/services.js

@@ -0,0 +1,476 @@
+'use strict';
+
+const crypto = require('crypto');
+const {z} = require('zod');
+const {toolError} = require('./_helpers');
+const {DATA_SERVICE_CREATION_SPEC} = require('../utils/constants');
+
+// Pre-validate a data service name against the platform's expected pattern.
+// Returns an error message string, or null if valid.
+//   - 2–40 chars
+//   - Must start with a letter
+//   - Letters, digits, underscore only (no hyphens, spaces, special chars)
+function _validateServiceName(name) {
+    if (typeof name !== 'string' || name.length === 0) {
+        return "'name' is required and must be a non-empty string.";
+    }
+    if (name.length < 2 || name.length > 40) {
+        return `'${name}' length is ${name.length}; must be 2–40 characters.`;
+    }
+    if (!/^[A-Za-z]/.test(name)) {
+        return `'${name}' must start with a letter.`;
+    }
+    if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(name)) {
+        return `'${name}' contains invalid characters. Allowed: letters, digits, underscore. No hyphens, spaces, or special chars. Use camelCase (e.g. 'companyEmployees') or snake_case ('company_employees').`;
+    }
+    return null;
+}
+
+// ─── Definition normalization ───────────────────────────────────────────────
+// Platform expects every field to carry a fixed set of properties (fieldLength,
+// paddingChar, paddingPosition, _typeChanged, dataPath, dataPathSegs). LLM
+// often emits sparse properties — this normalizer fills the defaults, wraps
+// Array children in the required `_self` wrapper, and computes dataPaths.
+
+const _PRIMITIVE_TYPES = new Set(['String', 'Number', 'Boolean', 'Date']);
+
+// Wrap an Array's children in the `_self` wrapper if missing.
+//   - 1 primitive child  → rename child to `_self` (its type becomes the array item type).
+//   - Multiple children OR object children → wrap them in a single `_self` Object.
+function _wrapArrayChildren(node) {
+    if (node.type !== 'Array') return;
+    const def = Array.isArray(node.definition) ? node.definition : [];
+    if (def.length === 1 && def[0].key === '_self') return; // already wrapped
+
+    if (def.length === 0) {
+        node.definition = [{
+            key: '_self', type: 'String',
+            properties: {name: '_self'}
+        }];
+        return;
+    }
+
+    if (def.length === 1 && _PRIMITIVE_TYPES.has(def[0].type)) {
+        const child = def[0];
+        child.key = '_self';
+        child.properties = child.properties || {};
+        if (!child.properties.name) child.properties.name = '_self';
+        node.definition = [child];
+        return;
+    }
+
+    // Children represent fields of the array's item — wrap them in a _self Object.
+    node.definition = [{
+        key: '_self',
+        type: 'Object',
+        definition: def,
+        properties: {name: '_self'}
+    }];
+}
+
+// Recursive normalize: fill universal property defaults, compute dataPath, recurse.
+function _normalizeNode(node, parentSegs) {
+    const isSelf = node.key === '_self';
+    const segs = isSelf ? [...parentSegs, '[#]'] : [...parentSegs, node.key];
+    const dataPath = segs.join('.').replace(/\.\[#\]/g, '[#]');
+
+    node.properties = node.properties || {};
+    const props = node.properties;
+
+    // Universal defaults present on every field in the working sample.
+    if (!('fieldLength' in props)) props.fieldLength = 10;
+    if (!('paddingChar' in props)) props.paddingChar = ' ';
+    if (!('paddingPosition' in props)) props.paddingPosition = 'suffix';
+    if (!props._typeChanged) props._typeChanged = node.type;
+
+    // Primitives carry an explicit default null when not set.
+    if (_PRIMITIVE_TYPES.has(node.type)) {
+        if (!('default' in props)) props.default = null;
+    }
+
+    // Date carries timezone metadata.
+    if (node.type === 'Date') {
+        if (!('defaultTimezone' in props)) props.defaultTimezone = 'zulu';
+        if (!('supportedTimezones' in props)) props.supportedTimezones = [];
+    }
+
+    // Computed paths are single source of truth — overwrite whatever LLM sent.
+    props.dataPath = dataPath;
+    props.dataPathSegs = segs;
+
+    if (node.type === 'Array') {
+        _wrapArrayChildren(node);
+    }
+    if (Array.isArray(node.definition)) {
+        for (const child of node.definition) {
+            _normalizeNode(child, segs);
+        }
+    }
+}
+
+// _id field gets the full property set the platform expects on top-level ID.
+function _normalizeIdField(idNode) {
+    idNode.properties = idNode.properties || {};
+    const e = idNode.properties;
+    idNode.properties = {
+        label: e.label ?? null,
+        readonly: e.readonly ?? false,
+        errorMessage: e.errorMessage ?? null,
+        name: e.name ?? 'ID',
+        required: e.required ?? false,
+        disabled: e.disabled ?? false,
+        fieldLength: e.fieldLength ?? 10,
+        paddingChar: e.paddingChar ?? ' ',
+        paddingPosition: e.paddingPosition ?? 'suffix',
+        _description: e._description ?? null,
+        _typeChanged: 'id',
+        _isParrentArray: e._isParrentArray ?? null,
+        _isGrpParentArray: e._isGrpParentArray ?? null,
+        _detailedType: e._detailedType ?? '',
+        dataPath: '_id',
+        dataPathSegs: ['_id']
+    };
+}
+
+// Top-level normalize entrypoint — first field must be _id, rest pass through _normalizeNode.
+function _normalizeServiceDefinition(definition) {
+    if (!Array.isArray(definition) || definition.length === 0) return;
+    for (let i = 0; i < definition.length; i++) {
+        const node = definition[i];
+        if (i === 0 && node.key === '_id') {
+            _normalizeIdField(node);
+        } else {
+            _normalizeNode(node, []);
+        }
+    }
+}
+
+// Inject `payload.role` — the platform's role configuration containing the three
+// standard roles (No Access / Manage / View) with freshly generated IDs, plus a
+// `fields` permission map mirroring `definition`. Skips if `payload.role` is already set.
+function _ensureRolesAndFields(payload) {
+    if (payload.role && Array.isArray(payload.role.roles) && payload.role.fields) return null;
+
+    const rid = (prefix) => `${prefix}${crypto.randomInt(1_000_000_000, 9_999_999_999)}`;
+
+    const roles = [
+        {
+            noAccessRole: true,
+            id: rid('PNA_'),
+            name: 'No Access',
+            operations: [],
+            description: 'This role removes all access to the record'
+        },
+        {
+            manageRole: true,
+            id: rid('P'),
+            name: 'Manage',
+            operations: [{method: 'POST'}, {method: 'PUT'}, {method: 'DELETE'}, {method: 'GET'}],
+            description: 'This role entitles an authorized user to create, update or delete a record'
+        },
+        {
+            viewRole: true,
+            id: rid('P'),
+            name: 'View',
+            operations: [{method: 'GET'}],
+            description: 'This role entitles an authorized user to view the record'
+        }
+    ];
+
+    const permMap = {};
+    for (const r of roles) permMap[r.id] = 'R';
+    const fields = _buildFields(payload.definition || [], permMap);
+
+    payload.role = {roles, fields};
+
+    return {
+        injected: true,
+        roleIds: roles.map(r => ({name: r.name, id: r.id}))
+    };
+}
+
+function _buildFields(definition, permMap) {
+    const out = {};
+    for (const field of definition) {
+        if (!field || !field.key) continue;
+        if (field.type === 'Object' && Array.isArray(field.definition)) {
+            out[field.key] = _buildFields(field.definition, permMap);
+        } else {
+            out[field.key] = {_t: field.type, _p: permMap};
+        }
+    }
+    return out;
+}
+
+// Auto-fill default connectors on a data service create payload if missing.
+// Returns null if the user already supplied both, otherwise an object describing what was filled.
+async function _ensureConnectors(payload, dnioClient, appName) {
+    payload.connectors = payload.connectors || {};
+    const needsData = !payload.connectors.data?._id;
+    const needsFile = !payload.connectors.file?._id;
+    if (!needsData && !needsFile) return null;
+
+    const connectors = await dnioClient.connectors.list(appName);
+    const list = Array.isArray(connectors) ? connectors : [];
+    const pickDefault = (category) =>
+        list.find(c => c.category === category && c.options?.default && c.options?.isValid !== false)
+        || list.find(c => c.category === category);
+
+    const filled = {};
+    if (needsData) {
+        const db = pickDefault('DB');
+        if (!db) throw new Error('No DB connector available in this app — run list_connectors to inspect.');
+        payload.connectors.data = {_id: db._id, options: {}};
+        filled.data = {_id: db._id, name: db.name, type: db.type};
+    }
+    if (needsFile) {
+        const storage = pickDefault('STORAGE');
+        if (!storage) throw new Error('No STORAGE connector available in this app — run list_connectors to inspect.');
+        payload.connectors.file = {_id: storage._id};
+        filled.file = {_id: storage._id, name: storage.name, type: storage.type};
+    }
+    return filled;
+}
+
+module.exports = function registerServicesTools({server, dnioClient, registry, userContext}) {
+    server.registerTool(
+        'get_data_service_spec',
+        {
+            title: 'Get Data Service Creation Spec',
+            description: 'Returns the schema spec for creating a data service — field types, hook formats, workflow config options, and a full example payload. MUST be called before create_data_service.',
+            inputSchema: {},
+            annotations: {readOnlyHint: true, idempotentHint: true}
+        },
+        async () => {
+            return {
+                content: [{
+                    type: 'text',
+                    text: JSON.stringify(DATA_SERVICE_CREATION_SPEC, null, 2)
+                }]
+            };
+        }
+    );
+
+    server.registerTool(
+        'create_data_service',
+        {
+            title: 'Create Data Service',
+            description: `Create a new data service. The full creation grammar is in get_data_service_spec — fetch it for nuance — but the critical rules are inlined here so you don't need a round-trip first:
+
+NAME RULES (platform-enforced; tool pre-validates and rejects on mismatch):
+  - 2–40 characters, must START with a letter.
+  - Allowed: letters, digits, underscore. NO hyphens, NO spaces, NO other special chars.
+  - Convention: camelCase (e.g. 'companyEmployees') or snake_case ('company_employees').
+  - 'company-employees' / 'Company Employees' / '1_employees' will be rejected.
+
+DEFINITION REQUIREMENTS:
+  - First entry MUST be the _id field: { key: '_id', type: 'String', prefix: '<3-letter-prefix>', counter: 1001, properties: { name: 'ID', fieldLength: 10, _typeChanged: 'id' } }.
+  - Every field's properties MUST include _typeChanged (= field.type, except _id which uses 'id') and may include _description.
+  - Primitive variant flags (live in properties): richText: true, email: true, enum: [...], precision: <int>, currency: true, dateType: 'date'|'datetime-local'.
+  - Object: nested 'definition' array with child fields.
+  - Array: nested 'definition' array describing the item schema.
+
+AUTO-INJECTED BY THIS TOOL (do not bother sending — they will be overridden):
+  - 'app' = currently selected app.
+  - 'connectors' = platform default DB + Storage if absent.
+  - 'role' = standard No Access / Manage / View roles + per-field permission map if absent.
+
+Pass everything else (definition, hooks, workflowConfig, stateModel, defaults) per the spec. On 'Name is invalid' platform errors, check the rule above first.`,
+            inputSchema: {
+                data: z.string().describe('JSON payload matching the creation spec from get_data_service_spec')
+            },
+            annotations: {destructiveHint: false, idempotentHint: false}
+        },
+        async (params) => {
+            if (!registry.selectedApp) {
+                return {content: [{type: 'text', text: 'No app selected. Use list_apps → select_app first.'}], isError: true};
+            }
+            try {
+                const payload = JSON.parse(params.data);
+
+                // Pre-validate name BEFORE platform call — surface clear hint on common errors.
+                const nameError = _validateServiceName(payload.name);
+                if (nameError) {
+                    return toolError(`Invalid 'name': ${nameError}`, new Error('client-side validation'));
+                }
+
+                payload.app = registry.selectedApp;
+
+                // Normalize definition: fill universal property defaults, wrap Array children
+                // in _self, compute dataPath/dataPathSegs. Required for the platform to accept.
+                _normalizeServiceDefinition(payload.definition);
+
+                dnioClient.setToken(userContext.token);
+
+                const autoFilled = await _ensureConnectors(payload, dnioClient, registry.selectedApp);
+                const rolesInfo = _ensureRolesAndFields(payload);
+                const result = await dnioClient.services.create(registry.selectedApp, payload);
+
+                const response = {result};
+                if (autoFilled) {
+                    response.connectorsAutoFilled = autoFilled;
+                }
+                if (rolesInfo) {
+                    response.rolesAutoFilled = rolesInfo;
+                }
+                return {content: [{type: 'text', text: JSON.stringify(response, null, 2)}]};
+            } catch (error) {
+                return toolError('Failed to create data service', error);
+            }
+        }
+    );
+
+    server.registerTool(
+        'get_data_service',
+        {
+            title: 'Get Data Service',
+            description: `Get details of a data service by ID. Use 'select' to fetch only needed fields (comma-separated).
+Common select patterns:
+- Overview: "_id,name,description,status,attributeCount,version"
+- Schema: "_id,name,definition,schemaFree"
+- Hooks: "_id,name,preHooks,workflowHooks"
+- Workflow: "_id,name,workflowConfig,stateModel"
+- Full edit: "_id,name,description,definition,preHooks,workflowHooks,workflowConfig,stateModel,schemaFree,permanentDeleteData,disableInsights,enableSearchIndex,allowedFileTypes"
+Use draft=true to get the unsaved draft version.`,
+            inputSchema: {
+                serviceId: z.string().min(1).describe('Service ID (e.g., SRVC13120)'),
+                select: z.string().optional().describe('Comma-separated fields to return. Omit to get all fields.'),
+                draft: z.boolean().optional().describe('If true, returns the draft version. Default: false')
+            },
+            annotations: {readOnlyHint: true, idempotentHint: true}
+        },
+        async (params) => {
+            try {
+                dnioClient.setToken(userContext.token);
+                const result = await dnioClient.services.get(
+                    registry.selectedApp,
+                    params.serviceId,
+                    {draft: params.draft || false, select: params.select}
+                );
+                return {content: [{type: 'text', text: JSON.stringify(result, null, 2)}]};
+            } catch (error) {
+                return toolError(`Failed to get data service ${params.serviceId}`, error);
+            }
+        }
+    );
+
+    server.registerTool(
+        'list_data_services',
+        {
+            title: 'List Data Services',
+            description: 'List all data services in the selected app. Use select to limit fields returned.',
+            inputSchema: {
+                select: z.string().optional().describe('Comma-separated fields. Default: "_id,name,description,status,attributeCount"'),
+                statusFilter: z.enum(['Active', 'Pending', 'Draft', 'Stopped']).optional().describe('Filter by status. Omit for all.')
+            },
+            annotations: {readOnlyHint: true, idempotentHint: true}
+        },
+        async (params) => {
+            try {
+                dnioClient.setToken(userContext.token);
+                const filter = params.statusFilter ? {status: params.statusFilter} : {};
+                const select = params.select || '_id,name,description,status,attributeCount';
+                const result = await dnioClient.services.list(registry.selectedApp, {filter, select});
+                return {content: [{type: 'text', text: JSON.stringify(result, null, 2)}]};
+            } catch (error) {
+                return toolError('Failed to list data services', error);
+            }
+        }
+    );
+
+    server.registerTool(
+        'update_data_service',
+        {
+            title: 'Update Data Service',
+            description: 'Update an existing data service. Call get_data_service first to get the current state, modify what you need, and send the full payload back. After updating, call deploy_data_service to apply changes.',
+            inputSchema: {
+                serviceId: z.string().min(1).describe('Service ID (e.g., SRVC13120)'),
+                data: z.string().describe('Full JSON payload with updated fields. Must include the complete definition array, not just changed fields.')
+            },
+            annotations: {destructiveHint: true, idempotentHint: false}
+        },
+        async (params) => {
+            if (!registry.selectedApp) {
+                return {content: [{type: 'text', text: 'No app selected. Use list_apps → select_app first.'}], isError: true};
+            }
+            try {
+                const payload = JSON.parse(params.data);
+                payload.app = registry.selectedApp;
+
+                // Same normalization as create — keeps property defaults and dataPaths in sync.
+                _normalizeServiceDefinition(payload.definition);
+
+                dnioClient.setToken(userContext.token);
+                const result = await dnioClient.services.update(
+                    registry.selectedApp,
+                    params.serviceId,
+                    payload
+                );
+                return {content: [{type: 'text', text: JSON.stringify(result, null, 2)}]};
+            } catch (error) {
+                return toolError(`Failed to update data service ${params.serviceId}`, error);
+            }
+        }
+    );
+
+    server.registerTool(
+        'deploy_data_service',
+        {
+            title: 'Deploy Data Service',
+            description: 'Deploy a data service after creation or update. This starts the Kubernetes deployment. Must be called after create_data_service or update_data_service to make changes live.',
+            inputSchema: {
+                serviceId: z.string().min(1).describe('Service ID to deploy (e.g., SRVC13120)')
+            },
+            annotations: {destructiveHint: false, idempotentHint: true}
+        },
+        async (params) => {
+            try {
+                dnioClient.setToken(userContext.token);
+                const result = await dnioClient.services.deploy(registry.selectedApp, params.serviceId);
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            serviceId: params.serviceId,
+                            status: 'Deployment initiated',
+                            result
+                        }, null, 2)
+                    }]
+                };
+            } catch (error) {
+                return toolError(`Failed to deploy data service ${params.serviceId}`, error);
+            }
+        }
+    );
+
+    server.registerTool(
+        'start_stop_data_service',
+        {
+            title: 'Start or Stop Data Service',
+            description: 'Start or stop a deployed data service.',
+            inputSchema: {
+                serviceId: z.string().min(1).describe('Service ID (e.g., SRVC13120)'),
+                action: z.enum(['start', 'stop']).describe('Whether to start or stop the service')
+            },
+            annotations: {destructiveHint: true, idempotentHint: true}
+        },
+        async (params) => {
+            try {
+                dnioClient.setToken(userContext.token);
+                const result = await dnioClient.services.startStop(
+                    registry.selectedApp,
+                    params.serviceId,
+                    {start: params.action === 'start'}
+                );
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({serviceId: params.serviceId, action: params.action, result}, null, 2)
+                    }]
+                };
+            } catch (error) {
+                return toolError(`Failed to ${params.action} data service ${params.serviceId}`, error);
+            }
+        }
+    );
+};

package/src/tools/user-groups.js

@@ -0,0 +1,5 @@
+'use strict';
+
+module.exports = function registerUserGroupsTools(_ctx) {
+    // TODO: register DNIO user groups tools
+};

package/src/tools/users.js

@@ -0,0 +1,5 @@
+'use strict';
+
+module.exports = function registerUsersTools(_ctx) {
+    // TODO: register DNIO users tools
+};

package/src/utils/constants.js

@@ -0,0 +1,135 @@
+const DATA_SERVICE_CREATION_SPEC = {
+    description: "Spec for creating a data service. Only include fields listed here.",
+
+    connectors: {
+        description: "Required. Specifies WHERE the data service stores its records and uploaded files. Call 'list_connectors' first to fetch available connectors and confirm with the user which to use. If the user does not specify, omit this field — create_data_service will auto-attach the platform default DB + Storage connectors.",
+        shape: {
+            data: {
+                _id: "Connector _id with category=DB (e.g. 'CON3112' MongoDB). REQUIRED.",
+                options: "Empty object {} unless the connector requires extra options."
+            },
+            file: {
+                _id: "Connector _id with category=STORAGE (e.g. 'CON3113' GridFS). REQUIRED."
+            }
+        },
+        example: {
+            data: {_id: "CON3112", options: {}},
+            file: {_id: "CON3113"}
+        }
+    },
+
+    fieldTypes: {
+        String: {
+            properties: ["name", "_typeChanged", "_description", "required", "default", "email", "richText", "enum", "pattern", "minLength", "maxLength", "fieldLength"],
+            variants: {
+                Text: "(no extra flag)",
+                LongText: "richText: true",
+                RichText: "richText: true",
+                Email: "email: true",
+                ListOfValues: "enum: ['A','B','C']"
+            }
+        },
+        Number: {
+            properties: ["name", "_typeChanged", "_description", "required", "default", "precision", "enum", "currency", "min", "max", "fieldLength"],
+            variants: {
+                Number: "precision: <int>",
+                ListOfNumber: "precision: <int>, enum: [1,2,3]",
+                Currency: "currency: true"
+            }
+        },
+        Boolean: {properties: ["name", "_typeChanged", "_description", "required", "default"]},
+        Date: {
+            properties: ["name", "_typeChanged", "_description", "required", "default", "dateType"],
+            variants: {
+                DateOnly: "dateType: 'date'",
+                DateTime: "dateType: 'datetime-local'"
+            }
+        },
+        Object: {properties: ["name", "_typeChanged", "_description"], note: "Contains nested 'definition' array with child fields"},
+        Array: {properties: ["name", "_typeChanged", "_description"], note: "Set type of items inside 'definition'"}
+    },
+
+    sharedPropertyNote: "Two property keys are shared across data-format AND data-service field definitions and MUST always be present in 'properties': '_typeChanged' (stored type, same as field.type — except _id field which uses '_typeChanged: \"id\"') and '_description' (free-form description; NOT 'description'). Variant flags (richText, email, enum, currency, dateType) work identically on both surfaces.",
+
+    idField: {
+        note: "First field must always be _id with prefix. Counter starts at 1001.",
+        example: {
+            key: "_id", type: "String", prefix: "USR", suffix: null, padding: null, counter: 1001,
+            properties: {name: "ID", fieldLength: 10, _typeChanged: "id"}
+        }
+    },
+
+    hooks: {
+        preHooks: {
+            description: "Executed before save. Array of hook objects.",
+            example: {name: "ValidateData", url: "https://example.com/webhook", type: "external", failMessage: ""}
+        },
+        workflowHooks: {
+            description: "Post-workflow hooks triggered on submit/approve/reject/rework/discard.",
+            triggers: ["submit", "approve", "reject", "rework", "discard"],
+            example: {name: "NotifyOnSubmit", url: "https://example.com/webhook", type: "external"}
+        }
+    },
+
+    stateModel: {
+        description: "Optional state machine on a field. Set enabled:true and define states.",
+        example: {
+            attribute: "status",
+            enabled: true,
+            initialStates: ["New"],
+            states: {New: ["Active", "Inactive"], Active: ["Inactive"]}
+        }
+    },
+
+    workflowConfig: {
+        description: "Maker-checker approval workflow.",
+        example: {enabled: true, makerCheckers: [{steps: [{name: "Approve", approvers: []}]}]}
+    },
+
+    defaults: {
+        schemaFree: false,
+        permanentDeleteData: true,
+        disableInsights: false,
+        enableSearchIndex: false,
+        allowedFileTypes: ["jpeg", "jpg", "png", "pdf", "csv", "xlsx", "json", "xml", "txt"]
+    },
+
+    examplePayload: {
+        name: "studentRecord",
+        description: "Stores student information for the school",
+        app: "<app-name>",
+        connectors: {
+            data: {_id: "CON3112", options: {}},
+            file: {_id: "CON3113"}
+        },
+        definition: [
+            {
+                key: "_id",
+                type: "String",
+                prefix: "STU",
+                suffix: null,
+                padding: null,
+                counter: 1001,
+                properties: {name: "ID", fieldLength: 10, _typeChanged: "id"}
+            },
+            {key: "fullName", type: "String", properties: {name: "fullName", required: true, _typeChanged: "String", _description: "Student full name"}},
+            {key: "email", type: "String", properties: {name: "email", email: true, _typeChanged: "String", _description: "Contact email"}},
+            {key: "grade", type: "Number", properties: {name: "grade", precision: 0, _typeChanged: "Number", _description: "Current grade"}},
+            {
+                key: "address", type: "Object", definition: [
+                    {key: "city", type: "String", properties: {name: "city", _typeChanged: "String"}},
+                    {key: "zip", type: "String", properties: {name: "zip", _typeChanged: "String"}}
+                ], properties: {name: "address", _typeChanged: "Object"}
+            }
+        ],
+        preHooks: [],
+        workflowHooks: {postHooks: {submit: [], discard: [], approve: [], rework: [], reject: []}},
+        stateModel: {attribute: "", initialStates: [], enabled: false},
+        workflowConfig: {enabled: false, makerCheckers: []}
+    }
+};
+
+
+module.exports = {
+    DATA_SERVICE_CREATION_SPEC
+}