wolves-mcp-tools

MCP (Model Context Protocol) server for the Wolves Experimentation 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

# 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:

{
  "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

cd mcp-tools
npm install

Build

npm run build

This compiles TypeScript from src/ to build/ using tsc.

Run

# Run compiled build
npm start

# Run in development mode (ts-node, no build needed)
npm run dev

Test

# 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.

# 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