castai-mcp-server 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CAST.AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# CAST.AI MCP Server
+
+Model Context Protocol (MCP) server for the CAST.AI API. This server enables Claude Desktop and other MCP clients to interact with your CAST.AI Kubernetes clusters through natural language.
+
+## Features
+
+- **5 Cluster Management Tools**:
+  - `list_clusters` - List all your Kubernetes clusters
+  - `get_cluster_details` - Get detailed information about a specific cluster
+  - `get_cluster_policies` - View cluster policies and configuration
+  - `get_cluster_score` - Get cluster optimization score
+  - `get_cluster_score_history` - View historical cluster score data
+
+- **Simple Authentication**: API key-based authentication (no OAuth complexity)
+- **Local Only**: Works with Claude Desktop via stdio transport
+- **Cluster Name Resolution**: Use either cluster UUID or friendly cluster name
+
+## Prerequisites
+
+- **For npx installation (recommended)**: Node.js 16+ and [uv](https://docs.astral.sh/uv/)
+- **For uvx installation**: [uv](https://docs.astral.sh/uv/) only
+- **For local development**: Python 3.11+ and [uv](https://docs.astral.sh/uv/)
+- **Always required**: CAST.AI account with API access
+
+## Installation
+
+### Quick Start (Recommended) ⭐
+
+The easiest way to use CAST.AI MCP Server - no installation or cloning required!
+
+**1. Get your CAST.AI API key**:
+   - Visit [console.cast.ai](https://console.cast.ai)
+   - Navigate to **Settings** > **API Keys**
+   - Click **Create API Key**
+   - Choose **Read-only** access (recommended) or **Full access**
+   - Copy the generated API key
+
+**2. Configure Claude Desktop**:
+
+Edit your Claude Desktop configuration file:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Add this configuration:
+
+```json
+{
+  "mcpServers": {
+    "castai": {
+      "command": "npx",
+      "args": ["-y", "castai-mcp-server@latest"],
+      "env": {
+        "CASTAI_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+**3. Restart Claude Desktop**
+
+That's it! The server will be automatically downloaded and run when needed.
+
+---
+
+### Alternative Installation Methods
+
+<details>
+<summary><b>Using uvx</b> (Python package manager)</summary>
+
+Requires: [uv](https://docs.astral.sh/uv/) installed
+
+```json
+{
+  "mcpServers": {
+    "castai": {
+      "command": "uvx",
+      "args": ["castai-mcp-server"],
+      "env": {
+        "CASTAI_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop.
+</details>
+
+<details>
+<summary><b>Development / Local Installation</b></summary>
+
+For local development or if you want to modify the code:
+
+1. **Clone the repository**:
+```bash
+cd ~/repos
+git clone https://github.com/castai/castai-mcp-external.git
+cd castai-mcp-external
+```
+
+2. **Install dependencies**:
+```bash
+uv sync
+```
+
+3. **Configure Claude Desktop**:
+```json
+{
+  "mcpServers": {
+    "castai": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/ABSOLUTE/PATH/TO/castai-mcp-external",
+        "run",
+        "python",
+        "main.py"
+      ],
+      "env": {
+        "CASTAI_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+**Important**: Replace `/ABSOLUTE/PATH/TO/castai-mcp-external` with the actual absolute path.
+
+4. **Restart Claude Desktop**
+</details>
+
+## Usage Examples
+
+Once configured, you can interact with your CAST.AI clusters using natural language in Claude Desktop:
+
+### List all clusters
+```
+Show me all my Kubernetes clusters
+```
+
+### Get cluster details
+```
+Get details for cluster "production-gke"
+```
+or
+```
+Show me information about cluster a1b2c3d4-e5f6-7890-abcd-ef1234567890
+```
+
+### View cluster policies
+```
+What are the policies configured for my staging cluster?
+```
+
+### Check cluster optimization score
+```
+What's the optimization score for my production cluster?
+```
+
+### View score history
+```
+Show me the historical cluster score for my main cluster
+```
+
+## Configuration
+
+### Environment Variables
+
+- `CASTAI_API_KEY` (required) - Your CAST.AI API key from console.cast.ai
+- `CASTAI_API_URL` (optional) - API endpoint URL (defaults to `https://api.cast.ai`)
+
+### Using a Different API Endpoint
+
+If you're using a non-production CAST.AI environment, you can override the API URL:
+
+```json
+{
+  "mcpServers": {
+    "castai": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/castai-mcp-external", "run", "python", "main.py"],
+      "env": {
+        "CASTAI_API_KEY": "your-api-key-here",
+        "CASTAI_API_URL": "https://api.dev-master.cast.ai"
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### Authentication Errors
+
+If you see a 401 authentication error:
+1. Verify your API key is correct in `claude_desktop_config.json`
+2. Check that the API key hasn't expired in the CAST.AI console
+3. Ensure the API key has the necessary permissions
+4. Restart Claude Desktop after making changes
+
+### Cluster Not Found
+
+If you get a "Cluster not found" error:
+- Verify you're using the exact cluster name as shown in CAST.AI console
+- Alternatively, use the cluster UUID instead of the name
+- Check that your API key has access to the cluster's organization
+
+### Server Not Starting
+
+If the MCP server doesn't appear in Claude Desktop:
+1. Check the Claude Desktop logs:
+   - **macOS**: `~/Library/Logs/Claude/mcp*.log`
+   - **Windows**: `%APPDATA%\Claude\Logs\mcp*.log`
+2. Verify the absolute path to `castai-mcp-external` is correct
+3. Ensure `uv` is installed and in your PATH
+4. Test the server manually:
+   ```bash
+   cd /path/to/castai-mcp-external
+   export CASTAI_API_KEY="your-key"
+   uv run python main.py
+   ```
+
+### View Server Logs
+
+To see detailed logs from the MCP server:
+```bash
+cd /path/to/castai-mcp-external
+export CASTAI_API_KEY="your-key"
+uv run python main.py
+```
+
+The server will output structured logs in logfmt format to stderr.
+
+## Security Best Practices
+
+1. **Use Read-Only API Keys**: For safety, create API keys with read-only access unless you specifically need write permissions
+2. **Rotate API Keys Regularly**: Periodically generate new API keys and update your configuration
+3. **Protect Your API Key**: Never commit API keys to version control or share them publicly
+4. **Use Environment Variables**: Always configure API keys via environment variables, not hardcoded in files
+
+## API Endpoints Used
+
+This MCP server uses the following CAST.AI API endpoints:
+
+- `GET /v1/kubernetes/external-clusters` - List clusters
+- `GET /v1/kubernetes/external-clusters/{id}` - Get cluster details
+- `GET /v1/kubernetes/clusters/{id}/policies` - Get cluster policies
+- `GET /v1/cost-reports/clusters/{id}/cluster-score` - Get cluster score
+- `GET /v1/cost-reports/clusters/{id}/cluster-score-history` - Get score history
+
+## Documentation
+
+- [CAST.AI API Documentation](https://api.cast.ai/v1/spec/#/)
+- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
+- [Claude Desktop Documentation](https://claude.ai/docs)
+
+## Support
+
+For issues or questions:
+- CAST.AI API Issues: [support@cast.ai](mailto:support@cast.ai)
+- MCP Server Issues: [GitHub Issues](https://github.com/castai/castai-mcp-external/issues)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

package/bin/castai-mcp-server.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const { execSync } = require('child_process');
+const os = require('os');
+
+// Determine uvx command based on platform
+const isWindows = os.platform() === 'win32';
+const uvxCommand = isWindows ? 'uvx.exe' : 'uvx';
+
+// Check if uv is installed
+function checkUvInstalled() {
+  try {
+    execSync(isWindows ? 'where uvx' : 'which uvx', { stdio: 'ignore' });
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+if (!checkUvInstalled()) {
+  console.error('Error: uv is not installed.');
+  console.error('');
+  console.error('CAST.AI MCP Server requires uv to be installed.');
+  console.error('');
+  console.error('Install uv:');
+  console.error('  macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh');
+  console.error('  Windows:     powershell -c "irm https://astral.sh/uv/install.ps1 | iex"');
+  console.error('  Or visit:    https://docs.astral.sh/uv/getting-started/installation/');
+  console.error('');
+  process.exit(1);
+}
+
+// Run the Python package via uvx
+const args = ['castai-mcp-server'];
+
+// Forward all command line arguments
+if (process.argv.length > 2) {
+  args.push(...process.argv.slice(2));
+}
+
+const child = spawn(uvxCommand, args, {
+  stdio: 'inherit',
+  env: process.env,
+  shell: isWindows
+});
+
+child.on('error', (error) => {
+  console.error(`Failed to start castai-mcp-server: ${error.message}`);
+  process.exit(1);
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code || 0);
+  }
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "castai-mcp-server",
+  "version": "0.2.1",
+  "description": "Model Context Protocol server for CAST.AI - manage Kubernetes clusters via natural language",
+  "bin": {
+    "castai-mcp-server": "./bin/castai-mcp-server.js"
+  },
+  "scripts": {
+    "test": "node bin/castai-mcp-server.js --help || true"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "castai",
+    "kubernetes",
+    "llm",
+    "claude",
+    "ai"
+  ],
+  "author": "CAST.AI <support@cast.ai>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/castai/castai-mcp-external.git"
+  },
+  "homepage": "https://github.com/castai/castai-mcp-external#readme",
+  "bugs": {
+    "url": "https://github.com/castai/castai-mcp-external/issues"
+  },
+  "files": [
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ]
+}