@aipermission/mcp 0.1.11 → 0.1.13

package/README.md

@@ -70,6 +70,10 @@ The generated MCP config contains a bearer token. Keep it private. For project-l
 
 `exec` is intended for non-interactive commands. The gateway closes stdin for MCP command bodies so stdin-reading commands cannot consume the internal shell wrapper. Use the web console for interactive work.
 
+Command responses can include `policy_warnings` for common high-risk command
+patterns. They are best-effort safety rails and do not replace token
+permissions, approval review, or operator judgment.
+
 File transfer tools are intentionally conservative. MCP can list transfer
 metadata, browse remote directories, start remote download queues, save
 completed downloads to explicit local paths, upload explicit local files, and

package/dist/resources/aipermission-operator/SKILL.md

@@ -34,7 +34,8 @@ the current reachability signal.
 
 ## Command Reasons
 
-Every `exec` call should include a short `reason`.
+Every single-server `exec` call should include a short `reason`. Multi-server
+`exec` calls with `server_ids` must include a short `reason`.
 
 Good reasons:
 
@@ -52,6 +53,30 @@ debug
 test
 ```
 
+## Bulk Command Flow
+
+Use `exec(server_ids, command, reason)` when the operator asks for the same
+non-interactive command on multiple servers, such as checking package update
+state, uptime, disk usage, or a service status across a small fleet.
+
+Before using multi-server `exec`:
+
+1. Call `list_servers()`.
+2. Choose only the requested target servers.
+3. Keep the command non-interactive and bounded.
+4. Use one clear reason that applies to every target.
+
+After multi-server `exec` returns:
+
+1. Inspect every item.
+2. For each item with `request_id`, poll `get_request(request_id)` until terminal.
+3. If several `always_run` items are still running, use `read_console(server_ids, tail)` to inspect live output in one read-only call.
+4. Treat `blocked` or unauthorized items as skipped, not failed executions.
+5. Do not assume all targets started just because the top-level status is `accepted`.
+
+Prefer individual `exec` calls when each server needs a different command,
+different reason, or separate investigation path.
+
 ## Approval Flow
 
 `approval_pending` is not terminal.
@@ -81,13 +106,17 @@ If the request is `error`, read the error text. SSH reachability, refused ports,
 authentication failures, and host-key failures are current connection signals;
 do not assume a listed server is live just because `list_servers` returned it.
 
+If a response or request contains `policy_warnings`, mention the warning briefly
+when it affects the next action. These warnings are best-effort safety rails, not
+permission to skip human judgment.
+
 ## Running Flow
 
 When `exec` or `get_request` returns `running`:
 
 1. If the server permission is `always_run`, call `read_console(server_id)` before sending another long-running command to the same server.
 2. Poll `get_request(request_id)` every 3-5 seconds.
-3. Use `read_console(server_id)` between polls only when the token has `always_run` permission.
+3. Use `read_console(server_id)` between polls only when the token has `always_run` permission. For a multi-server command, use `read_console(server_ids, tail)` to inspect several running consoles at once.
 4. Do not start another long-running command on the same server until the active request reaches a terminal status, unless the user explicitly asks.
 
 If the request appears stuck for an unusually long time and `read_console`

package/dist/server.js

@@ -25,7 +25,7 @@ const apiTransferTimeoutMs = Number.parseInt(process.env.AIPERMISSION_TRANSFER_T
 
 const server = new McpServer({
   name: "aipermission",
-  version: "0.1.2",
+  version: "0.1.13",
 });
 
 server.tool(
@@ -39,35 +39,86 @@ server.tool(
 
 server.tool(
   "exec",
-  "Execute a shell command on an allowed server through the local aipermission gateway. If status is approval_pending, follow assistant_hint and poll get_request. Long always_run commands return running; use read_console to continue watching.",
+  "Execute a shell command on one allowed server, or the same shell command across multiple allowed servers, through the local aipermission gateway. If status is approval_pending, follow assistant_hint and poll get_request. Long always_run commands return running; use read_console to continue watching.",
   {
-    server_id: z.number().int().positive().describe("Server id from list_servers."),
+    server_id: z.number().int().positive().optional().describe("Single server id from list_servers. Use either server_id or server_ids, not both."),
+    server_ids: z.array(z.number().int().positive()).min(1).max(25).optional().describe("Multiple server ids from list_servers for bulk execution. Up to 25 targets. Use either server_id or server_ids, not both."),
     command: z.string().min(1).describe("Shell command to execute."),
-    reason: z.string().optional().describe("Why this command is needed."),
+    reason: z.string().optional().describe("Why this command is needed. Required when using server_ids."),
   },
-  async ({ server_id, command, reason }) => {
-    return jsonToolResult(() => apiPost("/api/mcp/exec", {
-      server_id,
-      command,
-      reason: reason || "",
-    }));
+  async ({ server_id, server_ids, command, reason }) => {
+    return jsonToolResult(() => {
+      if (server_id && server_ids?.length) {
+        throw new Error("Use either server_id or server_ids, not both.");
+      }
+      if (!server_id && !server_ids?.length) {
+        throw new Error("server_id or server_ids is required.");
+      }
+      if (server_ids?.length) {
+        if (!String(reason || "").trim()) {
+          throw new Error("reason is required when using server_ids.");
+        }
+        return apiPost("/api/mcp/bulk-exec", {
+          server_ids,
+          command,
+          reason,
+        });
+      }
+      return apiPost("/api/mcp/exec", {
+        server_id,
+        command,
+        reason: reason || "",
+      });
+    });
   }
 );
 
 server.tool(
   "read_console",
-  "Read the latest persistent console transcript for an allowed server. Use this after a long-running exec returns running.",
+  "Read the latest persistent console transcript for one allowed server, or for multiple allowed servers after a multi-server exec. Use this after a long-running exec returns running.",
   {
-    server_id: z.number().int().positive().describe("Server id from list_servers."),
+    server_id: z.number().int().positive().optional().describe("Single server id from list_servers. Use either server_id or server_ids, not both."),
+    server_ids: z.array(z.number().int().positive()).min(1).max(25).optional().describe("Multiple server ids from list_servers. Up to 25 targets. Use either server_id or server_ids, not both."),
     tail: z.number().int().positive().max(100000).optional().describe("Maximum transcript characters to return."),
   },
-  async ({ server_id, tail }) => {
-    return jsonToolResult(() => {
-      const params = new URLSearchParams({ server_id: String(server_id) });
-      if (tail) {
-        params.set("tail", String(tail));
+  async ({ server_id, server_ids, tail }) => {
+    return jsonToolResult(async () => {
+      if (server_id && server_ids?.length) {
+        throw new Error("Use either server_id or server_ids, not both.");
+      }
+      if (!server_id && !server_ids?.length) {
+        throw new Error("server_id or server_ids is required.");
+      }
+      const readOne = (id) => {
+        const params = new URLSearchParams({ server_id: String(id) });
+        if (tail) {
+          params.set("tail", String(tail));
+        }
+        return apiGet(`/api/mcp/console?${params.toString()}`);
+      };
+      if (server_ids?.length) {
+        const unique = new Set(server_ids);
+        if (unique.size !== server_ids.length) {
+          throw new Error("server_ids must not contain duplicates.");
+        }
+        const items = await Promise.all(server_ids.map(async (id) => {
+          try {
+            return await readOne(id);
+          } catch (error) {
+            return {
+              status: "error",
+              server_id: id,
+              error: error?.message || "failed to read console",
+            };
+          }
+        }));
+        return {
+          status: "ok",
+          items,
+          assistant_hint: "Inspect each item independently. A listed server may have no active console, blocked read permission, or an SSH/session error.",
+        };
       }
-      return apiGet(`/api/mcp/console?${params.toString()}`);
+      return readOne(server_id);
     });
   }
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipermission/mcp",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "mcpName": "io.github.aipermission/aipermission-mcp",
   "description": "Local-first MCP bridge for the aipermission gateway.",
   "license": "MIT",

package/server.json

@@ -3,12 +3,12 @@
   "name": "io.github.aipermission/aipermission-mcp",
   "title": "AIPermission",
   "description": "Local-first MCP bridge for the AIPermission gateway.",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@aipermission/mcp",
-      "version": "0.1.11",
+      "version": "0.1.13",
       "transport": {
         "type": "stdio"
       }