touchstone-mcp-tools 1.0.1 → 1.0.3

package/build/handlers/wolves-handler.d.ts

@@ -43,6 +43,14 @@ export declare class WolvesHandler {
             progression_parameters?: any[];
         }>;
     }): Promise<ToolResult>;
+    updateSubscribers(params: {
+        experiment_id: string;
+        subscribers?: Array<{
+            id: string;
+            type: string;
+            tenantId: string;
+        }>;
+    }): Promise<ToolResult>;
     getExperiment(params: {
         experiment_id: string;
     }): Promise<ToolResult>;
@@ -52,4 +60,25 @@ export declare class WolvesHandler {
         status?: string;
         search?: string;
     }): Promise<ToolResult>;
+    logExperimentAction(params: {
+        action: string;
+        experiment: {
+            id: string;
+            name: string;
+            description?: string;
+            status?: string;
+            experiment_group?: string;
+            assignment_unit?: string;
+            progression_template?: string;
+            variants?: Array<{
+                id: string;
+                type: string;
+                description?: string;
+            }>;
+            subscribers?: string[];
+        };
+    }): Promise<ToolResult>;
+    getExperimentHistory(params: {
+        limit?: number;
+    }): Promise<ToolResult>;
 }

package/build/handlers/wolves-handler.js

@@ -1,4 +1,20 @@
 import { WolvesApiClient } from "../utils/wolves-api.js";
+import { existsSync, mkdirSync, writeFileSync, readdirSync, readFileSync } from "fs";
+import { join } from "path";
+// Generate 8-character variant ID: 4 lowercase letters + 4 digits
+// Matches ExP-Hub UI convention (e.g., "kifj6658", "tvan3734")
+function generateVariantId() {
+    const letters = "abcdefghijklmnopqrstuvwxyz";
+    const digits = "0123456789";
+    let result = "";
+    for (let i = 0; i < 4; i++) {
+        result += letters.charAt(Math.floor(Math.random() * letters.length));
+    }
+    for (let i = 0; i < 4; i++) {
+        result += digits.charAt(Math.floor(Math.random() * digits.length));
+    }
+    return result;
+}
 export class WolvesHandler {
     api;
     constructor(api) {
@@ -39,13 +55,18 @@ export class WolvesHandler {
     }
     // Tool 5: create_experiment
     async createExperiment(params) {
+        // Auto-generate 8-char variant IDs for variants that don't have one
+        const variants = params.variants.map((v) => ({
+            ...v,
+            id: v.id || generateVariantId(),
+        }));
         const result = await this.api.createExperiment({
             name: params.name,
             description: params.description,
             experimentation_group: params.experimentation_group,
             assignment_unit_id: params.assignment_unit_id,
             subscribers: params.subscribers,
-            variants: params.variants,
+            variants,
             metrics: params.metrics,
             progressions: params.progressions,
         });
@@ -54,7 +75,21 @@ export class WolvesHandler {
             message: `Experiment "${result.name}" created (ID: ${result.id})`,
         };
     }
-    // Tool 6: get_experiment
+    // Tool 6: update_subscribers
+    async updateSubscribers(params) {
+        let subscribers = params.subscribers;
+        // Default to current user from JWT when no subscribers provided
+        if (!subscribers || subscribers.length === 0) {
+            const user = this.api.getCurrentUser();
+            subscribers = [{ id: user.oid, type: "UserAccount", tenantId: user.tenantId }];
+        }
+        await this.api.updateSubscribers(params.experiment_id, { subscribers });
+        return {
+            data: { experiment_id: params.experiment_id, subscriber_count: subscribers.length },
+            message: `Updated ${subscribers.length} subscriber(s) for experiment "${params.experiment_id}"`,
+        };
+    }
+    // Tool 8: get_experiment
     async getExperiment(params) {
         const result = await this.api.getExperiment(params.experiment_id);
         return {
@@ -62,7 +97,7 @@ export class WolvesHandler {
             message: `Retrieved experiment "${result.name}" (status: ${result.status})`,
         };
     }
-    // Tool 7: list_experiments
+    // Tool 8: list_experiments
     async listExperiments(params) {
         const result = await this.api.listExperiments({
             page: params.page,
@@ -75,4 +110,45 @@ export class WolvesHandler {
             message: `Found ${result.items.length} experiment(s) (page ${result.page}/${result.total_pages}, total: ${result.total})`,
         };
     }
+    // Tool 9: log_experiment_action
+    async logExperimentAction(params) {
+        const expDir = join(process.cwd(), ".exp");
+        if (!existsSync(expDir)) {
+            mkdirSync(expDir, { recursive: true });
+        }
+        const now = new Date();
+        const timestamp = now.toISOString();
+        const filename = timestamp.replace(/[:.]/g, "-") + ".json";
+        const record = {
+            action: params.action,
+            timestamp,
+            experiment: params.experiment,
+        };
+        writeFileSync(join(expDir, filename), JSON.stringify(record, null, 2));
+        return {
+            data: record,
+            message: `Logged "${params.action}" for experiment "${params.experiment.name}"`,
+        };
+    }
+    // Tool 10: get_experiment_history
+    async getExperimentHistory(params) {
+        const expDir = join(process.cwd(), ".exp");
+        const limit = params.limit ?? 10;
+        if (!existsSync(expDir)) {
+            return { data: [], message: "No experiment history found" };
+        }
+        const files = readdirSync(expDir)
+            .filter((f) => f.endsWith(".json"))
+            .sort()
+            .reverse()
+            .slice(0, limit);
+        const records = files.map((f) => {
+            const content = readFileSync(join(expDir, f), "utf8");
+            return JSON.parse(content);
+        });
+        return {
+            data: records,
+            message: `Found ${records.length} experiment history record(s)`,
+        };
+    }
 }

package/build/schemas/wolves-tools.json

@@ -92,7 +92,7 @@
                         "type": "object",
                         "required": ["type"],
                         "properties": {
-                            "id": { "type": "string", "description": "Variant ID (auto-generated if omitted)" },
+                            "id": { "type": "string", "description": "Variant ID. 8-character alphanumeric (4 letters + 4 digits, e.g., 'kifj6658'). Auto-generated if omitted." },
                             "type": { "type": "string", "enum": ["control", "treatment"], "description": "Variant type" },
                             "description": { "type": "string", "description": "Variant description" }
                         }
@@ -130,6 +130,33 @@
             }
         }
     },
+    "update_subscribers": {
+        "name": "update_subscribers",
+        "description": "Update subscribers for an experiment. Subscribers receive notifications about experiment changes. If no subscribers are provided, defaults to the current logged-in user (resolved from auth token).",
+        "inputSchema": {
+            "type": "object",
+            "required": ["experiment_id"],
+            "properties": {
+                "experiment_id": {
+                    "type": "string",
+                    "description": "UUID of the experiment to update subscribers for"
+                },
+                "subscribers": {
+                    "type": "array",
+                    "description": "List of subscriber objects. If omitted, defaults to the current logged-in user.",
+                    "items": {
+                        "type": "object",
+                        "required": ["id", "type", "tenantId"],
+                        "properties": {
+                            "id": { "type": "string", "description": "Subscriber's user ID (from search_subscribers)" },
+                            "type": { "type": "string", "description": "Subscriber type (e.g., 'UserAccount')" },
+                            "tenantId": { "type": "string", "description": "Subscriber's tenant ID (from search_subscribers)" }
+                        }
+                    }
+                }
+            }
+        }
+    },
     "get_experiment": {
         "name": "get_experiment",
         "description": "Get detailed information about a specific experiment by its ID.",
@@ -153,5 +180,63 @@
                 "search": { "type": "string", "description": "Search in experiment name" }
             }
         }
+    },
+    "log_experiment_action": {
+        "name": "log_experiment_action",
+        "description": "Log an experiment action to local history (.exp/ directory). Called after creating an experiment to enable history-based recommendations in future runs.",
+        "inputSchema": {
+            "type": "object",
+            "required": ["action", "experiment"],
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "description": "The action performed (e.g., 'create_experiment')"
+                },
+                "experiment": {
+                    "type": "object",
+                    "required": ["id", "name"],
+                    "description": "Experiment details to log",
+                    "properties": {
+                        "id": { "type": "string", "description": "Experiment UUID" },
+                        "name": { "type": "string", "description": "Experiment name" },
+                        "description": { "type": "string", "description": "Experiment description" },
+                        "status": { "type": "string", "description": "Experiment status" },
+                        "experiment_group": { "type": "string", "description": "Experiment group ID used" },
+                        "assignment_unit": { "type": "string", "description": "Assignment unit ID used" },
+                        "progression_template": { "type": "string", "description": "Progression template ID used" },
+                        "variants": {
+                            "type": "array",
+                            "description": "Variants configured",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "id": { "type": "string" },
+                                    "type": { "type": "string" },
+                                    "description": { "type": "string" }
+                                }
+                            }
+                        },
+                        "subscribers": {
+                            "type": "array",
+                            "items": { "type": "string" },
+                            "description": "Subscriber display names"
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "get_experiment_history": {
+        "name": "get_experiment_history",
+        "description": "Get recent experiment history from local .exp/ directory. Returns the most recent records sorted by timestamp (newest first). Used to provide MRU-based recommendations when selecting experiment configuration.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "limit": {
+                    "type": "number",
+                    "description": "Maximum number of history records to return (default: 10)"
+                }
+            }
+        }
     }
 }

package/build/servers/wolves-server.js

@@ -42,12 +42,21 @@ export class WolvesServer {
                 case "create_experiment":
                     result = await this.handler.createExperiment(args);
                     break;
+                case "update_subscribers":
+                    result = await this.handler.updateSubscribers(args);
+                    break;
                 case "get_experiment":
                     result = await this.handler.getExperiment(args);
                     break;
                 case "list_experiments":
                     result = await this.handler.listExperiments(args);
                     break;
+                case "log_experiment_action":
+                    result = await this.handler.logExperimentAction(args);
+                    break;
+                case "get_experiment_history":
+                    result = await this.handler.getExperimentHistory(args);
+                    break;
                 default:
                     return wrapError(`Unknown tool: ${name}`);
             }
@@ -79,22 +88,7 @@ function wrapSuccess(result) {
     };
 }
 function wrapError(error) {
-    let message;
-    let statusCode;
-    let detail;
-    if (error && typeof error === "object" && "response" in error) {
-        // Axios error — extract API response details
-        const axiosError = error;
-        statusCode = axiosError.response?.status;
-        detail = axiosError.response?.data;
-        const apiDetail = detail?.detail || detail?.message || detail?.error || detail?.title;
-        message = apiDetail
-            ? `API error ${statusCode}: ${typeof apiDetail === "string" ? apiDetail : JSON.stringify(apiDetail)}`
-            : `Request failed with status code ${statusCode}`;
-    }
-    else {
-        message = error instanceof Error ? error.message : String(error);
-    }
+    const message = error instanceof Error ? error.message : String(error);
     return {
         content: [
             {
@@ -102,8 +96,6 @@ function wrapError(error) {
                 text: JSON.stringify({
                     success: false,
                     error: message,
-                    ...(statusCode ? { statusCode } : {}),
-                    ...(detail ? { detail } : {}),
                 }, null, 2),
             },
         ],

package/build/utils/token-manager.d.ts

@@ -1,8 +1,16 @@
+export interface TokenUserInfo {
+    oid: string;
+    tenantId: string;
+    email: string;
+    alias: string;
+    name: string;
+}
 export declare class TokenManager {
     private cachedTokens;
     private tokenFilePath;
     constructor();
     getToken(): Promise<string>;
+    getUserInfo(): TokenUserInfo;
     private isAccessTokenValid;
     private refreshAccessToken;
     private interactiveLogin;

package/build/utils/token-manager.js

@@ -46,6 +46,22 @@ export class TokenManager {
         await this.interactiveLogin();
         return this.cachedTokens.access_token;
     }
+    // ---- Public: User info from JWT ----
+    getUserInfo() {
+        if (!this.cachedTokens?.access_token) {
+            throw new Error("No access token available. Call getToken() first.");
+        }
+        const payload = this.cachedTokens.access_token.split(".")[1];
+        const decoded = JSON.parse(Buffer.from(payload, "base64url").toString());
+        const email = decoded.upn || decoded.unique_name || "";
+        return {
+            oid: decoded.oid || "",
+            tenantId: decoded.tid || "",
+            email,
+            alias: email.split("@")[0],
+            name: decoded.name || "",
+        };
+    }
     // ---- Private: Token lifecycle ----
     isAccessTokenValid() {
         if (!this.cachedTokens?.access_token)

package/build/utils/wolves-api.d.ts

@@ -1,4 +1,5 @@
 import { type AxiosError } from "axios";
+import { type TokenUserInfo } from "./token-manager.js";
 export interface TouchStoneApiConfig {
     baseUrl?: string;
 }
@@ -44,6 +45,14 @@ export interface SubscriberSearchResult {
     type: string;
     tenantId: string;
 }
+export interface SubscriberInput {
+    id: string;
+    type: string;
+    tenantId: string;
+}
+export interface UpdateSubscribersRequest {
+    subscribers: SubscriberInput[];
+}
 export interface VariantInput {
     id?: string;
     type: "control" | "treatment";
@@ -119,11 +128,13 @@ export declare class WolvesApiClient {
     private client;
     private tokenManager;
     constructor(config?: TouchStoneApiConfig);
+    getCurrentUser(): TokenUserInfo;
     listExperimentGroups(): Promise<ExperimentGroupResponse[]>;
     listProgressionTemplates(groupId: string): Promise<ProgressionTemplateResponse[]>;
     listAssignmentUnits(filter?: string): Promise<AssignmentUnitsListResponse>;
     searchSubscribers(search: string, count?: number, fetchUserPhoto?: boolean): Promise<SubscriberSearchResult[]>;
     createExperiment(data: CreateExperimentRequest): Promise<ExperimentDetail>;
+    updateSubscribers(experimentId: string, data: UpdateSubscribersRequest): Promise<void>;
     getExperiment(experimentId: string): Promise<ExperimentDetail>;
     listExperiments(params?: {
         page?: number;

package/build/utils/wolves-api.js

@@ -36,6 +36,9 @@ export class WolvesApiClient {
         });
     }
     // ---- Experiment Group endpoints ----
+    getCurrentUser() {
+        return this.tokenManager.getUserInfo();
+    }
     async listExperimentGroups() {
         const response = await this.client.get("/api/experiments/experiment-groups");
         return response.data;
@@ -69,6 +72,9 @@ export class WolvesApiClient {
         const response = await this.client.post("/api/experiments/experiments", data);
         return response.data;
     }
+    async updateSubscribers(experimentId, data) {
+        await this.client.put(`/api/experiments/experiments/${encodeURIComponent(experimentId)}/subscribers`, data);
+    }
     async getExperiment(experimentId) {
         const response = await this.client.get(`/api/experiments/experiments/${experimentId}`);
         return response.data;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "touchstone-mcp-tools",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "MCP tools for TouchStone Experimentation platform",
   "type": "module",
   "main": "build/index.js",