mcp-creatio 0.4.1 → 0.6.0

package/dist/server/mcp/tools-data.d.ts

@@ -5,40 +5,94 @@ export declare const getCurrentUserInfoDescriptor: {
     description: string;
     inputSchema: Record<string, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
 };
-export declare const readInput: z.ZodObject<{
+/** Which optional read params the active CRUD backend supports (mirrors CrudCapabilities). */
+export interface ReadCapabilities {
+    rawFilter: boolean;
+    expand: boolean;
+}
+export declare function buildReadInputShape(caps: ReadCapabilities): {
+    expand?: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    filter?: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
     entity: z.ZodString;
-    filter: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodString>>;
     filters: z.ZodOptional<z.ZodObject<{
         all: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
             field: z.ZodString;
             op: z.ZodEnum<{
                 eq: "eq";
+                ne: "ne";
+                gt: "gt";
+                ge: "ge";
+                lt: "lt";
+                le: "le";
                 contains: "contains";
                 startswith: "startswith";
                 endswith: "endswith";
+            }>;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+        }, z.core.$strip>, z.ZodObject<{
+            field: z.ZodString;
+            in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        }, z.core.$strip>]>>>;
+        any: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            field: z.ZodString;
+            op: z.ZodEnum<{
+                eq: "eq";
                 ne: "ne";
                 gt: "gt";
                 ge: "ge";
                 lt: "lt";
                 le: "le";
+                contains: "contains";
+                startswith: "startswith";
+                endswith: "endswith";
             }>;
             value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
         }, z.core.$strip>, z.ZodObject<{
             field: z.ZodString;
             in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
         }, z.core.$strip>]>>>;
-        any: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+    }, z.core.$strip>>;
+    select: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    orderBy: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+    top: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    skip: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    count: z.ZodOptional<z.ZodBoolean>;
+};
+export declare function buildReadInput(caps: ReadCapabilities): z.ZodObject<{
+    expand?: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    filter?: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+    entity: z.ZodString;
+    filters: z.ZodOptional<z.ZodObject<{
+        all: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
             field: z.ZodString;
             op: z.ZodEnum<{
                 eq: "eq";
+                ne: "ne";
+                gt: "gt";
+                ge: "ge";
+                lt: "lt";
+                le: "le";
                 contains: "contains";
                 startswith: "startswith";
                 endswith: "endswith";
+            }>;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+        }, z.core.$strip>, z.ZodObject<{
+            field: z.ZodString;
+            in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        }, z.core.$strip>]>>>;
+        any: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            field: z.ZodString;
+            op: z.ZodEnum<{
+                eq: "eq";
                 ne: "ne";
                 gt: "gt";
                 ge: "ge";
                 lt: "lt";
                 le: "le";
+                contains: "contains";
+                startswith: "startswith";
+                endswith: "endswith";
             }>;
             value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
         }, z.core.$strip>, z.ZodObject<{
@@ -46,12 +100,13 @@ export declare const readInput: z.ZodObject<{
             in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
         }, z.core.$strip>]>>>;
     }, z.core.$strip>>;
-    select: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodArray<z.ZodString>>>;
-    expand: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodArray<z.ZodString>>>;
-    orderBy: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodString>>;
+    select: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    orderBy: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
     top: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    skip: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    count: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
-export declare const readDescriptor: {
+export declare function buildReadDescriptor(caps: ReadCapabilities): {
     title: string;
     description: string;
     inputSchema: Record<string, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
@@ -225,4 +280,61 @@ export declare const callConfigurationServiceDescriptor: {
     description: string;
     inputSchema: Record<string, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
 };
+export declare const dataforgeSimilarTablesInput: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const dataforgeSimilarTablesDescriptor: {
+    title: string;
+    description: string;
+    inputSchema: Record<string, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+};
+export declare const dataforgeTableDetailsInput: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const dataforgeTableDetailsDescriptor: {
+    title: string;
+    description: string;
+    inputSchema: Record<string, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+};
+export declare const dataforgeTableRelationshipsInput: z.ZodObject<{
+    sourceTable: z.ZodString;
+    targetTable: z.ZodString;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    bidirectional: z.ZodOptional<z.ZodBoolean>;
+    skipDetails: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const dataforgeTableRelationshipsDescriptor: {
+    title: string;
+    description: string;
+    inputSchema: Record<string, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+};
+export declare const dataforgeLookupValuesInput: z.ZodObject<{
+    query: z.ZodString;
+    schemaName: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const dataforgeLookupValuesDescriptor: {
+    title: string;
+    description: string;
+    inputSchema: Record<string, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+};
+export declare const dataforgeStatusInput: z.ZodObject<{}, z.core.$strip>;
+export declare const dataforgeStatusDescriptor: {
+    title: string;
+    description: string;
+    inputSchema: Record<string, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+};
+export declare const globalSearchInput: z.ZodObject<{
+    query: z.ZodString;
+    entities: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    from: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const globalSearchDescriptor: {
+    title: string;
+    description: string;
+    inputSchema: Record<string, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+};
 //# sourceMappingURL=tools-data.d.ts.map

package/dist/server/mcp/tools-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools-data.d.ts","sourceRoot":"","sources":["../../../src/server/mcp/tools-data.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA0DxB,eAAO,MAAM,uBAAuB,gCAAyC,CAAC;AAE9E,eAAO,MAAM,4BAA4B;;;;CAuCvC,CAAC;AA+KH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAA2B,CAAC;AAElD,eAAO,MAAM,cAAc;;;;CAUzB,CAAC;AAsBH,eAAO,MAAM,WAAW;;;iBAA6B,CAAC;AAEtD,eAAO,MAAM,gBAAgB;;;;CAY3B,CAAC;AA0BH,eAAO,MAAM,WAAW;;;;iBAA6B,CAAC;AAEtD,eAAO,MAAM,gBAAgB;;;;CAS3B,CAAC;AAWH,eAAO,MAAM,WAAW;;;iBAA6B,CAAC;AAEtD,eAAO,MAAM,gBAAgB;;;;CAY3B,CAAC;AAEH,eAAO,MAAM,iBAAiB,gCAAe,CAAC;AAE9C,eAAO,MAAM,sBAAsB;;;;CAKjC,CAAC;AAUH,eAAO,MAAM,mBAAmB;;iBAAqC,CAAC;AAEtE,eAAO,MAAM,wBAAwB;;;;CAKnC,CAAC;AA0BH,eAAO,MAAM,mBAAmB;;;iBAAqC,CAAC;AAEtE,eAAO,MAAM,wBAAwB;;;;CAuCnC,CAAC;AAWH,eAAO,MAAM,qBAAqB;;iBAAuC,CAAC;AAE1E,eAAO,MAAM,0BAA0B;;;;CAKrC,CAAC;AA+CH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;iBAAuC,CAAC;AAE1E,eAAO,MAAM,0BAA0B;;;;CAKrC,CAAC;AAcH,eAAO,MAAM,wBAAwB;;iBAA0C,CAAC;AAEhF,eAAO,MAAM,6BAA6B;;;;CAYxC,CAAC;AASH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;iBAAiD,CAAC;AAE9F,eAAO,MAAM,oCAAoC;;;;CAK/C,CAAC;AAYH,eAAO,MAAM,wBAAwB;;iBAA0C,CAAC;AAEhF,eAAO,MAAM,6BAA6B;;;;CAKxC,CAAC;AA0BH,eAAO,MAAM,yBAAyB;;;;;iBAA2C,CAAC;AAElF,eAAO,MAAM,8BAA8B;;;;CAKzC,CAAC;AAWH,eAAO,MAAM,yBAAyB;;iBAA2C,CAAC;AAElF,eAAO,MAAM,8BAA8B;;;;CAKzC,CAAC;AAmBH,eAAO,MAAM,6BAA6B;;;;iBAA+C,CAAC;AAE1F,eAAO,MAAM,kCAAkC;;;;CAK7C,CAAC;AAWH,eAAO,MAAM,gCAAgC;;iBAAkD,CAAC;AAEhG,eAAO,MAAM,qCAAqC;;;;CAKhD,CAAC;AAiCH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;iBAA+C,CAAC;AAE1F,eAAO,MAAM,kCAAkC;;;;CAK7C,CAAC"}
+{"version":3,"file":"tools-data.d.ts","sourceRoot":"","sources":["../../../src/server/mcp/tools-data.ts"],"names":[],"mappings":"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"}

package/dist/server/mcp/tools-data.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.callConfigurationServiceDescriptor = exports.callConfigurationServiceInput = exports.deleteAdminOperationGranteeDescriptor = exports.deleteAdminOperationGranteeInput = exports.setAdminOperationGranteeDescriptor = exports.setAdminOperationGranteeInput = exports.deleteAdminOperationDescriptor = exports.deleteAdminOperationInput = exports.upsertAdminOperationDescriptor = exports.upsertAdminOperationInput = exports.refreshFeatureCacheDescriptor = exports.refreshFeatureCacheInput = exports.updateSysSettingDefinitionDescriptor = exports.updateSysSettingDefinitionInput = exports.setSysSettingsValueDescriptor = exports.setSysSettingsValueInput = exports.createSysSettingDescriptor = exports.createSysSettingInput = exports.querySysSettingsDescriptor = exports.querySysSettingsInput = exports.executeProcessDescriptor = exports.executeProcessInput = exports.describeEntityDescriptor = exports.describeEntityInput = exports.listEntitiesDescriptor = exports.listEntitiesInput = exports.deleteDescriptor = exports.deleteInput = exports.updateDescriptor = exports.updateInput = exports.createDescriptor = exports.createInput = exports.readDescriptor = exports.readInput = exports.getCurrentUserInfoDescriptor = exports.getCurrentUserInfoInput = void 0;
+exports.globalSearchDescriptor = exports.globalSearchInput = exports.dataforgeStatusDescriptor = exports.dataforgeStatusInput = exports.dataforgeLookupValuesDescriptor = exports.dataforgeLookupValuesInput = exports.dataforgeTableRelationshipsDescriptor = exports.dataforgeTableRelationshipsInput = exports.dataforgeTableDetailsDescriptor = exports.dataforgeTableDetailsInput = exports.dataforgeSimilarTablesDescriptor = exports.dataforgeSimilarTablesInput = exports.callConfigurationServiceDescriptor = exports.callConfigurationServiceInput = exports.deleteAdminOperationGranteeDescriptor = exports.deleteAdminOperationGranteeInput = exports.setAdminOperationGranteeDescriptor = exports.setAdminOperationGranteeInput = exports.deleteAdminOperationDescriptor = exports.deleteAdminOperationInput = exports.upsertAdminOperationDescriptor = exports.upsertAdminOperationInput = exports.refreshFeatureCacheDescriptor = exports.refreshFeatureCacheInput = exports.updateSysSettingDefinitionDescriptor = exports.updateSysSettingDefinitionInput = exports.setSysSettingsValueDescriptor = exports.setSysSettingsValueInput = exports.createSysSettingDescriptor = exports.createSysSettingInput = exports.querySysSettingsDescriptor = exports.querySysSettingsInput = exports.executeProcessDescriptor = exports.executeProcessInput = exports.describeEntityDescriptor = exports.describeEntityInput = exports.listEntitiesDescriptor = exports.listEntitiesInput = exports.deleteDescriptor = exports.deleteInput = exports.updateDescriptor = exports.updateInput = exports.createDescriptor = exports.createInput = exports.getCurrentUserInfoDescriptor = exports.getCurrentUserInfoInput = void 0;
+exports.buildReadInputShape = buildReadInputShape;
+exports.buildReadInput = buildReadInput;
+exports.buildReadDescriptor = buildReadDescriptor;
 const zod_1 = require("zod");
 const CRITICAL_WARNINGS = {
     FILTER_SELECT_SYNC: '⚠️ CRITICAL: When using $filter with $select:\n' +
@@ -15,6 +18,11 @@ const CRITICAL_WARNINGS = {
         "- String/Text fields: WITH single quotes! Example: Name eq 'John'\n" +
         "- Navigation properties: WITH single quotes! Example: Type/Name eq 'Employee'",
     TIME_CONVERSION: '⏰ TIME CONVERSION CRITICAL:\nWhen updating StartDate/DueDate, convert local time to UTC!',
+    LOOKUP_NAVIGATION: '🔗 FILTERING BY A LOOKUP (related record) — use NAVIGATION, not the scalar FK:\n' +
+        "- By name (best): Contact/Name eq 'Andrew Baker', Type/Name eq 'Employee'\n" +
+        '- By id: Contact/Id eq <guid>  (GUID, no quotes)\n' +
+        '- ❌ Do NOT filter the scalar `ContactId`/`OwnerId`/`AccountId` directly — Creatio OData 500s with "Column by path XxxId not found in schema".\n' +
+        '- The primary key `Id eq <guid>` DOES work as-is (it is a real column, not a lookup).',
 };
 const DATA_TYPES_DESC = {
     BASIC: 'DATA TYPES:\n' +
@@ -89,17 +97,18 @@ const baseCondition = zod_1.z.object({
     field: zod_1.z
         .string()
         .min(1)
-        .describe('Field to filter on. For lookups use navigation like Type/Name; for GUID columns use TypeId or Id.'),
+        .describe('Field to filter on. To filter by a linked record, use navigation: by name `Contact/Name` / `Type/Name`, or by id `Contact/Id`. ' +
+        'A scalar lookup FK (`ContactId`, `OwnerId`, `AccountId`) with a GUID value is auto-rewritten to `<Lookup>/Id`. The primary key is `Id`.'),
 });
 const compareCondition = baseCondition.extend({
     op: op.describe('Comparison operators: eq, ne, gt, ge, lt, le, contains, startswith, endswith.'),
-    value: value.describe("Value to compare with. Strings are escaped; GUIDs formatted as guid'...'."),
+    value: value.describe('Value to compare with. GUIDs are emitted unquoted for Id/lookup paths; other strings are quoted/escaped automatically.'),
 });
 const inCondition = baseCondition.extend({
     in: zod_1.z
         .array(zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean()]))
         .min(1)
-        .describe("Set of values (IN emulation with OR). GUIDs auto-formatted to guid'...' when applicable."),
+        .describe('Set of values (expanded to an OR group). Lookup FK GUIDs are auto-navigated.'),
 });
 const condition = zod_1.z.union([compareCondition, inCondition]);
 const filtersShape = zod_1.z
@@ -108,18 +117,18 @@ const filtersShape = zod_1.z
         .array(condition)
         .min(1)
         .optional()
-        .describe('All conditions (AND). Example: [{ field:"TypeId", op:"eq", value:"<GUID>" }]'),
+        .describe('All conditions (AND). Example: [{ field:"Stage/Name", op:"eq", value:"Presentation" }]'),
     any: zod_1.z
         .array(condition)
         .min(1)
         .optional()
         .describe('Any condition (OR). Example: [{ field:"Type/Name", op:"eq", value:"Employee" }, { field:"Type/Name", op:"eq", value:"Manager" }]'),
 })
-    .describe('Structured filters - alternative to raw $filter. Automatically handles OData syntax, escaping, etc.\n' +
-    'Tip: For lookups, prefer navigation properties (Field/Name) over IDs for better readability.\n\n' +
+    .describe('Structured filters - alternative to raw $filter. Automatically handles OData syntax, escaping, GUID formatting, and lookup navigation.\n' +
+    'Filter by a linked record via navigation (Contact/Name, Contact/Id) — or pass a scalar `ContactId` GUID and it is auto-rewritten to `Contact/Id`.\n\n' +
     'Examples:\n' +
-    '- Lookup by name: { all:[{ field:"Type/Name", op:"eq", value:"Employee" }] }\n' +
-    '- By GUID: { all:[{ field:"TypeId", op:"eq", value:"60733efc-..." }] }\n' +
+    '- Lookup by name: { all:[{ field:"Contact/Name", op:"eq", value:"Andrew Baker" }] }\n' +
+    '- Lookup by id: { all:[{ field:"ContactId", op:"eq", value:"60733efc-..." }] }\n' +
     '- Multiple AND: { all:[{ field:"IsActive", op:"eq", value:true }, { field:"Name", op:"contains", value:"John" }] }\n' +
     '- Multiple OR: { any:[{ field:"Status/Name", op:"eq", value:"Active" }, { field:"Status/Name", op:"eq", value:"Pending" }] }');
 const readInputShape = {
@@ -129,33 +138,31 @@ const readInputShape = {
         .describe('Creatio OData entity set to query (e.g., Contact, Account, Activity). Tip: call "list-entities" first, then "describe-entity" to confirm fields before reading.'),
     filter: zod_1.z
         .preprocess((v) => (typeof v === 'string' && v.trim() === '' ? undefined : v), zod_1.z.string().min(1).optional())
-        .describe("OData $filter clause. Use single quotes for strings and escape embedded ' as ''.\n" +
-        'Operators: eq, ne, gt, ge, lt, le, and, or, not, contains, startswith, endswith.\n\n' +
+        .describe('⚠️ OData backend ONLY — ignored when the DataService backend is active (the default). ' +
+        'Prefer the structured `filters` parameter, which works on both backends.\n' +
+        "OData $filter clause. Use single quotes for strings and escape embedded ' as ''.\n" +
+        'Operators: eq, ne, gt, ge, lt, le, and, or, not. Functions: contains(F,\'v\'), startswith(F,\'v\'), endswith(F,\'v\'), length(F), day(F).\n\n' +
         CRITICAL_WARNINGS.GUID_NO_QUOTES +
         '\n\n' +
-        '⚠️ IMPORTANT: When using $filter with $select:\n' +
-        '- Include ALL fields from filter in $select if possible\n' +
-        '- Example: filter by AccountId? Include AccountId in select array\n' +
-        '- Creatio may fail if filtered field is not in select list\n\n' +
+        CRITICAL_WARNINGS.LOOKUP_NAVIGATION +
+        '\n\n' +
         'Examples:\n' +
-        '- By GUID: AccountId eq 8ecab4a1-0ca3-4515-9399-efe0a19390bd\n' +
+        '- By primary Id: Id eq 8ecab4a1-0ca3-4515-9399-efe0a19390bd\n' +
+        "- Lookup by name: Contact/Name eq 'Andrew Baker' (RECOMMENDED)\n" +
+        '- Lookup by id (NAVIGATION): Contact/Id eq 8ecab4a1-0ca3-4515-9399-efe0a19390bd\n' +
         "- Text search: contains(Name,'Acme')\n" +
-        "- Multiple: contains(Name,'Baker') and IsActive eq true\n" +
-        "- Lookup by name: Type/Name eq 'Employee' (RECOMMENDED!)\n\n" +
-        '💡 BEST PRACTICE: Use structured filters parameter instead of raw $filter - it handles syntax automatically!'),
+        "- Multiple: contains(Name,'Baker') and Type/Name eq 'Employee'\n\n" +
+        '💡 BEST PRACTICE: prefer the structured `filters` parameter — it auto-rewrites lookup `XxxId` filters to the required `Xxx/Id` navigation for you.'),
     filters: filtersShape
         .optional()
-        .describe('Structured filters (alternative to raw $filter). Automatically handles proper OData syntax including GUID formatting.\n' +
-        'System automatically removes quotes from GUID values for Id fields.\n\n' +
-        '⚠️ IMPORTANT: When using filters with select parameter:\n' +
-        '- ALWAYS include filtered fields in select array\n' +
-        '- Creatio OData may fail if field is in filter but not in select\n\n' +
+        .describe('Structured filters (alternative to raw $filter). Handles OData syntax, GUID formatting, and lookup navigation automatically.\n\n' +
+        CRITICAL_WARNINGS.LOOKUP_NAVIGATION +
+        '\n(With this structured parameter you can pass either form — a `XxxId` field with a GUID value is auto-rewritten to `Xxx/Id`.)\n\n' +
         'Examples:\n' +
-        "- By GUID: { all:[{ field:'AccountId', op:'eq', value:'60733efc-f36b-1410-a883-16d83cab0980' }] }\n" +
-        "- By lookup name: { all:[{ field:'Type/Name', op:'eq', value:'Employee' }] } (RECOMMENDED!)\n" +
+        "- Lookup by name: { all:[{ field:'Contact/Name', op:'eq', value:'Andrew Baker' }] } (RECOMMENDED)\n" +
+        "- Lookup by id: { all:[{ field:'ContactId', op:'eq', value:'60733efc-f36b-1410-a883-16d83cab0980' }] }  // becomes Contact/Id eq <guid>\n" +
         "- Multiple AND: { all:[{ field:'IsActive', op:'eq', value:true }, { field:'Name', op:'contains', value:'John' }] }\n" +
-        "- Multiple OR: { any:[{ field:'StatusId', op:'eq', value:'guid1' }, { field:'StatusId', op:'eq', value:'guid2' }] }\n\n" +
-        '💡 If filtering by AccountId, ContactId, etc - include that field in select!'),
+        "- Multiple OR: { any:[{ field:'Stage/Name', op:'eq', value:'Presentation' }, { field:'Stage/Name', op:'eq', value:'Negotiation' }] }"),
     select: zod_1.z
         .preprocess((v) => (Array.isArray(v) && v.length === 0 ? undefined : v), zod_1.z.array(zod_1.z.string()).optional())
         .describe('Fields to return from the main entity. Strongly recommended for performance.\n\n' +
@@ -171,7 +178,9 @@ const readInputShape = {
         "Use 'describe-entity' to discover available field names."),
     expand: zod_1.z
         .preprocess((v) => (Array.isArray(v) && v.length === 0 ? undefined : v), zod_1.z.array(zod_1.z.string()).optional())
-        .describe('Navigation properties to expand (load related entities in one request).\n\n' +
+        .describe('⚠️ OData backend ONLY — ignored when the DataService backend is active (the default). ' +
+        'With DataService, read related fields by dotted column path in `select`/`filters` (e.g. `Account.Name`).\n\n' +
+        'Navigation properties to expand (load related entities in one request).\n\n' +
         'This is the OData $expand parameter. Loads related entity objects.\n' +
         'Very useful to get complete data without multiple requests!\n\n' +
         '✅ HOW TO USE:\n' +
@@ -206,22 +215,59 @@ const readInputShape = {
     top: zod_1.z.coerce
         .number()
         .int()
-        .positive()
+        .min(0)
         .max(1000)
         .optional()
-        .describe('Max rows to return (suggest 25\u2013200 for responsiveness).'),
+        .describe('Max rows to return ($top). Defaults to 50 when omitted (so results are never unbounded); raise it or paginate with skip for more. Use top:0 with count:true for a count-only query. Suggest 25\u2013200.'),
+    skip: zod_1.z.coerce
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe('Offset pagination ($skip): skip this many matching rows before returning. ' +
+        'Combine with top to page, e.g. page 3 of 25 \u2192 skip:50, top:25. ' +
+        'Pair with a stable orderBy so pages do not overlap.'),
+    count: zod_1.z
+        .boolean()
+        .optional()
+        .describe('When true, also return the TOTAL number of matching records ($count=true), ignoring top/skip. ' +
+        'The response shape becomes { total, value } instead of a bare array.\n' +
+        '\ud83d\udca1 For a COUNT-ONLY question ("how many opportunities does X have"), set count:true AND top:0 \u2014 ' +
+        'you get { total: N, value: [] } in one request instead of fetching rows. ' +
+        'Filter the same way as a normal read (e.g. lookups via ContactId \u2192 auto Contact/Id).'),
 };
-exports.readInput = zod_1.z.object(readInputShape);
-exports.readDescriptor = makeToolDescriptor({
-    title: 'Read records in Creatio',
-    description: 'Query Creatio records. Workflow: 1) list-entities 2) describe-entity 3) read with select, optional expand, filters/orderBy/top. ' +
-        'Key params: select (fields to return), filters or filter (conditions), expand (related entities), orderBy (sorting), top (limit). ' +
-        'Always include fields used in filters in select when select is provided. Use structured filters over raw $filter when possible. ' +
-        "Use expand to load related entities in one request (e.g. expand:['Account']). " +
-        'For date/time filtering see /datetime-guide prompt. For Contact/Owner filtering see /contactid-guide prompt. ' +
-        "Example: entity:'Order', select:['Id','Number','Amount','AccountId'], filters:{ all:[{ field:'AccountId', op:'eq', value:'<guid>' }] }, expand:['Account'], orderBy:'Amount desc', top:10",
-    inputShape: readInputShape,
-});
+// Split the full read shape into the always-portable fields and the OData-only escape
+// hatches (raw `filter` string, `expand`), so each backend registers only the parameters it
+// actually honors instead of advertising dead options.
+const { filter: odataFilterField, expand: odataExpandField, ...neutralReadShape } = readInputShape;
+function buildReadInputShape(caps) {
+    return {
+        ...neutralReadShape,
+        ...(caps.rawFilter ? { filter: odataFilterField } : {}),
+        ...(caps.expand ? { expand: odataExpandField } : {}),
+    };
+}
+function buildReadInput(caps) {
+    return zod_1.z.object(buildReadInputShape(caps));
+}
+function buildReadDescriptor(caps) {
+    const advanced = caps.rawFilter
+        ? 'Advanced (OData backend): a raw `filter` string and `expand` are also available. '
+        : '';
+    return makeToolDescriptor({
+        title: 'Read records in Creatio',
+        description: 'Query Creatio records. Workflow: 1) list-entities 2) describe-entity 3) read with select, filters, orderBy, top. ' +
+            'Key params: select (fields to return), filters (conditions — recommended), orderBy (sorting), top (limit), skip (pagination offset), count (return total). ' +
+            'Always include fields used in filters in select when select is provided. ' +
+            'Filter related records via navigation (Contact/Name, Contact/Id) — a scalar lookup `XxxId` with a GUID is handled for you. ' +
+            advanced +
+            'Paginate with skip+top (+ a stable orderBy). To COUNT, set count:true (response becomes { total, value }); for count-only use count:true + top:0. ' +
+            'For date/time filtering see /datetime-guide prompt. For Contact/Owner filtering see /contactid-guide prompt. ' +
+            "Examples: entity:'Order', select:['Id','Number','Amount'], filters:{ all:[{ field:'ContactId', op:'eq', value:'<guid>' }] }, orderBy:'Amount desc', top:25, skip:0. " +
+            "count-only: entity:'Opportunity', filters:{ all:[{ field:'ContactId', op:'eq', value:'<guid>' }] }, count:true, top:0.",
+        inputShape: buildReadInputShape(caps),
+    });
+}
 const createInputShape = {
     entity: zod_1.z
         .string()
@@ -316,7 +362,8 @@ const describeEntityInputShape = {
 exports.describeEntityInput = zod_1.z.object(describeEntityInputShape);
 exports.describeEntityDescriptor = makeToolDescriptor({
     title: 'Get entity description from Creatio',
-    description: 'Inspect schema for the given entity set: entity type, primary key(s), and properties with types/nullable. Use this before CRUD to avoid invalid fields.',
+    description: 'Inspect schema for the given entity set: entity type, primary key(s), and properties with types/nullable. Use this before CRUD to avoid invalid fields. ' +
+        'When DataForge is enabled on the environment, this tool transparently returns the richer DataForge column details (`source:"dataforge"`); otherwise it falls back to exact OData $metadata (`source:"odata"`). Behaviour and inputs are identical either way.',
     inputShape: describeEntityInputShape,
 });
 const executeProcessInputShape = {
@@ -568,4 +615,172 @@ exports.callConfigurationServiceDescriptor = makeToolDescriptor({
     description: 'Escape hatch for invoking any configuration-package REST service exposed at /0/rest/<service>/<method>. Use this when no dedicated MCP tool covers the operation. Always prefer the specific tools (`upsert-admin-operation`, `refresh-feature-cache`, sys-settings tools, etc.) when they exist — they validate inputs, handle wrapped responses, and document side effects. Returns `{status, contentType, body}`; JSON responses are auto-parsed.',
     inputShape: callConfigurationServiceInputShape,
 });
+// ---------------------------------------------------------------------------
+// DataForge — AI-oriented semantic discovery over the Creatio data model.
+//
+// These tools call the Creatio-hosted DataForge read API
+// (POST /0/rest/DataForgeSchemaReadService/<method>) which forwards to the
+// remote DataForge microservice. They COMPLEMENT, and do not replace,
+// `list-entities`/`describe-entity`:
+//   • describe-entity = authoritative, exact OData $metadata (always available,
+//     needs the exact entity name) → use it to confirm fields before CRUD.
+//   • DataForge       = fuzzy / semantic discovery (natural-language → table),
+//     relationship pathing, and lookup-value search (needs DataForge configured
+//     and synced) → use it to FIND the right table/columns/values first.
+// Typical chain: dataforge-similar-tables → describe-entity → read/create.
+//
+// Requires the MCP user to have the `CanReadDataStructureColumnDetails`
+// operation, and DataForge to be enabled on the environment
+// (DataForgeServiceUrl + IdentityServer settings). Use `dataforge-status` to
+// verify it is online and the data/lookups are synced.
+// ---------------------------------------------------------------------------
+const DATAFORGE_PREREQ_NOTE = '\n\nPrerequisites: DataForge must be enabled on this environment (DataForgeServiceUrl + IdentityServer settings) and the MCP user needs the `CanReadDataStructureColumnDetails` operation. ' +
+    'Run `dataforge-status` first if you are unsure whether DataForge is online. Returns `{status, contentType, body}`; on a disabled/misconfigured service `body.Success` is false with an `ErrorInfo`.';
+const dataforgeSimilarTablesInputShape = {
+    query: zod_1.z
+        .string()
+        .min(1)
+        .describe('Natural-language description of the data you are looking for (e.g. "customer support tickets", "продажі по угодах"). DataForge returns the table names that best match the meaning, not an exact text match.'),
+    limit: zod_1.z.coerce
+        .number()
+        .int()
+        .positive()
+        .max(200)
+        .optional()
+        .describe('Optional max number of candidate tables to return (server default ~50).'),
+};
+exports.dataforgeSimilarTablesInput = zod_1.z.object(dataforgeSimilarTablesInputShape);
+exports.dataforgeSimilarTablesDescriptor = makeToolDescriptor({
+    title: 'DataForge: find tables by meaning',
+    description: 'Semantic search for Creatio tables/entities from a natural-language query. ' +
+        'Use this FIRST when you do not know which entity holds the data the user is talking about — it maps a concept to candidate table names. ' +
+        'Then call `describe-entity` on the chosen table to get the authoritative field list before reading/creating.' +
+        DATAFORGE_PREREQ_NOTE,
+    inputShape: dataforgeSimilarTablesInputShape,
+});
+const dataforgeTableDetailsInputShape = {
+    query: zod_1.z
+        .string()
+        .min(1)
+        .describe('Natural-language query describing the table(s) you want detailed info about.'),
+    limit: zod_1.z.coerce
+        .number()
+        .int()
+        .positive()
+        .max(200)
+        .optional()
+        .describe('Optional max number of tables to return with details.'),
+};
+exports.dataforgeTableDetailsInput = zod_1.z.object(dataforgeTableDetailsInputShape);
+exports.dataforgeTableDetailsDescriptor = makeToolDescriptor({
+    title: 'DataForge: matching tables with details',
+    description: 'Like `dataforge-similar-tables`, but returns richer per-table details (description/columns as known to DataForge) for the best semantic matches. ' +
+        'For the canonical, exact field schema still confirm with `describe-entity` before CRUD.' +
+        DATAFORGE_PREREQ_NOTE,
+    inputShape: dataforgeTableDetailsInputShape,
+});
+const dataforgeTableRelationshipsInputShape = {
+    sourceTable: zod_1.z
+        .string()
+        .min(1)
+        .describe('Source table/entity name (e.g. "Contact"). Resolve it via dataforge-similar-tables if unsure.'),
+    targetTable: zod_1.z.string().min(1).describe('Target table/entity name (e.g. "Account").'),
+    limit: zod_1.z.coerce
+        .number()
+        .int()
+        .positive()
+        .max(50)
+        .optional()
+        .describe('Optional max number of relationship paths to return (server default ~5).'),
+    bidirectional: zod_1.z
+        .boolean()
+        .optional()
+        .describe('Search relationships in both directions. Defaults to true server-side.'),
+    skipDetails: zod_1.z
+        .boolean()
+        .optional()
+        .describe('Return only the path without extra column-level detail.'),
+};
+exports.dataforgeTableRelationshipsInput = zod_1.z.object(dataforgeTableRelationshipsInputShape);
+exports.dataforgeTableRelationshipsDescriptor = makeToolDescriptor({
+    title: 'DataForge: how two tables are related',
+    description: 'Find the relationship path(s) between two Creatio tables (which columns/joins connect them). ' +
+        'Use this to figure out how to `$expand` or join entities in a `read`, or to understand the data model around an entity.' +
+        DATAFORGE_PREREQ_NOTE,
+    inputShape: dataforgeTableRelationshipsInputShape,
+});
+const dataforgeLookupValuesInputShape = {
+    query: zod_1.z
+        .string()
+        .min(1)
+        .describe('Natural-language / partial text to match lookup values against (e.g. "in progress", "VIP").'),
+    schemaName: zod_1.z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Optional lookup schema/entity name to restrict the search to a single lookup (e.g. "CaseStatus").'),
+    limit: zod_1.z.coerce
+        .number()
+        .int()
+        .positive()
+        .max(100)
+        .optional()
+        .describe('Optional max number of lookup values to return (server default ~5).'),
+};
+exports.dataforgeLookupValuesInput = zod_1.z.object(dataforgeLookupValuesInputShape);
+exports.dataforgeLookupValuesDescriptor = makeToolDescriptor({
+    title: 'DataForge: find lookup values by meaning',
+    description: 'Fuzzy/semantic search for lookup values across (or within) Creatio lookups — returns matching values and their identifiers. ' +
+        'Useful to resolve a human phrase ("high priority", "закрита угода") to the correct lookup record Id to use in a filter or create/update payload.' +
+        DATAFORGE_PREREQ_NOTE,
+    inputShape: dataforgeLookupValuesInputShape,
+});
+exports.dataforgeStatusInput = zod_1.z.object({});
+exports.dataforgeStatusDescriptor = makeToolDescriptor({
+    title: 'DataForge: service status / is it enabled',
+    description: 'Check whether DataForge is enabled and healthy on this environment. ' +
+        'Calls DataForgeMaintenanceService.GetServiceStatus and returns `{ IsOnline, Liveness, Readiness, DataStructureReadiness, LookupsReadinessInfo }`. ' +
+        'Interpretation: IsOnline=false → DataForge is unreachable or DataForgeServiceUrl is not configured (the other dataforge-* tools will fail). ' +
+        'Readiness.HttpStatusCode=200 with non-empty DataStructureReadiness/LookupsReadinessInfo → the data model and lookups have been synced and search will return results. ' +
+        'If you only need a quick on/off signal, you can also query the `DataForgeServiceUrl` system setting (empty = disabled).',
+    inputShape: {},
+});
+// ---------------------------------------------------------------------------
+// Global Search — Creatio's cross-entity record search (Elasticsearch-backed),
+// the same engine behind the UI search box. Registered only when Global Search
+// is enabled on the environment (non-empty `GlobalSearchUrl`).
+// ---------------------------------------------------------------------------
+const globalSearchInputShape = {
+    query: zod_1.z
+        .string()
+        .min(1)
+        .describe('Free-text search across indexed records, exactly like the Creatio UI search box (e.g. "andrew baker", "acme invoice 2024"). Matches names, numbers and other indexed columns.'),
+    entities: zod_1.z
+        .array(zod_1.z.string().min(1))
+        .optional()
+        .describe('Optional list of entity schema names to restrict the search to (e.g. ["Contact","Account"]). Omit to search all indexed sections. Maps to the service `type` filter.'),
+    limit: zod_1.z.coerce
+        .number()
+        .int()
+        .positive()
+        .max(100)
+        .optional()
+        .describe('Max records to return (server default ~15).'),
+    from: zod_1.z.coerce
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe('Pagination offset (skip this many results). Use with the response `nextFrom`.'),
+};
+exports.globalSearchInput = zod_1.z.object(globalSearchInputShape);
+exports.globalSearchDescriptor = makeToolDescriptor({
+    title: 'Global Search: find records across entities',
+    description: 'Search Creatio records the way the UI search box does — full-text across all indexed entities (Elasticsearch-backed). ' +
+        'Use this to locate specific records by name/number/keyword when you do not know the exact entity or filter (e.g. "find Andrew Baker", "the Acme renewal opportunity"). ' +
+        'Calls GlobalSearchService.Search; returns matched records with `entityName`, `id`, `columnValues`, and highlighted `foundColumns`, plus `total`/`nextFrom` for paging. ' +
+        'Differs from `read`: `read` needs an exact entity + OData filter; global-search is fuzzy and cross-entity. ' +
+        'Prerequisites: Global Search must be enabled on the environment (non-empty `GlobalSearchUrl` + the `GlobalSearch_V2` feature). This tool is only registered when enabled.',
+    inputShape: globalSearchInputShape,
+});
 //# sourceMappingURL=tools-data.js.map