mc8yp 2.7.0 → 2.7.2

package/README.md

@@ -18,6 +18,7 @@ Operators stay in control through per-connection **restrictions** and **allow ru
 
 1. mc8yp discovers every microservice installed on the tenant that declares an OpenAPI spec, and derives typed method namespaces from those alongside the bundled Core (+ DTM) specs.
 2. Inside a `codemode` run, the agent finds the right method with `codemode.search`, inspects its exact input/output types with `codemode.describe`, and reads prose documentation (domain query languages, parameter syntax) with `docs.search`/`docs.read`.
+   `codemode.describe` works at three altitudes: no target lists the namespaces on this tenant, `describe("<namespace>")` lists every method in one namespace one line each — the callable target (`c8y.getAlarmCollectionResource`), `METHOD /path`, summary, no types — and `describe("<namespace>.<method>")` renders the full input/output types. The namespace listing is the survey step for when search keeps missing a domain's vocabulary; all ~250 core methods cost roughly 7k tokens, which is why full types stay method-level.
 3. In the same run, the agent calls the live Cumulocity API through the derived methods (`c8y.<method>({ ... })`). The namespaces are the complete surface — there is no raw-request escape hatch.
 4. mc8yp enforces configured restrictions and allow rules before any request leaves the host — blocked operations are also omitted from discovery entirely.
 
@@ -61,10 +62,46 @@ Behaviour worth knowing:
 - **The agent is told which namespaces are external.** `codemode.describe()` labels them `EXTERNAL MCP server at <url> — configured for this connection, NOT part of this tenant`, and the per-method describe repeats it. Whether a tenant namespace is backed by OpenAPI or MCP stays hidden (an implementation detail the agent cannot act on); tenant-vs-third-party is a data boundary it must be able to report on.
 - **Tool lists are fetched on first use and cached per MCP session**, then dropped 15 minutes after last use or immediately when the client closes its session cleanly. Rotating a token or changing a URL mid-session re-handshakes.
 - **A malformed entry fails the request** (HTTP 400 in server mode, a startup error in CLI) rather than silently leaving the agent without a namespace it was supposed to have. A well-formed but _unreachable_ server is reported in the `codemode.describe()` overview and retried on the next call.
-- **The tenant wins name collisions.** An external entry whose `name` matches a tenant namespace is skipped, so a header cannot shadow a real service.
+- **The tenant wins name collisions.** An external entry whose `name` matches a tenant namespace is skipped, so a header cannot shadow a real service. That skip is silent to the caller — use `POST /resolve-mcp-servers` (below) to catch it while configuring rather than discovering it as a missing namespace at run time.
 - **Egress is unrestricted by design.** The URL is used as given — any host, no allowlist, no private-range filtering. The header is part of the connection's trusted configuration (the sandbox cannot set it), but the consequence is that whoever can set headers on the deployed microservice can make it issue requests to any address it can reach, including tenant-internal ones. Front the deployment accordingly.
 - Path-based restriction/allow rules do **not** apply to these namespaces, same as for tenant-discovered MCP tools (see [Access policy](#access-policy)).
 
+#### Checking a configuration before you store it — `POST /resolve-mcp-servers`
+
+Whoever builds that header — a tenant admin UI, a deployment script — cannot answer three things on its own: which namespace an entry gets, whether that namespace is free, and whether the server actually answers with its credentials. This route answers all three in one call, so no consumer has to reimplement mc8yp's namespace rules or its MCP handshake:
+
+```http
+POST /service/mc8yp-server/resolve-mcp-servers
+Content-Type: application/json
+
+{ "servers": [{ "name": "MaStR registry", "url": "https://mastr.example/mcp", "token": "…" }] }
+```
+
+```jsonc
+{
+  "tenantUrl": "https://…cumulocity.com",
+  "tenantId": "t123",
+  "tenantNamespaces": ["c8y", "dtm", "knowledge_base_ms"], // null = the check could not run, see `warnings`
+  "warnings": [],
+  "servers": [
+    {
+      "name": "MaStR registry",
+      "namespace": "MaStR_registry", // derived — store THIS and send it in the header from now on
+      "status": "ok",                // ok | invalid | namespace-taken | unreachable
+      "server": { "name": "mastr-mcp", "version": "1.0.0" },
+      "tools": [{ "name": "search_units", "description": "…" }]
+    }
+  ]
+}
+```
+
+- **`name` may be free-form here.** It is sanitized into the namespace exactly as a contextPath is (`MaStR registry` → `MaStR_registry`, the same rule that makes `knowledge-base-ms` into `knowledge_base_ms`). An identifier passes through unchanged.
+- **`status` is the field to branch on**, and `namespace-taken` is the interesting one: reserved name, a namespace this tenant already holds, or a duplicate inside the same request. That is the collision that would otherwise be a silent skip at run time — `namespaceTakenBy` says who holds it. Tools are still reported for a taken entry, so renaming is the only fix needed.
+- **The header contract does not change.** Derivation is a configure-time convenience: resolve once, store the `namespace` you got back, keep sending it verbatim. The agent-visible namespace stays stable even if the derivation is refined later.
+- **Validation is the header's own**, so this route cannot green-light an entry the header would then 400.
+- **Nothing is persisted, and nothing is cached.** mc8yp holds no external server configuration of its own, and the handshake bypasses the per-session tool-list cache so the answer always reflects the credentials as sent.
+- Requires user auth (Authorization header or session cookie), like `POST /refresh-apis`.
+
 ## Two ways to run it
 
 - **Microservice mode** (recommended for production) — deploy inside Cumulocity IoT, expose `/mcp`, integrate with [AI Agent Manager](https://cumulocity.com/docs/ai/aim-introduction/). Auth comes from the request and the service user.

package/dist/{add-CO4XaqJr.mjs → add-CROAKWK4.mjs}

@@ -1,4 +1,5 @@
-import { a as parse, c as url, f as __commonJSMin, i as setStoredC8yAuth, l as consola, o as pipe, r as getStoredC8yAuth, s as string, t as cleanTenantUrl, u as defineCommand } from "./cli.mjs";
+import { t as __commonJSMin } from "./rolldown-runtime-CMFfr-1z.mjs";
+import { a as parse, c as url, i as setStoredC8yAuth, l as consola, o as pipe, r as getStoredC8yAuth, s as string, t as cleanTenantUrl, u as defineCommand } from "./cli.mjs";
 import process$1, { exit, stdin, stdout } from "node:process";
 import { styleText } from "node:util";
 import "node:path";
@@ -285,7 +286,7 @@ function wrapAnsi(string, columns, options) {
 	return String(string).normalize().split(CRLF_OR_LF).map((line) => exec(line, columns, options)).join("\n");
 }
 //#endregion
-//#region node_modules/.pnpm/@clack+core@1.4.1/node_modules/@clack/core/dist/index.mjs
+//#region node_modules/.pnpm/@clack+core@1.4.3/node_modules/@clack/core/dist/index.mjs
 var import_src = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	const ESC = "\x1B";
 	const CSI = `${ESC}[`;
@@ -339,7 +340,7 @@ var import_src = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	};
 })))();
 const settings = {
-	actions: new Set([
+	actions: /* @__PURE__ */ new Set([
 		"up",
 		"down",
 		"left",
@@ -593,7 +594,7 @@ var V = class {
 		}
 	}
 };
-var o = class extends V {
+let u$1 = class u extends V {
 	_mask = "•";
 	get cursor() {
 		return this._cursor;
@@ -605,8 +606,8 @@ var o = class extends V {
 		if (this.state === "submit" || this.state === "cancel") return this.masked;
 		const t = this.userInput;
 		if (this.cursor >= t.length) return `${this.masked}${styleText(["inverse", "hidden"], "_")}`;
-		const s = this.masked, r = s.slice(0, this.cursor), e = s.slice(this.cursor);
-		return `${r}${styleText("inverse", e[0])}${e.slice(1)}`;
+		const s = this.masked, r = s.slice(0, this.cursor), i = s.slice(this.cursor, this.cursor + 1), o = s.slice(this.cursor + 1);
+		return `${r}${styleText("inverse", i)}${o}`;
 	}
 	clear() {
 		this._clearUserInput();
@@ -614,30 +615,43 @@ var o = class extends V {
 	constructor({ mask: t, ...s }) {
 		super(s), this._mask = t ?? "•", this.on("userInput", (r) => {
 			this._setValue(r);
+		}), this.on("finalize", () => {
+			this.value === void 0 && (this.value = "");
 		});
 	}
 };
 //#endregion
-//#region node_modules/.pnpm/@clack+prompts@1.5.1/node_modules/@clack/prompts/dist/index.mjs
+//#region node_modules/.pnpm/@clack+prompts@1.7.0/node_modules/@clack/prompts/dist/index.mjs
 function isUnicodeSupported() {
 	if (process$1.platform !== "win32") return process$1.env.TERM !== "linux";
 	return Boolean(process$1.env.CI) || Boolean(process$1.env.WT_SESSION) || Boolean(process$1.env.TERMINUS_SUBLIME) || process$1.env.ConEmuTask === "{cmd::Cmder}" || process$1.env.TERM_PROGRAM === "Terminus-Sublime" || process$1.env.TERM_PROGRAM === "vscode" || process$1.env.TERM === "xterm-256color" || process$1.env.TERM === "alacritty" || process$1.env.TERMINAL_EMULATOR === "JetBrains-JediTerm";
 }
-const unicode = isUnicodeSupported(), unicodeOr = (e, o) => unicode ? e : o, S_STEP_ACTIVE = unicodeOr("◆", "*"), S_STEP_CANCEL = unicodeOr("■", "x"), S_STEP_ERROR = unicodeOr("▲", "x"), S_STEP_SUBMIT = unicodeOr("◇", "o"), S_BAR = unicodeOr("│", "|"), S_BAR_END = unicodeOr("└", "—"), S_PASSWORD_MASK = unicodeOr("▪", "•"), symbol = (e) => {
-	switch (e) {
+const unicode = isUnicodeSupported();
+const unicodeOr = (o, e) => unicode ? o : e;
+const S_STEP_ACTIVE = unicodeOr("◆", "*");
+const S_STEP_CANCEL = unicodeOr("■", "x");
+const S_STEP_ERROR = unicodeOr("▲", "x");
+const S_STEP_SUBMIT = unicodeOr("◇", "o");
+const S_BAR = unicodeOr("│", "|");
+const S_BAR_END = unicodeOr("└", "—");
+const S_PASSWORD_MASK = unicodeOr("▪", "•");
+const symbol = (o) => {
+	switch (o) {
 		case "initial":
 		case "active": return styleText("cyan", S_STEP_ACTIVE);
 		case "cancel": return styleText("red", S_STEP_CANCEL);
 		case "error": return styleText("yellow", S_STEP_ERROR);
 		case "submit": return styleText("green", S_STEP_SUBMIT);
 	}
-}, cancel = (o = "", t) => {
+};
+`${styleText("dim", "↑/↓")}`, `${styleText("dim", "Space:")}`, `${styleText("dim", "Enter:")}`;
+const cancel = (o = "", t) => {
 	const i = t?.output ?? process.stdout, e = t?.withGuide ?? settings.withGuide ? `${styleText("gray", S_BAR_END)}  ` : "";
 	i.write(`${e}${styleText("red", o)}
 
 `);
 };
-const password = (r) => new o({
+const password = (r) => new u$1({
 	validate: r.validate,
 	mask: r.mask ?? S_PASSWORD_MASK,
 	signal: r.signal,
@@ -664,6 +678,7 @@ ${e ? styleText("cyan", S_BAR_END) : ""}
 		}
 	}
 }).prompt();
+`${styleText("dim", "↑/↓")}`, `${styleText("dim", "Enter:")}`;
 `${styleText("gray", S_BAR)}`;
 //#endregion
 //#region src/cli/subcommands/subcommands/add.ts