npm package: @mindzie/mcp-server
Description: MCP server for mindzie process mining API - enables AI assistants to manage tenants, projects, and process mining data
Author: mindzie
Latest version: 1.1.0

# mindzie MCP Server

Model Context Protocol (MCP) server for the mindzie process mining API. Enables AI assistants like Claude to manage tenants, projects, datasets, investigations, notebooks, blocks, dashboards, and automation actions.

## Installation

### Using npx (Recommended)

No installation needed - just configure and run:

```bash
npx -y @mindzie/mcp-server
```

### Manual Installation

```bash
npm install -g @mindzie/mcp-server
```

## Terminology

Understanding mindzie's data model:

| Term | Description |
|------|-------------|
| **Tenant** | Organization/company account |
| **Project** | Container for datasets and investigations |
| **Dataset** | Event log data for process mining |
| **Investigation** | Container that holds analyses (like a folder) |
| **Analysis** | A notebook with an optional dashboard |
| **Notebook** | Contains filter and calculator blocks for analysis |
| **Dashboard** | Visualizes results from notebook blocks as panels |
| **Block** | Filter (reduces data) or Calculator (computes results) |

### Creating an Analysis via MCP

To create a full analysis:
1. Create a notebook with `mindzie_create_notebook` in an investigation
2. Add blocks to the notebook with `mindzie_create_block`
3. Optionally create a dashboard with `mindzie_create_dashboard`
4. Add panels to the dashboard with `mindzie_create_dashboard_panel`

**Note:** The UI creates a notebook and dashboard together when clicking "Empty Analysis". MCP keeps these operations separate for flexibility.

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `MINDZIE_API_KEY` | Yes | Your mindzie API key (Global API key for tenant operations) |
| `MINDZIE_BASE_URL` | No | API base URL (default: https://api.mindziestudio.com) |
| `MINDZIE_DEFAULT_TENANT` | No | Default tenant ID for operations |
| `MINDZIE_DEFAULT_PROJECT` | No | Default project ID for operations |
| `MINDZIE_TIMEOUT` | No | Request timeout in ms (default: 30000) |

### Getting Your API Key

1. Log in to mindzieStudio
2. Go to Settings -> API Keys
3. Create a new API key
4. For tenant management, you need a **Global API key** (created at /admin/global-api-keys)

## Claude Desktop Configuration

Add to your Claude Desktop config file:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mindzie": {
      "command": "npx",
      "args": ["-y", "@mindzie/mcp-server"],
      "env": {
        "MINDZIE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Available Tools (73 total)

### Tenant Management (requires Global API key)

| Tool | Description |
|------|-------------|
| `mindzie_list_tenants` | List all tenants with pagination |
| `mindzie_get_tenant` | Get tenant details by ID |
| `mindzie_create_tenant` | Create a new tenant |
| `mindzie_update_tenant` | Update tenant settings |
| `mindzie_delete_tenant` | Delete a tenant (requires triple verification) |

### Project Management

| Tool | Description |
|------|-------------|
| `mindzie_list_projects` | List projects in a tenant |
| `mindzie_get_project` | Get project details |
| `mindzie_create_project` | Create a new project |
| `mindzie_update_project` | Update project name/description |
| `mindzie_delete_project` | Delete a project |

### Dataset Management

| Tool | Description |
|------|-------------|
| `mindzie_list_datasets` | List datasets in a project |
| `mindzie_get_dataset` | Get dataset details |
| `mindzie_update_dataset_metadata` | Update dataset name/description/column mappings |
| `mindzie_delete_dataset` | Delete a dataset |

### Investigation Management

| Tool | Description |
|------|-------------|
| `mindzie_list_investigations` | List investigations in a project |
| `mindzie_get_investigation` | Get investigation details |
| `mindzie_create_investigation` | Create a new investigation |
| `mindzie_update_investigation` | Update investigation name/description |
| `mindzie_delete_investigation` | Delete an investigation |
| `mindzie_get_investigation_notebooks` | List notebooks in an investigation |

### Notebook Management

| Tool | Description |
|------|-------------|
| `mindzie_list_notebooks` | List notebooks in an investigation |
| `mindzie_get_notebook` | Get notebook details |
| `mindzie_create_notebook` | Create a new empty notebook |
| `mindzie_create_notebook_from_template` | Create notebook from a template |
| `mindzie_update_notebook` | Update notebook name/description |
| `mindzie_delete_notebook` | Delete a notebook |
| `mindzie_get_notebook_blocks` | List blocks in a notebook |
| `mindzie_execute_notebook` | Execute notebook and get results |
| `mindzie_get_notebook_url` | Get shareable notebook URL |

### Block Management

| Tool | Description |
|------|-------------|
| `mindzie_get_block` | Get block details and configuration |
| `mindzie_create_block` | Create a new block in a notebook |
| `mindzie_update_block` | Update block title/description/settings |
| `mindzie_delete_block` | Delete a block |
| `mindzie_move_block` | Move block to new position |
| `mindzie_execute_block` | Execute a single block |
| `mindzie_get_block_results` | Get block execution results |
| `mindzie_get_block_output_data` | Get filtered event log data from block |
| `mindzie_list_block_types` | List available block types (filters/calculators) |
| `mindzie_get_block_type` | Get block type details |
| `mindzie_get_block_type_schema` | Get configuration schema for block type |

### Dashboard Management

| Tool | Description |
|------|-------------|
| `mindzie_list_dashboards` | List dashboards in a project |
| `mindzie_get_dashboard` | Get dashboard details |
| `mindzie_create_dashboard` | Create a new dashboard |
| `mindzie_update_dashboard` | Update dashboard settings |
| `mindzie_delete_dashboard` | Delete a dashboard |
| `mindzie_copy_dashboard` | Create a copy of a dashboard |
| `mindzie_get_dashboard_url` | Get shareable dashboard URL |
| `mindzie_list_dashboard_panels` | List panels in a dashboard |
| `mindzie_create_dashboard_panel` | Create a panel linked to a block |
| `mindzie_update_dashboard_panel` | Update panel position/size/settings |
| `mindzie_delete_dashboard_panel` | Delete a panel |

### Execution Management

| Tool | Description |
|------|-------------|
| `mindzie_get_execution_status` | Get status of async execution |
| `mindzie_get_notebook_results` | Get detailed notebook execution results |
| `mindzie_wait_for_execution` | Wait for execution to complete with polling |

### Action Management (Automation)

| Tool | Description |
|------|-------------|
| `mindzie_list_actions` | List automation actions in a project |
| `mindzie_get_action` | Get action details with triggers and steps |
| `mindzie_create_action` | Create a new automation action |
| `mindzie_update_action` | Update action configuration |
| `mindzie_delete_action` | Delete an action |
| `mindzie_enable_action` | Enable an automation action |
| `mindzie_disable_action` | Disable an automation action |
| `mindzie_execute_action` | Manually trigger an action |
| `mindzie_list_action_executions` | List execution history for an action |
| `mindzie_get_action_execution` | Get details of specific execution |
| `mindzie_get_last_action_execution` | Get most recent execution |

### Action Log / Audit Trail

| Tool | Description |
|------|-------------|
| `mindzie_query_action_logs` | Query action logs with flexible filtering (date range, activity, entity type, user, outcome) |
| `mindzie_get_action_log_summary` | Get summary statistics for action logs (counts by outcome, top activities) |
| `mindzie_get_action_log` | Get a single action log entry by ID |

### Utility Tools

| Tool | Description |
|------|-------------|
| `mindzie_ping` | Test API connectivity |
| `mindzie_whoami` | Show current authentication context |

## Usage Examples

### List All Tenants

"List all my mindzie tenants"

### Create a New Tenant

"Create a new mindzie tenant called 'acme-corp' with display name 'Acme Corporation'"

### List Projects in a Tenant

"List all projects in tenant abc123-..."

### Create a Project

"Create a new project called 'Q4 Analysis' in tenant abc123-..."

### Create and Execute Analysis

"Create a notebook with an activity frequency filter and overview calculator, then execute it"

### Build a Dashboard

"Create a dashboard with panels showing case overview and activity frequency"

## Block Types

### Filter Blocks
Filters reduce the dataset by excluding cases or events that don't match criteria.

| Operator | Description |
|----------|-------------|
| ActivityFrequencyFilter | Filter by activity occurrence count |
| CaseFrequencyFilter | Filter by case occurrence patterns |
| TimeRangeFilter | Filter by date/time range |
| DurationFilter | Filter by case/activity duration |
| SequenceOrderFilter | Filter by activity sequence patterns |
| AttributeFilter | Filter by custom attribute values |

### Calculator Blocks
Calculators compute statistics and insights from the data.

| Operator | Description |
|----------|-------------|
| OverviewCalculator | Basic statistics (case count, event count, variants) |
| ActivityFrequencyCalculator | Count activities and frequencies |
| DurationCalculator | Calculate duration statistics |
| ResourceCalculator | Analyze resource utilization |
| VariantCalculator | Process variant analysis |
| ProcessMapCalculator | Generate process flow visualization |

## Development

### Building from Source

```bash
cd mindzieApiClients/TypeScript/mindzie-mcp-server
npm install
npm run build
```

### Running in Development Mode

```bash
npm run dev
```

### Testing Locally

1. Build the project: `npm run build`
2. Run directly: `node dist/index.js`
3. Or use with Claude Desktop config pointing to local path

## Error Codes

| Code | Description |
|------|-------------|
| `AUTHENTICATION_FAILED` | Invalid or missing API key |
| `VALIDATION_ERROR` | Invalid input parameters |
| `NOT_FOUND` | Resource not found |
| `PERMISSION_DENIED` | Insufficient permissions |
| `RATE_LIMITED` | Too many requests |
| `SERVER_ERROR` | Internal server error |
| `TIMEOUT` | Request timed out |
| `CONNECTION_ERROR` | Failed to connect to API |

## Roadmap

- [x] Tenant management tools
- [x] Project management tools
- [x] Dataset management tools (list, get, update, delete)
- [x] Investigation management tools
- [x] Notebook management and execution tools
- [x] Block management tools (create, configure, execute blocks)
- [x] Dashboard management tools
- [x] Action automation tools
- [x] Execution status polling tools
- [ ] Dataset upload tools (CSV file upload)
- [ ] Copilot integration tools

## License

MIT

## Support

For issues and feature requests, please contact mindzie support or create an issue in the repository.