@peernova/cuneiform-sf 1.0.2 → 1.0.4-beta.8

package/lib/mcp/tools/definition-tools.js

@@ -0,0 +1,199 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+import { ProfilingDefinitionService } from '../../services/ProfilingDefinitionService.js';
+import { ObjectFilteringService } from '../../services/ObjectFilteringService.js';
+import { DefinitionCreateOperation } from '../../operations/DefinitionCreateOperation.js';
+import { DefinitionPurgeOperation } from '../../operations/DefinitionPurgeOperation.js';
+import { McpErrorCodes } from '../errors.js';
+import { serviceResultToMcp, createMcpError, extractErrorMessage } from './tool-factory.js';
+/**
+ * Handler for cuneiform_definition_list tool invocation.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export async function handleDefinitionList(adapters, params) {
+    try {
+        const definitionService = new ProfilingDefinitionService({
+            soqlAdapter: adapters.soql,
+        });
+        // Get definitions with filters
+        const result = await definitionService.getDefinitions({
+            objectName: params.objectName,
+            status: params.status,
+            isActive: params.isActive,
+            limit: params.limit,
+        });
+        return serviceResultToMcp(result);
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to list definitions: ${extractErrorMessage(error, 'handleDefinitionList')}`);
+    }
+}
+/**
+ * Handler for cuneiform_definition_get tool invocation.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export async function handleDefinitionGet(adapters, params) {
+    try {
+        const definitionService = new ProfilingDefinitionService({
+            soqlAdapter: adapters.soql,
+        });
+        // Get specific definition
+        const result = await definitionService.getDefinitionById(params.definitionId);
+        return serviceResultToMcp(result);
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to get definition: ${extractErrorMessage(error, 'handleDefinitionGet')}`);
+    }
+}
+/**
+ * Handler for cuneiform_definition_get_by_key tool invocation.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export async function handleDefinitionGetByKey(adapters, params) {
+    try {
+        const definitionService = new ProfilingDefinitionService({
+            soqlAdapter: adapters.soql,
+        });
+        // Batch query: single SOQL with WHERE Name IN (...) instead of N separate queries
+        const batchResult = await definitionService.getDefinitionsByKeys(params.keys);
+        if (!batchResult.success) {
+            return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, batchResult.message ?? 'Failed to retrieve definitions');
+        }
+        // Collect successful definitions and warnings from batch result
+        const definitions = [];
+        const warnings = [];
+        for (const key of params.keys) {
+            const definition = batchResult.data.get(key.trim());
+            if (definition === null || definition === undefined) {
+                warnings.push(`Definition not found: ${key}`);
+            }
+            else {
+                definitions.push(definition);
+            }
+        }
+        // Return combined result
+        return serviceResultToMcp({
+            success: true,
+            data: {
+                definitions,
+                definitionsRetrieved: definitions.length,
+                warnings: warnings.length > 0 ? warnings : undefined,
+            },
+        });
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to get definitions by key: ${extractErrorMessage(error, 'handleDefinitionGetByKey')}`);
+    }
+}
+/**
+ * Handler for cuneiform_definition_create tool invocation.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export async function handleDefinitionCreate(adapters, params) {
+    try {
+        const { soql: soqlAdapter, rest: restAdapter } = adapters;
+        const definitionService = new ProfilingDefinitionService({ soqlAdapter, restAdapter });
+        const filteringService = new ObjectFilteringService({ restApiAdapter: restAdapter, soqlAdapter });
+        // Create operation
+        const operation = new DefinitionCreateOperation(definitionService, filteringService);
+        // Execute operation
+        const result = await operation.execute({
+            targetOrg: 'mcp-connection',
+            objects: params.objects,
+            filter: params.type,
+            namespace: params.namespace,
+            classification: params.classification,
+            withRecords: params.withRecords,
+            withoutRecords: params.withoutRecords,
+            category: params.category,
+            description: params.description,
+            dryRun: params.dryRun,
+        });
+        // Add dry run context to result
+        if (params.dryRun && result.success) {
+            return serviceResultToMcp({
+                success: true,
+                data: {
+                    ...result.data,
+                    dryRun: true,
+                    message: `[DRY RUN] Would create ${(result.data.total ?? 0) - (result.data.skipped ?? 0)} definitions. Set dryRun=false to execute.`,
+                },
+            });
+        }
+        return serviceResultToMcp(result);
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to create definitions: ${extractErrorMessage(error, 'handleDefinitionCreate')}`);
+    }
+}
+/**
+ * Handler for cuneiform_definition_update tool invocation.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export async function handleDefinitionUpdate(adapters, params) {
+    try {
+        const definitionService = new ProfilingDefinitionService({
+            soqlAdapter: adapters.soql,
+            restAdapter: adapters.rest,
+        });
+        const { definitionId, name, category, timeCategory, segmentCategory, description } = params;
+        const attributes = Object.fromEntries(Object.entries({ name, category, timeCategory, segmentCategory, description }).filter(([, v]) => v !== undefined));
+        const result = await definitionService.updateAttributes(definitionId, attributes);
+        if (!result.success) {
+            return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, result.message ?? 'Failed to update definition');
+        }
+        return serviceResultToMcp(result);
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to update definition: ${extractErrorMessage(error, 'handleDefinitionUpdate')}`);
+    }
+}
+/**
+ * Handler for cuneiform_definition_purge tool invocation.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export async function handleDefinitionPurge(adapters, params) {
+    try {
+        const definitionService = new ProfilingDefinitionService({
+            soqlAdapter: adapters.soql,
+            restAdapter: adapters.rest,
+        });
+        // Create operation
+        const operation = new DefinitionPurgeOperation(definitionService);
+        // Execute operation (legacy mapping — MCP schema will be expanded in a future ticket)
+        const result = await operation.execute({
+            targetOrg: 'mcp-connection',
+            objectNames: params.objectName ? [params.objectName] : undefined,
+            category: params.category,
+            isActive: params.isActive,
+        });
+        return serviceResultToMcp(result);
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to purge definitions: ${extractErrorMessage(error, 'handleDefinitionPurge')}`);
+    }
+}
+//# sourceMappingURL=definition-tools.js.map

package/lib/mcp/tools/definition-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition-tools.js","sourceRoot":"","sources":["../../../src/mcp/tools/definition-tools.ts"],"names":[],"mappings":"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"}

package/lib/mcp/tools/index.d.ts

@@ -0,0 +1,37 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { Connection } from '@salesforce/core';
+import { type McpAdapters } from '../config/mcp-config.js';
+/**
+ * Tool handler function type.
+ * Accepts session-scoped adapters and pre-validated input.
+ */
+export type ToolHandler = (adapters: McpAdapters, input: unknown) => Promise<CallToolResult>;
+/**
+ * Registry of tool handlers mapped by tool name.
+ *
+ * Derived from the authoritative tool registration in server.ts via getToolRegistrations().
+ * Used by invokeTool() for CLI dispatch and by tests for handler verification.
+ */
+export declare const TOOL_HANDLERS: Record<string, ToolHandler>;
+/**
+ * Retrieves a tool handler by name.
+ *
+ * @param toolName - Name of the tool
+ * @returns Tool handler function or undefined if not found
+ */
+export declare function getToolHandler(toolName: string): ToolHandler | undefined;
+/**
+ * Invokes a tool by name with the given input.
+ *
+ * When debug mode is enabled, logs:
+ * - Tool name and input params at start
+ * - Result status, timing, and size on completion
+ * - Error details on failure
+ *
+ * @param toolName - Name of the tool to invoke
+ * @param connection - Salesforce connection
+ * @param input - Tool input parameters
+ * @param debug - Enable debug logging (optional)
+ * @returns MCP CallToolResult
+ */
+export declare function invokeTool(toolName: string, connection: Connection, input: unknown, debug?: boolean): Promise<CallToolResult>;

package/lib/mcp/tools/index.js

@@ -0,0 +1,88 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+import { createMcpAdapters } from '../config/mcp-config.js';
+import { McpErrorCodes } from '../errors.js';
+import { DebugLogger } from '../../debug/debug-logger.js';
+import { getToolRegistrations } from '../server.js';
+import { createMcpError, extractErrorMessage } from './tool-factory.js';
+/**
+ * Registry of tool handlers mapped by tool name.
+ *
+ * Derived from the authoritative tool registration in server.ts via getToolRegistrations().
+ * Used by invokeTool() for CLI dispatch and by tests for handler verification.
+ */
+export const TOOL_HANDLERS = Object.fromEntries(getToolRegistrations().map((tool) => [tool.name, tool.handler]));
+/**
+ * Retrieves a tool handler by name.
+ *
+ * @param toolName - Name of the tool
+ * @returns Tool handler function or undefined if not found
+ */
+export function getToolHandler(toolName) {
+    return TOOL_HANDLERS[toolName];
+}
+/**
+ * Invokes a tool by name with the given input.
+ *
+ * When debug mode is enabled, logs:
+ * - Tool name and input params at start
+ * - Result status, timing, and size on completion
+ * - Error details on failure
+ *
+ * @param toolName - Name of the tool to invoke
+ * @param connection - Salesforce connection
+ * @param input - Tool input parameters
+ * @param debug - Enable debug logging (optional)
+ * @returns MCP CallToolResult
+ */
+export async function invokeTool(toolName, connection, input, debug) {
+    // Enable debug logger if requested
+    if (debug) {
+        DebugLogger.setEnabled(true);
+    }
+    const handler = getToolHandler(toolName);
+    if (!handler) {
+        const errorMsg = `Tool '${toolName}' not found`;
+        DebugLogger.log('MCP', toolName, 'error', errorMsg);
+        return createMcpError(McpErrorCodes.TOOL_NOT_FOUND, errorMsg);
+    }
+    // Log params at start (only when debug is enabled)
+    if (debug) {
+        DebugLogger.log('MCP', toolName, 'params', JSON.stringify(input));
+    }
+    // Construct per-call adapters for the CLI path (no session caching).
+    // MCP server path uses createMcpServer() which constructs adapters once.
+    const adapters = createMcpAdapters(connection);
+    const start = Date.now();
+    try {
+        const result = await handler(adapters, input);
+        const duration = Date.now() - start;
+        const success = !result.isError;
+        if (debug) {
+            try {
+                const resultStr = JSON.stringify(result);
+                const sizeBytes = new TextEncoder().encode(resultStr).length;
+                DebugLogger.logResult('MCP', toolName, success, duration, sizeBytes);
+            }
+            catch {
+                // Result not serializable (e.g., circular refs) — log without size
+                DebugLogger.logResult('MCP', toolName, success, duration);
+            }
+        }
+        else {
+            DebugLogger.logResult('MCP', toolName, success, duration);
+        }
+        return result;
+    }
+    catch (error) {
+        const errorMessage = extractErrorMessage(error, `invokeTool:${toolName}`);
+        DebugLogger.log('MCP', toolName, 'error', errorMessage);
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, errorMessage);
+    }
+}
+//# sourceMappingURL=index.js.map

package/lib/mcp/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp/tools/index.ts"],"names":[],"mappings":"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"}

package/lib/mcp/tools/object-tools.d.ts

@@ -0,0 +1,22 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { McpAdapters } from '../config/mcp-config.js';
+import { type ObjectListInput, type ObjectDescribeInput } from '../schemas/input-schemas.js';
+/**
+ * Handler for cuneiform_object_list tool invocation.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export declare function handleObjectList(adapters: McpAdapters, params: ObjectListInput): Promise<CallToolResult>;
+/**
+ * Handler for cuneiform_object_describe tool invocation.
+ *
+ * Routes by section parameter to return one section per call,
+ * keeping responses within LLM context budgets (~3 KB max).
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export declare function handleObjectDescribe(adapters: McpAdapters, params: ObjectDescribeInput): Promise<CallToolResult>;

package/lib/mcp/tools/object-tools.js

@@ -0,0 +1,306 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+import { ContactPointService } from '../../services/ContactPointService.js';
+import { ObjectDescribeService } from '../../services/ObjectDescribeService.js';
+import { ObjectFilteringService } from '../../services/ObjectFilteringService.js';
+import { ObjectListService } from '../../services/ObjectListService.js';
+import { RecordTypeService } from '../../services/RecordTypeService.js';
+import { TabDetectionService } from '../../services/TabDetectionService.js';
+import { decodeCursor, clampPageSize, createPaginationMetadata, PAGE_SIZE_DEFAULTS } from '../config/pagination.js';
+import { McpErrorCodes } from '../errors.js';
+import { OBJECT_DESCRIBE_SECTIONS } from '../schemas/input-schemas.js';
+import { serviceResultToMcp, serviceResultToMcpPaginated, createMcpError, extractErrorMessage, } from './tool-factory.js';
+/**
+ * Field type mapping from user-friendly categories to Salesforce field types.
+ */
+const FIELD_TYPE_MAP = {
+    text: ['string', 'textarea', 'url', 'email', 'phone'],
+    picklist: ['picklist', 'multipicklist'],
+    lookup: ['reference'],
+    number: ['double', 'currency', 'percent', 'int'],
+    date: ['date', 'datetime', 'time'],
+    formula: ['calculated'],
+    checkbox: ['boolean'],
+    id: ['id'],
+    address: ['address'],
+};
+/**
+ * Handler for cuneiform_object_list tool invocation.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export async function handleObjectList(adapters, params) {
+    try {
+        // Pagination: decode cursor and clamp page size
+        const offset = decodeCursor(params.cursor);
+        const pageSize = clampPageSize(params.limit, PAGE_SIZE_DEFAULTS.OBJECT_LIST.default, PAGE_SIZE_DEFAULTS.OBJECT_LIST.max);
+        const { soql: soqlAdapter, tooling: toolingAdapter, rest: restAdapter } = adapters;
+        const filteringService = new ObjectFilteringService({
+            restApiAdapter: restAdapter,
+            soqlAdapter,
+        });
+        const tabService = new TabDetectionService({
+            toolingAdapter,
+        });
+        const contactPointService = new ContactPointService({
+            restApiAdapter: restAdapter,
+        });
+        const objectListService = new ObjectListService({
+            objectFilteringService: filteringService,
+            tabDetectionService: tabService,
+            contactPointService,
+        });
+        // Build filter options with name pattern
+        const nameFilter = params.pattern
+            ? {
+                value: params.pattern,
+                operator: 'contains',
+            }
+            : undefined;
+        // Execute object list query with pagination
+        const result = await objectListService.listObjects({
+            type: params.filter,
+            namespace: params.namespace,
+            nameFilter,
+            withRecords: params.withRecords,
+            withoutRecords: params.withoutRecords,
+            limit: pageSize,
+            offset,
+            sort: params.sort
+                ? {
+                    field: params.sort,
+                    direction: 'asc',
+                }
+                : undefined,
+            includeTabs: true,
+            withContactPoints: params.contactPoints ?? false,
+        });
+        if (!result.success) {
+            return serviceResultToMcp(result);
+        }
+        // Build pagination metadata from service result
+        const pagination = createPaginationMetadata({
+            offset,
+            pageSize,
+            totalItems: result.data.totalCount,
+            returnedItems: result.data.returnedCount,
+        });
+        return serviceResultToMcpPaginated(result, pagination);
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to list objects: ${extractErrorMessage(error, 'handleObjectList')}`);
+    }
+}
+// ============================================================================
+// Object describe section handlers
+// ============================================================================
+/**
+ * Applies field type and pattern filters, then sorts.
+ */
+function filterAndSortFields(fields, fieldType, fieldPattern, sort) {
+    let result = fields;
+    if (fieldType) {
+        const allowedTypes = FIELD_TYPE_MAP[fieldType] || [fieldType];
+        result = result.filter((f) => allowedTypes.includes(f.type.toLowerCase()));
+    }
+    if (fieldPattern) {
+        const pattern = fieldPattern.toLowerCase();
+        result = result.filter((f) => f.name.toLowerCase().includes(pattern));
+    }
+    if (sort) {
+        result = [...result].sort((a, b) => {
+            if (sort === 'type')
+                return a.type.localeCompare(b.type);
+            if (sort === 'label')
+                return a.label.localeCompare(b.label);
+            return a.name.localeCompare(b.name);
+        });
+    }
+    return result;
+}
+/**
+ * Handles the summary section — object metadata + field classification + availableSections.
+ */
+async function handleDescribeSummary(describeService, objectName) {
+    const result = await describeService.describeObject(objectName);
+    if (!result.success) {
+        return serviceResultToMcp(result);
+    }
+    const obj = result.data;
+    return serviceResultToMcp({
+        success: true,
+        data: {
+            objectName: obj.objectName,
+            label: obj.label,
+            labelPlural: obj.labelPlural,
+            isCustom: obj.isCustom,
+            isQueryable: obj.isQueryable,
+            isCreateable: obj.isCreateable,
+            isUpdateable: obj.isUpdateable,
+            isDeletable: obj.isDeletable,
+            isSearchable: obj.isSearchable,
+            fieldClassification: obj.fieldClassification,
+            availableSections: [...OBJECT_DESCRIBE_SECTIONS],
+        },
+        message: `Summary for ${obj.objectName} (${obj.fieldClassification.totalFields} fields)`,
+    });
+}
+/**
+ * Handles the fields section — paginated fields with filtering and sorting.
+ */
+async function handleDescribeFields(describeService, params) {
+    const result = await describeService.describeObject(params.objectName);
+    if (!result.success) {
+        return serviceResultToMcp(result);
+    }
+    const filtered = filterAndSortFields(result.data.fields, params.fieldType, params.fieldPattern, params.sort);
+    const offset = decodeCursor(params.cursor);
+    const pageSize = clampPageSize(params.limit, PAGE_SIZE_DEFAULTS.FIELD_LIST.default, PAGE_SIZE_DEFAULTS.FIELD_LIST.max);
+    const page = filtered.slice(offset, offset + pageSize);
+    const pagination = createPaginationMetadata({
+        offset,
+        pageSize,
+        totalItems: filtered.length,
+        returnedItems: page.length,
+    });
+    return serviceResultToMcpPaginated({
+        success: true,
+        data: page,
+        message: `Fields for ${params.objectName}`,
+    }, pagination);
+}
+/**
+ * Handles the fieldDistribution section — field type counts.
+ */
+async function handleDescribeFieldDistribution(describeService, objectName) {
+    const result = await describeService.describeObject(objectName);
+    if (!result.success) {
+        return serviceResultToMcp(result);
+    }
+    const distResult = ObjectDescribeService.getFieldTypeDistribution(result.data.fields);
+    if (!distResult.success) {
+        return serviceResultToMcp(distResult);
+    }
+    return serviceResultToMcp({
+        success: true,
+        data: {
+            objectName,
+            totalFields: result.data.fields.length,
+            distribution: distResult.data,
+        },
+        message: `Field distribution for ${objectName}`,
+    });
+}
+/**
+ * Handles the recordTypes section — record types with pagination.
+ */
+async function handleDescribeRecordTypes(soqlAdapter, params) {
+    const recordTypeService = new RecordTypeService({ soqlAdapter });
+    const result = await recordTypeService.getRecordTypes(params.objectName);
+    if (!result.success) {
+        return serviceResultToMcp(result);
+    }
+    const offset = decodeCursor(params.cursor);
+    const pageSize = clampPageSize(params.limit, PAGE_SIZE_DEFAULTS.RECORD_TYPE_LIST.default, PAGE_SIZE_DEFAULTS.RECORD_TYPE_LIST.max);
+    const page = result.data.slice(offset, offset + pageSize);
+    const pagination = createPaginationMetadata({
+        offset,
+        pageSize,
+        totalItems: result.data.length,
+        returnedItems: page.length,
+    });
+    return serviceResultToMcpPaginated({
+        success: true,
+        data: page,
+        message: `Record types for ${params.objectName}`,
+    }, pagination);
+}
+/**
+ * Handles the relationships section — lookup fields and external references with pagination.
+ */
+async function handleDescribeRelationships(describeService, params) {
+    const result = await describeService.describeObject(params.objectName);
+    if (!result.success) {
+        return serviceResultToMcp(result);
+    }
+    const relationships = result.data.relationships;
+    // If relationship data is unavailable, return success with explicit warning
+    // rather than silently synthesizing empty arrays (which masks API/permission issues)
+    if (!relationships) {
+        return serviceResultToMcpPaginated({
+            success: true,
+            data: { items: [] },
+            warnings: [
+                'Relationship metadata was not returned by the describe API. ' +
+                    'This may indicate insufficient permissions or an API limitation.',
+            ],
+            message: `Relationships for ${params.objectName} (data unavailable)`,
+        }, createPaginationMetadata({ offset: 0, pageSize: 1, totalItems: 0, returnedItems: 0 }));
+    }
+    const allItems = [
+        ...relationships.lookupFields.map((lf) => ({ kind: 'lookup', ...lf })),
+        ...relationships.referencedBy.map((rb) => ({ kind: 'referencedBy', ...rb })),
+    ];
+    const offset = decodeCursor(params.cursor);
+    const pageSize = clampPageSize(params.limit, PAGE_SIZE_DEFAULTS.RELATIONSHIP_LIST.default, PAGE_SIZE_DEFAULTS.RELATIONSHIP_LIST.max);
+    const page = allItems.slice(offset, offset + pageSize);
+    const pagination = createPaginationMetadata({
+        offset,
+        pageSize,
+        totalItems: allItems.length,
+        returnedItems: page.length,
+    });
+    return serviceResultToMcpPaginated({
+        success: true,
+        data: {
+            referencedByCount: relationships.referencedByCount,
+            lookupFieldCount: relationships.lookupFields.length,
+            items: page,
+        },
+        message: `Relationships for ${params.objectName}`,
+    }, pagination);
+}
+/**
+ * Handler for cuneiform_object_describe tool invocation.
+ *
+ * Routes by section parameter to return one section per call,
+ * keeping responses within LLM context budgets (~3 KB max).
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export async function handleObjectDescribe(adapters, params) {
+    try {
+        const { soql: soqlAdapter, rest: restAdapter } = adapters;
+        const describeService = new ObjectDescribeService({
+            restApiAdapter: restAdapter,
+            soqlAdapter,
+        });
+        switch (params.section) {
+            case 'summary':
+                return await handleDescribeSummary(describeService, params.objectName);
+            case 'fields':
+                return await handleDescribeFields(describeService, params);
+            case 'fieldDistribution':
+                return await handleDescribeFieldDistribution(describeService, params.objectName);
+            case 'recordTypes':
+                return await handleDescribeRecordTypes(soqlAdapter, params);
+            case 'relationships':
+                return await handleDescribeRelationships(describeService, params);
+            default:
+                return createMcpError(McpErrorCodes.INVALID_TOOL_INPUT, `Unknown section: ${String(params.section)}`);
+        }
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to describe object: ${extractErrorMessage(error, 'handleObjectDescribe')}`);
+    }
+}
+//# sourceMappingURL=object-tools.js.map