# Parallel Works MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with the Parallel Works ACTIVATE REST API. This allows code assist agents to manage Parallel Works resources including clusters, storage, workflows, and more.

## Features

The MCP server provides tools for managing:

- **Clusters**: List and query compute clusters and nodes
- **Workflows**: List, inspect, and execute workflows
- **Storage**: Manage buckets, Lustre filesystems, and NFS storage
- **Sessions**: View and manage user sessions
- **Allocations**: Query budget allocations and usage
- **Machine Learning**: List and manage ML workspaces (AWS SageMaker, Azure ML)
- **Kubernetes**: Query Kubernetes clusters
- **User Resources**: Get notifications, organizations, and groups

## Installation

### Prerequisites

- Node.js 18+ or recent version
- Parallel Works ACTIVATE account with API access

### Setup

1. Clone or navigate to the project directory:
```bash
cd parallel-works-mcp
```

2. Install dependencies:
```bash
npm install
```

## Configuration

The MCP server requires authentication to connect to the Parallel Works API. You can authenticate using either:

### Option 1: API Key (Basic Auth)

```bash
export PARALLEL_WORKS_API_KEY="your-api-key-here"
```

### Option 2: Bearer Token (JWT)

```bash
export PARALLEL_WORKS_TOKEN="your-jwt-token-here"
```

### Optional: Custom API URL

```bash
export PARALLEL_WORKS_API_URL="https://activate.parallel.works"
```

## Usage

### Running the Server

Start the MCP server with stdio transport:

```bash
npm start
```

Or using Node directly:

```bash
node src/index.js
```

With custom API URL:

```bash
node src/index.js --api-url https://activate.parallel.works --api-key YOUR_KEY
```

With Bearer token:

```bash
node src/index.js --token YOUR_JWT_TOKEN
```

### MCP Client Configuration

The recommended way to add the MCP server is by editing your `~/.claude.json` configuration file directly:

```bash
# Open your Claude config file
nano ~/.claude.json
```

Add the MCP server configuration to each project where you want to use it:

```json
{
  "projects": {
    "/your/project/path": {
      "mcpServers": {
        "parallelworks": {
          "type": "stdio",
          "command": "node",
          "args": ["/absolute/path/to/parallel-works-mcp/src/index.js"],
          "env": {
            "PARALLEL_WORKS_API_KEY": "your-api-key-here"
          }
        }
      },
      "enabledMcpjsonServers": ["parallelworks"]
    }
  }
}
```

**Configuration options:**
| Field | Value |
|-------|-------|
| `type` | `"stdio"` - standard input/output communication |
| `command` | `"node"` - Node.js runtime |
| `args` | Array with absolute path to `src/index.js` |
| `env.PARALLEL_WORKS_API_KEY` | Your Parallel Works ACTIVATE API key |
| `enabledMcpjsonServers` | `["parallelworks"]` - enables the server |

**To enable for all projects**, add the same configuration under each project path in your `~/.claude.json` file.

## Available Tools

### Authentication & User Info

#### `get_auth_session`
Get the current authentication session and user information.

```json
{}
```

#### `get_organizations`
List organizations the user can access.

```json
{}
```

#### `get_groups`
Get groups for the authenticated user.

```json
{
  "provider": "aws-slurm",
  "network": "my-network"
}
```

### Cluster Operations

#### `list_clusters`
List all clusters the user can access.

```json
{}
```

#### `get_cluster_nodes`
Get nodes for a specific compute cluster.

```json
{
  "organization": "parallelworks",
  "user": "username",
  "clusterName": "my-cluster",
  "type": "compute"
}
```

### Workflow Operations

#### `list_workflows`
List all workflows for the authenticated user.

```json
{
  "filter": "workflows"
}
```

#### `get_workflow`
Get details of a specific workflow.

```json
{
  "workflow": "my-workflow"
}
```

#### `get_workflow_yaml`
Get the YAML configuration of a workflow.

```json
{
  "workflow": "my-workflow"
}
```

#### `run_workflow`
Run a workflow with optional input parameters.

```json
{
  "workflow": "my-workflow",
  "inputs": {
    "param1": "value1",
    "param2": "value2"
  }
}
```

### Storage Operations

#### `list_buckets`
List storage buckets the user can access.

```json
{
  "permission": "edit",
  "provisioned": true
}
```

#### `list_lustre`
List Lustre filesystems the user can access.

```json
{
  "permission": "mount",
  "provisioned": true
}
```

#### `list_nfs`
List NFS filesystems the user can access.

```json
{
  "permission": "edit",
  "provisioned": true
}
```

### Session Operations

#### `list_sessions`
List sessions for the authenticated user.

```json
{
  "type": "tunnel",
  "subdomain": "my-subdomain"
}
```

### Allocation Operations

#### `list_allocations`
List budget allocations the user can access.

```json
{
  "limit": 50,
  "skip": 0,
  "name": "production",
  "sort": "-total"
}
```

### Kubernetes Operations

#### `list_kubernetes_clusters`
List Kubernetes clusters accessible to the user.

```json
{}
```

### ML Workspace Operations

#### `list_ml_workspaces`
List Machine Learning Workspaces.

```json
{
  "csp": "aws",
  "region": "us-west-2",
  "provisioned": true
}
```

### Notifications

#### `get_notifications`
Get notifications for the authenticated user.

```json
{
  "limit": 20,
  "skip": 0,
  "read": false
}
```

## Example Conversations

### Listing Clusters

```
User: List all my clusters
Assistant: [calls list_clusters] Here are your clusters...
```

### Running a Workflow

```
User: Run the "data-processing" workflow with input dataset="s3://my-bucket/data"
Assistant: [calls run_workflow with workflow="data-processing", inputs={"dataset": "s3://my-bucket/data"}] Workflow started successfully...
```

### Checking Storage

```
User: What Lustre filesystems do I have access to?
Assistant: [calls list_lustre] You have access to the following Lustre filesystems...
```

### Managing Sessions

```
User: Show me all my active tunnel sessions
Assistant: [calls list_sessions with type="tunnel"] Here are your active tunnel sessions...
```

## Error Handling

The MCP server handles errors gracefully:

- **Authentication errors**: Check your API key or token
- **Network errors**: Verify your network connection and API URL
- **Invalid parameters**: Check the tool input schema
- **Resource not found**: Verify resource names and permissions

All errors are returned with descriptive messages in the response.

## Development

### Project Structure

```
parallel-works-mcp/
├── src/
│   └── index.js          # Main MCP server implementation
├── package.json           # Dependencies and scripts
├── pw-openapi.json       # OpenAPI specification (reference)
├── PROGRESS.md           # Development progress tracking
└── README.md             # This file
```

### Adding New Tools

To add a new tool:

1. Add the tool definition to the `tools` array in `src/index.js`
2. Add a case in the `CallToolRequestSchema` handler
3. Test the tool with your MCP client

Example:

```javascript
{
  name: 'my_new_tool',
  description: 'Does something useful',
  inputSchema: {
    type: 'object',
    properties: {
      param1: { type: 'string', description: 'First parameter' },
    },
    required: ['param1'],
  },
}
```

## API Reference

This MCP server is based on the Parallel Works ACTIVATE OpenAPI specification:
- **Base URL**: `https://activate.parallel.works`
- **Documentation**: [Parallel Works Docs](https://parallelworks.com/docs)
- **OpenAPI Spec**: Included as `pw-openapi.json`

## License

MIT

## Support

For issues or questions:
- Parallel Works Support: support@parallelworks.com
- GitHub Issues: [Create an issue in the repository]