mc8yp 2.5.0 → 2.5.2

package/dist/cli.mjs

@@ -1545,7 +1545,7 @@ const consola = createConsola();
 //#endregion
 //#region package.json
 var name = "mc8yp";
-var version = "2.5.0";
+var version = "2.5.2";
 var description$1 = "Cumulocity IoT MCP Server - Model Context Protocol integration for IoT device management";
 //#endregion
 //#region \0virtual:core-openapi
@@ -1995,7 +1995,11 @@ const specs = Object.freeze([
 				},
 				"/alarm/alarms/upsert": { "post": {
 					"operationId": "postAlarmUpsertResource",
-					"parameters": [{ "$ref": "#/components/parameters/acceptHeader" }, { "$ref": "#/components/parameters/processingModeHeader" }],
+					"parameters": [
+						{ "$ref": "#/components/parameters/acceptHeader" },
+						{ "$ref": "#/components/parameters/processingModeHeader" },
+						{ "$ref": "#/components/parameters/queryParam_alarm_incrementCount" }
+					],
 					"tags": ["Alarms"],
 					"summary": "Create or update an alarm",
 					"description": "Upserts an alarm based on the provided representation. If a non-cleared alarm with the same type and source already exists, it is updated; otherwise, a new alarm is created.\n\n<section><h5>Required roles</h5>\nROLE_ALARM_ADMIN <b>OR</b> owner of the source <b>OR</b> ALARM_ADMIN permission on the source\n</section>\n",
@@ -2016,11 +2020,11 @@ const specs = Object.freeze([
 					"responses": {
 						"200": {
 							"description": "An existing alarm was updated.",
-							"content": { "application/vnd.com.nsn.cumulocity.alarm+json": { "schema": { "$ref": "#/components/schemas/alarm" } } }
+							"content": { "application/vnd.com.nsn.cumulocity.alarmUpsertResponse+json": { "schema": { "$ref": "#/components/schemas/alarmUpsertResponse" } } }
 						},
 						"201": {
 							"description": "An alarm was created.",
-							"content": { "application/vnd.com.nsn.cumulocity.alarm+json": { "schema": { "$ref": "#/components/schemas/alarm" } } }
+							"content": { "application/vnd.com.nsn.cumulocity.alarmUpsertResponse+json": { "schema": { "$ref": "#/components/schemas/alarmUpsertResponse" } } }
 						}
 					}
 				} },
@@ -5112,6 +5116,55 @@ const specs = Object.freeze([
 						"responses": { "204": { "description": "A tenant was unsubscribed from an application." } }
 					}
 				},
+				"/tenant/tenants/{tenantId}/applications/restricted-roles": {
+					"parameters": [{ "$ref": "#/components/parameters/tenantId" }],
+					"get": {
+						"operationId": "getTenantApplicationRestrictedRolesResource",
+						"tags": ["Tenant applications"],
+						"summary": "Retrieve the microservice applications restricted roles list",
+						"description": "Retrieve the list of roles that are restricted from being requested by microservices subscribed to or owned by the tenant.\n\n<section><h5>Required roles</h5>\n(ROLE_TENANT_MANAGEMENT_READ <b>OR</b> ROLE_TENANT_ADMIN) <b>AND</b> (the current tenant is its parent <b>OR</b> is the management tenant <b>OR</b> is the current tenant)\n</section>\n",
+						"responses": { "200": { "$ref": "#/components/responses/tenantRestrictedRolesFound" } }
+					},
+					"put": {
+						"operationId": "putTenantApplicationRestrictedRolesResource",
+						"parameters": [{ "$ref": "#/components/parameters/acceptHeader" }],
+						"tags": ["Tenant applications"],
+						"summary": "Replace the microservice applications restricted roles list",
+						"description": "Replace tenant's restricted roles list entirely. Microservices that are subscribed to or owned by the tenant cannot request any role on this list.\nOnly roles that actually exist in the system are accepted. Duplicate roles in the request body are silently deduplicated.\n\n<section><h5>Required roles</h5>\n(ROLE_TENANT_MANAGEMENT_ADMIN <b>OR</b> ROLE_TENANT_MANAGEMENT_UPDATE <b>OR</b> ROLE_TENANT_ADMIN) <b>AND</b> (the current tenant is its parent <b>OR</b> is the management tenant <b>OR</b> is the current tenant)\n</section>\n",
+						"requestBody": {
+							"required": true,
+							"content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestrictedRoles" } } }
+						},
+						"responses": { "200": {
+							"description": "The restricted roles list was replaced and the updated tenant is sent in the response.",
+							"content": { "application/vnd.com.nsn.cumulocity.tenant+json": { "schema": { "$ref": "#/components/schemas/tenantWithRestrictedRoles" } } }
+						} }
+					}
+				},
+				"/tenant/tenants/{tenantId}/applications/restricted-roles/{roleId}": {
+					"parameters": [{ "$ref": "#/components/parameters/tenantId" }, { "$ref": "#/components/parameters/roleId" }],
+					"post": {
+						"operationId": "postTenantApplicationRestrictedRoleResource",
+						"parameters": [{ "$ref": "#/components/parameters/acceptHeader" }],
+						"tags": ["Tenant applications"],
+						"summary": "Add a role to the microservice restricted roles list",
+						"description": "Add a single role to tenant's restricted roles list. Microservices that are subscribed to or owned by the tenant cannot request roles on this list.\nIf the role is already in the list, the request is accepted and the list remains unchanged.\n\n<section><h5>Required roles</h5>\n(ROLE_TENANT_MANAGEMENT_ADMIN <b>OR</b> ROLE_TENANT_MANAGEMENT_UPDATE <b>OR</b> ROLE_TENANT_ADMIN) <b>AND</b> (the current tenant is its parent <b>OR</b> is the management tenant <b>OR</b> is the current tenant)\n</section>\n",
+						"responses": { "200": {
+							"description": "The role was added and the updated tenant is sent in the response.",
+							"content": { "application/vnd.com.nsn.cumulocity.tenant+json": { "schema": { "$ref": "#/components/schemas/tenantWithMoreRestrictedRoles" } } }
+						} }
+					},
+					"delete": {
+						"operationId": "deleteTenantApplicationRestrictedRoleResource",
+						"tags": ["Tenant applications"],
+						"summary": "Remove a role from the microservice restricted roles list",
+						"description": "Remove a single role from tenant's restricted roles list. Microservices that are subscribed to or owned by the tenant cannot request any role on this list.\n\n<section><h5>Required roles</h5>\n(ROLE_TENANT_MANAGEMENT_ADMIN <b>OR</b> ROLE_TENANT_MANAGEMENT_UPDATE <b>OR</b> ROLE_TENANT_ADMIN) <b>AND</b> (the current tenant is its parent <b>OR</b> is the management tenant <b>OR</b> is the current tenant)\n</section>\n",
+						"responses": { "200": {
+							"description": "The role was removed and the updated tenant is sent in the response.",
+							"content": { "application/vnd.com.nsn.cumulocity.tenant+json": { "schema": { "$ref": "#/components/schemas/tenantWithRestrictedRoles" } } }
+						} }
+					}
+				},
 				"/tenant/tenants/{tenantId}/trusted-certificates": {
 					"parameters": [{ "$ref": "#/components/parameters/tenantId" }],
 					"post": {
@@ -7010,6 +7063,16 @@ const specs = Object.freeze([
 							"example": "2021-03-30"
 						}
 					},
+					"queryParam_alarm_incrementCount": {
+						"name": "incrementCount",
+						"in": "query",
+						"description": "When set to `true`, the `count` property of an existing alarm is incremented during upsert.",
+						"schema": {
+							"type": "boolean",
+							"default": false,
+							"example": true
+						}
+					},
 					"queryParam_application_type": {
 						"name": "type",
 						"in": "query",
@@ -8363,6 +8426,10 @@ const specs = Object.freeze([
 							}
 						} }
 					},
+					"tenantRestrictedRolesFound": {
+						"description": "The request has succeeded and the restricted roles list is sent in the response.",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestrictedRoles" } } }
+					},
 					"tenantApplicationReferenceFound": {
 						"description": "The request has succeeded and the tenant applications are sent in the response.",
 						"content": { "application/vnd.com.nsn.cumulocity.applicationreferencecollection+json": { "schema": { "$ref": "#/components/schemas/ApplicationReferenceCollection" } } }
@@ -8725,6 +8792,57 @@ const specs = Object.freeze([
 						},
 						"additionalProperties": { "description": "It is possible to add an arbitrary number of additional properties as a list of key-value pairs, for example, `\"property1\": {}`, `\"property2\": \"value\"`. These properties are known as custom fragments and can be of any type, for example, object or string. Each custom fragment is identified by a unique name.\n\nReview [Getting started > Technical concepts > Cumulocity's domain model > Inventory > Fragments > Naming conventions of fragments](https://www.cumulocity.com/docs/concepts/domain-model/#naming-conventions-of-fragments) in the Cumulocity user documentation as there are characters that can not be used when naming custom fragments.\n" }
 					},
+					"alarmUpsertResponse": {
+						"type": "object",
+						"required": ["alarm", "previousState"],
+						"properties": {
+							"alarm": {
+								"description": "The alarm as it exists after the upsert operation.",
+								"allOf": [{ "$ref": "#/components/schemas/alarm" }]
+							},
+							"previousState": {
+								"description": "A snapshot of the alarm as it existed immediately before the upsert. This field is `null` when the upsert\ncreated a new alarm, and a full alarm representation when an existing alarm was updated.\n",
+								"nullable": true,
+								"allOf": [{ "$ref": "#/components/schemas/alarm" }]
+							}
+						},
+						"example": {
+							"alarm": {
+								"count": 1,
+								"creationTime": "2020-03-19T12:16:31.586Z",
+								"lastUpdated": "2020-03-20T13:41:39.678Z",
+								"id": "20200301",
+								"self": "https://<TENANT_DOMAIN>/alarm/alarms/20200301",
+								"severity": "MAJOR",
+								"source": {
+									"id": "251982",
+									"name": "My tracking device",
+									"self": "https://<TENANT_DOMAIN>/inventory/managedObjects/251982"
+								},
+								"status": "ACTIVE",
+								"text": "No data received from the device within the required interval.",
+								"time": "2020-03-19T00:00:00.000Z",
+								"type": "c8y_UnavailabilityAlarm"
+							},
+							"previousState": {
+								"count": 1,
+								"creationTime": "2020-03-19T12:16:31.586Z",
+								"lastUpdated": "2020-03-19T12:16:31.586Z",
+								"id": "20200301",
+								"self": "https://<TENANT_DOMAIN>/alarm/alarms/20200301",
+								"severity": "MINOR",
+								"source": {
+									"id": "251982",
+									"name": "My tracking device",
+									"self": "https://<TENANT_DOMAIN>/inventory/managedObjects/251982"
+								},
+								"status": "ACKNOWLEDGED",
+								"text": "No data received from the device within the required interval.",
+								"time": "2020-03-19T00:00:00.000Z",
+								"type": "c8y_UnavailabilityAlarm"
+							}
+						}
+					},
 					"auditApiResource": {
 						"type": "object",
 						"properties": {
@@ -11814,6 +11932,71 @@ const specs = Object.freeze([
 							"status": "ACTIVE"
 						}
 					},
+					"tenantWithRestrictedRoles": {
+						"allOf": [{ "$ref": "#/components/schemas/tenant" }],
+						"example": {
+							"id": "t07007007",
+							"self": "https://<TENANT_DOMAIN>/tenant/tenants/t07007007",
+							"adminEmail": "john@doe.com",
+							"adminName": "johndoe",
+							"allowCreateTenants": false,
+							"applications": {
+								"self": "https://<TENANT_DOMAIN>/tenant/tenants/t07007007/applications",
+								"references": []
+							},
+							"company": "ACME AG",
+							"contactName": "John Doe",
+							"contactPhone": "+52 333 567 1234",
+							"creationTime": "2020-05-02T20:00:29.907Z",
+							"customProperties": { "msForbiddenRoles": ["ROLE_TENANT_ADMIN", "ROLE_TENANT_MANAGEMENT_ADMIN"] },
+							"domain": "mytenant.cumulocity.com",
+							"ownedApplications": {
+								"self": "https://<TENANT_DOMAIN>/tenant/tenants/t07007007/applications",
+								"references": []
+							},
+							"parent": "t1511681",
+							"status": "ACTIVE"
+						}
+					},
+					"tenantWithMoreRestrictedRoles": {
+						"allOf": [{ "$ref": "#/components/schemas/tenant" }],
+						"example": {
+							"id": "t07007007",
+							"self": "https://<TENANT_DOMAIN>/tenant/tenants/t07007007",
+							"adminEmail": "john@doe.com",
+							"adminName": "johndoe",
+							"allowCreateTenants": false,
+							"applications": {
+								"self": "https://<TENANT_DOMAIN>/tenant/tenants/t07007007/applications",
+								"references": []
+							},
+							"company": "ACME AG",
+							"contactName": "John Doe",
+							"contactPhone": "+52 333 567 1234",
+							"creationTime": "2020-05-02T20:00:29.907Z",
+							"customProperties": { "msForbiddenRoles": [
+								"ROLE_TENANT_ADMIN",
+								"ROLE_TENANT_MANAGEMENT_ADMIN",
+								"ROLE_TENANT_ALARM_ADMIN"
+							] },
+							"domain": "mytenant.cumulocity.com",
+							"ownedApplications": {
+								"self": "https://<TENANT_DOMAIN>/tenant/tenants/t07007007/applications",
+								"references": []
+							},
+							"parent": "t1511681",
+							"status": "ACTIVE"
+						}
+					},
+					"RestrictedRoles": {
+						"description": "An array of role names that are restricted from being requested by microservices in the tenant.",
+						"type": "array",
+						"items": {
+							"type": "string",
+							"minLength": 1
+						},
+						"example": ["ROLE_TENANT_ADMIN", "ROLE_TENANT_MANAGEMENT_ADMIN"]
+					},
 					"option": {
 						"description": "A tuple storing tenant configuration.",
 						"type": "object",
@@ -57857,14 +58040,6 @@ async () => {
 }
 \`\`\`
 
-## Efficient Querying
-
-Parameters with \`schema.format === 'c8y:query'\` accept Cumulocity Query Language. Use \`queryBuilder()\` — injected into every execute sandbox — to construct the query string. Always prefer server-side filtering over fetching all pages: max \`pageSize\` is 2000 and tenants can have millions of objects.
-
-Key operators: \`eq\`, \`gt\`, \`ge\`, \`lt\`, \`le\`, \`and\`, \`or\`, \`not\`, \`has()\`, \`hasany()\`, \`bygroupid()\`, \`isinhierarchyof()\`. **There is no \`like\` or \`in\`** — use \`eq\` with \`*\` wildcards for substring matches (\`name eq '*pattern*'\`, case-insensitive), and \`or\` chains for multi-value ID matching. When the ID list is large, fetch all and join in memory instead.
-
-For the full syntax reference, run the query tool: \`() => coreSpec.tags.find(t => t.name === 'Query language')?.description\`
-
 ${getRuntimeSection()}
 
 ${getOpenApiSection()}
@@ -131836,22 +132011,6 @@ function createCumulocitySafeFetch(tenantUrl, authHeaders, restrictions = [], al
 		allowCompressedResponses: false
 	});
 }
-const QUERY_BUILDER_SOURCE = `\
-/**
- * Builds a Cumulocity query string for parameters of name "query" or with schema.format "c8y:query".
- * Use to filter server-side. This is always the preferred method if query parameters are present (max pageSize 2000).
- * No like/in operators — use eq with * wildcards (name eq '*pat*') or or-chains for multi-value.
- * To get query syntax documentation run query tool → () => coreSpec.tags.find(t => t.name === 'Query language')?.description
- * Use the path exactly as it appears in serviceSpecs — never prepend /service/<key>.
- * @example /inventory/managedObjects?\${queryBuilder({ filter: "type eq 'c8y_Firmware'" })}
- * @example <path>?\${queryBuilder({ filter: "name eq '*Ctrl*'", orderby: "name asc" })}
- */
-function queryBuilder({ filter, orderby, pageSize = 2000 } = {}) {
-  const parts = []
-  if (filter) parts.push('$filter=' + filter)
-  if (orderby) parts.push('$orderby=' + orderby)
-  return (parts.length ? 'query=' + parts.join(' ') + '&' : '') + 'pageSize=' + pageSize
-}`;
 function normalizeCode(functionCode) {
 	return functionCode.trim().replace(/^```(?:js|javascript|ts|typescript)?\s*/i, "").replace(/\s*```$/, "").trim();
 }
@@ -131943,7 +132102,6 @@ async function execute(functionCode) {
 	const restrictions = c8yMcpServer.ctx.custom?.restrictions ?? [];
 	const allowRules = c8yMcpServer.ctx.custom?.allowRules ?? [];
 	const code = [
-		QUERY_BUILDER_SOURCE,
 		`const __mc8ypExecute = (${normalizeCode(functionCode)});`,
 		"if (typeof __mc8ypExecute !== \"function\") { throw new TypeError(\"Execute code must evaluate to a function.\") }",
 		"export default await __mc8ypExecute();"
@@ -137407,16 +137565,21 @@ function refreshApiSpecs(tenantId, client) {
 function getCachedDiscovery(tenantId) {
 	return cache.get(tenantId);
 }
+const APPLICATIONS_PAGE_SIZE = 100;
+const APPLICATIONS_MAX_PAGES = 50;
 /**
 * Fetch and return discovered specs for the given tenant.
 * Throws on fatal errors (applications listing); individual spec download
 * failures are skipped.
 *
-* Uses `applicationsByTenant/{tenantId}` (via `listByTenant`) rather than
-* the user-scoped `applicationsByUser` endpoint so the call works with
-* service-user credentials — service users cannot call /user/currentUser,
-* which the user-scoped endpoint depends on. The tenantId is always known
-* at the call site (it is the discovery cache key).
+* Uses `/application/applications?tenant=<id>&type=MICROSERVICE`, paginated.
+* The `tenant` filter covers apps the tenant owns or is subscribed to, and
+* `type=MICROSERVICE` drops HOSTED/EXTERNAL apps — they can never contribute
+* a spec anyway (spec download goes through `/service/<contextPath>/`, which
+* only exists for microservices) and their large manifests were what made the
+* unpaginated response exceed gateway limits. The endpoint needs only
+* ROLE_APPLICATION_MANAGEMENT_READ and does not depend on /user/currentUser,
+* so it works with service-user credentials.
 *
 * All Cumulocity API calls go through the provided \@c8y/client. This module
 * never touches `fetch` directly so auth strategy choice (Basic, Bearer,
@@ -137425,9 +137588,19 @@ function getCachedDiscovery(tenantId) {
 * @param tenantId - Cumulocity tenant ID to list applications for
 */
 async function discoverApiSpecs(client, tenantId) {
-	let apps;
+	const apps = [];
 	try {
-		apps = (await client.application.listByTenant(tenantId, { pageSize: 2e3 })).data ?? [];
+		for (let currentPage = 1; currentPage <= APPLICATIONS_MAX_PAGES; currentPage++) {
+			const page = (await client.application.list({
+				tenant: tenantId,
+				type: "MICROSERVICE",
+				pageSize: APPLICATIONS_PAGE_SIZE,
+				currentPage,
+				withTotalPages: false
+			})).data ?? [];
+			apps.push(...page);
+			if (page.length < APPLICATIONS_PAGE_SIZE) break;
+		}
 	} catch (err) {
 		throw new Error(`Failed to fetch applications: ${c8yErrorSummary(err)}`);
 	}
@@ -140310,7 +140483,8 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 * deliberately browse all bundled snapshots regardless of installation,
 * use {@link getBundledOnlySpecs} (the CLI's no-tenant fallback).
 * @param discoveredSpecs Result of live API discovery for the tenant.
-* @param installedContextPaths Subscribed app context paths on the tenant.
+* @param installedContextPaths Context paths of microservices the tenant owns
+*   or is subscribed to (discovery filters to type=MICROSERVICE).
 */
 function resolveSpecs(discoveredSpecs, installedContextPaths) {
 	const specs = {};
@@ -140609,8 +140783,7 @@ async function getStoredC8yAuth() {
 }
 async function getCredentialsByTenantUrl(tenantUrl) {
 	const cleanedUrl = cleanTenantUrl(tenantUrl);
-	let entry = (await findCredentialsAsync(name, cleanedUrl))[0];
-	if (!entry) entry = (await findCredentialsAsync(name)).find((e) => cleanTenantUrl(e.account) === cleanedUrl);
+	const entry = (await findCredentialsAsync(name)).find((e) => cleanTenantUrl(e.account) === cleanedUrl);
 	if (!entry) throw new Error(`No stored credentials found for tenant URL: ${cleanedUrl}`);
 	return parseStoredUserC8yAuth(entry.password, cleanedUrl);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mc8yp",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "type": "module",
   "description": "Cumulocity IoT MCP Server - Model Context Protocol integration for IoT device management",
   "keywords": [