touchstone-mcp-tools 1.0.0

package/README.md

@@ -0,0 +1,199 @@
+# wolves-mcp-tools
+
+MCP (Model Context Protocol) server for the [Wolves Experimentation](https://wolves.microsoft.com) platform. Enables AI coding agents (Claude Code, Copilot CLI, Codex CLI) to create and manage A/B experiments through natural language interaction.
+
+## Prerequisites
+
+- **Node.js** >= 18.0.0
+- **Azure CLI** — You must be logged in via `az login` for authentication. The server uses `DefaultAzureCredential` to acquire tokens scoped to `https://graph.microsoft.com/.default`.
+
+## Installation
+
+```bash
+# Install from npm
+npm install wolves-mcp-tools
+
+# Or run directly via npx (no install needed)
+npx -y wolves-mcp-tools
+```
+
+## MCP Configuration
+
+Add the following to your `.mcp.json` to register the server with your AI coding agent:
+
+```json
+{
+  "mcpServers": {
+    "wolves-tools": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "wolves-mcp-tools"],
+      "description": "Wolves MCP tools for experiment management"
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_experiment` | Create a new A/B experiment in Wolves. Checks for duplicate names before creation. |
+| `update_experiment` | Update an existing experiment. Fetches current state and merges changes to prevent data loss. |
+| `list_experiments` | List all experiments with optional client-side filtering by status and result limiting. |
+| `get_experiment` | Get detailed information about a specific experiment by its UUID. |
+| `list_metrics` | List available metrics, optionally filtered by type (`count`, `sum`, `ratio`, `conversion`) or status. |
+| `list_api_keys` | List API keys, optionally filtered by experiment ID. |
+| `update_api_keys` | Update an API key's name, active status, or experiment/gate permissions. |
+
+### create_experiment
+
+Creates a new A/B experiment with the specified groups and configuration.
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `name` | string | Yes | — | Experiment name |
+| `groups` | array | Yes | — | Experiment groups (variants). First group defaults to control. |
+| `hypothesis` | string | No | — | Experiment hypothesis |
+| `allocationPercentage` | number | No | 100 | Overall traffic allocation (0-100) |
+| `targetDurationDays` | number | No | 14 | Target experiment duration in days |
+| `type` | string | No | `"ab"` | Experiment type |
+| `idType` | string | No | `"session_id"` | ID type for assignment |
+
+Each group requires `name` (string) and `size` (number, 0-100). Optional fields: `isControl` (boolean), `parameters` (array of `{name, type, value}`).
+
+### update_experiment
+
+Updates an existing experiment's configuration. Only provided fields are updated.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `experiment_id` | string (UUID) | Yes | The experiment to update |
+| `name` | string | No | New experiment name |
+| `hypothesis` | string | No | New hypothesis |
+| `allocationPercentage` | number | No | New traffic allocation (0-100) |
+| `groups` | array | No | Updated groups (replaces all existing) |
+| `targetDurationDays` | number | No | New target duration in days |
+| `type` | string | No | Experiment type |
+| `idType` | string | No | ID type for assignment |
+| `targetingCriteria` | string | No | Targeting criteria expression |
+| `analysisType` | string | No | Analysis type |
+| `defaultConfidenceInterval` | number | No | Default confidence interval |
+
+### list_experiments
+
+Lists all experiments with optional filtering.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `status` | string | No | Filter by: `"setup"`, `"in_progress"`, or `"completed"` |
+| `limit` | number | No | Maximum number of results to return |
+
+### get_experiment
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `experiment_id` | string (UUID) | Yes | The experiment to retrieve |
+
+### list_metrics
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | No | Filter by: `"count"`, `"sum"`, `"ratio"`, or `"conversion"` |
+| `status` | string | No | Filter by metric status |
+
+### list_api_keys
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `experiment_id` | string | No | Filter keys by experiment ID |
+
+### update_api_keys
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `key_id` | string (UUID) | Yes | The API key to update |
+| `name` | string | No | New name for the API key |
+| `is_active` | boolean | No | Whether the key is active |
+| `experiment_ids` | string[] | No | Experiment IDs this key has access to (replaces existing) |
+| `gate_ids` | string[] | No | Gate IDs this key has access to (replaces existing) |
+
+## Development
+
+### Setup
+
+```bash
+cd mcp-tools
+npm install
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+This compiles TypeScript from `src/` to `build/` using `tsc`.
+
+### Run
+
+```bash
+# Run compiled build
+npm start
+
+# Run in development mode (ts-node, no build needed)
+npm run dev
+```
+
+### Test
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage report
+npm run test:coverage
+```
+
+### Publish to npm
+
+The package is configured for publishing to the public npm registry.
+
+```bash
+# 1. Login to npm (one-time)
+npm login
+
+# 2. Publish (automatically runs build via prepublishOnly)
+npm publish
+```
+
+The `files` field in `package.json` ensures only the `build/` directory is included in the published package. No source code, tests, or documentation are shipped.
+
+## Architecture
+
+```
+mcp-tools/src/
++-- index.ts                    # Barrel exports
++-- servers/
+|   +-- wolves-server.ts        # MCP server wiring + CLI entry point
++-- handlers/
+|   +-- wolves-handler.ts       # Business logic (7 tool methods)
++-- utils/
+|   +-- token-manager.ts        # DefaultAzureCredential + token caching
+|   +-- wolves-api.ts           # Axios HTTP client for Wolves REST API
++-- schemas/
+    +-- wolves-tools.json       # MCP tool definitions (JSON Schema)
+```
+
+- **Server** — Registers MCP tools and routes calls to handler methods via stdio transport.
+- **Handler** — Implements business logic including duplicate name checking, fetch-then-merge updates, and client-side filtering.
+- **API Client** — Axios-based HTTP client with automatic Bearer token injection.
+- **Token Manager** — Acquires and caches Azure AD tokens using `DefaultAzureCredential`, auto-refreshing 5 minutes before expiry.
+
+## License
+
+MIT

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

@@ -0,0 +1,55 @@
+import { WolvesApiClient } from "../utils/wolves-api.js";
+export interface ToolResult {
+    data: any;
+    message: string;
+}
+export declare class WolvesHandler {
+    private api;
+    constructor(api?: WolvesApiClient);
+    listExperimentGroups(): Promise<ToolResult>;
+    listProgressionTemplates(params: {
+        group_id: string;
+    }): Promise<ToolResult>;
+    listAssignmentUnits(params: {
+        filter?: string;
+    }): Promise<ToolResult>;
+    searchSubscribers(params: {
+        search: string;
+        count?: number;
+        fetch_user_photo?: boolean;
+    }): Promise<ToolResult>;
+    createExperiment(params: {
+        name: string;
+        experimentation_group: string;
+        variants: Array<{
+            id?: string;
+            type: "control" | "treatment";
+            description?: string;
+        }>;
+        description?: string;
+        assignment_unit_id?: string;
+        subscribers?: string[];
+        metrics?: Array<{
+            name: string;
+            type: string;
+            description?: string;
+        }>;
+        progressions?: Array<{
+            name: string;
+            feature_gates?: any[];
+            stages?: any[];
+            progression_template_id?: string;
+            progression_template_parameters?: Record<string, any>;
+            progression_parameters?: any[];
+        }>;
+    }): Promise<ToolResult>;
+    getExperiment(params: {
+        experiment_id: string;
+    }): Promise<ToolResult>;
+    listExperiments(params: {
+        page?: number;
+        page_size?: number;
+        status?: string;
+        search?: string;
+    }): Promise<ToolResult>;
+}

package/build/handlers/wolves-handler.js

@@ -0,0 +1,77 @@
+import { WolvesApiClient } from "../utils/wolves-api.js";
+export class WolvesHandler {
+    api;
+    constructor(api) {
+        this.api = api || new WolvesApiClient();
+    }
+    // Tool 1: list_experiment_groups
+    async listExperimentGroups() {
+        const result = await this.api.listExperimentGroups();
+        return {
+            data: result,
+            message: `Found ${result.length} experiment group(s)`,
+        };
+    }
+    // Tool 2: list_progression_templates
+    async listProgressionTemplates(params) {
+        const result = await this.api.listProgressionTemplates(params.group_id);
+        return {
+            data: result,
+            message: `Found ${result.length} progression template(s) for group "${params.group_id}"`,
+        };
+    }
+    // Tool 3: list_assignment_units
+    async listAssignmentUnits(params) {
+        const result = await this.api.listAssignmentUnits(params.filter);
+        return {
+            data: result,
+            message: `Found ${result.value.length} assignment unit(s)`,
+        };
+    }
+    // Tool 4: search_subscribers
+    async searchSubscribers(params) {
+        const result = await this.api.searchSubscribers(params.search, params.count, params.fetch_user_photo);
+        return {
+            data: result,
+            message: `Found ${result.length} subscriber(s) matching "${params.search}"`,
+        };
+    }
+    // Tool 5: create_experiment
+    async createExperiment(params) {
+        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,
+            metrics: params.metrics,
+            progressions: params.progressions,
+        });
+        return {
+            data: result,
+            message: `Experiment "${result.name}" created (ID: ${result.id})`,
+        };
+    }
+    // Tool 6: get_experiment
+    async getExperiment(params) {
+        const result = await this.api.getExperiment(params.experiment_id);
+        return {
+            data: result,
+            message: `Retrieved experiment "${result.name}" (status: ${result.status})`,
+        };
+    }
+    // Tool 7: list_experiments
+    async listExperiments(params) {
+        const result = await this.api.listExperiments({
+            page: params.page,
+            page_size: params.page_size,
+            status: params.status,
+            search: params.search,
+        });
+        return {
+            data: result,
+            message: `Found ${result.items.length} experiment(s) (page ${result.page}/${result.total_pages}, total: ${result.total})`,
+        };
+    }
+}

package/build/index.d.ts

@@ -0,0 +1,5 @@
+export { WolvesServer } from "./servers/wolves-server.js";
+export { WolvesHandler, type ToolResult } from "./handlers/wolves-handler.js";
+export { WolvesApiClient } from "./utils/wolves-api.js";
+export { TokenManager } from "./utils/token-manager.js";
+export type { TouchStoneApiConfig, ExperimentGroupResponse, ProgressionTemplateResponse, AssignmentUnitItem, AssignmentUnitsListResponse, SubscriberSearchResult, VariantInput, MetricInput, ProgressionInput, CreateExperimentRequest, ExperimentDetail, ExperimentSummary, PaginatedExperimentsResponse, } from "./utils/wolves-api.js";

package/build/index.js

@@ -0,0 +1,5 @@
+// Barrel exports
+export { WolvesServer } from "./servers/wolves-server.js";
+export { WolvesHandler } from "./handlers/wolves-handler.js";
+export { WolvesApiClient } from "./utils/wolves-api.js";
+export { TokenManager } from "./utils/token-manager.js";

package/build/schemas/wolves-tools.json

@@ -0,0 +1,157 @@
+{
+    "list_experiment_groups": {
+        "name": "list_experiment_groups",
+        "description": "List all experimentation groups in TouchStone. Returns group IDs and names for use when creating experiments.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {}
+        }
+    },
+    "list_progression_templates": {
+        "name": "list_progression_templates",
+        "description": "List progression templates for a specific experimentation group. Returns available templates that can be used when creating experiment progressions.",
+        "inputSchema": {
+            "type": "object",
+            "required": ["group_id"],
+            "properties": {
+                "group_id": {
+                    "type": "string",
+                    "description": "The experimentation group ID (e.g., 'exponexpws~authoring')"
+                }
+            }
+        }
+    },
+    "list_assignment_units": {
+        "name": "list_assignment_units",
+        "description": "List assignment units in TouchStone. Assignment units define how users are assigned to experiment variants (e.g., by user ID, session ID).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "filter": {
+                    "type": "string",
+                    "description": "OData filter expression (e.g., 'IsArchived eq false')"
+                }
+            }
+        }
+    },
+    "search_subscribers": {
+        "name": "search_subscribers",
+        "description": "Search for subscribers by name or email. Subscribers can be added to experiments to receive notifications.",
+        "inputSchema": {
+            "type": "object",
+            "required": ["search"],
+            "properties": {
+                "search": {
+                    "type": "string",
+                    "description": "Search string for subscriber name or email"
+                },
+                "count": {
+                    "type": "number",
+                    "description": "Maximum number of results to return (default: 5)"
+                },
+                "fetch_user_photo": {
+                    "type": "boolean",
+                    "description": "Whether to include user photos in results (default: false)"
+                }
+            }
+        }
+    },
+    "create_experiment": {
+        "name": "create_experiment",
+        "description": "Create a new experiment in TouchStone. Requires a name, experimentation group, and at least one variant (control/treatment).",
+        "inputSchema": {
+            "type": "object",
+            "required": ["name", "experimentation_group", "variants"],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Name of the experiment"
+                },
+                "description": {
+                    "type": "string",
+                    "description": "Description of the experiment"
+                },
+                "experimentation_group": {
+                    "type": "string",
+                    "description": "Experimentation group ID (e.g., 'exponexpws~test')"
+                },
+                "assignment_unit_id": {
+                    "type": "string",
+                    "description": "Assignment unit ID (e.g., 'userid')"
+                },
+                "subscribers": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "List of subscriber display names to notify"
+                },
+                "variants": {
+                    "type": "array",
+                    "description": "Experiment variants. Must include at least one control and one treatment.",
+                    "minItems": 1,
+                    "items": {
+                        "type": "object",
+                        "required": ["type"],
+                        "properties": {
+                            "id": { "type": "string", "description": "Variant ID (auto-generated if omitted)" },
+                            "type": { "type": "string", "enum": ["control", "treatment"], "description": "Variant type" },
+                            "description": { "type": "string", "description": "Variant description" }
+                        }
+                    }
+                },
+                "metrics": {
+                    "type": "array",
+                    "description": "Metrics to track for this experiment",
+                    "items": {
+                        "type": "object",
+                        "required": ["name", "type"],
+                        "properties": {
+                            "name": { "type": "string", "description": "Metric name" },
+                            "type": { "type": "string", "description": "Metric type (e.g., 'Primary', 'Guardrail')" },
+                            "description": { "type": "string", "description": "Metric description" }
+                        }
+                    }
+                },
+                "progressions": {
+                    "type": "array",
+                    "description": "Progression configurations for staged rollout",
+                    "items": {
+                        "type": "object",
+                        "required": ["name"],
+                        "properties": {
+                            "name": { "type": "string", "description": "Progression name" },
+                            "feature_gates": { "type": "array", "description": "Feature gate conditions" },
+                            "stages": { "type": "array", "description": "Rollout stages" },
+                            "progression_template_id": { "type": "string", "description": "ID of the progression template to use" },
+                            "progression_template_parameters": { "type": "object", "description": "Template parameters" },
+                            "progression_parameters": { "type": "array", "description": "Progression parameters" }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "get_experiment": {
+        "name": "get_experiment",
+        "description": "Get detailed information about a specific experiment by its ID.",
+        "inputSchema": {
+            "type": "object",
+            "required": ["experiment_id"],
+            "properties": {
+                "experiment_id": { "type": "string", "description": "UUID of the experiment" }
+            }
+        }
+    },
+    "list_experiments": {
+        "name": "list_experiments",
+        "description": "List experiments with pagination and optional filtering. Returns experiment summaries with pagination metadata.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "page": { "type": "number", "description": "Page number (default: 1)" },
+                "page_size": { "type": "number", "description": "Results per page (default: 20, max: 100)" },
+                "status": { "type": "string", "description": "Filter by status: 'new', 'running', or 'stopped'" },
+                "search": { "type": "string", "description": "Search in experiment name" }
+            }
+        }
+    }
+}

package/build/servers/wolves-server.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { WolvesHandler } from "../handlers/wolves-handler.js";
+export declare class WolvesServer {
+    private server;
+    private handler;
+    constructor(handler?: WolvesHandler);
+    private setupToolHandlers;
+    private handleToolCall;
+    run(): Promise<void>;
+}

package/build/servers/wolves-server.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { WolvesHandler } from "../handlers/wolves-handler.js";
+import toolDefinitions from "../schemas/wolves-tools.json" with { type: "json" };
+export class WolvesServer {
+    server;
+    handler;
+    constructor(handler) {
+        this.handler = handler || new WolvesHandler();
+        this.server = new Server({ name: "touchstone-tools", version: "1.0.0" }, { capabilities: { tools: {} } });
+        this.setupToolHandlers();
+    }
+    setupToolHandlers() {
+        // List all available tools
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: Object.values(toolDefinitions),
+        }));
+        // Route tool calls to handler methods
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            return this.handleToolCall(name, args);
+        });
+    }
+    async handleToolCall(name, args) {
+        try {
+            let result;
+            switch (name) {
+                case "list_experiment_groups":
+                    result = await this.handler.listExperimentGroups();
+                    break;
+                case "list_progression_templates":
+                    result = await this.handler.listProgressionTemplates(args);
+                    break;
+                case "list_assignment_units":
+                    result = await this.handler.listAssignmentUnits(args);
+                    break;
+                case "search_subscribers":
+                    result = await this.handler.searchSubscribers(args);
+                    break;
+                case "create_experiment":
+                    result = await this.handler.createExperiment(args);
+                    break;
+                case "get_experiment":
+                    result = await this.handler.getExperiment(args);
+                    break;
+                case "list_experiments":
+                    result = await this.handler.listExperiments(args);
+                    break;
+                default:
+                    return wrapError(`Unknown tool: ${name}`);
+            }
+            return wrapSuccess(result);
+        }
+        catch (error) {
+            return wrapError(error);
+        }
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error("TouchStone MCP server running on stdio");
+    }
+}
+// ---- Response helpers ----
+function wrapSuccess(result) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    success: true,
+                    data: result.data,
+                    message: result.message,
+                }, null, 2),
+            },
+        ],
+    };
+}
+function wrapError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    success: false,
+                    error: message,
+                }, null, 2),
+            },
+        ],
+        isError: true,
+    };
+}
+// ---- Entry point ----
+import { fileURLToPath } from "url";
+import { realpathSync } from "fs";
+const currentFilePath = fileURLToPath(import.meta.url);
+const entryPointPath = process.argv[1] ? realpathSync(process.argv[1]) : "";
+if (currentFilePath === entryPointPath) {
+    const server = new WolvesServer();
+    server.run().catch(console.error);
+}

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

@@ -0,0 +1,9 @@
+export declare class TokenManager {
+    private credential;
+    private cachedToken;
+    private static readonly SCOPE;
+    private static readonly BUFFER_MS;
+    constructor();
+    getToken(): Promise<string>;
+    private isTokenValid;
+}

package/build/utils/token-manager.js

@@ -0,0 +1,32 @@
+import { DefaultAzureCredential } from "@azure/identity";
+export class TokenManager {
+    credential;
+    cachedToken = null;
+    // TouchStone API validates against Microsoft Graph
+    static SCOPE = "https://graph.microsoft.com/.default";
+    // Refresh token 5 minutes before expiry
+    static BUFFER_MS = 5 * 60 * 1000;
+    constructor() {
+        this.credential = new DefaultAzureCredential();
+    }
+    async getToken() {
+        if (this.isTokenValid()) {
+            return this.cachedToken.token;
+        }
+        try {
+            this.cachedToken = await this.credential.getToken(TokenManager.SCOPE);
+            return this.cachedToken.token;
+        }
+        catch (error) {
+            throw new Error("Azure authentication failed. Please ensure you are logged in by running `az login`. " +
+                `Details: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    isTokenValid() {
+        if (!this.cachedToken)
+            return false;
+        const now = Date.now();
+        const expiresAt = this.cachedToken.expiresOnTimestamp - TokenManager.BUFFER_MS;
+        return now < expiresAt;
+    }
+}

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

@@ -0,0 +1,134 @@
+import { type AxiosError } from "axios";
+export interface TouchStoneApiConfig {
+    baseUrl?: string;
+}
+export interface ExperimentGroupResponse {
+    id: string;
+    name: string;
+    description: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface ProgressionTemplateResponse {
+    id: string;
+    experiment_group_id: string;
+    name: string;
+    description: string | null;
+    template_config: Record<string, any>;
+    created_at: string;
+    updated_at: string;
+}
+export interface AssignmentUnitItem {
+    id: string;
+    displayName: string;
+    description: string | null;
+    isArchived: boolean;
+    runtimeId: string | null;
+    eTag: string | null;
+    experimentationGroups: string[];
+}
+export interface AssignmentUnitsListResponse {
+    count: number | null;
+    value: AssignmentUnitItem[];
+    nextLink: string | null;
+    nextLinkQuery: string | null;
+}
+export interface SubscriberSearchResult {
+    displayName: string;
+    mail: string | null;
+    mailNickname: string | null;
+    userPrincipalName: string | null;
+    department: string | null;
+    userPhotoBase64: string | null;
+    id: string;
+    type: string;
+    tenantId: string;
+}
+export interface VariantInput {
+    id?: string;
+    type: "control" | "treatment";
+    description?: string;
+}
+export interface MetricInput {
+    name: string;
+    type: string;
+    description?: string;
+}
+export interface ProgressionInput {
+    name: string;
+    feature_gates?: any[];
+    stages?: any[];
+    progression_template_id?: string;
+    progression_template_parameters?: Record<string, any>;
+    progression_parameters?: any[];
+}
+export interface CreateExperimentRequest {
+    name: string;
+    description?: string;
+    experimentation_group: string;
+    assignment_unit_id?: string;
+    subscribers?: string[];
+    variants: VariantInput[];
+    metrics?: MetricInput[];
+    progressions?: ProgressionInput[];
+}
+export interface ExperimentDetail {
+    id: string;
+    name: string;
+    description: string | null;
+    status: string;
+    experiment_group_id: string | null;
+    experiment_group_name: string | null;
+    owner_email: string | null;
+    subscribers: string[];
+    variants: any[];
+    metrics: any[];
+    progressions: any[];
+    created_at: string;
+    updated_at: string;
+    started_at: string | null;
+}
+export interface ExperimentSummary {
+    id: string;
+    name: string;
+    description: string | null;
+    status: string;
+    experiment_group_id: string | null;
+    experiment_group_name: string | null;
+    owner_email: string | null;
+    subscribers: string[];
+    variant_count: number;
+    metric_count: number;
+    progression_count: number;
+    created_at: string;
+    updated_at: string;
+    started_at: string | null;
+}
+export interface PaginatedExperimentsResponse {
+    items: ExperimentSummary[];
+    total: number;
+    page: number;
+    page_size: number;
+    total_pages: number;
+}
+export declare function normalizeError(error: AxiosError): {
+    message: string;
+    statusCode: number;
+};
+export declare class WolvesApiClient {
+    private client;
+    private tokenManager;
+    constructor(config?: TouchStoneApiConfig);
+    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>;
+    getExperiment(experimentId: string): Promise<ExperimentDetail>;
+    listExperiments(params?: {
+        page?: number;
+        page_size?: number;
+        status?: string;
+        search?: string;
+    }): Promise<PaginatedExperimentsResponse>;
+}

package/build/utils/wolves-api.js

@@ -0,0 +1,80 @@
+import axios from "axios";
+import { TokenManager } from "./token-manager.js";
+// ---- Error Handling ----
+export function normalizeError(error) {
+    if (error.response) {
+        const detail = error.response.data?.detail || error.message;
+        return { message: detail, statusCode: error.response.status };
+    }
+    if (error.request) {
+        return { message: "No response from TouchStone API", statusCode: 0 };
+    }
+    return { message: error.message, statusCode: 0 };
+}
+// ---- API Client ----
+export class WolvesApiClient {
+    client;
+    tokenManager;
+    constructor(config) {
+        this.tokenManager = new TokenManager();
+        const baseURL = config?.baseUrl
+            || process.env.TOUCHSTONE_API_BASE_URL
+            || "https://touchstone-dev.azurewebsites.net";
+        this.client = axios.create({
+            baseURL,
+            headers: {
+                "Content-Type": "application/json",
+                "X-Auth-Provider": "microsoft",
+            },
+            timeout: 30000,
+        });
+        // Request interceptor: inject Bearer token
+        this.client.interceptors.request.use(async (config) => {
+            const token = await this.tokenManager.getToken();
+            config.headers.Authorization = `Bearer ${token}`;
+            return config;
+        });
+    }
+    // ---- Experiment Group endpoints ----
+    async listExperimentGroups() {
+        const response = await this.client.get("/api/experiments/experiment-groups");
+        return response.data;
+    }
+    // ---- Progression Template endpoints ----
+    async listProgressionTemplates(groupId) {
+        const response = await this.client.get(`/api/experiments/experiment-groups/${encodeURIComponent(groupId)}/progression-templates`);
+        return response.data;
+    }
+    // ---- Assignment Unit endpoints ----
+    async listAssignmentUnits(filter) {
+        const params = {};
+        if (filter) {
+            params.filter = filter;
+        }
+        const response = await this.client.get("/api/experiments/assignment-units", { params });
+        return response.data;
+    }
+    // ---- Subscriber endpoints ----
+    async searchSubscribers(search, count, fetchUserPhoto) {
+        const params = {
+            search,
+            count: count ?? 5,
+            fetch_user_photo: fetchUserPhoto ?? false,
+        };
+        const response = await this.client.get("/api/experiments/subscribers/search", { params });
+        return response.data;
+    }
+    // ---- Experiment endpoints ----
+    async createExperiment(data) {
+        const response = await this.client.post("/api/experiments/experiments", data);
+        return response.data;
+    }
+    async getExperiment(experimentId) {
+        const response = await this.client.get(`/api/experiments/experiments/${experimentId}`);
+        return response.data;
+    }
+    async listExperiments(params) {
+        const response = await this.client.get("/api/experiments/experiments", { params });
+        return response.data;
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "touchstone-mcp-tools",
+  "version": "1.0.0",
+  "description": "MCP tools for TouchStone Experimentation platform",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "touchstone-mcp-tools": "build/servers/wolves-server.js"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/servers/wolves-server.js",
+    "dev": "tsx src/servers/wolves-server.ts",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@azure/identity": "^4.6.0",
+    "axios": "^1.7.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.0",
+    "@jest/globals": "^29.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT"
+}