@thalovant/mcp-server 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.0 — 2026-09-12
+
+- Use Node SDK 0.5.0 request hints, bounded embedded audio replies, and speakable intent examples. Keep embedded audio out of model text; offer explicit audio/resource content blocks through includeAudio.
+- Default runtime configuration tools to revision-guarded merging with at most three attempts and only HTTP 412 retries. Preserve explicit replacement with merge: false. Guarded merging requires hubs:read and paid hubs:write.
+- Cover actual encrypted runtime hints/audio and default conditional-write conflict handling through MCP tool calls. Preserve the existing tool catalog and align npm/OCI/registry versions.
+
 ## 0.2.0 — 2026-09-12
 
 - Add a read-only hub skill history tool using Node SDK 0.4.0. The catalog now has 46 default tools, 23 in read-only mode, and 48 with destructive tools enabled.

package/README.md

@@ -56,7 +56,7 @@ Minimum scopes for the full control-plane tool surface:
 
 | Scope | Used by |
 |-------|---------|
-| `hubs:read` | `thalovant_list_hubs`, `thalovant_get_hub`, `thalovant_get_analytics_overview`, `thalovant_list_marketplace_skills`, `thalovant_list_runtime_groups`, `thalovant_get_runtime_group`, `thalovant_get_runtime_group_config`, and the hub lookup inside `thalovant_create_client_identity` |
+| `hubs:read` | `thalovant_list_hubs`, `thalovant_get_hub`, `thalovant_get_analytics_overview`, `thalovant_list_marketplace_skills`, `thalovant_list_runtime_groups`, `thalovant_get_runtime_group`, `thalovant_get_runtime_group_config`, the guarded merge read in `thalovant_update_runtime_group_config`, and the hub lookup inside `thalovant_create_client_identity` |
 | `hubs:inspect` | `thalovant_get_hub_runtime_capabilities`, `thalovant_list_runtime_group_marketplace`, `thalovant_list_runtime_group_inventory`, `thalovant_list_hub_skills`, `thalovant_list_hub_skill_history` |
 | `hubs:write` | All hub and runtime-group provisioning: `thalovant_create_hub`, `thalovant_update_hub`, `thalovant_release_hub`, `thalovant_create_runtime_group`, `thalovant_update_runtime_group`, `thalovant_update_runtime_group_config`, `thalovant_release_runtime_group`, `thalovant_install_runtime_group_skill`, `thalovant_uninstall_runtime_group_skill`, the per-hub `thalovant_install_hub_skill`, `thalovant_update_hub_skill`, `thalovant_remove_hub_skill`, the hub rating tools, and the opt-in delete tools |
 | `clients:write` | `thalovant_create_client_identity` (`POST /v1/clients`) |
@@ -384,7 +384,7 @@ Destructive, **not registered unless explicitly enabled** (see [Destructive Tool
 Tool outputs redact credential-shaped fields. `thalovant_create_client_identity` does not return secret identity material; pass `savePath` when you want the full identity written to a local file with mode `0600`. `savePath` is confined to the server's identity directory (`THALOVANT_MCP_IDENTITY_DIR`, default `<config-dir>/thalovant/identities`): pass a plain filename, since absolute paths outside that directory and `..` traversal are rejected, so a model cannot drop a credential file into a git working tree or synced folder. `thalovant_config_status` reports the active `identityDir`.
 
 `thalovant_intent_inventory` uses the runtime identity and accepts `languages`,
-`describe`, `fallback`, and a per-query/batch `timeoutMs`. It returns registered
+`describe`, `fallback`, `speakable`, `slots`, `exampleLimit`, and a per-query/batch `timeoutMs`. It returns registered
 intents and examples, fallback skills, `fallbacks_known`, and `may_answer` by
 requested language. A missing or denied optional fallback-skill query remains
 unknown, rather than being reported as a known empty list. The optional probe
@@ -393,6 +393,33 @@ adds at most 1500ms. A silent listing can use engine manifests; disable this wit
 per-principal policy. `thalovant_get_operation` reads an operation ID returned by
 provisioning without replaying the write.
 
+## Request hints, embedded audio, and configuration merging
+
+`thalovant_ask` accepts `sttLang`, an ordered `pipeline`, and `location`
+with required `city` and optional `region`, `country`, `timezone`, `latitude`,
+and `longitude`. Hints apply to the current request. Omit unused hints;
+an empty pipeline is ignored, and blank language or city strings are rejected.
+
+Ask and Query return language, ordered event metadata, `hasAudio` and
+`droppedMedia`. Embedded hex stays out of text output. Opt into separate MCP
+audio blocks with `includeAudio: true`; unknown formats become embedded binary
+resource blocks. Clip and reply limits are 4 MiB and 16 MiB respectively,
+checked by the SDK before retention. The client owns playback. No skill-supplied
+path or URL is fetched. Inventory `speakable: true` renders examples without
+changing the raw patterns; `slots` supplies illustrative slot values, and
+`exampleLimit` limits examples per language to 1–20 (default 2).
+
+Configuration updates default to `merge: true`: GET the revision, deep-merge
+the caller's delta and PUT with `expected_revision`. Only HTTP 412 retries,
+with a fresh read and at most three total attempts. This requires `hubs:read`,
+`hubs:write`, and a paid plan. An older API without revision support fails before
+writing. There is no unconditional fallback. Supplied personas replace;
+omitted personas stay unchanged. For an intentional full replacement, pass
+`merge: false`, requiring `hubs:write`, a paid plan, and coordination with other writers.
+Guarded merges reject integers outside JavaScript's safe integer range in the
+delta or stored configuration before writing. Store large identifiers as strings
+or use an SDK that preserves large JSON integers.
+
 ## Destructive Tools
 
 `thalovant_delete_hub` and `thalovant_delete_runtime_group` are **disabled by default**. They are not merely blocked when called — they are never registered, so they do not appear in `tools/list` and a model cannot see or attempt them.
@@ -437,7 +464,7 @@ Runtime calls sharing the same hub client identity run sequentially within one
 MCP process. Use a distinct client identity for each independently running MCP
 server so the hub can keep their sessions separate.
 
-Version 0.2.0 uses `@thalovant/sdk` `^0.4.0` (0.4.0 through versions below 0.5.0). This release enforces
+Version 0.3.0 requires `@thalovant/sdk` `^0.5.1` (0.5.1 through versions below 0.6.0). This release enforces
 secure effective MQTT URLs and carries a single connection deadline through
 MQTT setup and HTTP failure cleanup. Runtime tools support
 HiveMind v3 Noise over WSS, HTTPS and MQTT over TLS. `thalovant_healthcheck`

package/dist/index.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
+import { runtimeReplyContent } from "./reply-output.js";
 import { throwIfRuntimeCancelled, withRuntimeLease } from "./runtime-lease.js";
 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, } from "@thalovant/sdk";
+import { DEFAULT_CONTROL_API_URL, 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";
@@ -718,21 +719,6 @@ async function withRuntimeClient(options, run) {
     ])).digest("hex");
     return withRuntimeLease(key, () => new ThalovantClient(identity, { protocol: options.protocol ?? "wss" }), client => run(client, signal), 6000, signal);
 }
-function summarizeReply(reply) {
-    const displayItems = reply.displayItems({ maxTextChars: 1_000 });
-    return {
-        text: reply.text,
-        displayText: reply.displayText,
-        utterances: reply.utterances,
-        handled: reply.handled,
-        ok: reply.ok,
-        sessionId: reply.sessionId,
-        requestId: reply.requestId,
-        displayItems,
-        events: reply.events.map((event) => redactSecrets(event.asObject())),
-        failureEvent: reply.failureEvent ? redactSecrets(reply.failureEvent.asObject()) : undefined,
-    };
-}
 /**
  * Base directory that saved client-identity files are confined to.
  *
@@ -1360,17 +1346,23 @@ export function createServer() {
         inputSchema: {
             ...runtimeAuthSchema,
             languages: z.array(z.string().trim().min(1).max(100)).min(1).max(20).default(["en-us"]),
+            speakable: z.boolean().default(false).describe("Render intent patterns into example sentences; preserve whole-sentence priority."),
+            slots: z.record(z.string().max(500)).optional().describe("Example values for named intent slots."),
+            exampleLimit: z.number().int().min(1).max(20).default(2),
             describe: z.boolean().default(true),
             fallback: z.boolean().default(true).describe("Try engine manifests if the intent listing is refused or unanswered."),
             timeoutMs: z.number().int().min(1_000).max(MAX_TIMEOUT_MS).default(DEFAULT_TIMEOUT_MS).describe("Per-query/batch timeout; the optional fallback-skill probe is capped at 1500ms."),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async ({ languages, describe, fallback, timeoutMs, ...runtime }) => withRuntimeClient(runtime, async (client, signal) => {
+    }, async ({ languages, describe, fallback, timeoutMs, speakable, slots, exampleLimit, ...runtime }) => withRuntimeClient(runtime, async (client, signal) => {
         await client.connect(undefined, signal);
         throwIfRuntimeCancelled(signal);
         const inventory = await client.intents(languages, { describe, fallback, timeoutMs: clampTimeout(timeoutMs) });
         return jsonContent(redactSecrets({
             ...inventory.asObject(),
+            examples: inventory.intents.map(intent => ({ id: intent.id,
+                languages: Object.fromEntries(inventory.languages.map(lang => [lang, intent.examples(lang, exampleLimit, { speakable, slots })])),
+            })),
             may_answer: Object.fromEntries(inventory.languages.map(lang => [lang, inventory.mayAnswer(lang)])),
         }));
     }));
@@ -1381,6 +1373,12 @@ export function createServer() {
             ...runtimeAuthSchema,
             text: z.string().min(1).max(20_000),
             timeoutMs: z.number().int().min(1_000).max(MAX_TIMEOUT_MS).default(DEFAULT_TIMEOUT_MS),
+            sttLang: z.string().trim().min(1).max(100).optional().describe("Language recognized by speech-to-text; the hub validates this hint."),
+            pipeline: z.array(z.string().trim().min(1).max(200)).max(32).optional(),
+            location: z.object({ city: z.string().trim().min(1).max(500), region: z.string().max(500).optional(), country: z.string().max(100).optional(),
+                latitude: z.number().finite().min(-90).max(90).optional(), longitude: z.number().finite().min(-180).max(180).optional(), timezone: z.string().max(200).optional(),
+            }).optional().describe("Request location, preferred over the hub's configured city."),
+            includeAudio: z.boolean().default(false).describe("Include bounded embedded skill clips as MCP audio/resources; default returns metadata without placing audio hex in text."),
             lang: z.string().min(1).optional(),
             sessionId: z.string().min(1).optional(),
             requestId: z.string().min(1).optional(),
@@ -1394,7 +1392,7 @@ export function createServer() {
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ text, timeoutMs, lang, sessionId, requestId, context, replySettleMs, emptyReplyWaitMs, ...runtime }) => {
+    }, async ({ text, timeoutMs, lang, sessionId, requestId, context, replySettleMs, emptyReplyWaitMs, sttLang, pipeline, location, includeAudio, ...runtime }) => {
         return withRuntimeClient(runtime, async (client, signal) => {
             const builtContext = context ? buildClientContext({}, context) : undefined;
             const reply = await client.ask(text, {
@@ -1404,10 +1402,12 @@ export function createServer() {
                 sessionId,
                 requestId,
                 context: builtContext,
+                sttLang, pipeline, location: location ? buildLocation(location) : undefined,
                 replySettleMs,
                 emptyReplyWaitMs,
             });
-            return jsonContent(redactSecrets(summarizeReply(reply)));
+            const output = runtimeReplyContent(reply, includeAudio);
+            return { content: [...jsonContent(redactSecrets(output.summary)).content, ...output.clips] };
         });
     });
     registerThalovantTool(server, "thalovant_query", {
@@ -1417,6 +1417,7 @@ export function createServer() {
             ...runtimeAuthSchema,
             text: z.string().trim().min(1).max(20_000),
             timeoutMs: z.number().int().min(1_000).max(MAX_TIMEOUT_MS).default(DEFAULT_TIMEOUT_MS),
+            includeAudio: z.boolean().default(false).describe("Include bounded embedded skill clips as MCP audio/resources."),
             lang: z.string().min(1).optional(),
             sessionId: z.string().min(1).optional(),
             requestId: z.string().min(1).optional(),
@@ -1425,14 +1426,15 @@ export function createServer() {
             replySettleMs: z.number().int().min(0).max(10_000).optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-    }, async ({ text, timeoutMs, lang, sessionId, requestId, queryId, context, replySettleMs, ...runtime }) => {
+    }, async ({ text, timeoutMs, lang, sessionId, requestId, queryId, context, replySettleMs, includeAudio, ...runtime }) => {
         return withRuntimeClient(runtime, async (client, signal) => {
             const reply = await client.query(text, {
                 signal,
                 timeoutMs: clampTimeout(timeoutMs), lang, sessionId, requestId, queryId,
                 context: context ? buildClientContext({}, context) : undefined, replySettleMs,
             });
-            return jsonContent(redactSecrets(summarizeReply(reply)));
+            const output = runtimeReplyContent(reply, includeAudio);
+            return { content: [...jsonContent(redactSecrets(output.summary)).content, ...output.clips] };
         });
     });
     registerThalovantTool(server, "thalovant_send_action", {
@@ -2030,7 +2032,7 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_get_runtime_group_config", {
         title: "Get Runtime Group Config",
-        description: "Read a Thalovant runtime group's runtime configuration and personas. Requires the hubs:read scope. Read this before thalovant_update_runtime_group_config so you know what the merge will land on.",
+        description: "Read a Thalovant runtime group's runtime configuration and personas. Requires the hubs:read scope. The revision returned by this call is used by safe configuration merges.",
         inputSchema: {
             ...controlPlaneSchema,
             runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),
@@ -2046,23 +2048,24 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_update_runtime_group_config", {
         title: "Update Runtime Group Config",
-        description: "Merge runtime configuration into a Thalovant runtime group. The API MERGES config into the stored configuration rather than replacing it, and marks the group pending so the runtime operator reconciles the change. personas, when provided, is REPLACED wholesale rather than merged; omit it to leave stored personas untouched. Requires the hubs:write scope and a paid plan.",
+        description: "Merge runtime configuration into a Thalovant runtime group. The SDK reads and deep-merges config, then writes with a revision precondition. Only explicit HTTP 412 conflicts retry, at most three attempts; older APIs fail before a write. Set merge=false for explicit unconditional replacement. personas, when provided, is REPLACED wholesale rather than merged; omit it to leave stored personas untouched. Requires hubs:read and paid hubs:write for merging; replacement needs paid hubs:write.",
         inputSchema: {
             ...controlPlaneSchema,
             runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),
+            merge: z.boolean().default(true).describe("False explicitly replaces the full configuration without a revision precondition."),
             config: jsonRecordSchema.describe("Configuration object merged into the stored configuration. Required."),
             personas: jsonRecordSchema.optional().describe("Replaces the stored personas outright. Left untouched when omitted."),
         },
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ runtimeGroupId, config, personas, ...auth }) => {
+    }, async ({ runtimeGroupId, config, personas, merge, ...auth }) => {
         const api = await createControlPlane(auth);
         ensureAuthenticated(api);
-        return jsonContent(redactSecrets(await callControlPlane("write", () => api.updateRuntimeGroupConfig(runtimeGroupId, config, { personas }))));
+        return jsonContent(redactSecrets(await callControlPlane("write", () => api.updateRuntimeGroupConfig(runtimeGroupId, config, { personas, merge }))));
     });
     registerThalovantTool(server, "thalovant_release_runtime_group", {
         title: "Release Runtime Group",

package/dist/reply-output.d.ts

@@ -0,0 +1,45 @@
+import type { ThalovantReply } from "@thalovant/sdk";
+/** Keep embedded skill bytes out of the language model's text context. */
+export declare function runtimeReplyContent(reply: ThalovantReply, includeAudio?: boolean): {
+    summary: {
+        text: string;
+        displayText: string;
+        utterances: string[];
+        handled: boolean;
+        ok: boolean;
+        sessionId: string | undefined;
+        requestId: string | undefined;
+        lang: string | undefined;
+        hasAudio: boolean;
+        droppedMedia: number;
+        displayItems: import("@thalovant/sdk").ThalovantDisplayItem[];
+        events: {
+            data: {
+                [x: string]: unknown;
+            };
+        }[];
+        media: {
+            eventIndex: number;
+            byteLength?: number;
+            mimeType?: string;
+            error?: string;
+        }[];
+        failureEvent: {
+            data: {
+                [x: string]: unknown;
+            };
+        } | undefined;
+    };
+    clips: ({
+        type: "audio";
+        data: string;
+        mimeType: string;
+    } | {
+        type: "resource";
+        resource: {
+            uri: string;
+            mimeType: string;
+            blob: string;
+        };
+    })[];
+};

package/dist/reply-output.js

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+function eventSummary(event) {
+    const { binary_data: _encoded, ...data } = event.data;
+    return { ...event.asObject(), data };
+}
+/** Keep embedded skill bytes out of the language model's text context. */
+export function runtimeReplyContent(reply, includeAudio = false) {
+    const clips = [];
+    const media = [];
+    const events = reply.events.map((event, eventIndex) => {
+        const output = eventSummary(event);
+        if (!event.isAudio)
+            return output;
+        try {
+            const bytes = Buffer.from(event.audioBytes());
+            const mimeType = bytes.subarray(0, 4).toString() === "RIFF" && bytes.subarray(8, 12).toString() === "WAVE" ? "audio/wav"
+                : bytes.subarray(0, 4).toString() === "OggS" ? "audio/ogg"
+                    : bytes.subarray(0, 4).toString() === "fLaC" ? "audio/flac"
+                        : bytes.subarray(0, 3).toString() === "ID3" ? "audio/mpeg" : "application/octet-stream";
+            media.push({ eventIndex, byteLength: bytes.length, mimeType });
+            if (includeAudio) {
+                const encoded = bytes.toString("base64");
+                clips.push(mimeType.startsWith("audio/") ? { type: "audio", data: encoded, mimeType } : {
+                    type: "resource", resource: { uri: `thalovant-audio://sha256/${createHash("sha256").update(bytes).digest("hex")}`, mimeType, blob: encoded },
+                });
+            }
+        }
+        catch {
+            media.push({ eventIndex, error: "Missing, invalid or oversized embedded audio." });
+        }
+        return output;
+    });
+    return { summary: {
+            text: reply.text, displayText: reply.displayText, utterances: reply.utterances,
+            handled: reply.handled, ok: reply.ok, sessionId: reply.sessionId, requestId: reply.requestId,
+            lang: reply.lang, hasAudio: reply.hasAudio ?? false, droppedMedia: reply.droppedMedia ?? 0,
+            displayItems: reply.displayItems({ maxTextChars: 1_000 }), events, media,
+            // A failure reference must not bypass text sanitization or add a clip
+            // outside the SDK's admitted event sequence and aggregate media budget.
+            failureEvent: reply.failureEvent ? eventSummary(reply.failureEvent) : undefined,
+        }, clips };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thalovant/mcp-server",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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.4.0",
+    "@thalovant/sdk": "^0.5.1",
     "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.2.0",
+  "version": "0.3.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@thalovant/mcp-server",
-      "version": "0.2.0",
+      "version": "0.3.0",
       "transport": {
         "type": "stdio"
       }
     },
     {
       "registryType": "oci",
-      "identifier": "ghcr.io/thalovant/thalovant-mcp:0.2.0",
+      "identifier": "ghcr.io/thalovant/thalovant-mcp:0.3.0",
       "transport": {
         "type": "streamable-http",
         "url": "http://127.0.0.1:3000/mcp"