@vibecloud/mcp-server 1.1.0

package/README.md

@@ -0,0 +1,298 @@
+# VibeCloud MCP Server
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that lets AI assistants like Claude Code interact with the VibeCloud API to provision cloud dev environments, create deployments, manage storage, configure domains, handle secrets, and more.
+
+## Installation
+
+Install globally from npm:
+
+```bash
+npm install -g @vibecloud/mcp-server
+```
+
+Or, if you prefer to build from source:
+
+```bash
+cd mcp-server
+npm install
+npm run build
+```
+
+## Prerequisites
+
+- **Node.js 18+** (for native `fetch` support)
+- **A VibeCloud account** at [remotevibecoder.com](https://remotevibecoder.com)
+
+## Quick Start
+
+### 1. Configure Claude Code
+
+Add the VibeCloud MCP server to your Claude Code configuration. Edit the file at `~/.claude.json` (or create it) and add a `mcpServers` entry.
+
+**Option A: API Key authentication (recommended for CI/programmatic use)**
+
+```json
+{
+  "mcpServers": {
+    "vibecloud": {
+      "command": "vibecloud-mcp",
+      "env": {
+        "VIBECLOUD_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+**Option B: JWT token authentication**
+
+```json
+{
+  "mcpServers": {
+    "vibecloud": {
+      "command": "vibecloud-mcp",
+      "env": {
+        "VIBECLOUD_API_TOKEN": "your-jwt-token-here"
+      }
+    }
+  }
+}
+```
+
+**Option C: Automatic via CLI login (recommended for local development)**
+
+If you have the VibeCloud CLI installed, just run `vibe login` and the MCP server will automatically pick up the JWT token from `~/.vibe/config.json`. No extra configuration needed:
+
+```json
+{
+  "mcpServers": {
+    "vibecloud": {
+      "command": "vibecloud-mcp"
+    }
+  }
+}
+```
+
+If you installed from source instead of npm, use `node /absolute/path/to/mcp-server/dist/index.js` as the command instead of `vibecloud-mcp`.
+
+### 2. Restart Claude Code
+
+After adding the configuration, restart Claude Code. The VibeCloud tools will appear in Claude's available tools.
+
+## Authentication
+
+The MCP server resolves credentials in the following priority order:
+
+1. **API Key** (`VIBECLOUD_API_KEY` env var): Sent as an `X-API-Key` header. Best for CI/CD pipelines and programmatic access.
+
+2. **JWT token** (`VIBECLOUD_API_TOKEN` env var): Sent as a `Bearer` token in the `Authorization` header.
+
+3. **Shared CLI config**: If you have already run `vibe login` from the VibeCloud CLI, the MCP server automatically reads the JWT token from `~/.vibe/config.json`. No extra setup needed.
+
+4. **Login via tool**: Ask Claude to use the `vibecloud_login` tool with your email and password. The token is saved to `~/.vibe/config.json` for future use.
+
+JWT tokens are automatically refreshed when they expire. If refresh fails, you'll be prompted to re-authenticate.
+
+## Available Tools (77 total)
+
+### Authentication
+| Tool | Description |
+|------|-------------|
+| `vibecloud_login` | Authenticate with email/password and store JWT token |
+| `vibecloud_register` | Create a new VibeCloud account |
+
+### User Profile
+| Tool | Description |
+|------|-------------|
+| `vibecloud_whoami` | Get your account info (email, name, ID) |
+| `vibecloud_update_profile` | Update your profile (name, etc.) |
+
+### Projects
+| Tool | Description |
+|------|-------------|
+| `vibecloud_list_projects` | List all projects |
+| `vibecloud_get_project` | Get details of a specific project |
+| `vibecloud_create_project` | Create a new project |
+| `vibecloud_update_project` | Update a project's name or settings |
+| `vibecloud_delete_project` | Delete a project |
+
+### API Keys
+| Tool | Description |
+|------|-------------|
+| `vibecloud_list_api_keys` | List all API keys |
+| `vibecloud_get_api_key` | Get details of a specific API key |
+| `vibecloud_create_api_key` | Create a new API key with scopes |
+| `vibecloud_update_api_key` | Update an API key's name or scopes |
+| `vibecloud_delete_api_key` | Revoke an API key |
+
+### Environments
+| Tool | Description |
+|------|-------------|
+| `vibecloud_create_environment` | Create a new cloud dev environment |
+| `vibecloud_list_environments` | List all environments |
+| `vibecloud_get_environment` | Get details of a specific environment |
+| `vibecloud_update_environment` | Update an environment's configuration |
+| `vibecloud_start_environment` | Start a stopped environment |
+| `vibecloud_stop_environment` | Stop a running environment |
+| `vibecloud_delete_environment` | Delete an environment |
+| `vibecloud_get_environment_status` | Get provisioning and server status |
+
+### Instances
+| Tool | Description |
+|------|-------------|
+| `vibecloud_list_instances` | List all running instances |
+| `vibecloud_get_instance` | Get details of a specific instance |
+| `vibecloud_get_instance_metrics` | Get CPU, memory, GPU metrics |
+| `vibecloud_cancel_shutdown` | Cancel an idle auto-shutdown |
+
+### Deployments
+| Tool | Description |
+|------|-------------|
+| `vibecloud_deploy` | Create a new production deployment with DNS/SSL |
+| `vibecloud_list_deployments` | List all deployments |
+| `vibecloud_get_deployment` | Get deployment details |
+| `vibecloud_update_deployment` | Update deployment settings |
+| `vibecloud_delete_deployment` | Delete a deployment |
+| `vibecloud_stop_deployment` | Stop a deployment (removes DNS) |
+| `vibecloud_check_deployment_health` | Run a health check on a deployment |
+| `vibecloud_enable_hosting` | Enable always-on hosting |
+| `vibecloud_disable_hosting` | Disable always-on hosting |
+| `vibecloud_connect_github` | Connect GitHub repo for auto-deploy |
+| `vibecloud_disconnect_github` | Disconnect GitHub auto-deploy |
+
+### Secrets (Infisical)
+| Tool | Description |
+|------|-------------|
+| `vibecloud_create_secret_identity` | Provision Infisical machine identity for secret injection |
+
+### Environment Variables
+| Tool | Description |
+|------|-------------|
+| `vibecloud_set_env_var` | Set/update an environment variable |
+| `vibecloud_list_env_vars` | List env vars (values masked) |
+| `vibecloud_delete_env_var` | Delete an environment variable |
+
+### Domains
+| Tool | Description |
+|------|-------------|
+| `vibecloud_list_domains` | List all custom domains |
+| `vibecloud_setup_domain` | Set up a custom domain for a deployment |
+| `vibecloud_verify_domain` | Verify DNS is configured correctly |
+| `vibecloud_delete_domain` | Remove a custom domain |
+
+### Storage Buckets
+| Tool | Description |
+|------|-------------|
+| `vibecloud_create_bucket` | Create an S3-compatible storage bucket |
+| `vibecloud_list_buckets` | List all storage buckets |
+| `vibecloud_get_bucket` | Get bucket details |
+| `vibecloud_get_bucket_by_name` | Look up a bucket by name |
+| `vibecloud_get_bucket_credentials` | Get S3 access credentials |
+| `vibecloud_delete_bucket` | Delete a bucket |
+
+### Servers
+| Tool | Description |
+|------|-------------|
+| `vibecloud_list_servers` | List all bare metal servers |
+| `vibecloud_get_server` | Get server details |
+| `vibecloud_create_server` | Provision a new bare metal server |
+| `vibecloud_power_on_server` | Power on a server |
+| `vibecloud_power_off_server` | Power off a server |
+| `vibecloud_delete_server` | Delete a server |
+
+### SSH Keys
+| Tool | Description |
+|------|-------------|
+| `vibecloud_list_ssh_keys` | List all registered SSH keys |
+| `vibecloud_create_ssh_key` | Register a new SSH public key |
+| `vibecloud_delete_ssh_key` | Remove an SSH key |
+
+### Organizations
+| Tool | Description |
+|------|-------------|
+| `vibecloud_list_organizations` | List organizations you belong to |
+| `vibecloud_get_organization` | Get organization details |
+| `vibecloud_get_organization_members` | List organization members |
+| `vibecloud_get_organization_projects` | List organization projects |
+
+### Billing
+| Tool | Description |
+|------|-------------|
+| `vibecloud_billing_status` | Get subscription and billing status |
+| `vibecloud_list_tiers` | List pricing tiers and features |
+| `vibecloud_get_usage` | Get current billing period usage |
+| `vibecloud_create_checkout` | Create a Stripe checkout session to upgrade |
+| `vibecloud_create_portal` | Open the Stripe billing portal |
+
+### Billing Add-Ons
+| Tool | Description |
+|------|-------------|
+| `vibecloud_list_add_ons` | List active billing add-ons |
+| `vibecloud_create_add_on` | Add a billing add-on |
+| `vibecloud_delete_add_on` | Remove a billing add-on |
+
+### Certificates
+| Tool | Description |
+|------|-------------|
+| `vibecloud_get_certificate` | Get certificate details |
+| `vibecloud_download_certificate` | Download certificate files |
+| `vibecloud_create_client_cert` | Generate a client certificate |
+| `vibecloud_revoke_certificate` | Revoke a certificate |
+
+### Network
+| Tool | Description |
+|------|-------------|
+| `vibecloud_create_network_auth_key` | Create a VPN network auth key |
+
+## Example Conversations
+
+Once configured, you can ask Claude things like:
+
+- "Who am I on VibeCloud?" (uses `vibecloud_whoami`)
+- "List my VibeCloud projects" (uses `vibecloud_list_projects`)
+- "Create a new environment called 'my-saas-app' with the gpu-l40s-1x plan"
+- "Deploy my app to VibeCloud with the name 'my-saas-app' on server 203.0.113.42"
+- "Set up secret injection for my deployment" (uses `vibecloud_create_secret_identity`)
+- "Set the DATABASE_URL environment variable on my deployment"
+- "Set up the custom domain myapp.com on my deployment" (uses `vibecloud_setup_domain`)
+- "Verify that my domain DNS is configured" (uses `vibecloud_verify_domain`)
+- "Create a storage bucket called 'user-uploads'"
+- "What's my current billing status?"
+- "Show me my server metrics" (uses `vibecloud_get_instance_metrics`)
+- "Cancel the auto-shutdown on my instance" (uses `vibecloud_cancel_shutdown`)
+- "Connect my GitHub repo acme/myapp to my deployment for auto-deploy"
+- "Create an API key with read and write access"
+- "List my organization members"
+- "Power off my server" (uses `vibecloud_power_off_server`)
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `VIBECLOUD_API_KEY` | _(none)_ | API key for authentication (sent as `X-API-Key` header) |
+| `VIBECLOUD_API_TOKEN` | _(none)_ | JWT token for authentication (sent as `Bearer` token) |
+| `VIBECLOUD_API_URL` | `https://api.remotevibecoder.com` | VibeCloud API base URL |
+
+## Development
+
+```bash
+# Watch mode - recompile on changes
+npm run dev
+
+# In another terminal, test with MCP inspector
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+## Architecture
+
+```
+mcp-server/
+  src/
+    index.ts    # MCP server - 77 tool definitions and request handlers
+    api.ts      # VibeCloud API client - HTTP methods for all endpoints
+  dist/         # Compiled JavaScript (generated by `npm run build`)
+  package.json
+  tsconfig.json
+```
+
+The server communicates over stdio using JSON-RPC, following the MCP specification. Each tool maps to one or more VibeCloud REST API endpoints. The API client handles authentication, error formatting, JWT auto-refresh, and token persistence.

package/dist/api.d.ts

@@ -0,0 +1,149 @@
+/**
+ * API response wrapper - VibeCloud API returns { data: ... } for success
+ * and { error: "..." } or { errors: {...} } for failures.
+ */
+interface ApiResponse<T = unknown> {
+    data?: T;
+    error?: string;
+    errors?: Record<string, string[]>;
+    message?: string;
+    dns?: Record<string, unknown>;
+    credentials?: Record<string, unknown>;
+    github?: Record<string, unknown>;
+    hosting?: Record<string, unknown>;
+}
+/**
+ * VibeCloudAPI is an HTTP client for the VibeCloud REST API.
+ *
+ * It handles authentication via API keys or JWT tokens. Authentication
+ * is resolved in priority order:
+ *   1. VIBECLOUD_API_KEY env var  (sent as X-API-Key header)
+ *   2. VIBECLOUD_API_TOKEN env var (sent as Bearer token)
+ *   3. ~/.vibe/config.json JWT    (sent as Bearer token, shared with CLI)
+ *
+ * JWT tokens are auto-refreshed on 401 responses.
+ */
+export declare class VibeCloudAPI {
+    private baseUrl;
+    private apiKey;
+    private token;
+    private refreshing;
+    constructor(baseUrl?: string);
+    /**
+     * Load JWT token from ~/.vibe/config.json (shared with the CLI).
+     */
+    private loadToken;
+    /**
+     * Save JWT token to ~/.vibe/config.json so the CLI can also use it.
+     */
+    private saveToken;
+    /**
+     * Check whether we currently have valid credentials (API key or JWT token).
+     */
+    isAuthenticated(): boolean;
+    private authHeaders;
+    /**
+     * Attempt to refresh the JWT token using the /auth/refresh endpoint.
+     * Returns true if refresh succeeded, false otherwise.
+     */
+    private refreshToken;
+    private request;
+    private get;
+    private post;
+    private put;
+    private patch;
+    private del;
+    private requireAuth;
+    /**
+     * Authenticate with email and password. Returns user info and stores
+     * the JWT token for subsequent requests.
+     */
+    login(email: string, password: string): Promise<{
+        token: string;
+        user: {
+            id: string;
+            email: string;
+            name: string;
+        };
+    }>;
+    /**
+     * Register a new account with email and password.
+     */
+    register(email: string, password: string, name?: string): Promise<ApiResponse>;
+    getMe(): Promise<ApiResponse>;
+    updateMe(params: Record<string, unknown>): Promise<ApiResponse>;
+    listProjects(): Promise<ApiResponse>;
+    getProject(projectId: string): Promise<ApiResponse>;
+    createProject(name: string): Promise<ApiResponse>;
+    updateProject(projectId: string, params: Record<string, unknown>): Promise<ApiResponse>;
+    deleteProject(projectId: string): Promise<ApiResponse>;
+    listApiKeys(): Promise<ApiResponse>;
+    getApiKey(keyId: string): Promise<ApiResponse>;
+    createApiKey(name: string, scopes: string[], projectId?: string): Promise<ApiResponse>;
+    updateApiKey(keyId: string, params: Record<string, unknown>): Promise<ApiResponse>;
+    deleteApiKey(keyId: string): Promise<ApiResponse>;
+    createEnvironment(name: string, plan?: string): Promise<ApiResponse>;
+    listEnvironments(): Promise<ApiResponse>;
+    getEnvironment(environmentId: string): Promise<ApiResponse>;
+    updateEnvironment(environmentId: string, params: Record<string, unknown>): Promise<ApiResponse>;
+    startEnvironment(environmentId: string): Promise<ApiResponse>;
+    stopEnvironment(environmentId: string): Promise<ApiResponse>;
+    deleteEnvironment(id: string): Promise<ApiResponse>;
+    getEnvironmentStatus(environmentId: string): Promise<ApiResponse>;
+    listInstances(): Promise<ApiResponse>;
+    getInstance(instanceId: string): Promise<ApiResponse>;
+    getInstanceMetrics(instanceId: string): Promise<ApiResponse>;
+    cancelShutdown(instanceId: string): Promise<ApiResponse>;
+    createDeployment(appName: string, serverIp: string, tier?: string): Promise<ApiResponse>;
+    listDeployments(): Promise<ApiResponse>;
+    getDeployment(deploymentId: string): Promise<ApiResponse>;
+    updateDeployment(deploymentId: string, params: Record<string, unknown>): Promise<ApiResponse>;
+    deleteDeployment(deploymentId: string): Promise<ApiResponse>;
+    enableHosting(deploymentId: string): Promise<ApiResponse>;
+    disableHosting(deploymentId: string): Promise<ApiResponse>;
+    connectGithub(deploymentId: string, repo: string, branch?: string): Promise<ApiResponse>;
+    disconnectGithub(deploymentId: string): Promise<ApiResponse>;
+    stopDeployment(deploymentId: string): Promise<ApiResponse>;
+    checkDeploymentHealth(deploymentId: string): Promise<ApiResponse>;
+    createSecretIdentity(deploymentId: string): Promise<ApiResponse>;
+    setEnvVar(deploymentId: string, key: string, value: string): Promise<ApiResponse>;
+    listEnvVars(deploymentId: string): Promise<ApiResponse>;
+    deleteEnvVar(deploymentId: string, key: string): Promise<ApiResponse>;
+    listDomains(): Promise<ApiResponse>;
+    setupDomain(domain: string, deploymentId: string): Promise<ApiResponse>;
+    verifyDomain(domain: string): Promise<ApiResponse>;
+    deleteDomain(domainId: string): Promise<ApiResponse>;
+    createBucket(name: string, provider?: string): Promise<ApiResponse>;
+    listBuckets(): Promise<ApiResponse>;
+    getBucket(bucketId: string): Promise<ApiResponse>;
+    getBucketByName(name: string): Promise<ApiResponse>;
+    getBucketCredentials(bucketId: string): Promise<ApiResponse>;
+    deleteBucket(bucketId: string): Promise<ApiResponse>;
+    listServers(): Promise<ApiResponse>;
+    getServer(serverId: string): Promise<ApiResponse>;
+    createServer(plan: string, region: string, projectId?: string): Promise<ApiResponse>;
+    powerOnServer(serverId: string): Promise<ApiResponse>;
+    powerOffServer(serverId: string): Promise<ApiResponse>;
+    deleteServer(serverId: string): Promise<ApiResponse>;
+    listSshKeys(): Promise<ApiResponse>;
+    createSshKey(name: string, publicKey: string): Promise<ApiResponse>;
+    deleteSshKey(keyId: string): Promise<ApiResponse>;
+    listOrganizations(): Promise<ApiResponse>;
+    getOrganization(orgId: string): Promise<ApiResponse>;
+    getOrganizationMembers(orgId: string): Promise<ApiResponse>;
+    getOrganizationProjects(orgId: string): Promise<ApiResponse>;
+    getBillingStatus(): Promise<ApiResponse>;
+    listTiers(): Promise<ApiResponse>;
+    getUsage(): Promise<ApiResponse>;
+    createCheckout(tier: string): Promise<ApiResponse>;
+    createPortal(): Promise<ApiResponse>;
+    listAddOns(): Promise<ApiResponse>;
+    createAddOn(name: string, deploymentId?: string): Promise<ApiResponse>;
+    deleteAddOn(addOnId: string): Promise<ApiResponse>;
+    getCertificate(certId: string): Promise<ApiResponse>;
+    downloadCertificate(certId: string): Promise<ApiResponse>;
+    createClientCert(): Promise<ApiResponse>;
+    revokeCertificate(certId: string): Promise<ApiResponse>;
+    createNetworkAuthKey(): Promise<ApiResponse>;
+}
+export {};