@aicommander/mcp 1.0.0

package/README.md

@@ -0,0 +1,62 @@
+# @aicommander/mcp
+
+Universal **stdio MCP server** for [AI Commander](https://aicommander.dev) — run shell commands on remote machines by talking to your AI client.
+
+Use this package to connect any MCP client that speaks **stdio** (Codex CLI, Claude Desktop's config file, Cursor, Windsurp, …) to your AI Commander relay. It wraps the remote HTTPS/SSE MCP endpoint so clients that can only launch a local process get the same `remote_exec` and `session_status` tools.
+
+> Using **Claude Code**? You don't need this package — add the relay directly:
+> `claude mcp add --transport http aicommander https://<your-worker>/mcp --header "Authorization: Bearer <token>"`
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `remote_exec` | Run a shell command on a machine by its `AIC-…` session code; streams stdout/stderr back. |
+| `session_status` | Check whether a machine is online and ready. |
+
+## Configuration
+
+Two environment variables:
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `AICOMMANDER_ADMIN_TOKEN` | **yes** | — | Admin token from `POST /api/admin/token` on your relay. |
+| `AICOMMANDER_SERVER` | no | `https://aic-worker.lrz.workers.dev` | Base URL of your self-hosted AI Commander Worker. |
+
+## Usage
+
+### Codex CLI — `~/.codex/config.toml`
+
+```toml
+[mcp_servers.aicommander]
+command = "npx"
+args = ["-y", "@aicommander/mcp"]
+env = { AICOMMANDER_ADMIN_TOKEN = "<token>", AICOMMANDER_SERVER = "https://<your-worker>" }
+```
+
+### Claude Desktop — `claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "aicommander": {
+      "command": "npx",
+      "args": ["-y", "@aicommander/mcp"],
+      "env": {
+        "AICOMMANDER_ADMIN_TOKEN": "<token>",
+        "AICOMMANDER_SERVER": "https://<your-worker>"
+      }
+    }
+  }
+}
+```
+
+Then just mention a session code in chat:
+
+> *"Show disk usage on AIC-WOLF-7421"*
+
+The client detects the `AIC-` prefix and calls `remote_exec` for you.
+
+## License
+
+MIT

package/dist/bin/mcp.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const SERVER_URL = process.env["AICOMMANDER_SERVER"] ?? "https://aic-worker.lrz.workers.dev";
+const ADMIN_TOKEN = process.env["AICOMMANDER_ADMIN_TOKEN"];
+if (!ADMIN_TOKEN) {
+    process.stderr.write("Error: AICOMMANDER_ADMIN_TOKEN environment variable is required\n");
+    process.exit(1);
+}
+const server = new McpServer({
+    name: "aicommander",
+    version: "1.0.0",
+});
+// Tool: remote_exec
+server.registerTool("remote_exec", {
+    description: "Execute a shell command on a remote machine running the AI Commander agent. " +
+        "Use this tool whenever the user mentions a server/machine code that starts with 'AIC-' " +
+        "(e.g. AIC-WOLF-7421). Streams stdout/stderr output in real time.",
+    inputSchema: {
+        code: z
+            .string()
+            .describe("AI Commander session code — always starts with 'AIC-' (e.g. AIC-WOLF-7421)"),
+        command: z
+            .string()
+            .describe("Shell command to execute (runs via /bin/sh -c on the remote machine)"),
+        cwd: z
+            .string()
+            .optional()
+            .describe("Working directory on the remote machine (optional)"),
+        timeout_ms: z
+            .number()
+            .optional()
+            .describe("Timeout in milliseconds. Default 300000 (5 min), max 3600000 (1 hr)"),
+    },
+}, async ({ code, command, cwd, timeout_ms }) => {
+    const res = await fetch(`${SERVER_URL}/mcp`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${ADMIN_TOKEN}`,
+            Accept: "text/event-stream",
+        },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "tools/call",
+            params: {
+                name: "remote_exec",
+                arguments: { code, command, cwd, timeout_ms },
+            },
+        }),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        return {
+            content: [{ type: "text", text: `Error ${res.status}: ${text}` }],
+            isError: true,
+        };
+    }
+    // Parse SSE stream
+    const text = await res.text();
+    const lines = text.split("\n");
+    const output = [];
+    for (const line of lines) {
+        if (!line.startsWith("data: "))
+            continue;
+        try {
+            const data = JSON.parse(line.slice(6));
+            // Result from tools/call
+            if (data?.result?.content) {
+                for (const c of data.result.content) {
+                    if (c.type === "text" && c.text !== undefined)
+                        output.push(c.text);
+                }
+            }
+            // Error
+            if (data?.error) {
+                return {
+                    content: [
+                        { type: "text", text: `Error: ${data.error.message}` },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        catch {
+            // ignore non-JSON lines
+        }
+    }
+    return {
+        content: [{ type: "text", text: output.join("") || "(no output)" }],
+    };
+});
+// Tool: session_status
+server.registerTool("session_status", {
+    description: "Check whether a remote machine is online and ready. Use this when the user asks about " +
+        "a server/machine identified by an AIC- code (e.g. AIC-WOLF-7421).",
+    inputSchema: {
+        code: z
+            .string()
+            .describe("AI Commander session code starting with 'AIC-' (e.g. AIC-WOLF-7421)"),
+    },
+}, async ({ code }) => {
+    const res = await fetch(`${SERVER_URL}/mcp`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${ADMIN_TOKEN}`,
+        },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "tools/call",
+            params: { name: "session_status", arguments: { code } },
+        }),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        return {
+            content: [{ type: "text", text: `Error ${res.status}: ${text}` }],
+            isError: true,
+        };
+    }
+    const data = (await res.json());
+    const content = data?.result?.content ?? [
+        { type: "text", text: JSON.stringify(data) },
+    ];
+    return {
+        content: content,
+    };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@aicommander/mcp",
+  "version": "1.0.0",
+  "description": "Universal stdio MCP server for AI Commander — connect Codex CLI, Claude Desktop, or any stdio MCP client to remote machines by session code.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "aicommander",
+    "remote-shell",
+    "claude",
+    "codex",
+    "ai-agent"
+  ],
+  "homepage": "https://aicommander.dev",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "aicommander-mcp": "./dist/bin/mcp.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.3"
+  }
+}