@thalovant/mcp-server 0.1.7 → 0.1.9

package/.env.example

@@ -3,6 +3,9 @@ THALOVANT_PROFILE=prod
 THALOVANT_API_URL=https://api.thalovant.com
 
 # Use one control-plane auth option for private/admin tools.
+# Recommended: a scoped, revocable API token (dashboard or device flow).
+# Minimum scopes for the full tool surface: hubs:read, clients:write, memory:read, memory:write.
+# THALOVANT_API_TOKEN=
 # THALOVANT_ACCESS_TOKEN=
 # THALOVANT_EMAIL=
 # THALOVANT_PASSWORD=

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.9
+
+- Added first-class scoped API token auth for the control plane: set `THALOVANT_API_TOKEN` and the server authenticates with the token directly and never calls the login endpoint. Precedence is `THALOVANT_API_TOKEN`, then `THALOVANT_ACCESS_TOKEN`, then the `THALOVANT_EMAIL`/`THALOVANT_PASSWORD` login fallback.
+- `thalovant_config_status` now reports the active control-plane auth mode (`controlPlaneAuthMode`: `api-token`, `access-token`, `email-password`, or `none`) and `hasApiToken`, without revealing token values.
+- Documented API tokens as the recommended auth mode for AI and CI use, including the minimum token scopes for the full control-plane tool surface: `hubs:read`, `clients:write`, `memory:read`, `memory:write`.
+- Clarified the unauthenticated-tool error to name `THALOVANT_API_TOKEN` as the recommended option.
+
+## 0.1.8
+
+- Tightened memory tool input validation to match the control-plane API exactly: `title` max 160, `content` max 4096, `source` max 64, `consentScope` max 128, `consentVersion` max 64, `retentionPolicy` max 64 on create/update, and list `query` max 240, so invalid values fail with a clear client-side error instead of an opaque API 422.
+- Capped `thalovant_list_public_hubs` `limit` at 48 to match the public hubs endpoint, which silently clamps larger page sizes; authenticated `thalovant_list_hubs` keeps its limit of 100.
+- Corrected `thalovant_get_hub` and `thalovant_create_client_identity` descriptions: the authenticated hub routes require a hub UUID; slugs are only accepted by the public hub tools.
+
 ## 0.1.7
 
 - Updated the MCP transport SDK to 1.30.0, removing the affected Hono adapter dependency range.

package/README.md

@@ -29,13 +29,43 @@ npm run build
 
 Node.js 20 or newer is required.
 
-## Local Stdio
+## Control-Plane Auth
 
 Public hub discovery does not need Thalovant credentials. Private control-plane tools and runtime hub tools read credentials only from the MCP server environment or server-side principal credential files. Do not pass API tokens or passwords through chat or tool arguments.
 
+The server selects control-plane auth in this order:
+
+1. `THALOVANT_API_TOKEN` — a scoped Thalovant API token. Recommended.
+2. `THALOVANT_ACCESS_TOKEN` — a pre-issued session access token.
+3. `THALOVANT_EMAIL` + `THALOVANT_PASSWORD` — interactive-account login fallback.
+
+When a token is set, the server never calls the login endpoint. `thalovant_config_status` reports the active mode as `controlPlaneAuthMode` without revealing token values.
+
+### API Tokens (Recommended For AI Agents And CI)
+
+Scoped API tokens are the right credential for AI and automation use: they are minted from the Thalovant dashboard (or through the device flow), carry only the scopes you grant, can be revoked individually, and never involve your account password or MFA. Tokens start with `tvpat_`.
+
+```bash
+export THALOVANT_API_TOKEN="tvpat_..."
+export THALOVANT_API_URL="https://api.thalovant.com"
+
+npm start
+```
+
+Minimum scopes for the full control-plane tool surface:
+
+| Scope | Used by |
+|-------|---------|
+| `hubs:read` | `thalovant_list_hubs`, `thalovant_get_hub`, `thalovant_get_analytics_overview`, and the hub lookup inside `thalovant_create_client_identity` |
+| `clients:write` | `thalovant_create_client_identity` (`POST /v1/clients`) |
+| `memory:read` | `thalovant_list_memory_items`, `thalovant_get_memory_summary`, `thalovant_get_memory_item` |
+| `memory:write` | `thalovant_create_memory_item`, `thalovant_update_memory_item`, `thalovant_delete_memory_item` |
+
+Grant fewer scopes for narrower deployments: a read-only assistant needs only `hubs:read` and `memory:read`. `thalovant_get_analytics_overview` with `admin: true` additionally requires an admin account with `admin:analytics`, which API tokens for regular use should not carry. Runtime hub tools (`thalovant_ask`, `thalovant_send_action`, and friends) use Thalovant client identities, not control-plane tokens.
+
+### Login Fallback
+
 ```bash
-export THALOVANT_ACCESS_TOKEN="..."
-# or
 export THALOVANT_EMAIL="you@example.com"
 export THALOVANT_PASSWORD="..."
 
@@ -45,6 +75,10 @@ export THALOVANT_API_URL="https://api.thalovant.com"
 npm start
 ```
 
+If neither a token nor email/password is configured, authenticated control-plane tools fail with a clear error naming the supported options.
+
+## Local Stdio
+
 The server speaks MCP over stdio and does not write logs to stdout.
 
 Runtime hub tools load local identities in this order:
@@ -208,6 +242,8 @@ MCP_HTTP_TRUST_PROXY=false
 
 ## Claude Desktop
 
+Recommended: authenticate with a scoped API token so the MCP config never contains your account password.
+
 ```json
 {
   "mcpServers": {
@@ -215,6 +251,7 @@ MCP_HTTP_TRUST_PROXY=false
       "command": "node",
       "args": ["/home/goldyfruit/Development/Thalovant/mcp/dist/index.js"],
       "env": {
+        "THALOVANT_API_TOKEN": "tvpat_...",
         "THALOVANT_PROFILE": "prod"
       }
     }
@@ -233,6 +270,7 @@ Use the same stdio command in your MCP client config:
       "command": "node",
       "args": ["/home/goldyfruit/Development/Thalovant/mcp/dist/index.js"],
       "env": {
+        "THALOVANT_API_TOKEN": "tvpat_...",
         "THALOVANT_PROFILE": "prod"
       }
     }

package/dist/index.js

@@ -14,10 +14,11 @@ import { mkdir } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRemoteJWKSet, jwtVerify } from "jose";
 import { z } from "zod";
-const VERSION = "0.1.7";
+const VERSION = "0.1.9";
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_TIMEOUT_MS = 300_000;
 const MAX_LIMIT = 100;
+const MAX_PUBLIC_HUBS_LIMIT = 48;
 const DEFAULT_HTTP_BODY_LIMIT_BYTES = 1_048_576;
 const DEFAULT_HTTP_RATE_LIMIT_MAX = 120;
 const DEFAULT_HTTP_RATE_LIMIT_WINDOW_MS = 60_000;
@@ -48,7 +49,14 @@ const SECRET_KEYS = [
     "secret",
 ];
 const protocolSchema = z.enum(["wss", "https", "mqtt"]);
-const limitSchema = z.number().int().min(1).max(MAX_LIMIT).default(25);
+const limitSchema = z.number().int().min(1).max(MAX_LIMIT).default(25).describe("Page size, 1-100.");
+const publicHubsLimitSchema = z
+    .number()
+    .int()
+    .min(1)
+    .max(MAX_PUBLIC_HUBS_LIMIT)
+    .default(25)
+    .describe("Page size, 1-48. The public hubs endpoint caps page size at 48.");
 const optionalCursorSchema = z.string().min(1).optional();
 const jsonRecordSchema = z.record(z.unknown());
 const controlPlaneSchema = {
@@ -415,7 +423,8 @@ async function createControlPlane(options) {
     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 accessToken = credential?.control?.accessToken ?? (canUseShared ? process.env.THALOVANT_ACCESS_TOKEN : undefined);
+    const accessToken = credential?.control?.accessToken ??
+        (canUseShared ? process.env.THALOVANT_API_TOKEN ?? process.env.THALOVANT_ACCESS_TOKEN : undefined);
     const api = new ThalovantControlPlane(apiUrl, {
         accessToken,
         userAgent: `thalovant-mcp/${VERSION}`,
@@ -431,9 +440,18 @@ async function createControlPlane(options) {
 }
 function ensureAuthenticated(api) {
     if (!api.accessToken) {
-        throw new Error("This tool requires Thalovant API auth. Configure THALOVANT_ACCESS_TOKEN, THALOVANT_EMAIL/THALOVANT_PASSWORD, or per-principal Thalovant credentials for this MCP principal.");
+        throw new Error("This tool requires Thalovant API auth. Configure THALOVANT_API_TOKEN (recommended: a scoped, revocable API token), THALOVANT_ACCESS_TOKEN, THALOVANT_EMAIL/THALOVANT_PASSWORD, or per-principal Thalovant credentials for this MCP principal.");
     }
 }
+function controlPlaneAuthModeFromEnv() {
+    if (process.env.THALOVANT_API_TOKEN)
+        return "api-token";
+    if (process.env.THALOVANT_ACCESS_TOKEN)
+        return "access-token";
+    if (process.env.THALOVANT_EMAIL && process.env.THALOVANT_PASSWORD)
+        return "email-password";
+    return "none";
+}
 async function createRuntimeClient(options) {
     const protocol = options.protocol ?? "wss";
     const principal = currentPrincipal();
@@ -888,6 +906,8 @@ export function createServer() {
         },
     }, async () => jsonContent({
         apiUrl: process.env.THALOVANT_API_URL ?? DEFAULT_CONTROL_API_URL,
+        controlPlaneAuthMode: controlPlaneAuthModeFromEnv(),
+        hasApiToken: Boolean(process.env.THALOVANT_API_TOKEN),
         hasAccessToken: Boolean(process.env.THALOVANT_ACCESS_TOKEN),
         hasEmailPassword: Boolean(process.env.THALOVANT_EMAIL && process.env.THALOVANT_PASSWORD),
         profile: process.env.THALOVANT_PROFILE,
@@ -897,9 +917,9 @@ export function createServer() {
     }));
     registerThalovantTool(server, "thalovant_list_public_hubs", {
         title: "List Public Hubs",
-        description: "List Thalovant public hubs. This read-only discovery call does not require authentication.",
+        description: "List Thalovant public hubs. This read-only discovery call does not require authentication. Page size is capped at 48.",
         inputSchema: {
-            limit: limitSchema,
+            limit: publicHubsLimitSchema,
             cursor: optionalCursorSchema,
             apiUrl: controlPlaneSchema.apiUrl,
         },
@@ -946,10 +966,13 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_get_hub", {
         title: "Get Hub",
-        description: "Fetch one authenticated Thalovant hub by id.",
+        description: "Fetch one authenticated Thalovant hub by UUID.",
         inputSchema: {
             ...controlPlaneSchema,
-            hubId: z.string().min(1),
+            hubId: z
+                .string()
+                .min(1)
+                .describe("Hub UUID. This authenticated route rejects slugs; slugs are only accepted by the public hub tools (thalovant_get_public_hub)."),
         },
         annotations: {
             readOnlyHint: true,
@@ -965,7 +988,10 @@ export function createServer() {
         description: "Create a Thalovant client identity for a hub. The identity is secret; output is redacted unless savePath is used.",
         inputSchema: {
             ...controlPlaneSchema,
-            hubId: z.string().min(1).describe("Hub id or slug accepted by the Thalovant SDK."),
+            hubId: z
+                .string()
+                .min(1)
+                .describe("Hub UUID. This authenticated route rejects slugs; slugs are only accepted by the public hub tools (thalovant_get_public_hub)."),
             name: z.string().min(1).max(128),
             siteId: z.string().min(1).optional(),
             ownerId: z.string().min(1).optional(),
@@ -1259,7 +1285,7 @@ export function createServer() {
             kind: z.enum(["note", "preference", "fact"]).optional(),
             ownerId: z.string().min(1).optional(),
             hubId: z.string().min(1).optional(),
-            query: z.string().min(1).optional(),
+            query: z.string().min(1).max(240).optional(),
             includeDeleted: z.boolean().optional(),
             includeExpired: z.boolean().optional(),
             limit: limitSchema,
@@ -1314,16 +1340,16 @@ export function createServer() {
             ...controlPlaneSchema,
             scope: z.enum(["personal", "workspace", "hub"]).optional(),
             kind: z.enum(["note", "preference", "fact"]).optional(),
-            title: z.string().max(512).nullable().optional(),
-            content: z.string().min(1).max(20_000),
+            title: z.string().max(160).nullable().optional(),
+            content: z.string().min(1).max(4_096),
             tags: z.array(z.string().min(1)).optional(),
             ownerId: z.string().min(1).optional(),
             hubId: z.string().min(1).optional(),
-            source: z.string().min(1).optional(),
+            source: z.string().min(1).max(64).optional(),
             metadata: jsonRecordSchema.optional(),
-            consentScope: z.string().min(1).optional(),
-            consentVersion: z.string().nullable().optional(),
-            retentionPolicy: z.string().min(1).optional(),
+            consentScope: z.string().min(1).max(128).optional(),
+            consentVersion: z.string().max(64).nullable().optional(),
+            retentionPolicy: z.string().min(1).max(64).optional(),
             expiresAt: z.string().nullable().optional(),
         },
         annotations: {
@@ -1345,13 +1371,13 @@ export function createServer() {
             ...controlPlaneSchema,
             memoryId: z.string().min(1),
             kind: z.enum(["note", "preference", "fact"]).optional(),
-            title: z.string().max(512).nullable().optional(),
-            content: z.string().min(1).max(20_000).optional(),
+            title: z.string().max(160).nullable().optional(),
+            content: z.string().min(1).max(4_096).optional(),
             tags: z.array(z.string().min(1)).optional(),
             metadata: jsonRecordSchema.optional(),
-            consentScope: z.string().min(1).optional(),
-            consentVersion: z.string().nullable().optional(),
-            retentionPolicy: z.string().min(1).optional(),
+            consentScope: z.string().min(1).max(128).optional(),
+            consentVersion: z.string().max(64).nullable().optional(),
+            retentionPolicy: z.string().min(1).max(64).optional(),
             expiresAt: z.string().nullable().optional(),
             clearExpiresAt: z.boolean().optional(),
         },

package/examples/claude_desktop_config.json

@@ -4,6 +4,7 @@
       "command": "node",
       "args": ["/absolute/path/to/thalovant-mcp/dist/index.js"],
       "env": {
+        "THALOVANT_API_TOKEN": "tvpat_...",
         "THALOVANT_PROFILE": "prod"
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thalovant/mcp-server",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Stdio and Streamable HTTP MCP server for Thalovant control-plane and hub runtime APIs.",
   "license": "MIT",
   "type": "module",
@@ -69,7 +69,7 @@
     "zod": "^3.25.76"
   },
   "overrides": {
-    "fast-uri": "3.1.4"
+    "fast-uri": "3.1.5"
   },
   "devDependencies": {
     "@types/node": "^22.18.12",

package/server.json

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