mcp-creatio 0.3.6

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+export declare const NAME: string;
+export declare const VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,IAAI,EAAE,MAKK,CAAC;AAEzB,eAAO,MAAM,OAAO,EAAE,MAKD,CAAC"}

package/dist/version.js

@@ -0,0 +1,10 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = exports.NAME = void 0;
+const package_json_1 = __importDefault(require("../package.json"));
+exports.NAME = package_json_1.default.name || 'creatio-mcp';
+exports.VERSION = package_json_1.default.version || '0.0.0';
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":";;;;;;AAAA,mEAAkC;AAErB,QAAA,IAAI,GAEf,sBAGA,CAAC,IAAI,IAAI,aAAa,CAAC;AAEZ,QAAA,OAAO,GAElB,sBAGA,CAAC,OAAO,IAAI,OAAO,CAAC"}

package/docs/coding-style.md

@@ -0,0 +1,30 @@
+# Coding Style Guide
+
+This guide defines the class/member layout used across the project so every contributor (human or LLM) can keep the codebase consistent and easy to read.
+
+## Class Member Ordering
+
+Group class members in the following order. Within each group sort by access level: `private` → `protected` → `public`.
+
+1. **Fields (readonly)** – immutable state declared with `readonly`.
+2. **Fields** – mutable fields.
+3. **Properties (getters only)**.
+4. **Properties with setters** – getter/setter pairs.
+5. **Constructors**.
+6. **Methods** – regular functions (again `private`, `protected`, `public`).
+
+Additional rules:
+
+- Prefix all private fields and methods with `_` (e.g., `_cache`, `_buildRequest`).
+- Prefer `protected` for members intended for subclasses, otherwise keep them `private` or `public`.
+- Avoid interleaving unrelated helper functions; keep the order strict even when a method depends on another declared later.
+- Use whitespace between groups to keep sections visually distinct.
+
+## Clean Code Expectations
+
+- Keep methods small and single-purpose. Extract helpers rather than nesting complex logic.
+- Use descriptive names; avoid abbreviations unless they are domain-specific and already established.
+- Log through the shared `log` helper. Never swallow errors silently.
+- Adhere to existing TypeScript strictness (no implicit `any`).
+
+When updating or creating a class, run through this list to ensure the structure matches before submitting changes.

package/ecosystem.config.json

@@ -0,0 +1,17 @@
+{
+  "apps": [
+    {
+      "name": "mcp-creatio",
+      "cwd": "C:/Projects/mcp-creatio",
+      "script": "dist/index.js",
+      "node_args": "",
+      "env": {
+        "CREATIO_BASE_URL": "http://tscore-dev-18:88/sae_m_seeenu_12458081_1106",
+        "CREATIO_LOGIN": "your_login",
+        "CREATIO_PASSWORD": "your_password",
+        "PORT": "7700",
+        "HOST": "0.0.0.0"
+      }
+    }
+  ]
+}

package/eslint.config.cjs

@@ -0,0 +1,95 @@
+module.exports = [
+  {
+    ignores: ['node_modules/**', 'dist/**', 'coverage/**'],
+  },
+  {
+    files: ['**/*.{ts,tsx,js,jsx}'],
+    languageOptions: {
+      parser: require('@typescript-eslint/parser'),
+      parserOptions: {
+        project: ['./tsconfig.json'],
+        tsconfigRootDir: __dirname,
+        sourceType: 'module'
+      }
+    },
+    plugins: {
+      prettier: require('eslint-plugin-prettier'),
+      '@typescript-eslint': require('@typescript-eslint/eslint-plugin'),
+      import: require('eslint-plugin-import')
+    },
+    rules: {
+      'prettier/prettier': [
+        'error',
+        {
+          singleQuote: true,
+          trailingComma: 'all',
+          semi: true,
+          printWidth: 100,
+          useTabs: true,
+          tabWidth: 4,
+          endOfLine: 'crlf'
+        }
+      ],
+      // Sort imported members while declaration order is handled by import/order
+      'sort-imports': [
+        'error',
+        {
+          ignoreCase: false,
+          ignoreDeclarationSort: true,
+          ignoreMemberSort: false,
+          memberSyntaxSortOrder: ['none', 'all', 'multiple', 'single'],
+          allowSeparatedGroups: true
+        }
+      ],
+      // Group and alphabetize import declarations: external first, then project/relative
+      'import/order': [
+        'error',
+        {
+          groups: [
+            'builtin',
+            'external',
+            'internal',
+            'parent',
+            'sibling',
+            'index',
+            'object',
+            'type'
+          ],
+          pathGroupsExcludedImportTypes: ['builtin'],
+          'newlines-between': 'always',
+          alphabetize: { order: 'asc', caseInsensitive: false }
+        }
+      ],
+      // Enforce curly braces for all control statements and a consistent brace style
+      curly: ['warn', 'all'],
+      'brace-style': ['error', '1tbs', { allowSingleLine: false }],
+  indent: ['error', 'tab', { SwitchCase: 1, VariableDeclarator: { var: 1, let: 1, const: 1 } }],
+      'linebreak-style': ['error', 'windows']
+      ,
+      '@typescript-eslint/explicit-member-accessibility': [
+        'error',
+        {
+          accessibility: 'explicit',
+          overrides: {
+            constructors: 'no-public'
+          }
+        }
+      ],
+      '@typescript-eslint/naming-convention': [
+        'error',
+        {
+          selector: 'method',
+          modifiers: ['private'],
+          format: ['camelCase'],
+          leadingUnderscore: 'require'
+        },
+        {
+          selector: 'method',
+          modifiers: ['public'],
+          format: ['camelCase'],
+          leadingUnderscore: 'forbid'
+        }
+      ]
+    }
+  }
+];

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "mcp-creatio",
+  "version": "0.3.6",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-creatio": "dist/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "clean": "rimraf ./dist",
+    "prebuild": "npm run clean",
+    "build": "tsc",
+    "start": "ts-node src/index.ts",
+    "start:cli": "ts-node src/cli.ts",
+    "start:stdio": "ts-node src/cli.ts",
+    "prepack": "npm run build",
+    "lint": "eslint --ext .ts src",
+    "lint:fix": "eslint --ext .ts src --fix",
+    "format": "prettier --write \"src/**/*.{ts,js,json,md}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,js,json,md}\""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CRACKISH/mcp-creatio.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/CRACKISH/mcp-creatio/issues"
+  },
+  "homepage": "https://github.com/CRACKISH/mcp-creatio#readme",
+  "description": "",
+  "devDependencies": {
+    "@types/express": "5.0.6",
+    "@types/node": "^25.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.0",
+    "@typescript-eslint/parser": "^8.56.0",
+    "eslint": "^9.39.3",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "prettier": "^3.8.1",
+    "rimraf": "^6.1.3",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@types/jsonwebtoken": "^9.0.10",
+    "fast-xml-parser": "^5.3.7",
+    "jsonwebtoken": "^9.0.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { getCreatioClientConfig } from './config-builder';
+import { AuthProviderType, CreatioEngineManager, CreatioServiceContext } from './creatio';
+import log from './log';
+import { Server } from './server';
+import { envBool } from './utils';
+
+type CliOptions = Record<string, string>;
+
+interface RuntimeState {
+	server?: Server;
+}
+
+function printHelp(): void {
+	const text = `
+MCP Creatio CLI
+
+Usage:
+  mcp-creatio [options]
+
+Options:
+  --base-url <url>             Creatio base URL
+  --url <url>                  Alias for --base-url
+  --login <value>              Creatio login (legacy auth)
+  --password <value>           Creatio password (legacy auth)
+  --client-id <value>          OAuth2 client credentials client_id
+  --client-secret <value>      OAuth2 client credentials client_secret
+  --id-base-url <url>          Creatio Identity base URL
+  --readonly <true|false>      Enable readonly mode
+  -h, --help                   Show this help
+
+Examples:
+  mcp-creatio --base-url https://tenant.creatio.com --login your_login --password your_password
+`.trim();
+	process.stdout.write(text + '\n');
+}
+
+function parseArgs(argv: string[]): CliOptions {
+	const opts: CliOptions = {};
+	for (let i = 0; i < argv.length; i++) {
+		const token = argv[i];
+		if (!token || !token.startsWith('-')) {
+			continue;
+		}
+
+		if (token === '--help' || token === '-h') {
+			opts.help = 'true';
+			continue;
+		}
+
+		if (!token.startsWith('--')) {
+			continue;
+		}
+
+		const eqIndex = token.indexOf('=');
+		if (eqIndex > 2) {
+			const key = token.slice(2, eqIndex);
+			const value = token.slice(eqIndex + 1);
+			opts[key] = value;
+			continue;
+		}
+
+		const key = token.slice(2);
+		const next = argv[i + 1];
+		if (next && !next.startsWith('-')) {
+			opts[key] = next;
+			i++;
+			continue;
+		}
+
+		opts[key] = 'true';
+	}
+	return opts;
+}
+
+function setEnvIfDefined(name: string, value?: string): void {
+	if (typeof value === 'string' && value.length > 0) {
+		process.env[name] = value;
+	}
+}
+
+function applyCliEnv(opts: CliOptions): void {
+	setEnvIfDefined('CREATIO_BASE_URL', opts['base-url'] || opts.url);
+	setEnvIfDefined('CREATIO_LOGIN', opts.login);
+	setEnvIfDefined('CREATIO_PASSWORD', opts.password);
+	setEnvIfDefined('CREATIO_CLIENT_ID', opts['client-id']);
+	setEnvIfDefined('CREATIO_CLIENT_SECRET', opts['client-secret']);
+	setEnvIfDefined('CREATIO_ID_BASE_URL', opts['id-base-url']);
+	setEnvIfDefined('READONLY_MODE', opts.readonly);
+}
+
+async function startStdio(server: Server): Promise<void> {
+	const mcp = await server.startMcp();
+	const transport = new StdioServerTransport();
+	await mcp.connect(transport);
+	log.info('stdio.server.start');
+}
+
+let shuttingDown = false;
+
+async function shutdown(signal: string, state: RuntimeState): Promise<void> {
+	if (shuttingDown) {
+		return;
+	}
+	shuttingDown = true;
+	log.appStop({ reason: signal || 'shutdown' });
+	try {
+		await state.server?.stopMcp();
+	} catch (err) {
+		log.error('shutdown.error', { error: String(err) });
+	}
+}
+
+async function main(): Promise<void> {
+	const opts = parseArgs(process.argv.slice(2));
+	if (opts.help === 'true') {
+		printHelp();
+		return;
+	}
+
+	applyCliEnv(opts);
+	const cfg = getCreatioClientConfig();
+
+	if (cfg.auth.kind === AuthProviderType.OAuth2Code) {
+		throw new Error(
+			'oauth2_code_requires_http_server: use "npm start" (HTTP /mcp mode) for OAuth2 authorization-code flow',
+		);
+	}
+
+	const provider = new CreatioServiceContext(cfg);
+	const engines = new CreatioEngineManager(provider);
+	const server = new Server(engines, { readonlyMode: envBool('READONLY_MODE', false) });
+	const state: RuntimeState = { server };
+
+	process.on('SIGINT', () => {
+		void shutdown('SIGINT', state).finally(() => process.exit(0));
+	});
+	process.on('SIGTERM', () => {
+		void shutdown('SIGTERM', state).finally(() => process.exit(0));
+	});
+
+	log.appStart({
+		env: {
+			node: process.version,
+			transport: 'stdio',
+		},
+	});
+
+	await startStdio(server);
+}
+
+main().catch((err) => {
+	log.error('startup.error', { error: String(err) });
+	process.exit(1);
+});

package/src/config-builder.ts

@@ -0,0 +1,76 @@
+import {
+	AuthProviderType,
+	CreatioClientAuthConfig,
+	CreatioClientConfig,
+	LegacyAuthConfig,
+	OAuth2AuthConfig,
+	OAuth2CodeAuthConfig,
+} from './creatio';
+import { env } from './utils';
+
+function getCreatioClientAuthConfig(): CreatioClientAuthConfig {
+	const codeConf = _getOAuth2CodeAuthConfig();
+	if (codeConf) {
+		return codeConf;
+	}
+	const oauth2Conf = _getOAuth2AuthConfig();
+	if (oauth2Conf) {
+		return oauth2Conf;
+	}
+	const legacyConf = _getLegacyAuthConfig();
+	if (legacyConf) {
+		return legacyConf;
+	}
+	throw new Error(
+		'You must set either CREATIO_CODE_* (client id, client secret, redirect, scope) or CREATIO_CLIENT_ID/CREATIO_CLIENT_SECRET, or both CREATIO_LOGIN and CREATIO_PASSWORD',
+	);
+}
+
+function _getOAuth2CodeAuthConfig(): OAuth2CodeAuthConfig | null {
+	const codeClientId = env('CREATIO_CODE_CLIENT_ID');
+	const codeClientSecret = env('CREATIO_CODE_CLIENT_SECRET');
+	const codeRedirectUri = env('CREATIO_CODE_REDIRECT_URI');
+	const codeScope = env('CREATIO_CODE_SCOPE');
+	if (codeClientId && codeClientSecret && codeRedirectUri && codeScope) {
+		return {
+			kind: AuthProviderType.OAuth2Code,
+			clientId: codeClientId,
+			clientSecret: codeClientSecret,
+			redirectUri: codeRedirectUri,
+			scope: codeScope,
+		};
+	}
+	return null;
+}
+
+function _getOAuth2AuthConfig(): OAuth2AuthConfig | null {
+	const clientId = env('CREATIO_CLIENT_ID');
+	const clientSecret = env('CREATIO_CLIENT_SECRET');
+	if (clientId && clientSecret) {
+		const conf: OAuth2AuthConfig = { kind: AuthProviderType.OAuth2, clientId, clientSecret };
+		const idb = env('CREATIO_ID_BASE_URL');
+		if (idb) {
+			conf.idBaseUrl = idb;
+		}
+		return conf;
+	}
+	return null;
+}
+
+function _getLegacyAuthConfig(): LegacyAuthConfig | null {
+	const login = env('CREATIO_LOGIN');
+	const password = env('CREATIO_PASSWORD');
+	if (login && password) {
+		return { kind: AuthProviderType.Legacy, login, password };
+	}
+	return null;
+}
+
+export function getCreatioClientConfig(): CreatioClientConfig {
+	const baseUrl = env('CREATIO_BASE_URL');
+	if (!baseUrl) {
+		throw new Error('Environment variable CREATIO_BASE_URL is required but not set');
+	}
+	const auth = getCreatioClientAuthConfig();
+	return { baseUrl, auth };
+}

package/src/consts.ts

@@ -0,0 +1,3 @@
+import { env } from './utils';
+
+export const HTTP_MCP_PORT = Number(env('PORT')) || 3000;

package/src/creatio/auth/auth-manager.ts

@@ -0,0 +1,27 @@
+import { CreatioClientConfig } from '../client-config';
+
+import { ICreatioAuthProvider } from './auth';
+import { AuthProviderType, LegacyProvider, OAuth2CodeProvider, OAuth2Provider } from './providers';
+
+export class CreatioAuthManager {
+	private readonly _config: CreatioClientConfig;
+	private readonly _provider: ICreatioAuthProvider;
+
+	constructor(config: CreatioClientConfig) {
+		this._config = config;
+		const authKind = this._config.auth.kind;
+		if (authKind === AuthProviderType.OAuth2) {
+			this._provider = new OAuth2Provider(this._config);
+		} else if (authKind === AuthProviderType.OAuth2Code) {
+			this._provider = new OAuth2CodeProvider(this._config);
+		} else if (authKind === AuthProviderType.Legacy) {
+			this._provider = new LegacyProvider(this._config);
+		} else {
+			throw new Error('unsupported_auth_config');
+		}
+	}
+
+	public getProvider(): ICreatioAuthProvider {
+		return this._provider;
+	}
+}

package/src/creatio/auth/auth.ts

@@ -0,0 +1,31 @@
+import { AuthProviderType } from './providers';
+
+export interface ICreatioAuthProvider {
+	type: AuthProviderType;
+	getHeaders(accept: string, isJson?: boolean): Promise<Record<string, string>>;
+	refresh(): Promise<void>;
+	revoke(): Promise<void>;
+	getAuthorizeUrl(state: string): Promise<string>;
+	finishAuthorization(code: string): Promise<void>;
+}
+
+export function buildHeaders(
+	accept: string,
+	isJson?: boolean,
+	token?: string,
+): Record<string, string> {
+	const headers: Record<string, string> = { Accept: accept };
+	if (isJson) {
+		headers['Content-Type'] = 'application/json';
+	}
+	if (token) {
+		headers['Authorization'] = `Bearer ${token}`;
+	}
+	return headers;
+}
+
+export const TOKEN_ENDPOINT = '/connect/token';
+export const AUTHORIZE_ENDPOINT = '/connect/authorize';
+export const REVOCATION_ENDPOINT = '/connect/revocation';
+export const TOKEN_BODY_SNIPPET_MAX = 1024;
+export const EXPIRES_MARGIN_SECONDS = 30;

package/src/creatio/auth/index.ts

@@ -0,0 +1,3 @@
+export * from './auth-manager';
+export type { ICreatioAuthProvider } from './auth';
+export { AuthProviderType } from './providers/type';

package/src/creatio/auth/providers/base-oauth2-provider.ts

@@ -0,0 +1,62 @@
+import { OAuth2AuthConfig, OAuth2CodeAuthConfig } from '../../client-config';
+import { EXPIRES_MARGIN_SECONDS, buildHeaders } from '../auth';
+
+import { BaseProvider } from './base-provider';
+
+type OAuthConfig = OAuth2AuthConfig | OAuth2CodeAuthConfig;
+
+export abstract class BaseOAuth2Provider<
+	T extends OAuthConfig = OAuthConfig,
+> extends BaseProvider<T> {
+	protected abstract readonly authErrorCode: string;
+
+	protected accessToken: string | undefined;
+
+	protected accessTokenExpiryMs: number | undefined;
+
+	protected abstract ensureAccessToken(force?: boolean): Promise<string | undefined>;
+
+	protected computeExpiryMs(expiresInSeconds: number, minSeconds: number = 1): number {
+		return Date.now() + Math.max(minSeconds, expiresInSeconds - EXPIRES_MARGIN_SECONDS) * 1000;
+	}
+
+	protected getIdentityBase(): string {
+		if (this.authConfig.idBaseUrl) {
+			let base = String(this.authConfig.idBaseUrl).replace(/\/$/, '');
+			if (!/\/0$/.test(base)) {
+				base = base + '/0';
+			}
+			return base;
+		}
+		let base = this.config.baseUrl.replace(/\/$/, '');
+		if (!/\/0$/.test(base)) {
+			base = base + '/0';
+		}
+		return base;
+	}
+
+	protected storageKey(userKey: string): string {
+		const base = this.getIdentityBase();
+		const kind = (this.config as any)?.auth?.kind ?? 'unknown';
+		const clientId = (this.config as any)?.auth?.clientId ?? 'noclient';
+		return `${kind}|${base}|${clientId}|${userKey}`;
+	}
+
+	protected throwNoTokenError(): void {
+		throw new Error(this.authErrorCode);
+	}
+
+	public async getHeaders(accept: string, isJson?: boolean): Promise<Record<string, string>> {
+		const token = await this.ensureAccessToken(false);
+		if (!token) {
+			this.throwNoTokenError();
+		}
+		return buildHeaders(accept, Boolean(isJson), token);
+	}
+
+	public async refresh(): Promise<void> {
+		this.accessToken = undefined;
+		this.accessTokenExpiryMs = undefined;
+		await this.ensureAccessToken(true);
+	}
+}

package/src/creatio/auth/providers/base-provider.ts

@@ -0,0 +1,42 @@
+import { CreatioClientAuthConfig, CreatioClientConfig } from '../../client-config';
+import { ICreatioAuthProvider } from '../auth';
+
+import { AuthProviderType } from './type';
+
+export abstract class BaseProvider<
+	T extends CreatioClientAuthConfig = CreatioClientAuthConfig,
+> implements ICreatioAuthProvider {
+	protected readonly config: CreatioClientConfig;
+
+	protected get authConfig(): T {
+		return this.config.auth as T;
+	}
+
+	public get type(): AuthProviderType {
+		return this.authConfig.kind;
+	}
+
+	constructor(config: CreatioClientConfig) {
+		this.config = config;
+	}
+
+	public getHeaders(accept: string, isJson?: boolean): Promise<Record<string, string>> {
+		throw new Error('Method not implemented.');
+	}
+
+	public refresh(): Promise<void> {
+		throw new Error('Method not implemented.');
+	}
+
+	public revoke(): Promise<void> {
+		throw new Error('Method not implemented.');
+	}
+
+	public getAuthorizeUrl(state: string): Promise<string> {
+		throw new Error('Method not implemented.');
+	}
+
+	public finishAuthorization(code: string): Promise<void> {
+		throw new Error('Method not implemented.');
+	}
+}

package/src/creatio/auth/providers/index.ts

@@ -0,0 +1,4 @@
+export * from './legacy-provider';
+export * from './oauth2-provider';
+export * from './oauth2-code-provider';
+export * from './type';