@thalovant/mcp-server 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.5.3 — 2026-09-26
+
+- A tool error says what the API said, not only the SDK's one-line message. That line is cut at 160 characters, and a `platform_image_required` refusal names every image each refused key may be instead -- longer than that -- so the list a model needed to retry was the part cut off, and `refused_images`, `allowed_images` and `allowed_repositories` never reached it at all. The error text now goes on with `code:`, `detail:` (the whole sentence, when the first line had to shorten it) and `fields:`, every other member of the body as compact, redacted JSON. A value a validation error echoes back from the request is redacted there and never reaches the first line.
+- A `platform_image_required` or `plan_limit` 403 gets a hint that fits it instead of the general "Insufficient scopes" hint: granting a scope changes neither.
+- The status behind a hint is read from the SDK error's `statusCode`, not parsed out of its message.
+- Take `@thalovant/sdk` ^0.8.7, whose `ThalovantApiError` carries `code`, `detail` and `problem`. The shared `api-error-vectors.json` run here twice: through the SDK that resolves, recorded before it is asserted, and through a real tool call against the built server.
+- New `api-errors` capability in the parity contract, declared `required`.
+
+## 0.5.2 — 2026-09-19
+
+- Take `@thalovant/sdk` ^0.8.2, which ends an ask the hub refuses at once as a typed refusal rather than waiting out its deadline and reporting that the hub did not answer in time. This server implements no part of an ask, so the behaviour arrives with the dependency -- and the shared refusal vectors now run here, against whatever version actually resolves, beside the conversation carry, the hive kinds and the binary frames.
+- The parity contract's `refusal` capability moves from `planned` to `required`. It was the last capability holding the reference's release gate.
+
 ## 0.5.1 — 2026-09-13
 
 - Expose advisory reply claim status and first-seen pipeline/skill identifiers, with shared conformance for fallback, mixed stages, legacy hubs and malformed stamps. Existing reply construction remains compatible.

package/README.md

@@ -1,5 +1,7 @@
 # Thalovant MCP Server
 
+[![M8ven Live Monitored](https://m8ven.ai/badge/mcp/thalovant-thalovant-mcp-1cyhb4)](https://m8ven.ai/mcp/thalovant-thalovant-mcp-1cyhb4)
+
 Public-ready MCP server for Thalovant control-plane and hub runtime APIs.
 
 It uses the official Thalovant Node.js SDK and the production MCP TypeScript SDK over stdio and Streamable HTTP, so it works with local MCP hosts such as Claude Desktop, Codex, Cursor, and remote MCP clients.
@@ -85,7 +87,7 @@ Grant fewer scopes for narrower deployments: a read-only assistant needs only `h
 
 `thalovant_list_hub_skills` returns the whole `GET /v1/hubs/{hub_id}/skills` envelope: `hub_id`, `runtime_group_id`, `observed_at`, `source`, the runtime's phase and message, and `data`, one row per skill (possibly empty) with `skill`, `title`, `marketplace_skill_id`, `package_name`, `source_type`, `install_source`, `version`, `version_pin`, `installed_version`, `observed_version`, `previous_version`, `latest_version`, `available_version`, `update_available`, `changelog`, `active`, `state`, the runtime's phase, message and last error, and `last_transition_at`. `state` is one of `pending`, `installed`, `failed`, `removing`, `drifted`, `quarantined`, or `unmanaged`; a change in progress shows as `pending`.
 
-Each write answers `202` with `operation_id`, `hub_id`, `runtime_group_id`, `skill`, `version` (`null` for a removal), `previous_version`, and `state` (`installing`, `updating`, or `removing`); pass `wait: true` to poll that operation every 2 s until it converges (`installed`, or `removed` for a removal; a `failed` or `timed_out` operation raises an error carrying its `error_message`), with a 120 s default `timeoutMs`, or follow it yourself with `thalovant_get_operation`. Installing a skill that is already installed at another version performs an update; the same version fails `409` with code `skill_version_already_installed`. A hub with no runtime group fails `404` with code `hub_without_runtime_group` (a plain `404` means an unknown hub or a skill that is not installed), and an unresolvable `latest` or an invalid version fails `422`. Errors are RFC 7807 problem bodies; the tool error keeps the short `message` and appends the root `code` in parentheses, for example `Thalovant API request failed with HTTP 409: Skill version already installed. (skill_version_already_installed)`.
+Each write answers `202` with `operation_id`, `hub_id`, `runtime_group_id`, `skill`, `version` (`null` for a removal), `previous_version`, and `state` (`installing`, `updating`, or `removing`); pass `wait: true` to poll that operation every 2 s until it converges (`installed`, or `removed` for a removal; a `failed` or `timed_out` operation raises an error carrying its `error_message`), with a 120 s default `timeoutMs`, or follow it yourself with `thalovant_get_operation`. Installing a skill that is already installed at another version performs an update; the same version fails `409` with code `skill_version_already_installed`. A hub with no runtime group fails `404` with code `hub_without_runtime_group` (a plain `404` means an unknown hub or a skill that is not installed), and an unresolvable `latest` or an invalid version fails `422`. Errors are RFC 7807 problem bodies; the tool error keeps the short `message`, which appends the root `code` in parentheses, for example `Thalovant API request failed with HTTP 409: Skill version already installed. (skill_version_already_installed)`, and then the code and the body's other fields (see [Tool Errors](#tool-errors)).
 
 Listing needs `hubs:inspect` (implied by `hubs:read`); the writes need `hubs:write` and a paid plan, and because scope is checked before plan a free-plan token sees `403`, never `402`. Hub-restricted tokens (a `hub_ids` allowlist) are honoured on all four routes. The server uses the published Node SDK hub-skill methods and preserves MCP cancellation checks during polling. A failed status read retains the accepted operation ID; use `thalovant_get_operation` with that ID instead of submitting the write again. No new poll starts at or after the polling deadline. That deadline does not cancel an HTTP request already in flight.
 
@@ -401,6 +403,31 @@ unknown (empty lists/strings), with explanatory notes. Intent language order is
 explicit and survives JSON key sorting. Each tool call retains its own identity
 lease; the server does not persist inventory or share a session across callers.
 
+## Tool Errors
+
+When the Thalovant API refuses a control-plane call, the tool result is an
+error whose text starts with the SDK's one-line message (which names the HTTP
+status and can be shortened) and then says what the API said, in full:
+
+```text
+Thalovant API request failed with HTTP 403: Only an administrator can run an image the platform does not release: bus may be one of ghcr.io/thalovant/ovos-messagebus:2026.09.2, ... (platform_image_required)
+code: platform_image_required
+detail: Only an administrator can run an image the platform does not release: bus may be one of ghcr.io/thalovant/ovos-messagebus:2026.09.2, ghcr.io/thalovant/ovos-messagebus:2026.09.3-alpha.1, ghcr.io/thalovant/ovos-messagebus:2026.08.7; core may be any tag or digest of ghcr.io/thalovant/ovos-core.
+fields: {"allowed_images":{"bus":[...],"core":[...]},"allowed_repositories":{"core":"ghcr.io/thalovant/ovos-core"},"component":"runtime_group","refused_images":{...}}
+```
+
+- `code` is the API's machine-readable code, when it sent one.
+- `detail` is the whole sentence, and appears only when the first line had to
+  shorten it.
+- `fields` is every other member of the error body as compact JSON (the
+  Problem+JSON `type`, `title`, `status` and `instance` are left out), with the
+  same secret redaction as every other tool output. A value a validation error
+  echoes back from the request is redacted there and never reaches the first
+  line. A plan refusal carries `resource`, `limit`, `used` and `plan` here.
+
+A hint may follow for statuses that need one. A `platform_image_required` or
+`plan_limit` 403 gets its own hint rather than the general scope hint.
+
 ## Request hints, embedded audio, and configuration merging
 
 `thalovant_ask` accepts `sttLang`, an ordered `pipeline`, and `location`

package/dist/api-error-output.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What a model reads when a control-plane call fails: the SDK's one-line
+ * message, then what the API actually said beside it.
+ *
+ * The message is bounded at 160 characters, and a structured refusal is
+ * usually longer than that -- a `platform_image_required` 403 names every
+ * image each refused key may be instead, and that list was the part cut off.
+ * So the code, the whole sentence (when the message line had to shorten it)
+ * and every other field of the body follow, as one compact JSON object.
+ * `redact` is the server's own secret redaction, applied to the fields: a
+ * validation error echoes back what it was sent.
+ *
+ * Returns undefined for anything that is not a `ThalovantApiError`.
+ */
+export declare function apiErrorText(error: unknown, redact: (value: unknown) => unknown): string | undefined;

package/dist/api-error-output.js

@@ -0,0 +1,54 @@
+import { ThalovantApiError } from "@thalovant/sdk";
+/**
+ * Problem+JSON members every refusal carries that say nothing the lines above
+ * them do not: the status is on the first line, and `type`/`title`/`instance`
+ * are the handler's own bookkeeping.
+ */
+const ENVELOPE = new Set(["type", "title", "status", "instance"]);
+/** A detail or a field list longer than this is cut, and says so. */
+const MAX_SECTION_CHARS = 4_000;
+function bounded(text) {
+    if (text.length <= MAX_SECTION_CHARS)
+        return text;
+    return `${text.slice(0, MAX_SECTION_CHARS)}… (${text.length - MAX_SECTION_CHARS} more characters)`;
+}
+/**
+ * What a model reads when a control-plane call fails: the SDK's one-line
+ * message, then what the API actually said beside it.
+ *
+ * The message is bounded at 160 characters, and a structured refusal is
+ * usually longer than that -- a `platform_image_required` 403 names every
+ * image each refused key may be instead, and that list was the part cut off.
+ * So the code, the whole sentence (when the message line had to shorten it)
+ * and every other field of the body follow, as one compact JSON object.
+ * `redact` is the server's own secret redaction, applied to the fields: a
+ * validation error echoes back what it was sent.
+ *
+ * Returns undefined for anything that is not a `ThalovantApiError`.
+ */
+export function apiErrorText(error, redact) {
+    if (!(error instanceof ThalovantApiError))
+        return undefined;
+    const lines = [error.message];
+    if (error.code)
+        lines.push(`code: ${error.code}`);
+    const shown = error.message.replace(/\s+/g, " ");
+    if (error.detail && !shown.includes(error.detail.replace(/\s+/g, " ").trim())) {
+        lines.push(`detail: ${bounded(error.detail)}`);
+    }
+    const problem = error.problem;
+    if (problem) {
+        const fields = {};
+        for (const [key, value] of Object.entries(problem)) {
+            if (ENVELOPE.has(key))
+                continue;
+            // Already on a line above when they were read as strings.
+            if ((key === "code" || key === "detail") && typeof value === "string")
+                continue;
+            fields[key] = value;
+        }
+        if (Object.keys(fields).length)
+            lines.push(`fields: ${bounded(JSON.stringify(redact(fields)))}`);
+    }
+    return lines.join("\n");
+}

package/dist/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { apiErrorText } from "./api-error-output.js";
 import { inventoryPresentation } from "./inventory-output.js";
 import { runtimeReplyContent } from "./reply-output.js";
 import { throwIfRuntimeCancelled, withRuntimeLease } from "./runtime-lease.js";
@@ -6,7 +7,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
-import { DEFAULT_CONTROL_API_URL, ThalovantClient, ThalovantControlPlane, ThalovantIdentity, buildClientContext, buildLocation, } from "@thalovant/sdk";
+import { DEFAULT_CONTROL_API_URL, ThalovantApiError, ThalovantClient, ThalovantControlPlane, ThalovantIdentity, buildClientContext, buildLocation, } from "@thalovant/sdk";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
 import { createServer as createHttpServer } from "node:http";
@@ -204,22 +205,30 @@ const releaseOptionsSchema = {
     channel: z.string().min(1).optional().describe("Release channel. Falls back to the workspace release policy when omitted."),
     mode: z.string().min(1).optional().describe('Release mode. Passing images without mode switches to "custom".'),
     version: z.string().min(1).optional().describe("Pinned release version."),
-    images: z.record(z.string().min(1)).optional().describe("Explicit image overrides. Switches to custom mode unless mode is also set."),
+    images: z.record(z.string().min(1)).optional().describe("Explicit image overrides. Switches to custom mode unless mode is also set. Non-admins may pass only images the platform releases for each key: a catalog pin of the stable or alpha channel, the resource's current, recommended or release-policy image, or the platform's default image; runtime core also accepts any tag or digest of ghcr.io/thalovant/ovos-core and hub listener any tag or digest of ghcr.io/thalovant/hivemind-listener, while bus and preview_bridge take only the listed images. Anything else fails with 403 platform_image_required, whose error lists allowed_images and allowed_repositories per refused key."),
     reason: z.string().min(1).optional().describe("Audit reason recorded with the release."),
 };
 function releaseOptionsFrom(args) {
     return { channel: args.channel, mode: args.mode, version: args.version, images: args.images, reason: args.reason };
 }
 const SCOPE_HINT_403 = 'HTTP 403 "Insufficient scopes" — the token lacks the scope this route needs: hubs:write for provisioning, hubs:read for the marketplace catalog, hubs:inspect for runtime-group and hub runtime views (hubs:write implies hubs:read, which implies hubs:inspect and hubs:preview). The API checks scope BEFORE the paid-plan gate, so a 403 can mask a plan problem and granting the scope may surface a 402 next. Free-plan API tokens are capped at hubs:read, clients:read, and clients:write, so a free-tier API token fails provisioning with this 403 and never reaches the 402. A 403 here can also mean the caller does not own the resource ("Ownership required"), or a plan restriction such as HUB_AUTOSCALING_NOT_INCLUDED or a custom hub domain the plan does not allow.';
+const PLATFORM_IMAGE_HINT_403 = 'HTTP 403 platform_image_required — only a platform administrator can run an image the platform does not release. This is not a scope problem: pick, for each key in refused_images, one of that key\'s allowed_images, or any tag or digest of its allowed_repositories entry (both are in the fields above), and retry.';
+const PLAN_LIMIT_HINT_403 = 'HTTP 403 plan_limit — the plan\'s allowance for the named resource is used up (see resource, used and limit in the fields above). Granting a scope will not help: free one (delete or reuse an existing one) or move the workspace to a larger plan.';
 const PLAN_HINT_402 = 'HTTP 402 "API access requires a paid plan." — the token is valid and correctly scoped but the tenant is on the free plan. Free-tier callers can browse the catalog (thalovant_list_marketplace_skills) and set hub ratings, but cannot create, update, release, or delete hubs and runtime groups, and cannot install skills.';
 const MARKETPLACE_HINT_402 = 'HTTP 402 "This skill requires paid marketplace access for the tenant plan." — a DIFFERENT 402 from the plan gate: the plan is paid enough to provision, but this catalog entry has access_tier "paid" and the plan does not include paid marketplace skills. thalovant_list_runtime_group_marketplace reports this per skill as purchase_required, installable, and access_message; check it before installing.';
 const HUB_SKILL_HINT_422 = 'HTTP 422 — the requested hub skill version is unusable: "latest" could not be resolved to a published version of that skill, or the version string is not a valid version. Check the skill name and its published versions with thalovant_list_marketplace_skills, or pass an explicit x.y.z.';
 const ETAG_HINT_412 = 'HTTP 412 "ETag mismatch" — the If-Match etag was missing or stale and nothing changed. Re-fetch the hub with thalovant_get_hub, read the `etag` field from the response BODY (there is no ETag response header), and retry with that exact value. The comparison is exact string equality, so do not rewrite or weaken the value.';
-function controlPlaneErrorHint(profile, status, body) {
+function controlPlaneErrorHint(profile, status, body, code) {
     switch (status) {
         case 402:
             return (profile === "skillInstall" || profile === "hubSkillInstall") && /marketplace/i.test(body) ? MARKETPLACE_HINT_402 : PLAN_HINT_402;
         case 403:
+            // A 403 that names its reason is not the scope problem the general hint
+            // describes, and sending a model off to grant scopes wastes the turn.
+            if (code === "platform_image_required")
+                return PLATFORM_IMAGE_HINT_403;
+            if (code === "plan_limit")
+                return PLAN_LIMIT_HINT_403;
             return SCOPE_HINT_403;
         case 404:
             return /hub_without_runtime_group/.test(body)
@@ -241,9 +250,10 @@ function controlPlaneErrorHint(profile, status, body) {
 /**
  * Run a control-plane call and, on failure, append actionable guidance.
  *
- * The SDK raises ThalovantApiError with the status embedded in the message
- * ("Thalovant API request failed with HTTP 412: ..."), so the status is
- * recovered by parsing rather than from a structured field.
+ * The status and code come from the SDK's ThalovantApiError. What the API
+ * said -- the code, the whole sentence, every other field of the body -- goes
+ * ahead of the hint (see apiErrorText); an error that is not an API error
+ * keeps its own message, and its status is read from it when it names one.
  */
 async function callControlPlane(profile, run) {
     try {
@@ -251,11 +261,13 @@ async function callControlPlane(profile, run) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        const status = Number(/HTTP (\d{3})/.exec(message)?.[1]);
-        const hint = Number.isFinite(status) ? controlPlaneErrorHint(profile, status, message) : undefined;
+        const apiError = error instanceof ThalovantApiError ? error : undefined;
+        const status = apiError?.statusCode ?? Number(/HTTP (\d{3})/.exec(message)?.[1]);
+        const said = [message, apiError?.code, apiError?.detail].filter(Boolean).join(" ");
+        const hint = Number.isFinite(status) ? controlPlaneErrorHint(profile, status, said, apiError?.code) : undefined;
         if (!hint)
             throw error;
-        throw new Error(`${message}\n\n${hint}`);
+        throw new Error(`${apiErrorText(error, redactSecrets) ?? message}\n\n${hint}`, { cause: error });
     }
 }
 const HUB_SKILL_DEFAULT_TIMEOUT_MS = 120_000;
@@ -586,7 +598,12 @@ function registerThalovantTool(server, name, config, handler) {
                 durationMs: Date.now() - start,
                 error: error instanceof Error ? error.message : String(error),
             });
-            throw error;
+            // An API error that no hint was added to still says what the API said:
+            // the SDK's message is one bounded line, and the structured fields a
+            // refusal carries (the images a caller may pin, a plan's numbers) are
+            // only on the error itself.
+            const text = apiErrorText(error, redactSecrets);
+            throw text === undefined ? error : new Error(text, { cause: error });
         }
     });
 }
@@ -1879,7 +1896,7 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_release_hub", {
         title: "Release Hub",
-        description: "Apply a release policy to a hub and return the updated hub. Every option is optional; omitted fields fall back to the workspace release policy. Passing images switches the hub to custom mode unless mode is also set. Requires the hubs:write scope and a paid plan. No etag is needed.",
+        description: "Apply a release policy to a hub and return the updated hub. Every option is optional; omitted fields fall back to the workspace release policy. Passing images switches the hub to custom mode unless mode is also set; non-admins may pass only images the platform releases (see images). Requires the hubs:write scope and a paid plan. No etag is needed.",
         inputSchema: {
             ...controlPlaneSchema,
             hubId: z.string().min(1).describe("Hub UUID."),
@@ -2072,7 +2089,7 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_release_runtime_group", {
         title: "Release Runtime Group",
-        description: "Apply a runtime image policy to a Thalovant runtime group and return the updated group. Options behave like thalovant_release_hub: everything is optional, omitted fields fall back to the workspace release policy, and passing images switches to custom mode unless mode is also set. Requires the hubs:write scope and a paid plan.",
+        description: "Apply a runtime image policy to a Thalovant runtime group and return the updated group. Options behave like thalovant_release_hub: everything is optional, omitted fields fall back to the workspace release policy, and passing images switches to custom mode unless mode is also set (non-admins: only images the platform releases, see images). Requires the hubs:write scope and a paid plan.",
         inputSchema: {
             ...controlPlaneSchema,
             runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thalovant/mcp-server",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Stdio and Streamable HTTP MCP server for Thalovant control-plane and hub runtime APIs.",
   "license": "MIT",
   "type": "module",
@@ -64,7 +64,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@thalovant/sdk": "^0.7.1",
+    "@thalovant/sdk": "^0.8.7",
     "jose": "^6.2.8",
     "zod": "^3.25.76"
   },

package/server.json

@@ -7,19 +7,19 @@
     "url": "https://github.com/thalovant/thalovant-mcp",
     "source": "github"
   },
-  "version": "0.5.1",
+  "version": "0.5.3",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@thalovant/mcp-server",
-      "version": "0.5.1",
+      "version": "0.5.3",
       "transport": {
         "type": "stdio"
       }
     },
     {
       "registryType": "oci",
-      "identifier": "ghcr.io/thalovant/thalovant-mcp:0.5.1",
+      "identifier": "ghcr.io/thalovant/thalovant-mcp:0.5.3",
       "transport": {
         "type": "streamable-http",
         "url": "http://127.0.0.1:3000/mcp"