ibmcloud-mcp-server 1.0.1

package/README.md

@@ -0,0 +1,233 @@
+# IBM Cloud CLI MCP Server
+
+Comprehensive MCP server wrapping the IBM Cloud CLI for Claude Code. Provides 80+ tools covering all major IBM Cloud services and operations.
+
+## Features
+
+- **Authentication** - Login, logout, target, regions
+- **Resource Management** - Service instances, keys, resource groups
+- **Cloud Foundry** - Apps, services, routes, marketplace
+- **Kubernetes** - Clusters, workers, worker pools, zones
+- **Container Registry** - Namespaces, images, quotas
+- **IAM** - Users, API keys, service IDs, access groups
+- **Catalog & Billing** - Service catalog, usage, billing
+
+## Tool Categories
+
+### Authentication (8 tools)
+| Tool | Description |
+|------|-------------|
+| `ibmcloud_login` | Login with API key or SSO |
+| `ibmcloud_logout` | Logout from IBM Cloud |
+| `ibmcloud_target` | Set target region/resource group |
+| `ibmcloud_api` | View/set API endpoint |
+| `ibmcloud_regions` | List available regions |
+| `ibmcloud_account_show` | Show current account |
+| `ibmcloud_account_list` | List accessible accounts |
+| `ibmcloud_config_list` | List CLI configuration |
+
+### Resource Management (14 tools)
+| Tool | Description |
+|------|-------------|
+| `ibmcloud_resource_groups` | List resource groups |
+| `ibmcloud_resource_group_create` | Create resource group |
+| `ibmcloud_resource_service_instances` | List service instances |
+| `ibmcloud_resource_service_instance` | Get instance details |
+| `ibmcloud_resource_service_instance_create` | Create instance |
+| `ibmcloud_resource_service_instance_delete` | Delete instance |
+| `ibmcloud_resource_service_instance_update` | Update instance |
+| `ibmcloud_resource_service_keys` | List service keys |
+| `ibmcloud_resource_service_key` | Get key details |
+| `ibmcloud_resource_service_key_create` | Create service key |
+| `ibmcloud_resource_service_key_delete` | Delete service key |
+| `ibmcloud_resource_search` | Search resources |
+| `ibmcloud_resource_tags` | List tags |
+| `ibmcloud_resource_tag_attach` | Attach tags |
+
+### Cloud Foundry (20 tools)
+| Tool | Description |
+|------|-------------|
+| `ibmcloud_cf_orgs` | List organizations |
+| `ibmcloud_cf_spaces` | List spaces |
+| `ibmcloud_cf_apps` | List applications |
+| `ibmcloud_cf_app` | Get app details |
+| `ibmcloud_cf_push` | Deploy application |
+| `ibmcloud_cf_start` | Start application |
+| `ibmcloud_cf_stop` | Stop application |
+| `ibmcloud_cf_restart` | Restart application |
+| `ibmcloud_cf_delete` | Delete application |
+| `ibmcloud_cf_logs` | View app logs |
+| `ibmcloud_cf_env` | Show environment variables |
+| `ibmcloud_cf_set_env` | Set environment variable |
+| `ibmcloud_cf_scale` | Scale application |
+| `ibmcloud_cf_routes` | List routes |
+| `ibmcloud_cf_services` | List services |
+| `ibmcloud_cf_marketplace` | List marketplace |
+| `ibmcloud_cf_create_service` | Create service |
+| `ibmcloud_cf_bind_service` | Bind service to app |
+| `ibmcloud_cf_unbind_service` | Unbind service |
+
+### Kubernetes (15 tools)
+| Tool | Description |
+|------|-------------|
+| `ibmcloud_ks_clusters` | List Kubernetes clusters |
+| `ibmcloud_ks_cluster` | Get cluster details |
+| `ibmcloud_ks_cluster_config` | Configure kubectl |
+| `ibmcloud_ks_cluster_create` | Create cluster |
+| `ibmcloud_ks_cluster_delete` | Delete cluster |
+| `ibmcloud_ks_workers` | List worker nodes |
+| `ibmcloud_ks_worker_pools` | List worker pools |
+| `ibmcloud_ks_worker_pool_create` | Create worker pool |
+| `ibmcloud_ks_worker_pool_resize` | Resize worker pool |
+| `ibmcloud_ks_zones` | List available zones |
+| `ibmcloud_ks_versions` | List K8s versions |
+| `ibmcloud_ks_flavors` | List machine flavors |
+
+### Container Registry (5 tools)
+| Tool | Description |
+|------|-------------|
+| `ibmcloud_cr_namespaces` | List namespaces |
+| `ibmcloud_cr_namespace_add` | Create namespace |
+| `ibmcloud_cr_images` | List images |
+| `ibmcloud_cr_image_rm` | Remove image |
+| `ibmcloud_cr_quota` | Get quota info |
+
+### IAM (18 tools)
+| Tool | Description |
+|------|-------------|
+| `ibmcloud_iam_users` | List users |
+| `ibmcloud_iam_user_invite` | Invite user |
+| `ibmcloud_iam_api_keys` | List API keys |
+| `ibmcloud_iam_api_key_create` | Create API key |
+| `ibmcloud_iam_api_key_delete` | Delete API key |
+| `ibmcloud_iam_service_ids` | List service IDs |
+| `ibmcloud_iam_service_id` | Get service ID |
+| `ibmcloud_iam_service_id_create` | Create service ID |
+| `ibmcloud_iam_service_id_delete` | Delete service ID |
+| `ibmcloud_iam_service_api_keys` | List service API keys |
+| `ibmcloud_iam_service_api_key_create` | Create service API key |
+| `ibmcloud_iam_access_groups` | List access groups |
+| `ibmcloud_iam_access_group` | Get access group |
+| `ibmcloud_iam_access_group_create` | Create access group |
+| `ibmcloud_iam_access_group_users` | List group users |
+| `ibmcloud_iam_access_group_user_add` | Add user to group |
+| `ibmcloud_iam_access_group_policies` | List group policies |
+| `ibmcloud_iam_access_group_policy_create` | Create policy |
+| `ibmcloud_iam_roles` | List IAM roles |
+
+### Catalog & Billing (7 tools)
+| Tool | Description |
+|------|-------------|
+| `ibmcloud_catalog_search` | Search service catalog |
+| `ibmcloud_catalog_service` | Get service details |
+| `ibmcloud_catalog_service_plans` | List service plans |
+| `ibmcloud_billing_account_usage` | Get account usage |
+| `ibmcloud_billing_resource_group_usage` | Get RG usage |
+| `ibmcloud_billing_resource_instances_usage` | Get instance usage |
+| `ibmcloud_billing_org_usage` | Get org usage |
+
+### Plugins (4 tools)
+| Tool | Description |
+|------|-------------|
+| `ibmcloud_plugin_list` | List installed plugins |
+| `ibmcloud_plugin_repo_plugins` | List available plugins |
+| `ibmcloud_plugin_install` | Install a plugin |
+| `ibmcloud_version` | Show CLI version |
+
+## Setup
+
+### 1. Prerequisites
+
+Install IBM Cloud CLI:
+```bash
+curl -fsSL https://clis.cloud.ibm.com/install/osx | sh
+```
+
+### 2. Install Dependencies
+
+```bash
+cd ~/mcp-servers/ibmcloud-mcp
+npm install
+npm run build
+```
+
+### 3. Add to Claude Code
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "ibmcloud": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/Users/matthewkarsten/mcp-servers/ibmcloud-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+## Architecture
+
+```
+Claude Code (Opus 4.5)
+         │
+         └──▶ IBM Cloud MCP Server
+                    │
+                    └──▶ ibmcloud CLI
+                              │
+                              ├── Resource Controller
+                              ├── Cloud Foundry API
+                              ├── Kubernetes Service
+                              ├── Container Registry
+                              ├── IAM Service
+                              └── Billing Service
+```
+
+## Usage Examples
+
+```
+User: List my IBM Cloud Kubernetes clusters
+
+Claude: [Uses ibmcloud_ks_clusters tool]
+Result:
+- mycluster (VPC Gen2, us-south, 1.28, 3 workers) - normal
+- dev-cluster (Classic, dal10, 1.27, 2 workers) - normal
+
+User: Create a new Cloud Object Storage instance
+
+Claude: [Uses ibmcloud_resource_service_instance_create]
+Created: my-cos-instance (cloud-object-storage, lite plan)
+```
+
+## IBM Cloud Services Supported
+
+- **Watson AI**: watsonx.ai, Watson Studio, Watson ML
+- **Storage**: Cloud Object Storage, Block Storage
+- **Databases**: Db2, PostgreSQL, MongoDB, Redis
+- **Containers**: Kubernetes, OpenShift, Container Registry
+- **Serverless**: Cloud Functions, Code Engine
+- **Networking**: VPC, Load Balancers, DNS
+- **Security**: Key Protect, Secrets Manager, IAM
+- **Integration**: API Connect, MQ, Event Streams
+
+## Files
+
+```
+ibmcloud-mcp/
+├── src/
+│   ├── index.ts    # MCP server implementation
+│   └── cli.ts      # IBM Cloud CLI wrapper
+├── dist/           # Compiled JavaScript
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Author
+
+Matthew Karsten
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+export interface CLIResult {
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export declare function executeIBMCloud(args: string[], options?: {
+    timeout?: number;
+    env?: Record<string, string>;
+}): Promise<CLIResult>;
+export declare function formatResult(result: CLIResult): string;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE;IACR,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B,GACA,OAAO,CAAC,SAAS,CAAC,CAqEpB;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAgBtD"}

package/dist/cli.js

@@ -0,0 +1,80 @@
+import { spawn } from "child_process";
+export async function executeIBMCloud(args, options) {
+    return new Promise((resolve) => {
+        const timeout = options?.timeout ?? 120000; // 2 minute default
+        const env = { ...process.env, ...options?.env };
+        // Add --output json flag if not already present and command supports it
+        const jsonCommands = [
+            "account",
+            "resource",
+            "iam",
+            "catalog",
+            "target",
+            "regions",
+            "api",
+        ];
+        const shouldAddJson = args.length > 0 &&
+            jsonCommands.some((cmd) => args[0] === cmd) &&
+            !args.includes("--output") &&
+            !args.includes("-o");
+        const finalArgs = shouldAddJson ? [...args, "--output", "json"] : args;
+        const child = spawn("ibmcloud", finalArgs, {
+            env,
+            shell: true,
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (data) => {
+            stdout += data.toString();
+        });
+        child.stderr.on("data", (data) => {
+            stderr += data.toString();
+        });
+        const timer = setTimeout(() => {
+            child.kill("SIGTERM");
+            resolve({
+                success: false,
+                stdout,
+                stderr: stderr + "\nCommand timed out",
+                exitCode: -1,
+            });
+        }, timeout);
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({
+                success: code === 0,
+                stdout: stdout.trim(),
+                stderr: stderr.trim(),
+                exitCode: code ?? -1,
+            });
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({
+                success: false,
+                stdout: "",
+                stderr: err.message,
+                exitCode: -1,
+            });
+        });
+    });
+}
+export function formatResult(result) {
+    if (result.success) {
+        return result.stdout || "Command completed successfully";
+    }
+    else {
+        let output = "";
+        if (result.stdout) {
+            output += result.stdout + "\n";
+        }
+        if (result.stderr) {
+            output += `Error: ${result.stderr}`;
+        }
+        if (!output) {
+            output = `Command failed with exit code ${result.exitCode}`;
+        }
+        return output;
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}