mcp-creatio 0.3.6

package/src/creatio/services/odata-crud-provider.ts

@@ -0,0 +1,210 @@
+import log from '../../log';
+import {
+	CrudDeleteParams,
+	CrudProvider,
+	CrudReadParams,
+	CrudUpdateParams,
+	CrudWriteParams,
+	EntitySchemaDescription,
+} from '../providers';
+
+import { CreatioHttpClient } from './http-client';
+import { ODataMetadataStore } from './metadata-store';
+
+export class ODataCrudProvider implements CrudProvider {
+	private readonly _client: CreatioHttpClient;
+	private readonly _metadataStore: ODataMetadataStore;
+
+	public readonly kind = 'creatio-odata';
+
+	constructor(client: CreatioHttpClient, metadataStore: ODataMetadataStore) {
+		this._client = client;
+		this._metadataStore = metadataStore;
+	}
+
+	private _buildODataQueryParams(
+		filter?: string,
+		select?: string[],
+		top?: number,
+		expand?: string[],
+		orderBy?: string,
+	): string[] {
+		const params: string[] = [];
+		if (filter) {
+			params.push(`$filter=${encodeURIComponent(filter)}`);
+		}
+		if (select && select.length > 0) {
+			params.push(`$select=${encodeURIComponent(select.join(','))}`);
+		}
+		if (expand && expand.length > 0) {
+			params.push(`$expand=${encodeURIComponent(expand.join(','))}`);
+		}
+		if (orderBy) {
+			params.push(`$orderby=${encodeURIComponent(orderBy)}`);
+		}
+		if (top) {
+			params.push(`$top=${top}`);
+		}
+		return params;
+	}
+
+	private _buildQueryString(params: string[]): string {
+		return params.length ? `?${params.join('&')}` : '';
+	}
+
+	private _extractODataValue(body: any): any {
+		return body && typeof body === 'object' && 'value' in body ? body.value : body;
+	}
+
+	private _buildEntityUrl(entity: string): string {
+		return `${this._client.odataRoot}/${entity}`;
+	}
+
+	private _formatEntityKey(id: string): string {
+		const GUID_PATTERN =
+			/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+		const NUMERIC_PATTERN = /^\d+$/;
+		if (NUMERIC_PATTERN.test(id) || GUID_PATTERN.test(id)) {
+			return id;
+		}
+		return `'${id.replace(/'/g, "''")}'`;
+	}
+
+	public listEntitySets(): Promise<string[]> {
+		return this._metadataStore.listEntitySets();
+	}
+
+	public describeEntity(entitySet: string): Promise<EntitySchemaDescription> {
+		return this._metadataStore.describeEntity(entitySet);
+	}
+
+	public async create({ entity, data }: CrudWriteParams) {
+		const url = this._buildEntityUrl(entity);
+		return this._client.executeWithTiming(
+			'create',
+			url,
+			async () => {
+				const headers = await this._client.getJsonHeaders();
+				return this._client.fetchWithAuth(url, async () => ({
+					method: 'POST',
+					headers,
+					body: JSON.stringify(data),
+				}));
+			},
+			async (response, duration) => {
+				this._client.logSuccess('create', response.status, duration, { entity });
+				return response.json().catch(() => ({}));
+			},
+			async (response, duration) =>
+				this._client.handleErrorResponse(
+					'create',
+					response,
+					duration,
+					'creatio_create_failed',
+					{
+						entity,
+						url,
+					},
+				),
+			{ entity },
+		);
+	}
+
+	public async read({ entity, filter, select, top, expand, orderBy }: CrudReadParams) {
+		const startTime = Date.now();
+		const queryParams = this._buildODataQueryParams(filter, select, top, expand, orderBy);
+		const url = this._buildEntityUrl(entity) + this._buildQueryString(queryParams);
+		const headers = await this._client.getJsonHeaders();
+		try {
+			const body = await this._client.fetchJson(url, async () => ({ headers }));
+			const result = this._extractODataValue(body);
+			const duration = Date.now() - startTime;
+			const resultCount = Array.isArray(result) ? result.length : result ? 1 : 0;
+			log.info('creatio.crud.read.success', {
+				entity,
+				filter,
+				select: select?.join(','),
+				expand: expand?.join(','),
+				orderBy,
+				top,
+				resultCount,
+				duration,
+			});
+			return result;
+		} catch (error: any) {
+			const duration = Date.now() - startTime;
+			log.error('creatio.crud.read.error', {
+				entity,
+				url,
+				error: String(error?.message ?? error),
+				duration,
+			});
+			throw error;
+		}
+	}
+
+	public async update({ entity, id, data }: CrudUpdateParams) {
+		const url = `${this._buildEntityUrl(entity)}(${this._formatEntityKey(id)})`;
+		return this._client.executeWithTiming(
+			'update',
+			url,
+			async () => {
+				const headers = await this._client.getJsonHeaders();
+				return this._client.fetchWithAuth(url, async () => ({
+					method: 'PATCH',
+					headers,
+					body: JSON.stringify(data),
+				}));
+			},
+			async (response, duration) => {
+				this._client.logSuccess('update', response.status, duration, { entity, id });
+				return response.text();
+			},
+			async (response, duration) =>
+				this._client.handleErrorResponse(
+					'update',
+					response,
+					duration,
+					'creatio_update_failed',
+					{
+						entity,
+						id,
+						url,
+					},
+				),
+			{ entity, id },
+		);
+	}
+
+	public async delete({ entity, id }: CrudDeleteParams) {
+		const url = `${this._buildEntityUrl(entity)}(${this._formatEntityKey(id)})`;
+		return this._client.executeWithTiming(
+			'delete',
+			url,
+			async () => {
+				const headers = await this._client.getJsonHeaders();
+				return this._client.fetchWithAuth(url, async () => ({
+					method: 'DELETE',
+					headers,
+				}));
+			},
+			async (response, duration) => {
+				this._client.logSuccess('delete', response.status, duration, { entity, id });
+				return response.text();
+			},
+			async (response, duration) =>
+				this._client.handleErrorResponse(
+					'delete',
+					response,
+					duration,
+					'creatio_delete_failed',
+					{
+						entity,
+						id,
+						url,
+					},
+				),
+			{ entity, id },
+		);
+	}
+}

package/src/creatio/services/process-service-provider.ts

@@ -0,0 +1,76 @@
+import { ExecuteProcessParams, ExecuteProcessResult, ProcessProvider } from '../providers';
+
+import { CreatioHttpClient } from './http-client';
+
+export class ProcessServiceProvider implements ProcessProvider {
+	private readonly _client: CreatioHttpClient;
+
+	public readonly kind = 'creatio-process-service';
+
+	constructor(client: CreatioHttpClient) {
+		this._client = client;
+	}
+
+	private _getServiceUrl(): string {
+		return `${this._client.normalizedBaseUrl}/0/ServiceModel/ProcessEngineService.svc/RunProcess`;
+	}
+
+	private _createProcessParameterValues(parameters?: Record<string, any>): Array<{
+		name: string;
+		value: any;
+	}> {
+		const parameterValues: Array<{
+			name: string;
+			value: any;
+		}> = [];
+		if (!parameters) {
+			return parameterValues;
+		}
+		Object.entries(parameters).forEach(([name, value]) => {
+			let encodedValue = value;
+			if (value instanceof Date) {
+				encodedValue = value.toISOString();
+			}
+			parameterValues.push({
+				name,
+				value: encodedValue,
+			});
+		});
+		return parameterValues;
+	}
+
+	public async executeProcess({ processName, parameters }: ExecuteProcessParams) {
+		const url = this._getServiceUrl();
+		return this._client.executeWithTiming(
+			'execute-process',
+			url,
+			async () => {
+				const body = {
+					schemaName: processName,
+					parameterValues: this._createProcessParameterValues(parameters),
+					resultParameterNames: [],
+				};
+				const requestInit = await this._client.createPostRequest(body);
+				return this._client.fetchWithAuth(url, async () => requestInit);
+			},
+			async (response, duration) => {
+				this._client.logSuccess('execute-process', response.status, duration, {
+					processName,
+				});
+				return (await response.json()) as ExecuteProcessResult;
+			},
+			async (response, duration) =>
+				this._client.handleErrorResponse(
+					'execute-process',
+					response,
+					duration,
+					'creatio_execute_process_failed',
+					{
+						processName,
+						url,
+					},
+				),
+			{ processName },
+		);
+	}
+}

package/src/creatio/services/sys-settings-service-provider.ts

@@ -0,0 +1,192 @@
+import { randomUUID } from 'node:crypto';
+
+import {
+	CreateSysSettingRequest,
+	CreateSysSettingResult,
+	QuerySysSettingsResponse,
+	SysSettingDefinition,
+	SysSettingDefinitionUpdate,
+	SysSettingInsertResponse,
+	SysSettingUpdateResponse,
+	SysSettingsProvider,
+} from '../providers';
+
+import { CreatioHttpClient } from './http-client';
+
+export class SysSettingsServiceProvider implements SysSettingsProvider {
+	private readonly _client: CreatioHttpClient;
+
+	public readonly kind = 'creatio-sys-settings-service';
+
+	constructor(client: CreatioHttpClient) {
+		this._client = client;
+	}
+
+	private _getSetValuesUrl(): string {
+		return `${this._client.normalizedBaseUrl}/0/DataService/json/SyncReply/PostSysSettingsValues`;
+	}
+
+	private _getQueryUrl(): string {
+		return `${this._client.normalizedBaseUrl}/0/DataService/json/SyncReply/QuerySysSettings`;
+	}
+
+	private _getInsertUrl(): string {
+		return `${this._client.normalizedBaseUrl}/0/DataService/json/SyncReply/InsertSysSettingRequest`;
+	}
+
+	private _getUpdateUrl(): string {
+		return `${this._client.normalizedBaseUrl}/0/DataService/json/SyncReply/UpdateSysSettingRequest`;
+	}
+
+	private async _insertSetting(
+		definition: SysSettingDefinition,
+	): Promise<SysSettingInsertResponse> {
+		const payload = {
+			id: definition.id ?? randomUUID(),
+			...definition,
+		};
+		return this._sendDefinitionRequest(
+			'insert-sys-setting',
+			this._getInsertUrl(),
+			payload,
+			(response) => response.json() as Promise<SysSettingInsertResponse>,
+			'creatio_insert_sys_setting_failed',
+		);
+	}
+
+	private async _updateSetting(
+		definition: SysSettingDefinitionUpdate,
+	): Promise<SysSettingUpdateResponse> {
+		const payload = {
+			...definition,
+		};
+		return this._sendDefinitionRequest(
+			'update-sys-setting',
+			this._getUpdateUrl(),
+			payload,
+			(response) => response.json() as Promise<SysSettingUpdateResponse>,
+			'creatio_update_sys_setting_failed',
+		);
+	}
+
+	private async _sendDefinitionRequest<T>(
+		operation: string,
+		url: string,
+		payload: Partial<SysSettingDefinition> & { id?: string | undefined },
+		parser: (response: Response) => Promise<T>,
+		errorPrefix: string,
+	): Promise<T> {
+		return this._client.executeWithTiming(
+			operation,
+			url,
+			async () => {
+				const requestInit = await this._client.createPostRequest(payload);
+				return this._client.fetchWithAuth(url, async () => requestInit);
+			},
+			async (response, duration) => {
+				const body = await parser(response);
+				this._client.logSuccess(operation, response.status, duration, {
+					code: payload.code,
+					id: payload.id,
+				});
+				return body;
+			},
+			async (response, duration) =>
+				this._client.handleErrorResponse(operation, response, duration, errorPrefix, {
+					code: payload.code,
+					id: payload.id,
+					url,
+				}),
+			{ code: payload.code, id: payload.id },
+		);
+	}
+
+	public async setValues(sysSettingsValues: Record<string, any>): Promise<any> {
+		const url = this._getSetValuesUrl();
+		return this._client.executeWithTiming(
+			'set-sys-settings-value',
+			url,
+			async () => {
+				const body = {
+					isPersonal: false,
+					sysSettingsValues,
+				};
+				const requestInit = await this._client.createPostRequest(body);
+				return this._client.fetchWithAuth(url, async () => requestInit);
+			},
+			async (response, duration) => {
+				this._client.logSuccess('set-sys-settings-value', response.status, duration, {
+					settingsCount: Object.keys(sysSettingsValues).length,
+				});
+				return response.text();
+			},
+			async (response, duration) =>
+				this._client.handleErrorResponse(
+					'set-sys-settings-value',
+					response,
+					duration,
+					'creatio_set_sys_settings_value_failed',
+					{
+						settingsCount: Object.keys(sysSettingsValues).length,
+						url,
+					},
+				),
+			{ settingsCount: Object.keys(sysSettingsValues).length },
+		);
+	}
+
+	public async queryValues(sysSettingCodes: string[]): Promise<QuerySysSettingsResponse> {
+		if (!sysSettingCodes || sysSettingCodes.length === 0) {
+			return { success: true, values: {} };
+		}
+		const url = this._getQueryUrl();
+		return this._client.executeWithTiming(
+			'query-sys-settings',
+			url,
+			async () => {
+				const body = {
+					sysSettingsNameCollection: sysSettingCodes,
+				};
+				const requestInit = await this._client.createPostRequest(body);
+				return this._client.fetchWithAuth(url, async () => requestInit);
+			},
+			async (response, duration) => {
+				const payload = (await response.json()) as QuerySysSettingsResponse;
+				this._client.logSuccess('query-sys-settings', response.status, duration, {
+					settingsCount: sysSettingCodes.length,
+				});
+				return payload;
+			},
+			async (response, duration) =>
+				this._client.handleErrorResponse(
+					'query-sys-settings',
+					response,
+					duration,
+					'creatio_query_sys_settings_failed',
+					{
+						settingsCount: sysSettingCodes.length,
+						url,
+					},
+				),
+			{ settingsCount: sysSettingCodes.length },
+		);
+	}
+
+	public async createSetting({
+		definition,
+		initialValue,
+	}: CreateSysSettingRequest): Promise<CreateSysSettingResult> {
+		const insertResult = await this._insertSetting(definition);
+		let setValueResult: any;
+		if (initialValue !== undefined) {
+			setValueResult = await this.setValues({ [definition.code]: initialValue });
+		}
+		return { insertResult, setValueResult };
+	}
+
+	public updateDefinition(
+		definition: SysSettingDefinitionUpdate,
+	): Promise<SysSettingUpdateResponse> {
+		return this._updateSetting(definition);
+	}
+}

package/src/creatio/services/user-info-provider.ts

@@ -0,0 +1,41 @@
+import { CurrentUserInfo, UserProvider } from '../providers';
+
+import { CreatioHttpClient } from './http-client';
+
+export class UserInfoProvider implements UserProvider {
+	private readonly _client: CreatioHttpClient;
+
+	public readonly kind = 'creatio-user-info-service';
+
+	constructor(client: CreatioHttpClient) {
+		this._client = client;
+	}
+
+	private _getServiceUrl(): string {
+		return `${this._client.normalizedBaseUrl}/0/ServiceModel/UserInfoService.svc/GetCurrentUserInfo`;
+	}
+
+	public async getCurrentUserInfo(): Promise<CurrentUserInfo> {
+		const url = this._getServiceUrl();
+		return this._client.executeWithTiming(
+			'getCurrentUserInfo',
+			url,
+			async () => {
+				const requestInit = await this._client.createPostRequest();
+				return this._client.fetchWithAuth(url, async () => requestInit);
+			},
+			async (response, duration) => {
+				this._client.logSuccess('getCurrentUserInfo', response.status, duration);
+				const body = await response.json().catch(() => ({}));
+				return body as CurrentUserInfo;
+			},
+			async (response, duration) =>
+				this._client.handleErrorResponse(
+					'getCurrentUserInfo',
+					response,
+					duration,
+					'creatio_get_current_user_info_failed',
+				),
+		);
+	}
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+import { getCreatioClientConfig } from './config-builder';
+import { HTTP_MCP_PORT } from './consts';
+import { CreatioEngineManager, CreatioServiceContext } from './creatio';
+import log from './log';
+import { HttpServer, Server } from './server';
+import { envBool } from './utils';
+
+let _httpInstance: HttpServer | undefined;
+
+async function main() {
+	log.appStart({ env: { node: process.version, HTTP_MCP_PORT } });
+	const cfg = getCreatioClientConfig();
+	const provider = new CreatioServiceContext(cfg);
+	const engines = new CreatioEngineManager(provider);
+	const server = new Server(engines, { readonlyMode: envBool('READONLY_MODE', false) });
+	const http = new HttpServer(server);
+	_httpInstance = http;
+	await http.start(HTTP_MCP_PORT);
+}
+
+let shuttingDown = false;
+
+async function shutdown(signal?: string) {
+	if (shuttingDown) {
+		return;
+	}
+	shuttingDown = true;
+	try {
+		log.appStop({ reason: signal || 'shutdown' });
+		await _httpInstance?.stop();
+	} catch (err) {
+		log.error('shutdown.error', { error: String(err) });
+	} finally {
+		process.exit(0);
+	}
+}
+
+main().catch((err) => {
+	log.error('startup.error', { error: String(err) });
+	process.exit(1);
+});
+
+process.on('SIGINT', () => shutdown('SIGINT'));
+process.on('SIGTERM', () => shutdown('SIGTERM'));

package/src/log.ts

@@ -0,0 +1,141 @@
+export type LogLevel = 'info' | 'warn' | 'error';
+export type CreatioAuthKind = 'legacy' | 'oauth2' | 'oauth2_code';
+
+export interface LogConfig {
+	level?: LogLevel;
+}
+
+let _correlationId: string | undefined;
+
+export function setCorrelationId(correlationId: string) {
+	_correlationId = correlationId;
+}
+
+export function getCorrelationId(): string | undefined {
+	return _correlationId;
+}
+
+export function clearCorrelationId() {
+	_correlationId = undefined;
+}
+
+function timestamp() {
+	return new Date().toISOString();
+}
+
+function output(level: LogLevel, msg: string, meta?: Record<string, any>) {
+	const entry: any = { ts: timestamp(), level, msg };
+	if (_correlationId) {
+		entry.correlationId = _correlationId;
+	}
+	if (meta && Object.keys(meta).length) {
+		entry.meta = meta;
+	}
+	const line = JSON.stringify(entry);
+	if (level === 'error') {
+		console.error(line);
+	} else if (level === 'warn') {
+		console.warn(line);
+	} else {
+		console.log(line);
+	}
+}
+
+export function info(msg: string, meta?: Record<string, any>) {
+	output('info', msg, meta);
+}
+export function warn(msg: string, meta?: Record<string, any>) {
+	output('warn', msg, meta);
+}
+export function error(msg: string, meta?: Record<string, any>) {
+	output('error', msg, meta);
+}
+export function appStart(meta?: Record<string, any>) {
+	info('app.start', meta);
+}
+export function appStop(meta?: Record<string, any>) {
+	info('app.stop', meta);
+}
+export function serverStart(name?: string, version?: string, meta?: Record<string, any>) {
+	info('mcp.server.start', { name, version, ...meta });
+}
+export function serverStop(name?: string, version?: string, meta?: Record<string, any>) {
+	info('mcp.server.stop', { name, version, ...meta });
+}
+export function httpStart(port: number, meta?: Record<string, any>) {
+	info('http.server.start', { port, ...meta });
+}
+export function httpStop(port: number, meta?: Record<string, any>) {
+	info('http.server.stop', { port, ...meta });
+}
+export function sessionConnect(sessionId: string, ip?: string, meta?: Record<string, any>) {
+	info('session.connect', { sessionId, ip, ...meta });
+}
+export function sessionDisconnect(sessionId: string, ip?: string, meta?: Record<string, any>) {
+	info('session.disconnect', { sessionId, ip, ...meta });
+}
+export function creatioAuthStart(baseUrl: string, authKind?: CreatioAuthKind) {
+	info('creatio.auth.start', { baseUrl, authKind });
+}
+export function creatioAuthOk(baseUrl: string, authKind?: CreatioAuthKind) {
+	info('creatio.auth.ok', { baseUrl, authKind });
+}
+export function creatioAuthFailed(baseUrl: string, error: string, authKind?: CreatioAuthKind) {
+	warn('creatio.auth.failed', { baseUrl, error, authKind });
+}
+export function httpRequest(method: string, url: string, meta?: Record<string, any>) {
+	info('http.request', { method, url, ...meta });
+}
+export function httpResponse(
+	method: string,
+	url: string,
+	status: number,
+	duration?: number,
+	meta?: Record<string, any>,
+) {
+	info('http.response', { method, url, status, duration, ...meta });
+}
+export function httpError(
+	method: string,
+	url: string,
+	errorMsg: string,
+	meta?: Record<string, any>,
+) {
+	error('http.error', { method, url, error: errorMsg, ...meta });
+}
+export function logOperation(
+	operation: string,
+	duration: number,
+	success: boolean,
+	meta?: Record<string, any>,
+) {
+	info(`operation.${success ? 'success' : 'failed'}`, {
+		operation,
+		duration,
+		...meta,
+	});
+}
+
+export default {
+	info,
+	warn,
+	error,
+	appStart,
+	appStop,
+	serverStart,
+	serverStop,
+	httpStart,
+	httpStop,
+	sessionConnect,
+	sessionDisconnect,
+	creatioAuthStart,
+	creatioAuthOk,
+	creatioAuthFailed,
+	httpRequest,
+	httpResponse,
+	httpError,
+	logOperation,
+	setCorrelationId,
+	getCorrelationId,
+	clearCorrelationId,
+};