@thalovant/mcp-server 0.6.2 → 0.6.4

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.6.4 — 2026-10-19
+
+- **Descriptions that say what a runtime tool changes.** `thalovant_send_action`, `thalovant_send_code` and `thalovant_wait_for_event` had one-line descriptions that didn't say whether the tool changes anything. A scanner that reads only names and descriptions rated all three as high-risk tools that execute, `thalovant_wait_for_event` included, though it was already annotated `readOnlyHint: true`. `thalovant_send_action` now says the hub routes its payload like a spoken request, so a skill may act on it. `thalovant_send_code` says the hub receives its value as an exact utterance, and both say they return without waiting for a reply and that `THALOVANT_MCP_READONLY` leaves them out. `thalovant_wait_for_event` says it only listens and sends the hub nothing, and that `sessionId`, `requestId` and `context` filter which events count. `payload`, `title`, `value`, `kind`, `label` and `eventName` now have their own descriptions. Schemas, annotations and behaviour are unchanged.
+- The Claude Desktop and Codex examples start the published package with `npx -y @thalovant/mcp-server`. They used to point at a path on one developer's machine.
+- `package.json`, `server.json`, the OCI label, the README and this file move to 0.6.4 together.
+
+## 0.6.3 — 2026-10-11
+
+- **Sentences in the language the hub answers in.** `thalovant_intent_inventory` takes `@thalovant/sdk` 0.9.9, which lists a language the hub never loaded in one of the hub's own languages: the same language in another region first, then the hub's own language, then the one with the most sentences. A hub loads its `lang` and `secondary_langs` and lists nothing under any other tag, so on 2026-10-11 a ja-JP, es-ES or de-DE request came back empty on every public hub, even though the hub answers those people. The output's `listed_in` names the language each requested language was listed in. `examples` are now rendered from that language (they used to be rendered from the requested tag and came back empty). `presentation.notes` says when the sentences are in another language, so an agent can tell the user.
+- **Fallback skills that exist.** The SDK reads fallbacks from `ovos.skills.list` and no longer asks `ovos.skills.fallback.list`, which ovos-core reverted the day it landed. Skills with no intents, such as Daily Desk's memory skill, now appear. `priority` is `null`: the hub does not say in which order it tries fallbacks, and the list is in skill id order. The tool description and README say so. A connection needs `ovos.skills.list` on its allow-list; until then fallbacks stay unknown, as before.
+- Takes `@thalovant/sdk` ^0.9.9, and the lock resolves the published 0.9.9. The parity contract acknowledges reference digest `5b973a65ab58` (see thalovant/thalovant-python-sdk#105).
+- `package.json`, `server.json`, the OCI label, the README and this file move to 0.6.3 together.
+
 ## 0.6.2 — 2026-10-02
 
 - Takes `@thalovant/sdk` ^0.9.3, which the lock resolves. Its `reply.claimed` now recognizes a skill's own confident fallback-tier answer; the earlier range silently swallowed a genuinely successful Home Assistant reply (a `claimed` answer from the home skill's fallback tier read as "nothing answered"). No code change in this package: the logic is the SDK's `replyClaimMetadata`, which `src/reply-output.ts` delegates to.

package/README.md

@@ -24,6 +24,8 @@ Thalovant publishes SDKs for Python, Node.js, Go, and Rust. This server uses Nod
 
 ## Install
 
+Run the published package with `npx -y @thalovant/mcp-server`, or build it from a checkout:
+
 ```bash
 npm install
 npm run build
@@ -308,8 +310,8 @@ Recommended: authenticate with a scoped API token so the MCP config never contai
 {
   "mcpServers": {
     "thalovant": {
-      "command": "node",
-      "args": ["/home/goldyfruit/Development/Thalovant/mcp/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "@thalovant/mcp-server"],
       "env": {
         "THALOVANT_API_TOKEN": "tvpat_...",
         "THALOVANT_PROFILE": "prod"
@@ -327,8 +329,8 @@ Use the same stdio command in your MCP client config:
 {
   "mcpServers": {
     "thalovant": {
-      "command": "node",
-      "args": ["/home/goldyfruit/Development/Thalovant/mcp/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "@thalovant/mcp-server"],
       "env": {
         "THALOVANT_API_TOKEN": "tvpat_...",
         "THALOVANT_PROFILE": "prod"
@@ -418,10 +420,17 @@ Tool outputs redact credential-shaped fields. `thalovant_create_client_identity`
 
 `thalovant_intent_inventory` uses the runtime identity and accepts `languages`,
 `describe`, `fallback`, `speakable`, `sentence`, `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
-adds at most 1500ms. A silent listing can use engine manifests; disable this with
+intents and examples, fallback skills, `fallbacks_known`, `listed_in`, and
+`may_answer` by requested language. `listed_in` names the hub language each
+requested language was listed in. A hub lists nothing under a language it did
+not load, so a language with no sentences is listed in its usual form (`en-CA`
+in `en-US`) or in the closest language the hub loaded, and `examples` are
+rendered in that language. When `listed_in` differs from what was asked, the
+sentences are in another language, and `presentation.notes` says so. Fallback
+skills come from `ovos.skills.list`, in skill id order, with `priority: null`:
+the hub does not say in which order it tries them. A missing or denied
+fallback-skill query remains unknown, rather than being reported as a known
+empty list. The optional probe adds at most 1500ms. A silent listing can use engine manifests; disable this with
 `fallback: false`. Both new tools are available in read-only mode and respect
 per-principal policy. `thalovant_get_operation` reads an operation ID returned by
 provisioning without replaying the write.
@@ -531,7 +540,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.6.2 requires `@thalovant/sdk` `^0.9.3` (0.9.3 through versions below 0.10.0). Since 0.5.1 the server enforces
+Version 0.6.4 requires `@thalovant/sdk` `^0.9.9` (0.9.9 through versions below 0.10.0). Since 0.5.1 the server 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

@@ -1614,7 +1614,7 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_intent_inventory", {
         title: "Runtime Intent Inventory",
-        description: "Discover a hub's registered intents, language examples and fallback skills using its runtime identity. Unknown fallback support remains distinct from a known empty list; answerability is a conservative hint.",
+        description: "Discover a hub's registered intents, language examples and fallback skills using its runtime identity. listed_in names, per requested language, the hub language the sentences were listed in: a hub lists nothing under a language it did not load, so a language with no sentences is listed in its usual form or the closest language the hub loaded. When listed_in differs from the language asked, tell the user which language the sentences are in. Fallback skills come from ovos.skills.list in skill id order; the hub does not say in which order they are tried, so priority is null. Unknown fallback support remains distinct from a known empty list; answerability is a conservative hint.",
         inputSchema: {
             ...runtimeAuthSchema,
             languages: z.array(z.string().trim().min(1).max(100)).min(1).max(20).default(["en-us"]),
@@ -1634,8 +1634,12 @@ export function createServer() {
         return jsonContent(redactSecrets({
             ...inventory.asObject(),
             presentation: inventoryPresentation(inventory),
+            // Keyed by the language asked, rendered from the tag that answered:
+            // a Spanish phone on an English hub gets the English sentences, and
+            // listed_in says so.
             examples: inventory.intents.map(intent => ({ id: intent.id,
-                languages: Object.fromEntries(inventory.languages.map(lang => [lang, intent.examples(lang, exampleLimit, { speakable, sentence, slots })])),
+                languages: Object.fromEntries(inventory.languages.map((lang, index) => [lang,
+                    intent.examples(inventory.listedIn[index] ?? lang, exampleLimit, { speakable, sentence, slots })])),
             })),
             may_answer: Object.fromEntries(inventory.languages.map(lang => [lang, inventory.mayAnswer(lang)])),
         }));
@@ -1713,11 +1717,11 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_send_action", {
         title: "Send Action",
-        description: "Send a structured action payload to a Thalovant hub.",
+        description: "Send one action to a Thalovant hub using a saved identity, the way a button or a shortcut would. The hub routes payload like a spoken request, so the skill that takes it can change things: switch a light, start a timer, play music. Returns once the action is sent, without waiting for the reply; use thalovant_ask to read the answer. THALOVANT_MCP_READONLY leaves this tool out.",
         inputSchema: {
             ...runtimeAuthSchema,
-            payload: z.string().min(1).max(20_000),
-            title: z.string().min(1).max(512).optional(),
+            payload: z.string().min(1).max(20_000).describe("The request the hub routes, in words, such as \"turn on the kitchen light\"."),
+            title: z.string().min(1).max(512).optional().describe("A label carried with the action in its context (input.title)."),
             lang: z.string().min(1).optional(),
             sessionId: z.string().min(1).optional(),
             requestId: z.string().min(1).optional(),
@@ -1745,12 +1749,12 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_send_code", {
         title: "Send Code",
-        description: "Send an exact typed, scanned, barcode, QR, or serial value to a Thalovant hub.",
+        description: "Send one exact value to a Thalovant hub using a saved identity: something typed, scanned, a barcode, a QR code or a serial number. The hub receives it as an utterance whose input is marked exact, and a skill that recognizes the value may act on it. Returns once the value is sent, without waiting for a reply. THALOVANT_MCP_READONLY leaves this tool out.",
         inputSchema: {
             ...runtimeAuthSchema,
-            value: z.string().min(1).max(20_000),
-            kind: z.string().min(1).max(64).optional(),
-            label: z.string().min(1).max(128).optional(),
+            value: z.string().min(1).max(20_000).describe("The value exactly as read; only leading and trailing spaces are trimmed."),
+            kind: z.string().min(1).max(64).optional().describe("What the value is, such as barcode, qr or serial. Defaults to code."),
+            label: z.string().min(1).max(128).optional().describe("A label carried with the value in its context (input.label)."),
             lang: z.string().min(1).optional(),
             sessionId: z.string().min(1).optional(),
             requestId: z.string().min(1).optional(),
@@ -1802,10 +1806,10 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_wait_for_event", {
         title: "Wait For Event",
-        description: "Wait for one named hub event using a saved identity.",
+        description: "Wait for one named hub event using a saved identity and return it: the first eventName the hub sends once the connection is made, or a timeout error after timeoutMs. sessionId, requestId and context narrow it to events carrying the same values. Listens only: it opens the connection and sends the hub no message, so it changes nothing.",
         inputSchema: {
             ...runtimeAuthSchema,
-            eventName: z.string().min(1).max(256),
+            eventName: z.string().min(1).max(256).describe("The bus message type to wait for, such as speak or recognizer_loop:utterance."),
             timeoutMs: z.number().int().min(1_000).max(MAX_TIMEOUT_MS).default(DEFAULT_TIMEOUT_MS),
             sessionId: z.string().min(1).optional(),
             requestId: z.string().min(1).optional(),

package/dist/inventory-output.js

@@ -6,6 +6,12 @@ export function inventoryPresentation(runtime, generatedAt = new Date().toISOStr
         `Runtime discovery source: ${runtime.source}.`,
         ...runtime.denied.map(query => `Query refused or unanswered: ${query}.`),
         ...(!runtime.fallbacksKnown ? ["Fallback skill support is unknown."] : []),
+        ...(runtime.fallbacks.length > 0 ? ["Fallback skills are in skill id order; the hub does not say in which order it tries them."] : []),
+        ...runtime.languages.flatMap((lang, index) => {
+            const listed = runtime.listedIn[index];
+            return listed && listed.toLowerCase().replaceAll("_", "-") !== lang.toLowerCase().replaceAll("_", "-")
+                ? [`Sentences for ${lang} are listed in ${listed}: the hub has none under ${lang}.`] : [];
+        }),
     ];
     const inventory = new Inventory("", "", "hub", generatedAt, runtime.skills.map(skill => new Skill(skill.skillId, friendlyTitle(skill.skillId), [], skill.intents.map(intent => new Intent(intent.id, intent.name, intent.skillId, intent.engine, intent.phrases, intent.languages)))), notes);
     return { ...inventory.asObject(), languages_present: languagesPresent(inventory) };

package/package.json

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