@aipermission/mcp 0.1.9 → 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
@@ -98,11 +102,11 @@ Supported clients:
 - `gemini`: `GEMINI.md`
 - `custom`: prints portable Markdown to stdout
 
-These instructions teach the agent how to poll `approval_pending` and `running` requests, handle `stale` approvals by sending a fresh request, read live console output, write short reasons, use explicit file transfer paths, and avoid printing secrets. The default installer uses the operator instruction bundled in the npm package; `--source` accepts local file paths only and rejects HTTP(S) sources.
+These instructions teach the agent how to poll `approval_pending` and `running` requests, handle `stale` approvals by sending a fresh request, read live console output, recover stuck persistent console sessions with `restart_console_session`, write short reasons, use explicit file transfer paths, and avoid printing secrets. The default installer uses the operator instruction bundled in the npm package; `--source` accepts local file paths only and rejects HTTP(S) sources.
 
 ## Security Boundary
 
-This package talks to a local AIPermission gateway. `AIPERMISSION_API_URL` must point to `localhost`, `127.0.0.1`, or `[::1]`; remote URLs are rejected before the bearer token is sent. Do not expose the gateway on LAN or the public internet, and do not use it as a shared DevOps service. Tokens grant access only to the servers and execution rules configured in the gateway UI. Token/server permissions may be temporary; expired grants are omitted from `list_servers` and no longer authorize command, console, or file-transfer tools.
+This package talks to a local AIPermission gateway. `AIPERMISSION_API_URL` must point to `localhost`, `127.0.0.1`, or `[::1]`; remote URLs are rejected before the bearer token is sent. Do not expose the gateway on LAN or the public internet, and do not use it as a shared DevOps service. Tokens grant access only to the servers and execution rules configured in the gateway UI. Token/server permissions may be temporary; expired grants are omitted from `list_servers` and no longer authorize command, console, or file-transfer tools. `list_servers` is permission-scoped, not a live SSH health check; treat `exec` connection errors as the current reachability signal.
 
 ## License
 

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

@@ -27,9 +27,15 @@ If no server is visible, say that the current token has no accessible servers.
 If `expires_at` is present, treat access as temporary. Finish within that
 maintenance window or ask the operator to extend access.
 
+`list_servers()` is permission-scoped, not a live health check. A visible server
+may still be powered off, unreachable, reject SSH authentication, or require host
+key review. Treat `exec` dial, timeout, authentication, and host-key errors as
+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:
 
@@ -47,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.
@@ -72,6 +102,13 @@ stale
 
 If the request is `declined`, read `user_note` and follow the user's correction.
 If the request is `stale`, the approval context changed before execution; send a fresh `exec` request with the current command and reason instead of trying to reuse the old approval.
+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
 
@@ -79,15 +116,16 @@ 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`
-shows no useful progress, ask the operator before recovery. When the operator
-agrees, call `restart_console_session(server_id)`. This closes the
-gateway-owned persistent console session and the next `exec` opens a fresh SSH
-session. Treat any canceled request as inconclusive and re-run only the minimal
-safe inspection needed.
+shows no useful progress, ask the operator before recovery unless they already
+asked you to recover the session. When recovery is approved, call
+`restart_console_session(server_id)`. This does not intentionally run a remote
+shell command; it closes the gateway-owned persistent console session and the
+next `exec` opens a fresh SSH session. Treat any canceled request as
+inconclusive and re-run only the minimal safe inspection needed.
 
 ## Message Flow
 

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.9",
+  "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.9",
+  "version": "0.1.13",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@aipermission/mcp",
-      "version": "0.1.9",
+      "version": "0.1.13",
       "transport": {
         "type": "stdio"
       }