npm package: @shakudo/shakudo-platform-mcp
Description: Model Context Protocol server for Shakudo Platform API with enhanced image builder tools
Author: Hyperplane Team
Latest version: 1.1.3

# Hyperplane MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to the Hyperplane API for managing data science and machine learning workloads on Kubernetes.

## Overview

This MCP server provides **3 tested and production-ready microservice management tools** that can be used by AI assistants like Claude. Currently focused on core microservice operations with additional tools to be enabled after testing:

- **✅ Microservice Management**: Search, restart, and monitor microservices (PRODUCTION-TESTED)

**🚧 Additional Categories (126+ tools) - Disabled until testing complete**:
- Pipeline Job Management, Interactive Computing, Distributed Computing, Container Images, Platform Services, Security & Access, Monitoring, Multi-Cluster, and more...

## Installation

### Prerequisites

- [Bun](https://bun.sh/) runtime (recommended) or Node.js 18 or higher

### Install Dependencies

```bash
bun install
```

### Build

```bash
bun run build
```

The server automatically connects to the Hyperplane API at `http://api-server.hyperplane-core.svc.cluster.local:80/graphql`.

## Usage

### With Claude Desktop

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "shakudo-microservices": {
      "command": "bun",
      "args": ["run", "dev"],
      "cwd": "/absolute/path/to/shakudo-platform-mcp/mcp-server",
      "env": {
        "HYPERPLANE_API_ENDPOINT": "http://api-server.hyperplane-core.svc.cluster.local:80/graphql"
      }
    }
  }
}
```

**Setup Steps**:

1. **Build the server**:
   ```bash
   cd /path/to/shakudo-platform-mcp/mcp-server
   bun run build
   ```

2. **Update the configuration path**:
   - Replace `/absolute/path/to/shakudo-platform-mcp/mcp-server` with your actual path
   - Ensure the path is absolute, not relative

3. **Alternative using built version**:
   ```json
   {
     "mcpServers": {
       "shakudo-microservices": {
         "command": "node",
         "args": ["/absolute/path/to/shakudo-platform-mcp/mcp-server/build/index.js"],
         "env": {
           "HYPERPLANE_API_ENDPOINT": "http://api-server.hyperplane-core.svc.cluster.local:80/graphql"
         }
       }
     }
   }
   ```

4. **Restart Claude Desktop** after saving the configuration

5. **Verify connection**: You should see "shakudo-microservices" in the MCP section of Claude Desktop

**Available Tools After Setup**:
- `searchMicroservice` - Find microservices by name
- `restartService` - Restart microservices/services  
- `getPodEvents` - Monitor logs and startup progress

### With MCP Inspector

For development and testing:

```bash
bun run inspector
```

### Direct Usage

```bash
bun run dev
```

### Quick Start

Use the provided run script:

```bash
./run.sh
```

## Available Tools

### ✅ Microservice Management (3 tools) - PRODUCTION-TESTED
- `searchMicroservice` - Search for microservices by name *(Key tool for microservice discovery)* ✅ **TESTED**
- `restartService` - Restart microservices/services directly ✅ **TESTED**
- `getPodEvents` - Get pod events and logs for microservices ✅ **TESTED**

### 🚧 Additional Tool Categories (Disabled Until Testing Complete)

**Pipeline Job Management** (9 untested tools):
- `createPipelineJob`, `cancelPipelineJob`, `triggerJobInstance`, `getJobStatistics`, `createScheduledJob`, `cancelScheduledJob`, `checkJobYamlEdited`, `getJobPodSpec`, `scaleService`

**Interactive Computing Sessions** (7 untested tools):
- `createHyperHubSession`, `cancelSession`, `restartSessionProcess`, `getSessionStatistics`, `updateSessionGroup`, `getSessionPodSpec`, `checkUserServiceUrl`

**Distributed Computing Clusters** (10 untested tools):
- `getDaskClusterCount`, `cancelUserDaskPods`, `getRayClusterCount`, `createDaskCluster`, `createRayCluster`, `deleteDaskCluster`, `deleteRayCluster`, `scaleDaskCluster`, `scaleRayCluster`, `cancelUserRayPods`

**Container Image Management** (7 untested tools):
- `createImageBuilderJob`, `getImageBuilderStatistics`, `cancelImageBuilderJob`, `getImageBuilderJob`, `listImageBuilderJobs`, `deleteImageBuilderJob`, `retryImageBuilderJob`

**Platform Applications** (12 untested tools):
- `installPlatformApp`, `getPlatformCatalogue`, `getPlatformAppStatistics`, `scaleStackComponentDown`, `scaleStackComponentToDefault`, `installStackComponent`, `getHelmAppVersion`, `getAllHelmAppVersions`, `uninstallPlatformApp`, `updatePlatformApp`, `countPinnedPlatformApps`, `restartPlatformApp`

**Security & Access Control** (9 untested tools):
- `createHyperplaneSecret`, `createServiceAccount`, `deleteServiceAccount`, `toggleAirGapMode`, `checkAirGapMode`, `checkNamespaceAccess`, `getAuthorizationPolicies`, `updateServiceAccount`, `deactivateServiceAccount`

**Monitoring & Observability** (8 untested tools):
- `getPodData`, `getPVCStatus`, `getPriorityClasses`, `getNamespaceEventLogs`, `getNamespaceServices`, `checkActiveTraffic`, `getResourceMetrics`, `getClusterHealth`

**Notifications & Alerting** (4 untested tools):
- `sendEmailNotification`, `addNotification`, `createJobNotificationTarget`, `triggerAlert`

**Namespace Management** (3 untested tools):
- `getNamespaces`, `scaleDownNamespaceResources`, `scaleNamespaceResourcesToDefault`

**Traffic Management** (5 untested tools):
- `createTrafficSplitVsvc`, `updateTrafficSplitVsvc`, `deactivateTrafficSplitVsvc`, `getTrafficSplitVsvcs`, `countTrafficSplitVsvcs`

**Multi-Cluster Management** (6 untested tools):
- `createSatelliteCluster`, `cancelSatellitePipelineJob`, `cancelScheduledJobOnSatelliteCluster`, `countJobsOnSatelliteCluster`, `getChildJobsOnSatelliteCluster`, `countSatelliteEnvironmentConfig`

**Environment Configuration** (2 untested tools):
- `createEnvironmentConfig`, `countEnvironmentConfig`

**User Management** (2 untested tools):
- `getOrCreateHyperplaneUser`, `updateHyperplaneUserGroup`

**Data Management** (4 untested tools):
- `getDatalakeBucketName`, `getBytebaseSQLCode`, `createCloudSqlProxy`, `countCloudSqlProxy`

> **Note**: These 126+ additional tools will be gradually enabled as they are tested and verified to work correctly with the Hyperplane API.

## Example Usage

Here are some example interactions with the MCP server:

### Create a Machine Learning Pipeline

```
Create a new ML training pipeline job named "customer-churn-model" that:
- Uses the pipeline YAML at "pipelines/ml/churn-model.yaml"
- Has 3 retry attempts
- Sends notifications to "ml-team-slack"
- Requires 4 CPU cores and 16GB RAM
```

### Launch a Development Environment

```
Create a new Jupyter session called "data-exploration" using the "python-ml-gpu" environment with 2 CPUs, 8GB RAM, and 1 GPU for exploring the customer dataset.
```

### Deploy a Dask Cluster

```
Create a Dask cluster named "data-processing-cluster" with 5 worker nodes, each having 2 CPUs and 4GB RAM, for parallel data processing.
```

### Monitor System Health

```
Check the health status of the Kubernetes cluster and show me any pods in the "ml-platform" namespace that are having issues.
```

### Find and Restart Microservices

```
Search for the "shakbot-service-v2" microservice and restart it.
```

Example workflow ✅ **TESTED & WORKING**:
1. Search: `searchMicroservice` with term "shakbot-service-v2" ✅
2. Restart: `restartService` with the returned microservice ID ✅  
3. Monitor: `getPodEvents` with the microservice ID to track startup progress ✅
4. Alternative: `scaleService` with replicas 0 (stop) then 1 (start)

### Complete Microservice Restart & Monitoring Pattern

Real-world usage pattern verified with shakbot-service-v2:

```bash
# Step 1: Find the microservice
searchMicroservice("shakbot-service-v2")
# Returns: ID "62051482-0ae7-42cd-91b8-919224f8e4fb", status "in progress"

# Step 2: Restart the service
restartService("62051482-0ae7-42cd-91b8-919224f8e4fb") 
# Returns: "Succeeded"

# Step 3: Monitor startup progress with periodic log checks
getPodEvents("62051482-0ae7-42cd-91b8-919224f8e4fb")
```

**Typical Startup Sequence Observed**:
1. **Pod Creation** (0-10s): Kubernetes containers created and started
2. **Environment Setup** (10-20s): Package manager installation, config files
3. **Dependencies** (20-40s): npm/pnpm package installation (475 packages)
4. **Database Init** (40-50s): Table creation, migrations
5. **Application Start** (50-60s): Next.js server ready, service operational

**Monitoring Tips**:
- Check logs immediately after restart to confirm pod creation
- Monitor every 10-30 seconds during dependency installation
- Look for "Ready in Xms" message for full startup confirmation
- Total startup time typically 45-90 seconds for full services

## Development

### Watch Mode

```bash
bun run watch
```

### Testing with Inspector

```bash
bun run inspector
```

## Error Handling

The MCP server returns raw GraphQL errors as requested, providing full error details for debugging and troubleshooting.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with the MCP inspector
5. Submit a pull request

## License

MIT License - see the LICENSE file for details.