@thalovant/mcp-server 0.1.19 → 0.1.20

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.20
+
+- Require HTTPS for credential-bearing API calls, preserving explicit loopback HTTP for local development. Reject API redirects through the SDK. Instantiate runtime clients only after acquiring their identity lease.
+- Bind server-managed Thalovant tokens and password login to their configured API origin. Reject cross-origin tool overrides before any outbound request, including credentials for remote principals; retain configured custom origins and anonymous public discovery.
+- Add `thalovant_query` for routed HiveMind queries, preserving query/request/session correlation and runtime identity cleanup; hide it in read-only mode. The default catalogue now contains 41 tools.
+- Add read-only `thalovant_intent_inventory` and `thalovant_get_operation` tools for runtime discovery and asynchronous provisioning status. Inventory preserves fallback knowledge and conservative answerability.
+- Require Node SDK 0.3.9 for aligned intent discovery, request correlation, whole-operation reply deadlines, fixed Ask settlement windows, cancellation and retained cleanup ownership, and credential-safe control-plane redirect handling.
+- Retain the runtime identity lease until actual cleanup, even after a caller close timeout; failed cleanup blocks later identity reuse with an explicit error. Bound queued lease acquisition to six seconds without releasing pending ownership or executing expired callers.
+- Upgrade the test runner to Vitest 4.1.11 to remove GHSA-82fw-gwwq-j7x9.
+- Test Node 20, 22 and 24; add per-principal/shared credential regressions and exercise the inventory tool over a real HTTPS Noise session.
+
 ## 0.1.19
 
 - Require Node SDK 0.3.5 or newer so runtime tools receive secure MQTT URL enforcement and bounded MQTT setup and HTTP failure cleanup.

package/README.md

@@ -93,6 +93,13 @@ npm start
 
 If neither a token nor email/password is configured, authenticated control-plane tools fail with a clear error naming the supported options.
 
+Configured API tokens and login credentials are bound to the origin of their
+configured `apiUrl` or `THALOVANT_API_URL` (default `https://api.thalovant.com`).
+A tool argument cannot redirect those credentials to another origin. Equivalent
+URL spellings and paths on the same origin are allowed; custom origins must be
+configured alongside their credentials. Anonymous public discovery may still
+select a custom API URL.
+
 ## Local Stdio
 
 The server speaks MCP over stdio and does not write logs to stdout.
@@ -305,8 +312,10 @@ Read-only:
 - `thalovant_get_public_hub`
 - `thalovant_list_hubs`
 - `thalovant_get_hub`
+- `thalovant_get_operation`
 - `thalovant_identity_status`
 - `thalovant_healthcheck`
+- `thalovant_intent_inventory`
 - `thalovant_wait_for_event`
 - `thalovant_get_analytics_overview`
 - `thalovant_list_memory_items`
@@ -327,6 +336,7 @@ Writes or hub events:
 
 - `thalovant_create_client_identity`
 - `thalovant_ask`
+- `thalovant_query`
 - `thalovant_send_action`
 - `thalovant_send_code`
 - `thalovant_emit_event`
@@ -355,6 +365,16 @@ 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
+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
+`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.
+
 ## 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.
@@ -399,7 +419,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.1.19 uses `@thalovant/sdk` 0.3.5 or newer. This release enforces
+Version 0.1.20 uses `@thalovant/sdk` `^0.3.9` (0.3.9 through versions below 0.4.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`
@@ -413,6 +433,13 @@ failure preserves those pins; replacing a server key requires an explicit,
 verified trust change. HTTPS identities must advertise the hub's HTTPS plugin,
 and MQTT requires the identity's broker credentials and topic prefix.
 
+Runtime tools retain their identity lease through actual cleanup. If the close
+caller times out, a later tool waits up to six seconds for that cleanup before opening a session.
+A queued tool that reaches this deadline fails without executing later or releasing
+the previous session's identity.
+An actual cleanup failure marks the identity unavailable to later calls instead
+of risking concurrent sessions.
+
 ## Development
 
 ```bash
@@ -429,3 +456,16 @@ npm pack --dry-run
 ## License
 
 MIT. This is the right default for a public integration server: it is permissive, compatible with the MIT Thalovant Node SDK and MCP TypeScript SDK, and does not force downstream agent or enterprise users into a reciprocal licensing model.
+
+Credential-bearing control-plane calls require HTTPS. Explicit loopback HTTP
+(`localhost`, `127.0.0.1`, `[::1]`) remains supported for local development.
+API redirects are rejected so password-login bodies cannot be forwarded.
+Runtime clients are constructed only after acquiring their identity lease.
+
+`thalovant_query` sends a routed HiveMind query; the hub may cascade it according
+to its routing policy. It accepts `text`, `timeoutMs`, `lang`, `sessionId`,
+`requestId`, `queryId`, `context` and `replySettleMs`, plus the runtime identity
+options, and returns the same normalized reply shape as `thalovant_ask`. A query
+may trigger actions, so read-only mode hides it. Conversation workflows use
+`sessionId` with ask/query and the existing event-wait tool; MCP does not expose
+one tool for every SDK conversation or event-listener method.

package/SECURITY.md

@@ -20,3 +20,13 @@ Do not open public issues for vulnerabilities. Email security reports to `hello@
 - Keep `THALOVANT_ALLOW_SHARED_CREDENTIALS=false` for multi-user deployments.
 - Set exact `MCP_HTTP_ALLOWED_HOSTS` and `MCP_HTTP_ALLOWED_ORIGINS`.
 - Send audit logs to your log pipeline with `MCP_AUDIT_LOG=stderr` or `MCP_AUDIT_LOG_FILE`.
+
+
+Server-managed Thalovant tokens and password login are bound to their configured
+control-plane origin. Tool-provided `apiUrl` overrides with a different origin
+are rejected before any request is sent. Configure a custom API origin together
+with its credentials; per-principal credentials follow the same rule.
+
+Control-plane credentials require HTTPS, with an explicit loopback HTTP exception
+for local development (`localhost`, `127.0.0.1`, `[::1]`). API redirects are rejected,
+including redirects that would preserve password-login request bodies.

package/dist/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { 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";
@@ -77,7 +78,7 @@ const controlPlaneSchema = {
         .string()
         .url()
         .optional()
-        .describe("Control-plane base URL. Defaults to https://api.thalovant.com."),
+        .describe("Control-plane base URL. Configured credentials may only be used on their configured origin; defaults to https://api.thalovant.com."),
 };
 const contextSchema = z
     .object({
@@ -567,20 +568,40 @@ function redactSecrets(value) {
     }
     return output;
 }
+/** Keep server-managed credentials on their configured control-plane origin. */
 async function createControlPlane(options) {
     const principal = currentPrincipal();
     const credential = await credentialForPrincipal(principal);
     const canUseShared = allowSharedThalovantCredentials(principal);
-    const apiUrl = options.apiUrl ?? credential?.control?.apiUrl ?? (canUseShared ? process.env.THALOVANT_API_URL : undefined) ?? DEFAULT_CONTROL_API_URL;
+    const configuredApiUrl = credential?.control?.apiUrl ?? (canUseShared ? process.env.THALOVANT_API_URL : undefined) ?? DEFAULT_CONTROL_API_URL;
+    const apiUrl = options.apiUrl ?? configuredApiUrl;
     const accessToken = credential?.control?.accessToken ??
         (canUseShared ? process.env.THALOVANT_API_TOKEN ?? process.env.THALOVANT_ACCESS_TOKEN : undefined);
+    const email = canUseShared ? process.env.THALOVANT_EMAIL : undefined;
+    const password = canUseShared ? process.env.THALOVANT_PASSWORD : undefined;
+    if (accessToken || (email && password)) {
+        let endpoint;
+        let configuredEndpoint;
+        try {
+            endpoint = new URL(apiUrl);
+            configuredEndpoint = new URL(configuredApiUrl);
+        }
+        catch {
+            throw new Error("The configured control-plane API URL is invalid.");
+        }
+        if (endpoint.origin !== configuredEndpoint.origin) {
+            throw new Error("apiUrl must use the configured Thalovant credential origin.");
+        }
+        const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(endpoint.hostname);
+        if (endpoint.protocol !== "https:" && !(endpoint.protocol === "http:" && loopback)) {
+            throw new Error("Credential-bearing control-plane requests require HTTPS (except explicit loopback HTTP).");
+        }
+    }
     const api = new ThalovantControlPlane(apiUrl, {
         accessToken,
         userAgent: `thalovant-mcp/${VERSION}`,
     });
     if (!accessToken && canUseShared) {
-        const email = process.env.THALOVANT_EMAIL;
-        const password = process.env.THALOVANT_PASSWORD;
         if (email && password) {
             await api.login(email, password, { scope: options.loginScope ?? process.env.THALOVANT_SCOPE });
         }
@@ -601,28 +622,26 @@ function controlPlaneAuthModeFromEnv() {
         return "email-password";
     return "none";
 }
-async function createRuntimeClient(options) {
-    const protocol = options.protocol ?? "wss";
+async function createRuntimeIdentity(options) {
     const principal = currentPrincipal();
     const credential = await credentialForPrincipal(principal);
     const runtimeCredential = credential?.runtime;
     const canUseShared = allowSharedThalovantCredentials(principal);
     const canUseToolPaths = canUseShared || parseBool(process.env.MCP_HTTP_ALLOW_CLIENT_CREDENTIAL_PATHS, false);
     if (runtimeCredential?.identity) {
-        return new ThalovantClient(new ThalovantIdentity(runtimeCredential.identity), { protocol });
+        return new ThalovantIdentity(runtimeCredential.identity);
     }
     if (runtimeCredential?.identityFile) {
-        return ThalovantClient.fromIdentityFile(runtimeCredential.identityFile, { protocol });
+        return ThalovantIdentity.fromFile(runtimeCredential.identityFile);
     }
     if (runtimeCredential?.configPath || runtimeCredential?.profile) {
-        return ThalovantClient.fromConfig({
+        return ThalovantIdentity.fromConfig({
             path: runtimeCredential.configPath,
             profile: runtimeCredential.profile,
-            protocol,
         });
     }
     if (runtimeCredential?.fromEnv && canUseShared) {
-        return ThalovantClient.fromEnv({ protocol });
+        return ThalovantIdentity.fromEnv();
     }
     if (isRemotePrincipal(principal) && !canUseShared && !canUseToolPaths) {
         throw new Error("No per-principal Thalovant runtime identity is configured for this authenticated MCP principal.");
@@ -631,57 +650,31 @@ async function createRuntimeClient(options) {
         throw new Error("Runtime identity path/config arguments are disabled for remote MCP principals.");
     }
     if (options.identityFile) {
-        return ThalovantClient.fromIdentityFile(options.identityFile, { protocol });
+        return ThalovantIdentity.fromFile(options.identityFile);
     }
     if (options.configPath || options.profile) {
-        return ThalovantClient.fromConfig({
+        return ThalovantIdentity.fromConfig({
             path: options.configPath,
             profile: options.profile ?? process.env.THALOVANT_PROFILE,
-            protocol,
         });
     }
     if (!canUseShared) {
         throw new Error("No per-principal Thalovant runtime identity is configured for this authenticated MCP principal.");
     }
     if (options.fromEnv || process.env.THALOVANT_ACCESS_KEY) {
-        return ThalovantClient.fromEnv({ protocol });
+        return ThalovantIdentity.fromEnv();
     }
-    return ThalovantClient.fromConfig({
+    return ThalovantIdentity.fromConfig({
         profile: process.env.THALOVANT_PROFILE,
-        protocol,
     });
 }
-// The hub HTTP/MQTT queues and Noise sessions are keyed by client identity.
-// A second tool call must finish after the first closes that identity's session.
-const runtimeLeases = new Map();
-/**
- * Hold an identity lease through both the tool action and client cleanup.
- * This keeps HTTP/MQTT admissions from replacing another call's Noise session;
- * a failed action still closes its client before the next lease starts.
- */
+/** Use one identity lease through the action and actual retained cleanup. */
 async function withRuntimeClient(options, run) {
-    const client = await createRuntimeClient(options);
+    const identity = await createRuntimeIdentity(options);
     const key = createHash("sha256").update(JSON.stringify([
-        client.identity.endpointBase(), client.identity.accessKey,
+        identity.endpointBase(), identity.accessKey,
     ])).digest("hex");
-    const previous = runtimeLeases.get(key) ?? Promise.resolve();
-    let release;
-    const current = new Promise(resolve => { release = resolve; });
-    runtimeLeases.set(key, current);
-    await previous;
-    try {
-        return await run(client);
-    }
-    finally {
-        try {
-            await client.close();
-        }
-        finally {
-            release();
-            if (runtimeLeases.get(key) === current)
-                runtimeLeases.delete(key);
-        }
-    }
+    return withRuntimeLease(key, () => new ThalovantClient(identity, { protocol: options.protocol ?? "wss" }), run);
 }
 function summarizeReply(reply) {
     const displayItems = reply.displayItems({ maxTextChars: 1_000 });
@@ -1214,6 +1207,16 @@ export function createServer() {
         ensureAuthenticated(api);
         return jsonContent(redactSecrets(await api.getHub(hubId)));
     });
+    registerThalovantTool(server, "thalovant_get_operation", {
+        title: "Get Provisioning Operation",
+        description: "Read the status of an asynchronous control-plane operation returned by provisioning.",
+        inputSchema: { ...controlPlaneSchema, operationId: z.string().min(1).max(500) },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ operationId, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await api.getOperation(operationId)));
+    });
     registerThalovantTool(server, "thalovant_create_client_identity", {
         title: "Create Client Identity",
         description: "Create a Thalovant client identity for a hub. The identity is secret; output is redacted unless savePath is used.",
@@ -1309,6 +1312,24 @@ export function createServer() {
             return jsonContent(redactSecrets(client.healthcheck()));
         });
     });
+    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.",
+        inputSchema: {
+            ...runtimeAuthSchema,
+            languages: z.array(z.string().trim().min(1).max(100)).min(1).max(20).default(["en-us"]),
+            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) => {
+        const inventory = await client.intents(languages, { describe, fallback, timeoutMs: clampTimeout(timeoutMs) });
+        return jsonContent(redactSecrets({
+            ...inventory.asObject(),
+            may_answer: Object.fromEntries(inventory.languages.map(lang => [lang, inventory.mayAnswer(lang)])),
+        }));
+    }));
     registerThalovantTool(server, "thalovant_ask", {
         title: "Ask Hub",
         description: "Send one text request to a Thalovant hub using a saved identity and return the normalized reply.",
@@ -1344,6 +1365,30 @@ export function createServer() {
             return jsonContent(redactSecrets(summarizeReply(reply)));
         });
     });
+    registerThalovantTool(server, "thalovant_query", {
+        title: "Query Hub",
+        description: "Send a routed HiveMind query using a saved identity and return the normalized reply. The hub may cascade the query according to its routing policy; a query can trigger actions.",
+        inputSchema: {
+            ...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),
+            lang: z.string().min(1).optional(),
+            sessionId: z.string().min(1).optional(),
+            requestId: z.string().min(1).optional(),
+            queryId: z.string().min(1).optional(),
+            context: contextSchema,
+            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 }) => {
+        return withRuntimeClient(runtime, async (client) => {
+            const reply = await client.query(text, {
+                timeoutMs: clampTimeout(timeoutMs), lang, sessionId, requestId, queryId,
+                context: context ? buildClientContext({}, context) : undefined, replySettleMs,
+            });
+            return jsonContent(redactSecrets(summarizeReply(reply)));
+        });
+    });
     registerThalovantTool(server, "thalovant_send_action", {
         title: "Send Action",
         description: "Send a structured action payload to a Thalovant hub.",

package/dist/runtime-lease.d.ts

@@ -0,0 +1,8 @@
+/** Runtime identities admit one Noise session at a time across MCP tool calls. */
+interface RuntimeClosable {
+    close(): Promise<void>;
+    waitForClosed(): Promise<void>;
+}
+/** A caller timeout never releases an identity before actual cleanup settles. */
+export declare function withRuntimeLease<T, C extends RuntimeClosable>(key: string, createClient: () => C, run: (client: C) => Promise<T>, acquireTimeoutMs?: number): Promise<T>;
+export {};

package/dist/runtime-lease.js

@@ -0,0 +1,64 @@
+const leases = new Map();
+/** A caller timeout never releases an identity before actual cleanup settles. */
+export async function withRuntimeLease(key, createClient, run, acquireTimeoutMs = 6000) {
+    if (!Number.isFinite(acquireTimeoutMs) || acquireTimeoutMs <= 0) {
+        throw new Error("Runtime identity acquisition deadline expired.");
+    }
+    const previous = leases.get(key) ?? Promise.resolve();
+    let release;
+    let fail;
+    const current = new Promise((resolve, reject) => { release = resolve; fail = reject; });
+    // A failed cleanup poisons this identity's barrier. Observe it even when no
+    // later caller arrives; later tools fail instead of replacing that session.
+    void current.catch(() => undefined);
+    leases.set(key, current);
+    const releaseIdentity = () => {
+        release();
+        if (leases.get(key) === current)
+            leases.delete(key);
+    };
+    const failIdentity = () => {
+        fail(new Error("Previous runtime session cleanup failed; this identity remains unavailable."));
+    };
+    let timer;
+    try {
+        await Promise.race([
+            previous,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error("Runtime identity acquisition deadline expired; previous session cleanup is still pending.")), acquireTimeoutMs);
+            }),
+        ]);
+    }
+    catch (error) {
+        // An expired waiter never runs or closes its unused client. Its place in
+        // the chain remains occupied until the prior owner actually retires.
+        void previous.then(releaseIdentity, failIdentity);
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    let client;
+    try {
+        client = createClient();
+    }
+    catch (error) {
+        releaseIdentity();
+        throw error;
+    }
+    try {
+        return await run(client);
+    }
+    finally {
+        let closing;
+        try {
+            closing = client.close();
+        }
+        catch (error) {
+            failIdentity();
+            throw error;
+        }
+        void client.waitForClosed().then(releaseIdentity, failIdentity);
+        await closing;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thalovant/mcp-server",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "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.3.5",
+    "@thalovant/sdk": "^0.3.9",
     "jose": "^6.2.8",
     "zod": "^3.25.76"
   },
@@ -74,6 +74,6 @@
   "devDependencies": {
     "@types/node": "^22.18.12",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.11"
   }
 }

package/server.json

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