@shellexec/mcp 1.0.0

package/README.md

@@ -0,0 +1,91 @@
+# ShellExec MCP Server
+
+MCP (Model Context Protocol) server for [ShellExec](https://app.shellexec.sh). Lets AI assistants like Claude, Cursor, and Windsurf manage your servers through ShellExec.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_agents` | List all agents with status |
+| `get_agent` | Get details for a specific agent |
+| `execute_command` | Run a command on one agent |
+| `execute_on_all` | Run a command on all online agents |
+| `get_allowlist` | View allowed commands |
+| `get_command_history` | View recent command history |
+
+## Setup
+
+### Claude Desktop / Claude Code
+
+Add to your Claude config (`~/.claude.json` or Claude Desktop settings):
+
+```json
+{
+  "mcpServers": {
+    "shellexec": {
+      "command": "npx",
+      "args": ["-y", "shellexec-mcp", "--api-key", "sk-your-api-key"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "shellexec": {
+      "command": "npx",
+      "args": ["-y", "shellexec-mcp", "--api-key", "sk-your-api-key"]
+    }
+  }
+}
+```
+
+### Environment variables
+
+Alternatively, use environment variables:
+
+```json
+{
+  "mcpServers": {
+    "shellexec": {
+      "command": "npx",
+      "args": ["-y", "shellexec-mcp"],
+      "env": {
+        "SHELLEXEC_API_KEY": "sk-your-api-key",
+        "SHELLEXEC_API_URL": "https://app.shellexec.sh"
+      }
+    }
+  }
+}
+```
+
+## Usage Examples
+
+Once configured, you can ask your AI assistant:
+
+- *"List my servers"*
+- *"Check the uptime on all agents"*
+- *"Run df -h on web-1"*
+- *"What commands have been run today?"*
+- *"Show me the disk usage across all servers"*
+- *"What commands are in the allowlist?"*
+
+## Configuration
+
+| Option | Env Var | CLI Flag | Default |
+|--------|---------|----------|---------|
+| API Key | `SHELLEXEC_API_KEY` | `--api-key` | Required |
+| API URL | `SHELLEXEC_API_URL` | `--api-url` | `https://app.shellexec.sh` |
+
+## Development
+
+```bash
+npm install
+npm run build
+SHELLEXEC_API_KEY=sk-... node dist/index.js
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+const API_KEY = process.env.SHELLEXEC_API_KEY || process.argv.find((_, i, a) => a[i - 1] === "--api-key") || "";
+const API_BASE = process.env.SHELLEXEC_API_URL || process.argv.find((_, i, a) => a[i - 1] === "--api-url") || "https://app.shellexec.sh";
+if (!API_KEY) {
+    console.error("Error: SHELLEXEC_API_KEY environment variable or --api-key argument required");
+    process.exit(1);
+}
+// ---------------------------------------------------------------------------
+// API client
+// ---------------------------------------------------------------------------
+async function api(path, options = {}) {
+    const res = await fetch(`${API_BASE}${path}`, {
+        ...options,
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${API_KEY}`,
+            ...(options.headers || {}),
+        },
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => res.statusText);
+        throw new Error(`ShellExec API error ${res.status}: ${text}`);
+    }
+    return res.json();
+}
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+const server = new mcp_js_1.McpServer({
+    name: "shellexec",
+    version: "1.0.0",
+});
+// --- list_agents ---
+server.tool("list_agents", "List all ShellExec agents with their hostname, UUID, online status, and last seen time", {}, async () => {
+    const data = await api("/api/agents");
+    if (data.agents.length === 0) {
+        return { content: [{ type: "text", text: "No agents found." }] };
+    }
+    const lines = data.agents.map(a => `${a.online ? "●" : "○"} ${a.hostname || "(no hostname)"} — ${a.uuid} — ${a.online ? "online" : "offline"} — last seen: ${a.last_seen || "never"}`);
+    return {
+        content: [{ type: "text", text: `${data.agents.length} agent(s):\n\n${lines.join("\n")}` }],
+    };
+});
+// --- execute_command ---
+server.tool("execute_command", "Execute a shell command on a specific agent. The command must be in the allowlist. Returns output, exit code, and whether sudo was used.", {
+    agent_uuid: zod_1.z.string().describe("UUID of the agent to execute the command on"),
+    command: zod_1.z.string().describe("The shell command to execute (must be in the allowlist)"),
+}, async ({ agent_uuid, command }) => {
+    const data = await api(`/api/agents/${agent_uuid}/exec`, {
+        method: "POST",
+        body: JSON.stringify({ command }),
+    });
+    let text = `Exit code: ${data.exit_code}`;
+    if (data.used_sudo)
+        text += " (ran with sudo)";
+    text += "\n";
+    if (data.output)
+        text += `\nOutput:\n${data.output}`;
+    if (data.error && data.error !== "command not allowed")
+        text += `\nError:\n${data.error}`;
+    if (data.error === "command not allowed")
+        text += "\nCommand not in allowlist — add it via the ShellExec dashboard first.";
+    if (data.sudo_hint)
+        text += `\n\nSudo permissions:\n${data.sudo_hint}`;
+    return {
+        content: [{ type: "text", text: text.trim() }],
+        isError: data.exit_code !== 0,
+    };
+});
+// --- execute_on_all ---
+server.tool("execute_on_all", "Execute a shell command on ALL online agents simultaneously. Returns results from each agent.", {
+    command: zod_1.z.string().describe("The shell command to execute on all online agents"),
+}, async ({ command }) => {
+    const data = await api("/api/agents/exec-all", {
+        method: "POST",
+        body: JSON.stringify({ command }),
+    });
+    if (data.results.length === 0) {
+        return { content: [{ type: "text", text: "No online agents found." }] };
+    }
+    const sections = data.results.map(r => {
+        let section = `--- ${r.hostname || r.agent_uuid} (exit ${r.exit_code}${r.used_sudo ? ", sudo" : ""}, ${r.duration_ms}ms) ---`;
+        if (r.output)
+            section += `\n${r.output.trimEnd()}`;
+        if (r.error && r.error !== "command not allowed")
+            section += `\nError: ${r.error}`;
+        if (r.error === "command not allowed")
+            section += `\nDENIED — command not in allowlist`;
+        return section;
+    });
+    return {
+        content: [{ type: "text", text: sections.join("\n\n") }],
+    };
+});
+// --- get_agent ---
+server.tool("get_agent", "Get detailed information about a specific agent by UUID", {
+    agent_uuid: zod_1.z.string().describe("UUID of the agent"),
+}, async ({ agent_uuid }) => {
+    const data = await api(`/api/agents/${agent_uuid}`);
+    return {
+        content: [{
+                type: "text",
+                text: `Hostname: ${data.hostname}\nUUID: ${data.uuid}\nStatus: ${data.online ? "Online" : "Offline"}\nLast seen: ${data.last_seen || "never"}`,
+            }],
+    };
+});
+// --- get_allowlist ---
+server.tool("get_allowlist", "Get the list of commands that agents are allowed to execute. Supports glob wildcards.", {}, async () => {
+    const data = await api("/api/allowlist");
+    if (data.commands.length === 0) {
+        return { content: [{ type: "text", text: "Allowlist is empty. No commands can be executed. Add commands via the ShellExec dashboard." }] };
+    }
+    return {
+        content: [{ type: "text", text: `Allowed commands (${data.commands.length}):\n\n${data.commands.map(c => `  ${c}`).join("\n")}` }],
+    };
+});
+// --- get_command_history ---
+server.tool("get_command_history", "View recent command execution history with output, exit codes, and timing", {
+    limit: zod_1.z.number().optional().default(10).describe("Number of recent commands to return (default 10, max 100)"),
+    agent_uuid: zod_1.z.string().optional().describe("Filter by agent UUID (optional)"),
+    search: zod_1.z.string().optional().describe("Search commands by keyword (optional)"),
+}, async ({ limit, agent_uuid, search }) => {
+    const params = new URLSearchParams();
+    params.set("limit", String(Math.min(limit || 10, 100)));
+    if (agent_uuid)
+        params.set("agent_uuid", agent_uuid);
+    if (search)
+        params.set("search", search);
+    const data = await api(`/api/commands?${params.toString()}`);
+    if (data.commands.length === 0) {
+        return { content: [{ type: "text", text: "No commands found." }] };
+    }
+    const lines = data.commands.map(c => {
+        const ts = new Date(c.executed_at).toLocaleString();
+        const host = c.agent_hostname || c.agent_uuid.substring(0, 8);
+        const sudo = c.used_sudo ? " [sudo]" : "";
+        const denied = c.exit_code === -1 && c.error === "command not allowed" ? " [DENIED]" : "";
+        let line = `[${ts}] ${host} $ ${c.command} → exit ${c.exit_code}${sudo}${denied} (${c.duration_ms}ms)`;
+        if (c.output)
+            line += `\n  ${c.output.trimEnd().split("\n").join("\n  ")}`;
+        return line;
+    });
+    return {
+        content: [{ type: "text", text: `${data.total} total commands. Showing ${data.commands.length}:\n\n${lines.join("\n\n")}` }],
+    };
+});
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@shellexec/mcp",
+  "version": "1.0.0",
+  "description": "MCP server for ShellExec — remote command execution via AI assistants",
+  "main": "dist/index.js",
+  "bin": {
+    "shellexec-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "keywords": ["mcp", "shellexec", "remote-execution", "claude", "ai-tools"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const API_KEY = process.env.SHELLEXEC_API_KEY || process.argv.find((_, i, a) => a[i - 1] === "--api-key") || "";
+const API_BASE = process.env.SHELLEXEC_API_URL || process.argv.find((_, i, a) => a[i - 1] === "--api-url") || "https://app.shellexec.sh";
+
+if (!API_KEY) {
+  console.error("Error: SHELLEXEC_API_KEY environment variable or --api-key argument required");
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// API client
+// ---------------------------------------------------------------------------
+
+async function api<T>(path: string, options: RequestInit = {}): Promise<T> {
+  const res = await fetch(`${API_BASE}${path}`, {
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${API_KEY}`,
+      ...(options.headers as Record<string, string> || {}),
+    },
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => res.statusText);
+    throw new Error(`ShellExec API error ${res.status}: ${text}`);
+  }
+
+  return res.json() as Promise<T>;
+}
+
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+
+const server = new McpServer({
+  name: "shellexec",
+  version: "1.0.0",
+});
+
+// --- list_agents ---
+server.tool(
+  "list_agents",
+  "List all ShellExec agents with their hostname, UUID, online status, and last seen time",
+  {},
+  async () => {
+    const data = await api<{ agents: Array<{ uuid: string; hostname: string; online: boolean; last_seen: string }> }>("/api/agents");
+
+    if (data.agents.length === 0) {
+      return { content: [{ type: "text", text: "No agents found." }] };
+    }
+
+    const lines = data.agents.map(a =>
+      `${a.online ? "●" : "○"} ${a.hostname || "(no hostname)"} — ${a.uuid} — ${a.online ? "online" : "offline"} — last seen: ${a.last_seen || "never"}`
+    );
+
+    return {
+      content: [{ type: "text", text: `${data.agents.length} agent(s):\n\n${lines.join("\n")}` }],
+    };
+  }
+);
+
+// --- execute_command ---
+server.tool(
+  "execute_command",
+  "Execute a shell command on a specific agent. The command must be in the allowlist. Returns output, exit code, and whether sudo was used.",
+  {
+    agent_uuid: z.string().describe("UUID of the agent to execute the command on"),
+    command: z.string().describe("The shell command to execute (must be in the allowlist)"),
+  },
+  async ({ agent_uuid, command }) => {
+    const data = await api<{
+      output: string; error: string; exit_code: number;
+      used_sudo?: boolean; sudo_hint?: string;
+    }>(`/api/agents/${agent_uuid}/exec`, {
+      method: "POST",
+      body: JSON.stringify({ command }),
+    });
+
+    let text = `Exit code: ${data.exit_code}`;
+    if (data.used_sudo) text += " (ran with sudo)";
+    text += "\n";
+    if (data.output) text += `\nOutput:\n${data.output}`;
+    if (data.error && data.error !== "command not allowed") text += `\nError:\n${data.error}`;
+    if (data.error === "command not allowed") text += "\nCommand not in allowlist — add it via the ShellExec dashboard first.";
+    if (data.sudo_hint) text += `\n\nSudo permissions:\n${data.sudo_hint}`;
+
+    return {
+      content: [{ type: "text", text: text.trim() }],
+      isError: data.exit_code !== 0,
+    };
+  }
+);
+
+// --- execute_on_all ---
+server.tool(
+  "execute_on_all",
+  "Execute a shell command on ALL online agents simultaneously. Returns results from each agent.",
+  {
+    command: z.string().describe("The shell command to execute on all online agents"),
+  },
+  async ({ command }) => {
+    const data = await api<{
+      results: Array<{
+        agent_uuid: string; hostname: string;
+        output: string; error: string; exit_code: number;
+        used_sudo?: boolean; duration_ms: number;
+      }>;
+    }>("/api/agents/exec-all", {
+      method: "POST",
+      body: JSON.stringify({ command }),
+    });
+
+    if (data.results.length === 0) {
+      return { content: [{ type: "text", text: "No online agents found." }] };
+    }
+
+    const sections = data.results.map(r => {
+      let section = `--- ${r.hostname || r.agent_uuid} (exit ${r.exit_code}${r.used_sudo ? ", sudo" : ""}, ${r.duration_ms}ms) ---`;
+      if (r.output) section += `\n${r.output.trimEnd()}`;
+      if (r.error && r.error !== "command not allowed") section += `\nError: ${r.error}`;
+      if (r.error === "command not allowed") section += `\nDENIED — command not in allowlist`;
+      return section;
+    });
+
+    return {
+      content: [{ type: "text", text: sections.join("\n\n") }],
+    };
+  }
+);
+
+// --- get_agent ---
+server.tool(
+  "get_agent",
+  "Get detailed information about a specific agent by UUID",
+  {
+    agent_uuid: z.string().describe("UUID of the agent"),
+  },
+  async ({ agent_uuid }) => {
+    const data = await api<{
+      uuid: string; hostname: string; online: boolean; last_seen: string;
+    }>(`/api/agents/${agent_uuid}`);
+
+    return {
+      content: [{
+        type: "text",
+        text: `Hostname: ${data.hostname}\nUUID: ${data.uuid}\nStatus: ${data.online ? "Online" : "Offline"}\nLast seen: ${data.last_seen || "never"}`,
+      }],
+    };
+  }
+);
+
+// --- get_allowlist ---
+server.tool(
+  "get_allowlist",
+  "Get the list of commands that agents are allowed to execute. Supports glob wildcards.",
+  {},
+  async () => {
+    const data = await api<{ commands: string[] }>("/api/allowlist");
+
+    if (data.commands.length === 0) {
+      return { content: [{ type: "text", text: "Allowlist is empty. No commands can be executed. Add commands via the ShellExec dashboard." }] };
+    }
+
+    return {
+      content: [{ type: "text", text: `Allowed commands (${data.commands.length}):\n\n${data.commands.map(c => `  ${c}`).join("\n")}` }],
+    };
+  }
+);
+
+// --- get_command_history ---
+server.tool(
+  "get_command_history",
+  "View recent command execution history with output, exit codes, and timing",
+  {
+    limit: z.number().optional().default(10).describe("Number of recent commands to return (default 10, max 100)"),
+    agent_uuid: z.string().optional().describe("Filter by agent UUID (optional)"),
+    search: z.string().optional().describe("Search commands by keyword (optional)"),
+  },
+  async ({ limit, agent_uuid, search }) => {
+    const params = new URLSearchParams();
+    params.set("limit", String(Math.min(limit || 10, 100)));
+    if (agent_uuid) params.set("agent_uuid", agent_uuid);
+    if (search) params.set("search", search);
+
+    const data = await api<{
+      commands: Array<{
+        id: number; agent_uuid: string; agent_hostname?: string;
+        command: string; output: string; error: string;
+        exit_code: number; used_sudo: boolean;
+        duration_ms: number; executed_at: string;
+      }>;
+      total: number;
+    }>(`/api/commands?${params.toString()}`);
+
+    if (data.commands.length === 0) {
+      return { content: [{ type: "text", text: "No commands found." }] };
+    }
+
+    const lines = data.commands.map(c => {
+      const ts = new Date(c.executed_at).toLocaleString();
+      const host = c.agent_hostname || c.agent_uuid.substring(0, 8);
+      const sudo = c.used_sudo ? " [sudo]" : "";
+      const denied = c.exit_code === -1 && c.error === "command not allowed" ? " [DENIED]" : "";
+      let line = `[${ts}] ${host} $ ${c.command} → exit ${c.exit_code}${sudo}${denied} (${c.duration_ms}ms)`;
+      if (c.output) line += `\n  ${c.output.trimEnd().split("\n").join("\n  ")}`;
+      return line;
+    });
+
+    return {
+      content: [{ type: "text", text: `${data.total} total commands. Showing ${data.commands.length}:\n\n${lines.join("\n\n")}` }],
+    };
+  }
+);
+
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "declaration": true,
+    "sourceMap": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}