mcp-creatio 0.3.8 → 0.4.0

package/src/server/mcp/prompts-data.ts

@@ -887,10 +887,406 @@ export const SYS_SETTINGS_PROMPT = {
 	}),
 };
 
+const FEATURE_TOGGLE_GUIDE = `
+# 🚦 Feature Toggling Guide for Creatio
+
+## 🧭 Quick Map
+
+Creatio feature toggles are stored in TWO database-backed entities, both reachable via OData:
+
+| Entity                   | What it represents                                                       | When to use                          |
+|--------------------------|--------------------------------------------------------------------------|--------------------------------------|
+| \`Feature\`                | Catalog row for a feature (Code, Name, Description, DefaultState)         | Read/create/update/delete the toggle |
+| \`AdminUnitFeatureState\`  | Per-user/role override (FeatureId, SysAdminUnitId, FeatureState)          | Override a feature for one principal |
+
+There is **NO** dedicated feature CRUD tool — use the existing \`read\`, \`create\`, \`update\`, \`delete\` tools on the entity sets above. The only feature-specific tool is \`refresh-feature-cache\`.
+
+> ℹ️ The Freedom UI in Creatio shows a virtual section called *AppFeature* that adds a couple of computed columns (\`Source\`, \`StateForCurrentUser\`). Those virtual entities are **not** exposed through OData — always use the persisted \`Feature\` and \`AdminUnitFeatureState\` tables from automation.
+
+---
+
+## 📋 Feature Columns
+
+| Column          | Type     | Notes                                                                  |
+|-----------------|----------|------------------------------------------------------------------------|
+| \`Id\`            | Guid     | Primary key                                                            |
+| \`Code\`          | string   | Feature code. Must match \`^[a-zA-Z]+[a-zA-Z0-9-_.]*$\`                   |
+| \`Name\`          | string   | Display name (commonly equal to \`Code\`)                                |
+| \`Description\`   | string   | Optional description                                                   |
+| \`DefaultState\`  | Int32    | **0 = disabled, 1 = enabled**. NOT a boolean — always send integers.   |
+| \`ProcessListeners\` | Int32 | Internal flag — leave it as the default value                          |
+| \`CreatedOn\` / \`ModifiedOn\` | DateTime | Audit fields                                                |
+
+---
+
+## 📋 AdminUnitFeatureState Columns
+
+| Column            | Type   | Notes                                                            |
+|-------------------|--------|------------------------------------------------------------------|
+| \`Id\`              | Guid   | Primary key                                                      |
+| \`FeatureId\`       | Guid   | FK → \`Feature.Id\`                                                |
+| \`SysAdminUnitId\`  | Guid   | FK → \`SysAdminUnit.Id\` (the user or role)                        |
+| \`FeatureState\`    | Int32  | **0 = disabled, 1 = enabled** for that admin unit                 |
+| \`ProcessListeners\`| Int32  | Internal flag — leave default                                     |
+
+\`SysAdminUnitId\` is the **SysAdminUnit.Id** of the principal (not its ContactId). Look it up explicitly when you only know a user/role name.
+
+---
+
+## 🛠️ Common Workflows
+
+### 1. List features
+
+\`\`\`json
+{
+  "entity": "Feature",
+  "select": ["Id", "Code", "Name", "Description", "DefaultState"],
+  "top": 200,
+  "orderBy": "Code asc"
+}
+\`\`\`
+
+### 2. Look up one feature by code
+
+\`\`\`json
+{
+  "entity": "Feature",
+  "filters": { "all": [ { "field": "Code", "op": "eq", "value": "MyFeature" } ] },
+  "select": ["Id", "Code", "DefaultState"],
+  "top": 1
+}
+\`\`\`
+
+### 3. Enable or disable a feature globally (change default state)
+
+\`\`\`json
+{
+  "entity": "Feature",
+  "id": "<feature-guid>",
+  "data": { "DefaultState": 1 }
+}
+\`\`\`
+
+Use \`1\` to enable, \`0\` to disable. After the update, run \`refresh-feature-cache\` with the same feature \`Code\` so the new value is visible to every connected user.
+
+### 4. Create a new feature
+
+\`\`\`json
+{
+  "entity": "Feature",
+  "data": {
+    "Code": "MyNewFeature",
+    "Name": "MyNewFeature",
+    "Description": "Enables the new dashboard",
+    "DefaultState": 0
+  }
+}
+\`\`\`
+
+Then refresh the cache.
+
+### 5. Override a feature for a specific user or role
+
+First resolve the principal's \`SysAdminUnit.Id\`:
+
+\`\`\`json
+{
+  "entity": "SysAdminUnit",
+  "filters": { "all": [ { "field": "Name", "op": "eq", "value": "Supervisor" } ] },
+  "select": ["Id", "Name", "SysAdminUnitTypeValue"],
+  "top": 1
+}
+\`\`\`
+
+Then create or update the override:
+
+\`\`\`json
+{
+  "entity": "AdminUnitFeatureState",
+  "data": {
+    "FeatureId": "<feature-guid>",
+    "SysAdminUnitId": "<sysadminunit-guid>",
+    "FeatureState": 1
+  }
+}
+\`\`\`
+
+If an override row already exists for the same \`(FeatureId, SysAdminUnitId)\` pair, query it first and \`update\` it instead of creating a duplicate. Refresh the cache afterwards.
+
+### 6. Inspect overrides for a feature
+
+\`\`\`json
+{
+  "entity": "AdminUnitFeatureState",
+  "filters": { "all": [ { "field": "FeatureId", "op": "eq", "value": "<feature-guid>" } ] },
+  "select": ["Id", "FeatureId", "SysAdminUnitId", "FeatureState"]
+}
+\`\`\`
+
+### 7. Remove an override
+
+\`\`\`json
+{ "entity": "AdminUnitFeatureState", "id": "<override-guid>" }
+\`\`\`
+
+### 8. Delete a feature
+
+\`\`\`json
+{ "entity": "Feature", "id": "<feature-guid>" }
+\`\`\`
+
+Deletes the catalog row. Existing \`AdminUnitFeatureState\` rows tied to that feature should be removed first (query them with the filter from step 6) — Creatio will reject the delete if dependent rows remain.
+
+---
+
+## 🔁 When to refresh the cache
+
+Call the \`refresh-feature-cache\` tool **after** any write that changes feature state:
+- Updated \`Feature.DefaultState\` → refresh with that feature's \`Code\`.
+- Created, updated, or deleted an \`AdminUnitFeatureState\` row → refresh with the affected feature's \`Code\`.
+- If you do not know (or don't have) the code, call \`refresh-feature-cache\` with no arguments to clear the cache for every feature.
+
+Reads alone do **not** require a refresh.
+
+---
+
+## ❌ Common Mistakes
+
+- ❌ Sending \`true\`/\`false\` for \`DefaultState\` or \`FeatureState\` — both columns are **Int32** (0 / 1).
+- ❌ Using \`AppFeature\` / \`AppFeatureState\` over OData — those are virtual UI-only entities. Use \`Feature\` / \`AdminUnitFeatureState\`.
+- ❌ Confusing \`SysAdminUnit.Id\` with \`ContactId\` — overrides use \`SysAdminUnit.Id\`.
+- ❌ Forgetting to call \`refresh-feature-cache\` after writes (other users keep seeing the old state).
+- ❌ Creating a duplicate \`AdminUnitFeatureState\` for the same \`(FeatureId, SysAdminUnitId)\` pair instead of updating the existing one.
+- ❌ Using a \`Code\` that doesn't match \`^[a-zA-Z]+[a-zA-Z0-9-_.]*$\` — the platform validator rejects it.
+- ❌ Trying to manage features that are NOT in the \`Feature\` table — Creatio OData v4 does not expose virtual entities (\`AppFeature\` / \`AppFeatureState\`). Features defined only in \`web.config\` or via non-DB providers are invisible to MCP until a backing row exists in \`Feature\`.
+
+---
+
+## ✅ Final Checklist
+
+Before reporting a feature change as done:
+- [ ] Used \`Feature\` for the catalog and \`AdminUnitFeatureState\` for per-user/role overrides.
+- [ ] Sent state values as integers (0 / 1), not booleans.
+- [ ] Resolved the principal via \`SysAdminUnit\` (Id, not ContactId).
+- [ ] Called \`refresh-feature-cache\` (with \`featureCode\` when possible) after every write.
+`.trim();
+
+export const FEATURE_TOGGLE_PROMPT = {
+	name: 'feature-toggle-guide',
+	title: 'Creatio Feature Toggle Guide',
+	description:
+		'How to read, create, update and delete feature toggles via the AppFeature / AppFeatureState OData entities, and when to call refresh-feature-cache',
+	argsSchema: {},
+	callback: () => ({
+		messages: [
+			{
+				role: 'user' as const,
+				content: { type: 'text' as const, text: FEATURE_TOGGLE_GUIDE },
+			},
+		],
+	}),
+};
+
+const ADMIN_OPERATION_GUIDE = `
+# 🛡️ Creatio System Operations (SysAdminOperation) Guide
+
+## 🧭 Quick Map
+
+Creatio system operations are admin-level permission flags that gate features such as \`CanUseODataService\`, \`CanManageAdministration\`, \`CanChangeAdminOperationGrantee\`, etc. They live in two database tables:
+
+| Table                       | Holds                                                          | OData reachable? |
+|-----------------------------|----------------------------------------------------------------|------------------|
+| \`SysAdminOperation\`         | The operation definition: Name, Code, Description              | Read ✅ / Write ❌ |
+| \`SysAdminOperationGrantee\`  | Per-admin-unit grants (FK to operation + SysAdminUnit + allow) | Read ✅ / Write ❌ |
+
+Modification of both tables is blocked through OData v4 (\`DataServiceRestrictedModifySchemas\` in \`Web.config\`). All writes go through Creatio's dedicated **\`/0/rest/RightsService/\`** endpoints, wrapped by these MCP tools:
+
+| Need                                     | Tool                                  |
+|------------------------------------------|---------------------------------------|
+| Read catalog / grant rows                | Standard \`read\` on the two entities  |
+| Create or rename an operation            | \`upsert-admin-operation\`             |
+| Delete operation(s)                      | \`delete-admin-operation\`             |
+| Grant or revoke for users/roles          | \`set-admin-operation-grantee\`        |
+| Remove a specific grant row by Id        | \`delete-admin-operation-grantee\`     |
+
+⚠️ Do NOT attempt \`create\` / \`update\` / \`delete\` on \`SysAdminOperation\` or \`SysAdminOperationGrantee\` through the generic OData tools — Creatio rejects those writes.
+
+---
+
+## 📋 SysAdminOperation Columns
+
+| Column          | Type     | Notes                                                              |
+|-----------------|----------|--------------------------------------------------------------------|
+| \`Id\`            | Guid     | Primary key                                                        |
+| \`Code\`          | string   | Operation code, e.g., \`CanUseODataService\`. Conventionally PascalCase. |
+| \`Name\`          | string   | Display name                                                       |
+| \`Description\`   | string   | Optional description                                               |
+
+## 📋 SysAdminOperationGrantee Columns
+
+| Column                  | Type    | Notes                                                                       |
+|-------------------------|---------|-----------------------------------------------------------------------------|
+| \`Id\`                    | Guid    | Primary key                                                                 |
+| \`SysAdminOperationId\`   | Guid    | FK to \`SysAdminOperation\`                                                   |
+| \`SysAdminUnitId\`        | Guid    | FK to \`SysAdminUnit\` (use SysAdminUnit.Id, NOT ContactId)                   |
+| \`CanExecute\`            | bool    | \`true\` = allow, \`false\` = deny                                            |
+| \`Position\`              | Int32   | Order within conflicting rules; lower wins for the same admin unit          |
+
+---
+
+## 🛠️ Common Workflows
+
+### 1. List system operations
+
+\`\`\`json
+{
+  "entity": "SysAdminOperation",
+  "select": ["Id", "Code", "Name", "Description"],
+  "top": 200,
+  "orderBy": "Code asc"
+}
+\`\`\`
+
+### 2. Look up an operation by code
+
+\`\`\`json
+{
+  "entity": "SysAdminOperation",
+  "filters": { "all": [ { "field": "Code", "op": "eq", "value": "CanUseODataService" } ] },
+  "select": ["Id", "Code", "Name", "Description"],
+  "top": 1
+}
+\`\`\`
+
+### 3. Create a new system operation
+
+Call \`upsert-admin-operation\` without an \`id\`:
+
+\`\`\`json
+{
+  "name": "Can do MCP test",
+  "code": "CanDoMcpTest",
+  "description": "Demo operation managed via MCP"
+}
+\`\`\`
+
+The response includes the generated \`id\`. Capture it for the grant step.
+
+### 4. Rename / re-describe an existing operation
+
+Call \`upsert-admin-operation\` with the existing \`id\`:
+
+\`\`\`json
+{
+  "id": "<operation-guid>",
+  "name": "Can do MCP test (renamed)",
+  "code": "CanDoMcpTest",
+  "description": "Updated description"
+}
+\`\`\`
+
+Code is required even when unchanged.
+
+### 5. Grant the operation to a user or role
+
+Resolve the SysAdminUnit first:
+
+\`\`\`json
+{
+  "entity": "SysAdminUnit",
+  "filters": { "all": [ { "field": "Name", "op": "eq", "value": "Supervisor" } ] },
+  "select": ["Id", "Name", "SysAdminUnitTypeValue"],
+  "top": 1
+}
+\`\`\`
+
+Then call \`set-admin-operation-grantee\`:
+
+\`\`\`json
+{
+  "adminOperationId": "<operation-guid>",
+  "adminUnitIds": ["<sysadminunit-guid-1>", "<sysadminunit-guid-2>"],
+  "canExecute": true
+}
+\`\`\`
+
+Use \`canExecute: false\` to deny instead of allow. The service upserts the grantee rows internally — repeated calls for the same pair update the existing row instead of duplicating it.
+
+### 6. Inspect current grants for an operation
+
+⚠️ **Filter via the navigation property, not the raw FK column.** Creatio OData v4 rejects direct \`SysAdminOperationId eq <guid>\` / \`SysAdminUnitId eq <guid>\` filters on this entity with HTTP 500. Use \`SysAdminOperation/Id\` and \`SysAdminUnit/Id\` instead:
+
+\`\`\`json
+{
+  "entity": "SysAdminOperationGrantee",
+  "filters": { "all": [ { "field": "SysAdminOperation/Id", "op": "eq", "value": "<operation-guid>" } ] },
+  "select": ["Id", "SysAdminOperationId", "SysAdminUnitId", "CanExecute", "Position"]
+}
+\`\`\`
+
+### 7. Remove a specific grant row
+
+Use the row Id from step 6:
+
+\`\`\`json
+{ "ids": ["<grantee-guid>"] }
+\`\`\`
+
+Call \`delete-admin-operation-grantee\`. Prefer toggling \`canExecute\` via \`set-admin-operation-grantee\` if the goal is to flip allow ↔ deny rather than fully remove the rule.
+
+### 8. Delete an operation entirely
+
+\`\`\`json
+{ "ids": ["<operation-guid-1>", "<operation-guid-2>"] }
+\`\`\`
+
+Call \`delete-admin-operation\`. RightsService cascades cleanup of related grantee rows.
+
+---
+
+## ❌ Common Mistakes
+
+- ❌ Trying to write to \`SysAdminOperation\` or \`SysAdminOperationGrantee\` via the generic OData \`create\` / \`update\` / \`delete\` tools — these tables are in \`DataServiceRestrictedModifySchemas\`.
+- ❌ Passing the all-zero GUID as \`id\` to \`upsert-admin-operation\` to "create" — RightsService rejects it. Omit \`id\` and let the tool generate a fresh one.
+- ❌ Using \`ContactId\` instead of \`SysAdminUnit.Id\` for grantees.
+- ❌ Forgetting to confirm with \`read\` that the change landed — RightsService responses return \`success: true\` only when the underlying entity actually saved.
+- ❌ Granting the operation to many units one by one — pass the full \`adminUnitIds\` array in a single call.
+- ❌ Filtering \`SysAdminOperationGrantee\` by the raw \`SysAdminOperationId\` / \`SysAdminUnitId\` columns — Creatio OData returns HTTP 500 for those. Use the navigation property syntax \`SysAdminOperation/Id\` / \`SysAdminUnit/Id\`.
+
+---
+
+## ✅ Final Checklist
+
+Before reporting a system-operation change as done:
+- [ ] Used \`SysAdminOperation\` / \`SysAdminOperationGrantee\` only for reading.
+- [ ] Used \`upsert-admin-operation\` / \`delete-admin-operation\` for catalog writes.
+- [ ] Used \`set-admin-operation-grantee\` / \`delete-admin-operation-grantee\` for grants.
+- [ ] Resolved each principal through \`SysAdminUnit\` (Id, not ContactId).
+- [ ] Re-read the affected rows to confirm the change landed.
+`.trim();
+
+export const ADMIN_OPERATION_PROMPT = {
+	name: 'admin-operation-guide',
+	title: 'Creatio System Operations (SysAdminOperation) Guide',
+	description:
+		'How to manage SysAdminOperation and SysAdminOperationGrantee via the dedicated RightsService tools (upsert/delete operation, set/delete grantee), with reads still routed through the standard OData read tool',
+	argsSchema: {},
+	callback: () => ({
+		messages: [
+			{
+				role: 'user' as const,
+				content: { type: 'text' as const, text: ADMIN_OPERATION_GUIDE },
+			},
+		],
+	}),
+};
+
 export const ALL_PROMPTS = [
 	CREATE_ACTIVITY_PROMPT,
 	DATETIME_PROMPT,
 	CONTACTID_PROMPT,
 	TAGGING_PROMPT,
 	SYS_SETTINGS_PROMPT,
+	FEATURE_TOGGLE_PROMPT,
+	ADMIN_OPERATION_PROMPT,
 ] as const;

package/src/server/mcp/server.ts

@@ -12,10 +12,16 @@ import { NAME, VERSION } from '../../version';
 import { buildFilterFromStructured } from './filters';
 import { ALL_PROMPTS } from './prompts-data';
 import {
+	callConfigurationServiceDescriptor,
+	callConfigurationServiceInput,
 	createDescriptor,
 	createInput,
 	createSysSettingDescriptor,
 	createSysSettingInput,
+	deleteAdminOperationDescriptor,
+	deleteAdminOperationGranteeDescriptor,
+	deleteAdminOperationGranteeInput,
+	deleteAdminOperationInput,
 	deleteDescriptor,
 	deleteInput,
 	describeEntityDescriptor,
@@ -30,12 +36,18 @@ import {
 	querySysSettingsInput,
 	readDescriptor,
 	readInput,
+	refreshFeatureCacheDescriptor,
+	refreshFeatureCacheInput,
+	setAdminOperationGranteeDescriptor,
+	setAdminOperationGranteeInput,
 	setSysSettingsValueDescriptor,
 	setSysSettingsValueInput,
 	updateDescriptor,
 	updateInput,
 	updateSysSettingDefinitionDescriptor,
 	updateSysSettingDefinitionInput,
+	upsertAdminOperationDescriptor,
+	upsertAdminOperationInput,
 } from './tools-data';
 
 type ToolHandler = (payload: any) => Promise<any>;
@@ -216,6 +228,9 @@ export class Server {
 		);
 		if (!this._readonly) {
 			const process = this._engines.process;
+			const feature = this._engines.feature;
+			const adminOperation = this._engines.adminOperation;
+			const configuration = this._engines.configuration;
 			this._registerHandlerWithDescriptor(
 				'create',
 				createDescriptor,
@@ -301,6 +316,102 @@ export class Server {
 					};
 				}),
 			);
+			this._registerHandlerWithDescriptor(
+				'refresh-feature-cache',
+				refreshFeatureCacheDescriptor,
+				withValidation(refreshFeatureCacheInput, async ({ featureCode }) => {
+					const result = await feature.clearFeaturesCache(featureCode);
+					return {
+						content: [
+							{
+								type: 'text',
+								text: JSON.stringify(result, null, 2),
+							},
+						],
+					};
+				}),
+			);
+			this._registerHandlerWithDescriptor(
+				'upsert-admin-operation',
+				upsertAdminOperationDescriptor,
+				withValidation(upsertAdminOperationInput, async ({ id, name, code, description }) => {
+					const result = await adminOperation.upsertAdminOperation({
+						...(id !== undefined ? { id } : {}),
+						name,
+						code,
+						...(description !== undefined ? { description } : {}),
+					});
+					return {
+						content: [
+							{ type: 'text', text: JSON.stringify(result, null, 2) },
+						],
+					};
+				}),
+			);
+			this._registerHandlerWithDescriptor(
+				'delete-admin-operation',
+				deleteAdminOperationDescriptor,
+				withValidation(deleteAdminOperationInput, async ({ ids }) => {
+					const result = await adminOperation.deleteAdminOperation(ids);
+					return {
+						content: [
+							{ type: 'text', text: JSON.stringify(result, null, 2) },
+						],
+					};
+				}),
+			);
+			this._registerHandlerWithDescriptor(
+				'set-admin-operation-grantee',
+				setAdminOperationGranteeDescriptor,
+				withValidation(
+					setAdminOperationGranteeInput,
+					async ({ adminOperationId, adminUnitIds, canExecute }) => {
+						const result = await adminOperation.setAdminOperationGrantee({
+							adminOperationId,
+							adminUnitIds,
+							canExecute,
+						});
+						return {
+							content: [
+								{ type: 'text', text: JSON.stringify(result, null, 2) },
+							],
+						};
+					},
+				),
+			);
+			this._registerHandlerWithDescriptor(
+				'delete-admin-operation-grantee',
+				deleteAdminOperationGranteeDescriptor,
+				withValidation(deleteAdminOperationGranteeInput, async ({ ids }) => {
+					const result = await adminOperation.deleteAdminOperationGrantee(ids);
+					return {
+						content: [
+							{ type: 'text', text: JSON.stringify(result, null, 2) },
+						],
+					};
+				}),
+			);
+			this._registerHandlerWithDescriptor(
+				'call-configuration-service',
+				callConfigurationServiceDescriptor,
+				withValidation(
+					callConfigurationServiceInput,
+					async ({ service, method, httpMethod, body, query }) => {
+						const result = await configuration.call({
+							service,
+							method,
+							httpMethod,
+							...(body !== undefined ? { body } : {}),
+							...(query !== undefined ? { query } : {}),
+						});
+						return {
+							content: [
+								{ type: 'text', text: JSON.stringify(result, null, 2) },
+							],
+						};
+					},
+				),
+			);
 		}
 	}