SkyeNet-MCP-ACE

Instructions

Implementation Reference

• src/index.ts:397-576 (handler)

  MCP server tool handler for 'execute_updateset_operation'. Validates input, resolves file placeholders, calls the update set client, applies context overflow protection, and returns JSON response.

  if (request.params.name === 'execute_updateset_operation') {
    try {
      // Check if update set client was initialized successfully
      if (!updateSetClient) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                success: false,
                error: {
                  code: 'INITIALIZATION_ERROR',
                  message: 'ServiceNow update set client failed to initialize',
                  details:
                    initError instanceof Error ? initError.message : 'Unknown error',
                },
              }),
            },
          ],
          isError: true,
        };
      }
  
      // Extract parameters from tool arguments
      const args = request.params.arguments as Record<string, unknown> | undefined;
      const operation = args?.operation as string | undefined;
      const name = args?.name as string | undefined;
      const description = args?.description as string | undefined;
      const scope = args?.scope as string | undefined;
      const setAsWorking = args?.set_as_working as boolean | undefined;
      const updateSetSysId = args?.update_set_sys_id as string | undefined;
      const table = args?.table as string | undefined;
      const sysId = args?.sys_id as string | undefined;
      const data = args?.data as Record<string, any> | Record<string, any>[] | undefined;
      const batch = args?.batch as boolean | undefined;
      const xmlSysIds = args?.xml_sys_ids as string[] | undefined;
      const query = args?.query as string | undefined;
      const force = args?.force as boolean | undefined;
      const limit = args?.limit as number | undefined;
      const offset = args?.offset as number | undefined;
      const filters = args?.filters as Record<string, any> | undefined;
      const responseMode = args?.response_mode as string | undefined;
      const quiet = args?.quiet as boolean | undefined;
  
      // Validate required parameters
      if (!operation) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                success: false,
                error: {
                  code: UPDATE_SET_ERROR_CODES.MISSING_PARAMETER,
                  message: 'Required parameter "operation" is missing',
                  details: 'Please provide the operation type (create, set_working, show_working, clear_working, insert, update, rehome, contents, recent, list, info, complete, reopen, delete, diff_default)',
                },
              }),
            },
          ],
          isError: true,
        };
      }
  
      // Resolve file placeholders in the request arguments
      let resolvedArgs = {
        operation: operation as any,
        name,
        description,
        scope,
        set_as_working: setAsWorking,
        update_set_sys_id: updateSetSysId,
        table,
        sys_id: sysId,
        data,
        batch,
        xml_sys_ids: xmlSysIds,
        query,
        force,
        limit,
        offset,
        filters,
        response_mode: responseMode as any,
        quiet,
      };
  
      try {
        const resolution = resolveFilePlaceholders(resolvedArgs);
        resolvedArgs = resolution.data;
      } catch (error) {
        if (error instanceof FilePlaceholderError) {
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify({
                  success: false,
                  error: {
                    code: 'FILE_PLACEHOLDER_ERROR',
                    message: 'Failed to resolve file placeholder',
                    details: `${error.placeholder}: ${error.message}`,
                  },
                }),
              },
            ],
            isError: true,
          };
        }
        
        // Re-throw unknown errors
        throw error;
      }
  
      // Set timestamp after file placeholder resolution for accurate XML detection
      // Subtract 500ms to account for timing between placeholder resolution and record creation
      const timestampBefore = Date.now() - 500;
  
      // Execute the update set operation
      const result = await updateSetClient.executeUpdateSetOperation({
        operation: resolvedArgs.operation,
        name: resolvedArgs.name,
        description: resolvedArgs.description,
        scope: resolvedArgs.scope,
        set_as_working: resolvedArgs.set_as_working,
        update_set_sys_id: resolvedArgs.update_set_sys_id,
        table: resolvedArgs.table,
        sys_id: resolvedArgs.sys_id,
        data: resolvedArgs.data,
        batch: resolvedArgs.batch,
        xml_sys_ids: resolvedArgs.xml_sys_ids,
        query: resolvedArgs.query,
        force: resolvedArgs.force,
        limit: resolvedArgs.limit,
        offset: resolvedArgs.offset,
        filters: resolvedArgs.filters,
        custom_timestamp_before: timestampBefore,
        response_mode: responseMode as any,
        quiet: resolvedArgs.quiet,
      });
  
      // Apply global context overflow prevention
      const { response: protectedResult, monitoring } = globalContextOverflowPrevention.monitorResponse(result, 'execute_updateset_operation', responseMode);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(protectedResult, null, 2),
          },
        ],
      };
  
    } catch (error) {
      const errorResponse = {
        success: false,
        error: {
          code: 'UNKNOWN_ERROR',
          message: 'An unexpected error occurred',
          details: undefined as string | undefined,
        },
      };
  
      if (error instanceof ServiceNowUpdateSetError) {
        errorResponse.error.code = error.code;
        errorResponse.error.message = error.message;
        errorResponse.error.details = `HTTP Status: ${error.statusCode || 'N/A'}`;
      } else if (error instanceof Error) {
        errorResponse.error.message = error.message;
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(errorResponse),
          },
        ],
        isError: true,
      };
    }

• src/servicenow/updateSetClient.ts:130-368 (handler)

  Core ServiceNowUpdateSetClient.executeUpdateSetOperation method. Main entry point that validates requests and routes to specific update set operations like create, insert, rehome, etc.

  async executeUpdateSetOperation(request: UpdateSetOperationRequest): Promise<UpdateSetOperationResult> {
    const startTime = Date.now();
  
    try {
      // Validate input
      this.validateUpdateSetRequest(request);
  
      // Route to appropriate operation
      let result: any;
      let metadata: any = {
        operation: request.operation,
        executionTime: 0,
        timestamp: new Date().toISOString(),
        working_set: this.workingUpdateSet,
      };
  
      switch (request.operation) {
        case 'create':
          result = await this.createUpdateSet(request);
          if (request.set_as_working && result.update_set) {
            this.setWorkingSet(result.update_set);
            result.working_set = this.workingUpdateSet;
          }
          break;
  
        case 'set_working':
          if (!request.update_set_sys_id) {
            throw new ServiceNowUpdateSetError(
              UPDATE_SET_ERROR_CODES.MISSING_PARAMETER,
              undefined,
              'update_set_sys_id is required for set_working operation'
            );
          }
          const updateSet = await this.getUpdateSetInfo(request.update_set_sys_id);
          this.setWorkingSet(updateSet);
          result = { working_set: this.workingUpdateSet };
          break;
  
        case 'show_working':
          result = { working_set: this.workingUpdateSet };
          break;
  
        case 'clear_working':
          this.clearWorkingSet();
          result = { working_set: null };
          break;
  
        case 'insert':
          if (!request.table || !request.data) {
            throw new ServiceNowUpdateSetError(
              UPDATE_SET_ERROR_CODES.MISSING_PARAMETER,
              undefined,
              'table and data are required for insert operation'
            );
          }
          result = await this.insertWithReassignment(
            request.table,
            request.data as Record<string, any>,
            request.update_set_sys_id,
            request.custom_timestamp_before
          );
          break;
  
        case 'update':
          if (!request.table || !request.sys_id || !request.data) {
            throw new ServiceNowUpdateSetError(
              UPDATE_SET_ERROR_CODES.MISSING_PARAMETER,
              undefined,
              'table, sys_id, and data are required for update operation'
            );
          }
          result = await this.updateWithReassignment(
            request.table,
            request.sys_id,
            request.data as Record<string, any>,
            request.update_set_sys_id,
            request.custom_timestamp_before
          );
          break;
  
        case 'rehome':
          if (!request.xml_sys_ids && !request.query) {
            throw new ServiceNowUpdateSetError(
              UPDATE_SET_ERROR_CODES.MISSING_PARAMETER,
              undefined,
              'xml_sys_ids or query is required for rehome operation'
            );
          }
          if (request.xml_sys_ids) {
            result = await this.rehomeXMLByIds(
              request.xml_sys_ids,
              request.update_set_sys_id || this.getWorkingSetId(),
              request.force || false
            );
          } else {
            result = await this.rehomeXMLByQuery(
              request.query!,
              request.update_set_sys_id || this.getWorkingSetId(),
              request.force || false
            );
          }
          break;
  
        case 'contents':
          result = await this.getUpdateSetContents(
            request.update_set_sys_id || this.getWorkingSetId(),
            request.response_mode
          );
          break;
  
        case 'recent':
          result = await this.getRecentXML(request.limit || 50, request.response_mode);
          break;
  
        case 'list':
          result = await this.listUpdateSets(request.filters, request.limit, request.offset);
          break;
  
        case 'info':
          if (!request.update_set_sys_id) {
            throw new ServiceNowUpdateSetError(
              UPDATE_SET_ERROR_CODES.MISSING_PARAMETER,
              undefined,
              'update_set_sys_id is required for info operation'
            );
          }
          result = { update_set: await this.getUpdateSetInfo(request.update_set_sys_id) };
          break;
  
        case 'complete':
          if (!request.update_set_sys_id) {
            throw new ServiceNowUpdateSetError(
              UPDATE_SET_ERROR_CODES.MISSING_PARAMETER,
              undefined,
              'update_set_sys_id is required for complete operation'
            );
          }
          result = await this.completeUpdateSet(request.update_set_sys_id);
          break;
  
        case 'reopen':
          if (!request.update_set_sys_id) {
            throw new ServiceNowUpdateSetError(
              UPDATE_SET_ERROR_CODES.MISSING_PARAMETER,
              undefined,
              'update_set_sys_id is required for reopen operation'
            );
          }
          
          // Check if state changes are disabled
          if (process.env.SKYENET_UPDATESET_DISABLE_STATE_CHANGES === 'true') {
            throw new ServiceNowUpdateSetError(
              UPDATE_SET_ERROR_CODES.OPERATION_DISABLED,
              undefined,
              'Reopen operation is disabled due to ServiceNow business rule limitations. Use create, list, contents, recent, diff, and complete operations instead.'
            );
          }
          
          result = await this.reopenUpdateSet(request.update_set_sys_id);
          break;
  
        case 'delete':
          if (!request.update_set_sys_id) {
            throw new ServiceNowUpdateSetError(
              UPDATE_SET_ERROR_CODES.MISSING_PARAMETER,
              undefined,
              'update_set_sys_id is required for delete operation'
            );
          }
          
          // Check if state changes are disabled
          if (process.env.SKYENET_UPDATESET_DISABLE_STATE_CHANGES === 'true') {
            throw new ServiceNowUpdateSetError(
              UPDATE_SET_ERROR_CODES.OPERATION_DISABLED,
              undefined,
              'Delete operation is disabled due to ServiceNow business rule limitations. Use create, list, contents, recent, diff, and complete operations instead.'
            );
          }
          
          result = await this.deleteUpdateSet(request.update_set_sys_id);
          break;
  
        case 'diff_default':
          result = await this.diffAgainstDefault(
            request.update_set_sys_id || this.getWorkingSetId(),
            request.response_mode
          );
          break;
  
        default:
          throw new ServiceNowUpdateSetError(
            UPDATE_SET_ERROR_CODES.INVALID_OPERATION,
            undefined,
            `Invalid operation: ${request.operation}`
          );
      }
  
      const executionTime = Date.now() - startTime;
      metadata.executionTime = executionTime;
  
      // Estimate response size for metadata
      const responseSize = JSON.stringify(result).length;
      metadata.responseSize = responseSize;
      metadata.contextOverflowPrevention = responseSize > 40000; // 40KB threshold
  
      // Handle quiet mode for update operations - ultra-minimal response
      if (request.quiet && (request.operation === 'insert' || request.operation === 'update' || request.operation === 'set_working')) {
        return {
          success: true,
          data: {
            message: 'Update accepted'
          },
          metadata: {
            operation: request.operation,
            executionTime: 0,
            timestamp: new Date().toISOString(),
            quiet_mode: true
          }
        };
      }
  
      return {
        success: true,
        data: result,
        metadata,
      };
  
    } catch (error) {
      if (error instanceof ServiceNowUpdateSetError) {
        throw error;
      }
      
      throw new ServiceNowUpdateSetError(
        UPDATE_SET_ERROR_CODES.NETWORK_ERROR,
        undefined,
        `Update set operation failed: ${error instanceof Error ? error.message : 'Unknown error'}`
      );
    }
  }

• src/index.ts:702-787 (registration)

  Tool registration in MCP server's listTools handler, defining name, description, and full input schema with all parameters and enums.

  {
    name: 'execute_updateset_operation',
    description:
      'Manage ServiceNow update sets with lifecycle operations, XML reassignment, and working set tracking. ⚠️ SANDBOX ONLY - modifies update sets. 🛡️ Auto-limits large results. Use pagination for big datasets. 📁 Use {{file:path}} for large data.',
    inputSchema: {
      type: 'object',
      properties: {
        operation: {
          type: 'string',
          enum: ['create', 'set_working', 'show_working', 'clear_working', 'insert', 'update', 'rehome', 'contents', 'recent', 'list', 'info', 'complete', 'reopen', 'delete', 'diff_default'],
          description: 'The update set operation to perform. Required.',
        },
        name: {
          type: 'string',
          description: 'Update set name (required for create operation).',
        },
        description: {
          type: 'string',
          description: 'Update set description (optional for create operation).',
        },
        scope: {
          type: 'string',
          description: 'Update set scope (optional, defaults to configured scope).',
        },
        set_as_working: {
          type: 'boolean',
          description: 'Set the created update set as working set (for create operation).',
        },
        update_set_sys_id: {
          type: 'string',
          description: 'Update set sys_id for operations that require it.',
        },
        table: {
          type: 'string',
          description: 'Table name for insert/update operations.',
        },
        sys_id: {
          type: 'string',
          description: 'Record sys_id for update operations.',
        },
        data: {
          type: 'object',
          description: 'Record data for insert/update operations. Can be single object or array for batch operations. Supports {{file:...}} placeholders to load content from local files.',
        },
        batch: {
          type: 'boolean',
          description: 'Enable batch mode for multiple record operations.',
        },
        xml_sys_ids: {
          type: 'array',
          items: { type: 'string' },
          description: 'Array of XML sys_ids for rehome operations.',
        },
        query: {
          type: 'string',
          description: 'ServiceNow encoded query string for rehome operations.',
        },
        force: {
          type: 'boolean',
          description: 'Force reassignment even if XML is not in Default update set.',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of records to return for list/recent operations.',
        },
        offset: {
          type: 'number',
          description: 'Number of records to skip for pagination.',
        },
        filters: {
          type: 'object',
          description: 'Filters for list operations (scope, state, created_by, sys_created_on).',
        },
        response_mode: {
          type: 'string',
          enum: ['full', 'minimal', 'compact'],
          description: 'Response verbosity: full (all data), minimal (essential only), compact (summarized). Default: full',
        },
        quiet: {
          type: 'boolean',
          description: 'Compact acknowledgment for update operations to avoid RESPONSE_TOO_LARGE errors. Default: false.',
        },
      },
      required: ['operation'],
    },
  },

• src/servicenow/updateSetClient.ts:7-28 (schema)

  TypeScript type imports for UpdateSetOperationRequest and UpdateSetOperationResult used for input/output validation in the handler.

    UpdateSetOperationRequest,
    UpdateSetOperationResult,
    UpdateSetErrorResponse,
    UpdateSetRecord,
    XMLRecord,
    WorkingSetState,
    UpdateSetContents,
    RecentXMLActivity,
    UpdateSetDiff,
    XMLSummary,
    XMLDetectionResult,
    XMLReassignmentResult,
    UpdateSetFilters,
    UpdateSetClientConfig,
    DEFAULT_UPDATE_SET_CONFIG,
    loadUpdateSetConfig,
    ServiceNowUpdateSetError,
    UPDATE_SET_ERROR_CODES,
    isWorkingSetState,
    isUpdateSetRecord,
    isXMLRecord,
  } from './updateSetTypes.js';