Установить статус записи

Instructions

Implementation Reference

• src/workflows/set-status.ts:23-162 (handler)

  Registers the bpm_set_status tool on the MCP server. The handler: (1) resolves the collection reference, (2) auto-detects a status lookup field (by checking property names containing Status/Stage/State), or uses an explicit status_field parameter, (3) resolves the human-readable status name via lookup resolver, (4) updates the record via OData, and (5) returns a success message with structured data.

  export function registerSetStatusTool(server: McpServer, services: ServiceContainer): void {
    const meta = getTool('bpm_set_status');
    server.registerTool(
      meta.name,
      {
        title: meta.title,
        description: meta.description,
        inputSchema: {
          collection: z.string().describe('Имя коллекции (EntitySet), например: Opportunity, Lead, Activity'),
          id: z.string().describe('UUID записи, у которой меняется статус'),
          status: z.string().describe('Человекочитаемое имя статуса (Name справочника)'),
          status_field: z
            .string()
            .optional()
            .describe(
              'Явное имя поля-статуса (если в коллекции несколько кандидатов: StatusId, StageId и т.п.)'
            ),
        },
        annotations: meta.annotations,
      },
      async (params): Promise<CallToolResult> => {
        if (!services.initialized) return notInitialized();
        try {
          await services.authManager.ensureAuthenticated();
  
          const collRef = await services.metadataManager.resolveCollectionReference(params.collection);
          if (collRef.name === null) {
            throw new UnknownCollectionError(params.collection, collRef.suggestions);
          }
          const collection = collRef.name;
  
          const entityMeta = await services.metadataManager.getEntityMetadata(collection);
  
          let statusField: EntityProperty | undefined;
          if (params.status_field) {
            const ref = await services.metadataManager.resolveFieldReference(collection, params.status_field);
            if (ref.name === null) {
              throw new BpmApiError(
                `Поле "${params.status_field}" не найдено в коллекции ${collection}`,
                400,
                collection,
                undefined,
                ref.suggestions
              );
            }
            statusField = entityMeta.properties.find((p) => p.name === ref.name);
          } else {
            const candidates = entityMeta.properties.filter(
              (p) => p.isLookup && isStatusFieldName(p.name)
            );
            if (candidates.length === 0) {
              throw new BpmApiError(
                `В коллекции ${collection} не найдено lookup-поле статуса (имя содержит Status/Stage/State).`,
                400,
                collection,
                undefined,
                undefined,
                [
                  `Запросите схему: bpm_get_schema(${collection}).`,
                  `Или передайте имя поля явно через status_field.`,
                ]
              );
            }
            if (candidates.length > 1) {
              throw new BpmApiError(
                `Найдено несколько статусных полей: ${candidates.map((c) => c.name).join(', ')}. Передайте status_field явно.`,
                400,
                collection,
                undefined,
                candidates.map((c) => c.name),
                [`Повторите вызов, добавив параметр status_field='<нужное имя>'.`]
              );
            }
            statusField = candidates[0];
          }
  
          if (!statusField) {
            throw new BpmApiError(
              `Не удалось определить статусное поле в коллекции ${collection}.`,
              400,
              collection
            );
          }
  
          const lookupInfo = await services.metadataManager.getLookupInfo(collection, statusField.name);
          if (!lookupInfo) {
            throw new BpmApiError(
              `Поле ${statusField.name} в ${collection} не является lookup-полем — изменение статуса невозможно.`,
              400,
              collection
            );
          }
  
          const lookupResult = await services.lookupResolver.resolve(
            lookupInfo.lookupCollection,
            params.status,
            lookupInfo.displayColumn
          );
          if (!lookupResult.resolved || !lookupResult.id) {
            throw new BpmApiError(
              `Статус "${params.status}" не разрешён в справочнике ${lookupInfo.lookupCollection}.${lookupInfo.displayColumn} (matchCount=${lookupResult.matchCount}).`,
              400,
              collection,
              undefined,
              lookupResult.candidates.map((c) => c.displayValue),
              [
                `Запросите доступные значения: bpm_get_records(${lookupInfo.lookupCollection}, select='Id,${lookupInfo.displayColumn}').`,
              ]
            );
          }
  
          await services.odataClient.updateRecord(collection, params.id, {
            [statusField.name]: lookupResult.id,
          });
  
          return {
            content: [
              {
                type: 'text',
                text: `Статус ${collection}(${params.id}) установлен: ${statusField.name} = "${params.status}" (${lookupResult.id}).`,
              },
            ],
            structuredContent: {
              collection,
              id: params.id,
              status_field: statusField.name,
              status_id: lookupResult.id,
              status_value: params.status,
            },
          };
        } catch (error) {
          const toolError = formatToolError(error, params.collection);
          return {
            content: [{ type: 'text', text: JSON.stringify(toolError, null, 2) }],
            isError: true,
          };
        }
      }
    );
  }

• src/workflows/set-status.ts:18-21 (helper)

  Helper that checks if a field name contains 'status', 'stage', or 'state' (case-insensitive) to auto-detect status fields in entity metadata.

  function isStatusFieldName(name: string): boolean {
    const lower = name.toLowerCase();
    return lower.includes('status') || lower.includes('stage') || lower.includes('state');
  }

• src/workflows/set-status.ts:30-41 (schema)

  Zod input schema defining the 4 parameters: collection (string), id (UUID string), status (human-readable status name), and optional status_field (explicit field name when ambiguity exists).

  inputSchema: {
    collection: z.string().describe('Имя коллекции (EntitySet), например: Opportunity, Lead, Activity'),
    id: z.string().describe('UUID записи, у которой меняется статус'),
    status: z.string().describe('Человекочитаемое имя статуса (Name справочника)'),
    status_field: z
      .string()
      .optional()
      .describe(
        'Явное имя поля-статуса (если в коллекции несколько кандидатов: StatusId, StageId и т.п.)'
      ),
  },
  annotations: meta.annotations,

• src/tools/registry.ts:280-287 (registration)

  Tool metadata registration in the central registry TOOLS array, with name, title, description, annotations (idempotent, open-world), blurb, and category 'workflow'.

    name: 'bpm_set_status',
    title: 'Установить статус записи',
    description:
      'Установить статус записи по человекочитаемому имени. Сервер сам найдёт поле-статус в коллекции (StatusId/StageId) и разрешит UUID статуса в его справочнике.',
    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
    blurb: 'установить статус по имени (Status/Stage авто-детект)',
    category: 'workflow',
  },