captain-tool 0.0.2 → 0.0.6

package/README.md

@@ -0,0 +1,182 @@
+# captain-tool
+
+An MCP server that connects your AI coding agent to [Captain](https://app.getcaptain.dev) — a release train management and SDLC orchestration platform.
+
+Once installed, your AI agent can interact with your Captain workspace directly in conversation: checking pipeline status, reviewing deployments, managing artifacts, and more.
+
+---
+
+## Supported clients
+
+- Claude Desktop
+- Claude Code (CLI)
+- VS Code + Copilot
+- Cursor
+- Windsurf
+
+---
+
+## Requirements
+
+- Node.js 16+
+- A [Captain](https://app.getcaptain.dev) account
+- One of the supported AI clients above
+
+---
+
+## Installation
+
+```bash
+npm install -g captain-tool
+```
+
+---
+
+## Setup (recommended)
+
+Run the interactive setup wizard to automatically configure your AI client(s):
+
+```bash
+captain-tool setup
+```
+
+The wizard will detect your platform, find the binary, and write the correct MCP config for whichever client(s) you select. Supports all 5 clients above in one step.
+
+---
+
+## Manual setup
+
+### Claude Desktop
+
+Edit `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+
+**macOS / Linux:**
+```json
+{
+  "mcpServers": {
+    "captain-tool": {
+      "command": "captain-tool",
+      "env": {
+        "CAPTAIN_API_URL": "https://app.getcaptain.dev/"
+      }
+    }
+  }
+}
+```
+
+**Windows** (requires `cmd /c` wrapper so the shell can resolve the `.cmd` shim):
+```json
+{
+  "mcpServers": {
+    "captain-tool": {
+      "command": "cmd",
+      "args": ["/c", "captain-tool"],
+      "env": {
+        "CAPTAIN_API_URL": "https://app.getcaptain.dev/"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop to activate.
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add captain-tool -- cmd /c captain-tool
+```
+
+### VS Code + Copilot
+
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-0098FF?logo=visualstudiocode)](vscode:mcp/install?%7B%22name%22%3A%22captain-tool%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22captain-tool%22%5D%2C%22env%22%3A%7B%22CAPTAIN_API_URL%22%3A%22https%3A%2F%2Fapp.getcaptain.dev%2F%22%7D%7D)
+
+Or edit `%APPDATA%\Code\User\mcp.json` (Windows) / `~/.config/Code/User/mcp.json` (Linux) / `~/Library/Application Support/Code/User/mcp.json` (macOS):
+
+```json
+{
+  "servers": {
+    "captain-tool": {
+      "type": "stdio",
+      "command": "captain-tool",
+      "env": {
+        "CAPTAIN_API_URL": "https://app.getcaptain.dev/"
+      }
+    }
+  }
+}
+```
+
+Reload VS Code (`Ctrl+Shift+P` → "Developer: Reload Window") to activate.
+
+### Cursor
+
+Edit `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "captain-tool": {
+      "command": "captain-tool",
+      "env": {
+        "CAPTAIN_API_URL": "https://app.getcaptain.dev/"
+      }
+    }
+  }
+}
+```
+
+Restart Cursor to activate.
+
+### Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json` (macOS/Linux) or `%USERPROFILE%\.codeium\windsurf\mcp_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "captain-tool": {
+      "command": "captain-tool",
+      "env": {
+        "CAPTAIN_API_URL": "https://app.getcaptain.dev/"
+      }
+    }
+  }
+}
+```
+
+Restart Windsurf to activate.
+
+---
+
+## First use
+
+Once connected, ask your AI agent:
+
+> "Check captain status and get me set up."
+
+It will walk you through logging in and selecting your workspace. After that, you can ask things like:
+
+```
+Show me all my pipelines.
+What's the current state of my active workspace?
+List any unhealthy connectors.
+What components do we have?
+Show me the deployment history for component comp-xyz.
+```
+
+---
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CAPTAIN_API_URL` | `https://app.getcaptain.dev/` | Captain backend URL |
+| `CAPTAIN_DB_PATH` | platform default | Local state and auth token |
+| `CAPTAIN_REQUEST_TIMEOUT_SECONDS` | `30` | HTTP timeout per request |
+
+---
+
+## Learn more
+
+Visit [app.getcaptain.dev](https://app.getcaptain.dev) to learn more about Captain.

package/bin/captain-tool-setup

@@ -132,6 +132,29 @@ const CLIENTS = [
 
 // ── Config entry builders ─────────────────────────────────────────────────────
 
+/**
+ * Build { command, args } that correctly invokes the captain-tool binary
+ * (or npx fallback) on the current OS.
+ *
+ * WHY the cmd /c wrapper on Windows?
+ *   On Windows, `npx` is installed as `npx.cmd` — a CMD batch script.
+ *   Processes launched without a shell (as MCP hosts do) cannot execute .cmd
+ *   files directly; they must be routed through `cmd /c`.  A bare .exe path
+ *   does NOT need this wrapper, so we only apply it when falling back to npx.
+ */
+function resolveCommand(binaryPath) {
+  if (binaryPath) {
+    // Direct binary — works on all platforms without a shell wrapper.
+    return { command: binaryPath, args: [] };
+  }
+  // Fallback: invoke via npx.  On Windows wrap with cmd /c so the host can
+  // execute the npx.cmd batch script.
+  if (process.platform === 'win32') {
+    return { command: 'cmd', args: ['/c', 'npx', 'captain-tool'] };
+  }
+  return { command: 'npx', args: ['captain-tool'] };
+}
+
 /**
  * Build the MCP server entry object for Format A clients
  * (Claude Desktop, Claude Code, Cursor, Windsurf).
@@ -140,9 +163,10 @@ const CLIENTS = [
  * No "type" field required.
  */
 function buildEntryFormatA(binaryPath) {
+  const { command, args } = resolveCommand(binaryPath);
   return {
-    command: binaryPath,
-    args: [],
+    command,
+    args,
     env: {
       CAPTAIN_API_URL,
     },
@@ -156,10 +180,11 @@ function buildEntryFormatA(binaryPath) {
  * Requires a "type": "stdio" field.
  */
 function buildEntryFormatB(binaryPath) {
+  const { command, args } = resolveCommand(binaryPath);
   return {
     type: 'stdio',
-    command: binaryPath,
-    args: [],
+    command,
+    args,
     env: {
       CAPTAIN_API_URL,
     },
@@ -258,17 +283,21 @@ async function main() {
   console.log('');
 
   // Resolve the absolute binary path — same logic as the runner.
+  // If no platform binary is installed we fall back to npx (null triggers the
+  // npx path in resolveCommand / buildEntry*).
   const binaryPath = findBinary();
-  if (!binaryPath) {
-    console.error(
-      'Error: captain-tool binary not found.\n' +
-      'Make sure you installed the package on a supported platform:\n' +
-      '  npm install -g captain-tool\n'
+  if (binaryPath) {
+    console.log(`Binary path: ${binaryPath}`);
+  } else {
+    const fallback = process.platform === 'win32'
+      ? 'cmd /c npx captain-tool'
+      : 'npx captain-tool';
+    console.warn(
+      `Warning: no pre-built binary found for this platform.\n` +
+      `Falling back to: ${fallback}\n` +
+      `For best performance, install on a supported platform: win32-x64, darwin-x64, darwin-arm64, linux-x64\n`
     );
-    process.exit(1);
   }
-
-  console.log(`Binary path: ${binaryPath}`);
   console.log('');
 
   // Present the client menu.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "captain-tool",
-  "version": "0.0.2",
+  "version": "0.0.6",
   "description": "MCP server connecting Claude Desktop and VS Code Copilot to Captain Cloud",
   "bin": {
     "captain-tool": "bin/captain-tool",
@@ -10,10 +10,10 @@
     "postinstall": "node scripts/postinstall.js"
   },
   "optionalDependencies": {
-    "@captain-tool/captain-tool-win32-x64": "0.0.2",
-    "@captain-tool/captain-tool-darwin-x64": "0.0.2",
-    "@captain-tool/captain-tool-darwin-arm64": "0.0.2",
-    "@captain-tool/captain-tool-linux-x64": "0.0.2"
+    "@captain-tool/captain-tool-win32-x64": "0.0.6",
+    "@captain-tool/captain-tool-darwin-x64": "0.0.6",
+    "@captain-tool/captain-tool-darwin-arm64": "0.0.6",
+    "@captain-tool/captain-tool-linux-x64": "0.0.6"
   },
   "files": [
     "bin/",