@aipermission/mcp 0.1.14 → 0.2.0

package/README.md

@@ -1,10 +1,16 @@
 # @aipermission/mcp
 
-Local-first MCP bridge for the AIPermission gateway.
+Local-first MCP bridge for the AIPermission connector gateway.
 
-AIPermission lets AI coding assistants use scoped server access through a local gateway without receiving SSH private keys or server credentials.
+AIPermission lets AI coding assistants use scoped connector actions through a
+local gateway without receiving SSH private keys, database passwords, API
+credentials, or other connector secrets.
 
-The gateway is intentionally local-only. Run it on the developer machine and keep the URL on `localhost`; remote servers are SSH targets, not places to host the gateway for LAN or internet users.
+The gateway is intentionally local-only. Run it on the developer machine and
+keep the URL on `localhost`; remote systems are connector targets, not places
+to host the gateway for LAN or internet users. SSH and Postgres are built-in
+connectors that use the same target/profile/action permission model as future
+connectors.
 
 ![AIPermission demo: AI installs Uptime Kuma through approval-based SSH access](https://raw.githubusercontent.com/aipermission/aipermission/main/docs/assets/demo/aipermission-demo.gif)
 
@@ -49,39 +55,25 @@ The generated MCP config contains a bearer token. Keep it private. For project-l
 
 ## Tools
 
-- `list_servers`
-- `exec`
-- `get_request`
-- `list_requests`
-- `read_console`
-- `restart_console_session`
-- `send_message`
-- `list_file_transfers`
-- `get_file_transfer`
-- `list_file_transfer_batches`
-- `get_file_transfer_batch`
-- `browse_remote_files`
-- `start_file_download`
-- `save_file_download`
-- `upload_files`
-- `pause_file_transfer_batch`
-- `resume_file_transfer_batch`
-- `cancel_file_transfer_batch`
-
-`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
-pause/resume/cancel queues. `always_run` starts queues immediately.
-`approval_required` creates a local approval queue in AIPermission Transfer
-Center; the operator can approve selected files and reject the rest with a note.
-MCP tool responses never include file contents, gateway temporary paths, archive
-staging paths, or local upload contents.
+- `list_connector_targets`
+- `get_connector_help`
+- `get_connector_actions`
+- `call_connector_action`
+- `get_connector_action_request`
+
+All integration work goes through connector targets. SSH, Postgres, and future
+connectors share the same model: target, credential profile, connector action,
+token action permission, approval, history, and audit.
+
+For SSH, call `get_connector_actions(target_ref)` to discover actions such as
+`exec`, `read_console`, `restart_console_session`, `browse_remote_files`, and
+`start_file_download`. SSH `exec` is intended for non-interactive commands. Use
+the web console for truly interactive work.
+
+Connector responses can include `approval_pending` or `running`. Poll
+`get_connector_action_request(request_id)` until the request reaches a terminal
+status. MCP tool responses never include file contents, gateway temporary paths,
+archive staging paths, or local upload contents.
 
 ## Operator Skill
 
@@ -102,11 +94,24 @@ 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, 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.
+These instructions teach the agent how to discover connector targets, poll
+`approval_pending` and `running` connector action requests, handle `stale`
+approvals by sending a fresh request, 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. `list_servers` is permission-scoped, not a live SSH health check; treat `exec` connection errors as the current reachability signal.
+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 connector targets, credential profiles, and action rules configured in the
+gateway UI. Connector permissions may be temporary; expired grants are omitted
+from `list_connector_targets` and no longer authorize connector actions. Target
+visibility is permission-scoped, not a live health check; treat action execution
+errors as the current reachability signal.
 
 ## License
 

package/dist/cli.js

@@ -39,8 +39,7 @@ Install skill flags:
   --source /path/to/SKILL.md  Local file only; HTTP(S) sources are rejected
 
 Security:
-  Prefer the hidden token prompt or --token-stdin. --token is still accepted
-  for automation, but it can be saved in shell history. AIPERMISSION_API_URL
-  must point to localhost, 127.0.0.1, or [::1].
+  Use the hidden token prompt or --token-stdin. AIPERMISSION_API_URL must point
+  to localhost, 127.0.0.1, or [::1].
 	`);
 }

package/dist/init.js

@@ -122,6 +122,9 @@ export function parseFlags(argv) {
       result.tokenStdin = true;
       continue;
     }
+    if (key === "token") {
+      throw new Error("--token is not supported; use the hidden prompt or --token-stdin");
+    }
     result[key] = inlineValue ?? argv[i + 1] ?? "";
     if (inlineValue === undefined) {
       i += 1;
@@ -228,10 +231,6 @@ async function resolveToken(flags, rl) {
   if (flags.tokenStdin) {
     return flags.stdinToken;
   }
-  if (flags.token) {
-    console.warn(`${color.yellow}Warning:${color.reset} --token can be saved in shell history. Prefer the hidden prompt or --token-stdin.`);
-    return String(flags.token).trim();
-  }
   return askSecret(rl, "API token");
 }
 

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

@@ -1,48 +1,51 @@
 ---
 name: aipermission-operator
-description: Use when operating servers through the AIPermission MCP gateway. Guides AI agents to handle approval_pending/running states, poll get_request, read live console output, write short reasons, avoid leaking secrets, and keep command execution safe and auditable.
+description: Use when operating targets through the AIPermission MCP gateway. Guides AI agents to discover connector targets, call connector actions, handle approval_pending/running states, write short reasons, avoid leaking secrets, and keep execution auditable.
 ---
 
 # AIPermission Operator
 
 ## Core Rule
 
-Use AIPermission as a local, developer-controlled execution gateway.
+Use AIPermission as a local, developer-controlled permission gateway.
 
-You are allowed to operate only the servers returned by `list_servers()`. Do not ask for SSH passwords, private keys, database passwords, or raw credentials. The gateway owns credentials, permissions, approvals, console sessions, and audit history.
+You are allowed to operate only the connector targets returned by
+`list_connector_targets()`. Do not ask for SSH passwords, private keys, database
+passwords, API keys, or raw credentials. The gateway owns credentials,
+permissions, approvals, runtime sessions, and audit history.
 
-AIPermission is not a general DevOps control plane. Treat it as a temporary, scoped maintenance/debugging channel controlled by the human operator.
+AIPermission is not a hosted DevOps control plane. Treat it as a temporary,
+scoped maintenance/debugging channel controlled by the human operator.
 
-## Initial Discovery
+## Discovery
 
-Before executing commands:
+Before acting:
 
-1. Call `list_servers()`.
-2. Read each server's `name`, `id`, `execution_rule`, optional `expires_at`,
-   and `hints`.
-3. Use the numeric `id` returned by the tool.
-4. Pick the narrowest server set that can answer the task.
+1. Call `list_connector_targets()`.
+2. Pick the relevant `target_ref`.
+3. Call `get_connector_help(target_ref)` the first time you use that connector.
+4. Call `get_connector_actions(target_ref)` and choose the narrowest action.
+5. Call `call_connector_action(target_ref, action_name, input, reason)`.
 
-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.
+If no target is visible, say that the current token has no accessible connector
+targets. If an action grant includes `expires_at`, treat access as temporary and
+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.
+Target visibility is permission-scoped, not a live health check. A visible SSH
+target may still be powered off, unreachable, reject authentication, or require
+host-key review. A visible database/API target may still reject the credential
+profile. Treat action errors as the current reachability/authorization signal.
 
-## Command Reasons
+## Reasons
 
-Every single-server `exec` call should include a short `reason`. Multi-server
-`exec` calls with `server_ids` must include a short `reason`.
+Every `call_connector_action` should include a short `reason`.
 
 Good reasons:
 
 ```text
 Check Docker service state before cleanup.
 Inspect recent kubelet errors on worker node.
-Verify trial worker deployment after node label change.
+List Postgres schemas before a read-only metadata query.
 ```
 
 Avoid vague reasons:
@@ -53,41 +56,16 @@ 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.
 
-When `exec` returns `approval_pending`:
+When `call_connector_action` returns `approval_pending`:
 
 1. Read `retry_after_seconds`; default to 3 seconds if missing.
 2. Wait that long.
-3. Call `get_request(request_id)`.
+3. Call `get_connector_action_request(request_id)`.
 4. Continue polling until the status is terminal.
-5. If status becomes `running`, keep polling `get_request(request_id)`; `read_console` is only available when the token has `always_run` permission for that server.
 
 Terminal statuses:
 
@@ -100,89 +78,34 @@ error
 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.
+If the request is `declined`, read the note/error and follow the user's
+correction. If the request is `stale`, the approval context changed before
+execution; send a fresh `call_connector_action` request with the current target,
+action, input, and reason.
 
 ## 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. 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 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
-
-Use `send_message(message, server_id?, session_id?)` for short operator-visible notes.
-
-Good messages:
-
-```text
-Docker install started; waiting for package installation to finish.
-K3s agent joined. Checking node labels now.
-The command is still running; reading console output before next step.
-```
+When `call_connector_action` or `get_connector_action_request` returns
+`running`:
 
-When a response includes `user_note`, treat it as live operator guidance. Apply it before continuing.
+1. Poll `get_connector_action_request(request_id)` every 3-5 seconds.
+2. Do not start another long-running action on the same target/profile until the
+   active request reaches a terminal status, unless the user explicitly asks.
+3. For SSH `exec`, use the SSH connector's `read_console` action when live
+   output is needed and the token has permission for it.
+4. If an SSH request appears stuck for an unusually long time, ask the operator
+   before recovery unless they already asked you to recover. When approved, call
+   the SSH connector's `restart_console_session` action for the same target_ref.
 
-## File Transfer Flow
+## SSH Practice
 
-File transfer tools use the target server permission. `always_run` starts the
-queue immediately. `approval_required` creates a local approval queue in
-AIPermission Transfer Center; wait for the operator to approve selected files or
-reject the queue with a note.
-
-Use them only when the user explicitly asks to move files or inspect transfer
-state. Prefer the smallest explicit path set. Do not use globs, recursive copy,
-or directory transfer unless a future tool explicitly supports those behaviors.
-
-For remote-to-local downloads:
-
-1. Call `start_file_download(server_id, remote_paths, archive_name?)`.
-2. Poll `get_file_transfer_batch(batch_id)` until the batch is terminal.
-   If the status is `pending_approval`, wait and poll again after the operator
-   decides in the local UI.
-3. If completed and the user asked for a local copy, call
-   `save_file_download(batch_id, local_path, overwrite?)` with an explicit local
-   destination.
-4. Report the saved path and status metadata. Do not print file contents unless
-   the user explicitly asks you to inspect the saved file.
-
-For local-to-remote uploads, call `upload_files(server_id, local_paths,
-remote_dir, overwrite?)` only with explicit local paths supplied by the user or
-clearly located in the current local workspace. Poll `get_file_transfer_batch`
-for progress.
-
-The local AIPermission UI shows active and recent transfer queues in Transfer
-Center. The operator can pause, resume, or cancel queues there.
-
-## Safe Shell Practice
-
-Prefer commands that are:
+For SSH connector `exec`, prefer commands that are:
 
 - non-interactive
 - bounded in output
 - explicit about destructive actions
 - easy to audit from history
 
-MCP `exec` closes stdin for the command body. Do not use commands that wait for interactive stdin. Use flags such as `-y`, `--no-pager`, heredoc-created files, or the manual web console for interactive work.
-
 Use examples like:
 
 ```sh
@@ -194,6 +117,14 @@ df -h
 free -m
 ```
 
+Avoid huge unbounded output:
+
+```sh
+cat huge.log
+journalctl
+docker logs NAME
+```
+
 For apt on Debian/Ubuntu:
 
 ```sh
@@ -208,89 +139,22 @@ After install/uninstall checks in the same shell, refresh command lookup:
 hash -r 2>/dev/null || true
 ```
 
-For package verification, prefer installed-state checks over ambiguous removed-package residue:
+## File Transfer
 
-```sh
-dpkg-query -W -f='${db:Status-Abbrev} ${binary:Package} ${Version}\n' docker-ce docker-ce-cli 2>/dev/null | grep '^ii'
-```
-
-## Output Hygiene
-
-Avoid huge unbounded output.
-
-Prefer:
-
-```sh
-tail -n 100 /path/to/log
-journalctl --no-pager -n 100
-docker logs --tail 100 NAME
-kubectl logs --tail=100 POD
-```
+Use connector file-transfer actions only when the user explicitly asks to move
+files or inspect remote paths. Prefer the smallest explicit path set. Do not use
+globs, recursive copy, or directory transfer unless a connector action
+explicitly supports that behavior.
 
-Avoid:
-
-```sh
-cat huge.log
-journalctl
-docker logs NAME
-```
+MCP connector responses never include file contents, gateway temp paths, archive
+staging paths, or local upload contents.
 
 ## Secret Hygiene
 
-Command text, command output, history, audit records, and console transcript may be stored in the encrypted local database.
-
-Do not print secrets unless the user explicitly asks and accepts the risk. Avoid commands that dump:
-
-- private keys
-- `.env` files
-- token files
-- database passwords
-- cloud credentials
-- Kubernetes secrets
-
-Prefer existence and metadata checks:
-
-```sh
-test -f /path/to/.env && echo exists
-ls -l /path/to/secret-file
-kubectl get secret NAME -o jsonpath='{.metadata.name}'
-```
-
-## Destructive Actions
-
-Before destructive actions:
-
-1. Inspect current state.
-2. Explain the exact destructive command in the `reason`.
-3. Prefer one clear destructive step at a time.
-4. Verify after completion.
-
-Examples of destructive actions:
-
-- deleting containers, volumes, images
-- uninstalling packages
-- removing files
-- restarting critical services
-- changing Kubernetes labels or draining nodes
-
-## Multi-Server Work
-
-For multiple servers:
-
-1. Check visibility with `list_servers()`.
-2. Work one risky operation at a time.
-3. Keep each command targeted to one server unless the user explicitly requests batch behavior.
-4. Summarize per-server status after each phase.
-
-## Final Response
-
-When reporting back to the user, include:
-
-- servers touched
-- commands or command groups run
-- important findings
-- changes made
-- verification results
-- any pending/recommended next steps
+Command text, action input, action output, history, audit records, and console
+transcripts may be stored in the encrypted local database. Avoid printing
+secrets. Prefer checking whether a file/key exists before reading credential
+files or environment files.
 
-Keep it concise and operational.
+If a secret appears in output, do not repeat it. Summarize the finding and ask
+the operator how to rotate or redact it.

package/dist/server.js

@@ -6,368 +6,87 @@ if (process.argv[2] === "init") {
   process.exit(0);
 }
 
-import fs from "node:fs";
-import fsp from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { Readable } from "node:stream";
-import { pipeline } from "node:stream/promises";
+import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { normalizeLocalAPIURL } from "./local-url.js";
 import { jsonToolResult } from "./results.js";
 
+const packageMetadata = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const apiUrl = normalizeLocalAPIURL(process.env.AIPERMISSION_API_URL);
 const apiToken = process.env.AIPERMISSION_API_TOKEN || "";
 const apiTimeoutMs = Number.parseInt(process.env.AIPERMISSION_HTTP_TIMEOUT_MS || "60000", 10);
-const apiTransferTimeoutMs = Number.parseInt(process.env.AIPERMISSION_TRANSFER_TIMEOUT_MS || "7200000", 10);
 
 const server = new McpServer({
   name: "aipermission",
-  version: "0.1.14",
+  version: packageMetadata.version,
 });
 
 server.tool(
-  "list_servers",
-  "List servers this aipermission token can access. Credentials are never returned.",
+  "list_connector_targets",
+  "List connector targets this AIPermission token can access. Credentials and secrets are never returned.",
   {},
   async () => {
-    return jsonToolResult(() => apiGet("/api/mcp/servers"));
+    return jsonToolResult(() => apiGet("/api/mcp/connector-targets"));
   }
 );
 
 server.tool(
-  "exec",
-  "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.",
+  "get_connector_help",
+  "Read AI-facing help for one connector target/profile. Use this before calling connector actions for the first time.",
   {
-    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. Required when using server_ids."),
+    target_ref: z.string().min(1).describe("Target ref from list_connector_targets in connector:target_id:profile_id format."),
   },
-  async ({ server_id, server_ids, command, reason }) => {
+  async ({ target_ref }) => {
     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 || "",
-      });
+      const params = new URLSearchParams({ target_ref });
+      return apiGet(`/api/mcp/connector-help?${params.toString()}`);
     });
   }
 );
 
 server.tool(
-  "read_console",
-  "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.",
+  "get_connector_actions",
+  "List actions exposed by one connector target/profile. Action execution is still checked against token permissions.",
   {
-    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."),
+    target_ref: z.string().min(1).describe("Target ref from list_connector_targets in connector:target_id:profile_id format."),
   },
-  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 readOne(server_id);
-    });
-  }
-);
-
-server.tool(
-  "restart_console_session",
-  "Restart the persistent console session for a server when it appears stuck. This closes the current gateway-owned console session and the next exec will open a fresh SSH session.",
-  {
-    server_id: z.number().int().positive().describe("Server id from list_servers."),
-  },
-  async ({ server_id }) => {
-    return jsonToolResult(() => apiPost("/api/mcp/console/restart", {
-      server_id,
-    }));
-  }
-);
-
-server.tool(
-  "get_request",
-  "Read an aipermission command request by id. Use this after exec returns approval_pending or running.",
-  {
-    request_id: z.number().int().positive().describe("Request id returned by exec."),
-  },
-  async ({ request_id }) => {
-    return jsonToolResult(() => apiGet(`/api/mcp/requests/${request_id}`));
-  }
-);
-
-server.tool(
-  "list_requests",
-  "List command requests for this token. Optionally filter by status such as pending_approval, running, completed, failed, declined, or error.",
-  {
-    status: z.string().optional().describe("Optional request status filter."),
-  },
-  async ({ status }) => {
+  async ({ target_ref }) => {
     return jsonToolResult(() => {
-      const params = new URLSearchParams();
-      if (status) {
-        params.set("status", status);
-      }
-      const suffix = params.toString() ? `?${params.toString()}` : "";
-      return apiGet(`/api/mcp/requests${suffix}`);
+      const params = new URLSearchParams({ target_ref });
+      return apiGet(`/api/mcp/connector-actions?${params.toString()}`);
     });
   }
 );
 
 server.tool(
-  "send_message",
-  "Send a short note to the aipermission Console messages panel for the human operator.",
+  "call_connector_action",
+  "Call one connector action through AIPermission. If status is approval_pending or running, follow assistant_hint and poll get_connector_action_request.",
   {
-    message: z.string().min(1).describe("Message to show in the Console messages panel."),
-    server_id: z.number().int().positive().optional().describe("Optional server id this message is about."),
-    session_id: z.number().int().positive().optional().describe("Optional console session id this message is about."),
+    target_ref: z.string().min(1).describe("Target ref from list_connector_targets."),
+    action_name: z.string().min(1).describe("Action name from get_connector_actions."),
+    input: z.record(z.unknown()).optional().describe("Connector-specific action input."),
+    reason: z.string().optional().describe("Why this connector action is needed."),
   },
-  async ({ message, server_id, session_id }) => {
-    return jsonToolResult(() => apiPost("/api/mcp/messages", {
-      message,
-      server_id: server_id || null,
-      session_id: session_id || null,
+  async ({ target_ref, action_name, input, reason }) => {
+    return jsonToolResult(() => apiPost("/api/mcp/connector-actions/call", {
+      target_ref,
+      action_name,
+      input: input || {},
+      reason: reason || "",
     }));
   }
 );
 
 server.tool(
-  "list_file_transfers",
-  "List file transfer records visible to this token. Results never include local temp paths, archive paths, local upload contents, or file contents.",
-  {
-    server_id: z.number().int().positive().optional().describe("Optional server id from list_servers."),
-    direction: z.enum(["upload", "download"]).optional().describe("Optional transfer direction."),
-    status: z.enum(["pending_approval", "pending", "running", "paused", "completed", "failed", "canceled"]).optional().describe("Optional transfer status."),
-    limit: z.number().int().positive().max(100).optional().describe("Maximum records to return."),
-    offset: z.number().int().min(0).optional().describe("Pagination offset."),
-  },
-  async ({ server_id, direction, status, limit, offset }) => {
-    return jsonToolResult(() => {
-      const params = new URLSearchParams();
-      if (server_id) params.set("server_id", String(server_id));
-      if (direction) params.set("direction", direction);
-      if (status) params.set("status", status);
-      if (limit) params.set("limit", String(limit));
-      if (offset) params.set("offset", String(offset));
-      const suffix = params.toString() ? `?${params.toString()}` : "";
-      return apiGet(`/api/mcp/file-transfers${suffix}`);
-    });
-  }
-);
-
-server.tool(
-  "get_file_transfer",
-  "Read one file transfer record visible to this token. Local temp paths, archive paths, local upload contents, and file contents are never returned.",
-  {
-    transfer_id: z.number().int().positive().describe("Transfer id from list_file_transfers or get_file_transfer_batch."),
-  },
-  async ({ transfer_id }) => {
-    return jsonToolResult(() => apiGet(`/api/mcp/file-transfers/${transfer_id}`));
-  }
-);
-
-server.tool(
-  "list_file_transfer_batches",
-  "List file transfer queues visible to this token. Use get_file_transfer_batch for per-file progress.",
-  {
-    server_id: z.number().int().positive().optional().describe("Optional server id from list_servers."),
-    direction: z.enum(["upload", "download"]).optional().describe("Optional transfer direction."),
-    status: z.enum(["pending_approval", "pending", "running", "paused", "completed", "failed", "canceled"]).optional().describe("Optional transfer status."),
-    limit: z.number().int().positive().max(100).optional().describe("Maximum records to return."),
-    offset: z.number().int().min(0).optional().describe("Pagination offset."),
-  },
-  async ({ server_id, direction, status, limit, offset }) => {
-    return jsonToolResult(() => {
-      const params = new URLSearchParams();
-      if (server_id) params.set("server_id", String(server_id));
-      if (direction) params.set("direction", direction);
-      if (status) params.set("status", status);
-      if (limit) params.set("limit", String(limit));
-      if (offset) params.set("offset", String(offset));
-      const suffix = params.toString() ? `?${params.toString()}` : "";
-      return apiGet(`/api/mcp/file-transfer-batches${suffix}`);
-    });
-  }
-);
-
-server.tool(
-  "get_file_transfer_batch",
-  "Read one file transfer queue with per-file progress. Use save_file_download to write a completed MCP-started download to an explicit local path.",
-  {
-    batch_id: z.number().int().positive().describe("Batch id from list_file_transfer_batches or start_file_download."),
-  },
-  async ({ batch_id }) => {
-    return jsonToolResult(() => apiGet(`/api/mcp/file-transfer-batches/${batch_id}`));
-  }
-);
-
-server.tool(
-  "browse_remote_files",
-  "Browse a remote server directory through AIPermission. Requires always_run permission. This lists remote metadata only and does not read local files.",
-  {
-    server_id: z.number().int().positive().describe("Server id from list_servers."),
-    path: z.string().optional().describe("Absolute remote directory path. Defaults to /."),
-  },
-  async ({ server_id, path }) => {
-    return jsonToolResult(() => apiPost("/api/mcp/file-transfers/browse", {
-      server_id,
-      path: path || "/",
-    }));
-  }
-);
-
-server.tool(
-  "start_file_download",
-  "Start a remote file download queue through AIPermission. always_run starts immediately; approval_required creates a local approval queue. Use get_file_transfer_batch for progress, then save_file_download to write a completed download to the local machine.",
-  {
-    server_id: z.number().int().positive().describe("Server id from list_servers."),
-    remote_paths: z.array(z.string().min(1)).min(1).max(100).describe("Absolute remote file paths to download sequentially."),
-    archive_name: z.string().optional().describe("Optional archive filename for multi-file downloads."),
-  },
-  async ({ server_id, remote_paths, archive_name }) => {
-    return jsonToolResult(() => apiPost("/api/mcp/file-transfers/download-batch", {
-      server_id,
-      remote_paths,
-      archive_name: archive_name || "",
-    }));
-  }
-);
-
-server.tool(
-  "save_file_download",
-  "Save a completed MCP-started download batch to the local filesystem. File contents are written by the local MCP process and are not returned to the AI response.",
-  {
-    batch_id: z.number().int().positive().describe("Completed download batch id from start_file_download or list_file_transfer_batches."),
-    local_path: z.string().min(1).describe("Local file path or existing directory where the completed download should be saved."),
-    overwrite: z.boolean().optional().describe("Whether to overwrite an existing local file. Defaults to false."),
-  },
-  async ({ batch_id, local_path, overwrite }) => {
-    return jsonToolResult(async () => {
-      const batch = await apiGet(`/api/mcp/file-transfer-batches/${batch_id}`);
-      if (batch?.direction !== "download") {
-        throw new Error("batch is not a download");
-      }
-      if (batch?.status !== "completed") {
-        throw new Error(`download batch is not completed; current status is ${batch?.status || "unknown"}`);
-      }
-      const filename = suggestedDownloadFilename(batch);
-      const destination = await resolveLocalDestination(local_path, filename, Boolean(overwrite));
-      const saved = await apiDownloadToFile(`/api/mcp/file-transfer-batches/${batch_id}/download`, destination, Boolean(overwrite));
-      return {
-        status: "saved",
-        batch_id,
-        local_path: saved.path,
-        file_name: path.basename(saved.path),
-        bytes_written: saved.bytes,
-        assistant_hint: "The file was saved by the local MCP process. Do not print file contents unless the user explicitly asks you to inspect the saved file.",
-      };
-    });
-  }
-);
-
-server.tool(
-  "upload_files",
-  "Upload local files to a remote server through AIPermission. always_run starts immediately; approval_required stages the files locally and waits for local approval before writing to the remote server. File contents are read by the local MCP process and are not returned to the AI response.",
-  {
-    server_id: z.number().int().positive().describe("Server id from list_servers."),
-    local_paths: z.array(z.string().min(1)).min(1).max(100).describe("Local file paths to upload sequentially."),
-    remote_dir: z.string().min(1).describe("Absolute remote directory where files should be uploaded."),
-    overwrite: z.boolean().optional().describe("Whether to overwrite existing remote files. Defaults to false."),
-  },
-  async ({ server_id, local_paths, remote_dir, overwrite }) => {
-    return jsonToolResult(async () => {
-      const files = await resolveUploadFiles(local_paths);
-      const batch = await apiPostMultipart("/api/mcp/file-transfers/upload-batch", {
-        server_id: String(server_id),
-        remote_dir,
-        overwrite: overwrite ? "true" : "false",
-      }, files);
-      return batch;
-    });
-  }
-);
-
-server.tool(
-  "pause_file_transfer_batch",
-  "Pause an active file transfer queue started or visible through AIPermission. Requires always_run permission for that server.",
-  {
-    batch_id: z.number().int().positive().describe("Batch id from list_file_transfer_batches or start_file_download."),
-  },
-  async ({ batch_id }) => {
-    return jsonToolResult(() => apiPost(`/api/mcp/file-transfer-batches/${batch_id}/pause`, {}));
-  }
-);
-
-server.tool(
-  "resume_file_transfer_batch",
-  "Resume a paused file transfer queue. Requires always_run permission for that server.",
-  {
-    batch_id: z.number().int().positive().describe("Batch id from list_file_transfer_batches or start_file_download."),
-  },
-  async ({ batch_id }) => {
-    return jsonToolResult(() => apiPost(`/api/mcp/file-transfer-batches/${batch_id}/resume`, {}));
-  }
-);
-
-server.tool(
-  "cancel_file_transfer_batch",
-  "Cancel a pending, running, or paused file transfer queue. Requires always_run permission for that server.",
+  "get_connector_action_request",
+  "Read one connector action request by id. Use this after call_connector_action returns approval_pending or running.",
   {
-    batch_id: z.number().int().positive().describe("Batch id from list_file_transfer_batches or start_file_download."),
+    request_id: z.number().int().positive().describe("Request id returned by call_connector_action."),
   },
-  async ({ batch_id }) => {
-    return jsonToolResult(() => apiPost(`/api/mcp/file-transfer-batches/${batch_id}/cancel`, {}));
+  async ({ request_id }) => {
+    return jsonToolResult(() => apiGet(`/api/mcp/connector-action-requests/${request_id}`));
   }
 );
 
@@ -390,48 +109,12 @@ async function apiPost(path, body) {
   });
 }
 
-async function apiPostMultipart(path, fields, files) {
-  const boundary = `aipermission-${Date.now()}-${Math.random().toString(16).slice(2)}`;
-  return apiRequest(path, {
-    method: "POST",
-    headers: {
-      "Content-Type": `multipart/form-data; boundary=${boundary}`,
-    },
-    body: Readable.from(multipartBody(boundary, fields, files)),
-    duplex: "half",
-    timeoutMs: apiTransferTimeoutMs,
-  });
-}
-
-async function apiDownloadToFile(pathValue, destination, overwrite) {
-  const response = await apiFetch(pathValue, {
-    method: "GET",
-    timeoutMs: apiTransferTimeoutMs,
-  });
-  if (!response.ok) {
-    const text = await response.text();
-    const data = parseResponseBody(text);
-    throw new Error(data?.error || `aipermission API request failed with ${response.status}`);
-  }
-  let bytes = 0;
-  const output = fs.createWriteStream(destination, {
-    flags: overwrite ? "w" : "wx",
-    mode: 0o600,
-  });
-  output.on("bytesWritten", (value) => {
-    bytes = value;
-  });
-  await pipeline(Readable.fromWeb(response.body), output);
-  const stat = await fsp.stat(destination);
-  return { path: destination, bytes: stat.size || bytes };
-}
-
 async function apiRequest(path, options) {
   const response = await apiFetch(path, options);
   const text = await response.text();
   const data = parseResponseBody(text);
   if (!response.ok) {
-    throw new Error(data?.error || `aipermission API request failed with ${response.status}`);
+    throw new Error(data?.error || `AIPermission API request failed with ${response.status}`);
   }
   return data;
 }
@@ -440,24 +123,22 @@ async function apiFetch(path, options) {
   if (!apiToken) {
     throw new Error("AIPERMISSION_API_TOKEN is required.");
   }
-  const timeoutValue = options.timeoutMs || apiTimeoutMs;
-  const timeout = Number.isFinite(timeoutValue) && timeoutValue > 0 ? timeoutValue : 60000;
+  const timeout = Number.isFinite(apiTimeoutMs) && apiTimeoutMs > 0 ? apiTimeoutMs : 60000;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeout);
-  const { timeoutMs: _timeoutMs, ...requestOptions } = options;
   let response;
   try {
     response = await fetch(`${apiUrl}${path}`, {
-      ...requestOptions,
+      ...options,
       signal: controller.signal,
       headers: {
         Authorization: `Bearer ${apiToken}`,
-        ...(requestOptions.headers || {}),
+        ...(options.headers || {}),
       },
     });
   } catch (error) {
     if (error?.name === "AbortError") {
-      throw new Error(`aipermission API request timed out after ${timeout}ms`);
+      throw new Error(`AIPermission API request timed out after ${timeout}ms`);
     }
     throw error;
   } finally {
@@ -473,91 +154,6 @@ function parseResponseBody(text) {
   try {
     return JSON.parse(text);
   } catch {
-    return { error: text.trim() || "Invalid non-JSON response from aipermission gateway." };
-  }
-}
-
-async function resolveUploadFiles(localPaths) {
-  const files = [];
-  const seen = new Set();
-  for (const rawPath of localPaths) {
-    const resolved = expandHome(rawPath);
-    if (seen.has(resolved)) {
-      throw new Error(`duplicate local path: ${resolved}`);
-    }
-    seen.add(resolved);
-    const stat = await fsp.stat(resolved).catch((error) => {
-      throw new Error(`cannot read local file ${resolved}: ${error.message}`);
-    });
-    if (!stat.isFile()) {
-      throw new Error(`local path is not a regular file: ${resolved}`);
-    }
-    files.push({
-      field: "files",
-      path: resolved,
-      name: path.basename(resolved),
-      size: stat.size,
-    });
-  }
-  return files;
-}
-
-async function resolveLocalDestination(localPath, suggestedName, overwrite) {
-  const resolved = expandHome(localPath);
-  const existing = await fsp.stat(resolved).catch((error) => {
-    if (error?.code === "ENOENT") return null;
-    throw error;
-  });
-  if (existing?.isDirectory()) {
-    return resolveLocalDestination(path.join(resolved, suggestedName), suggestedName, overwrite);
-  }
-  if (existing && !overwrite) {
-    throw new Error(`local file already exists: ${resolved}`);
+    return { error: text };
   }
-  const parent = path.dirname(resolved);
-  const parentStat = await fsp.stat(parent).catch((error) => {
-    throw new Error(`local directory does not exist: ${parent}: ${error.message}`);
-  });
-  if (!parentStat.isDirectory()) {
-    throw new Error(`local parent path is not a directory: ${parent}`);
-  }
-  return resolved;
-}
-
-function suggestedDownloadFilename(batch) {
-  if (Array.isArray(batch?.items) && batch.items.length === 1 && batch.items[0]?.file_name) {
-    return safeLocalFilename(batch.items[0].file_name);
-  }
-  if (batch?.archive_name) {
-    return safeLocalFilename(batch.archive_name);
-  }
-  return `aipermission-download-${batch?.id || Date.now()}.zip`;
-}
-
-function safeLocalFilename(value) {
-  const base = path.basename(String(value || "").replaceAll("\0", ""));
-  return base || "aipermission-download";
-}
-
-function expandHome(value) {
-  const text = String(value || "").trim();
-  if (text === "~") return os.homedir();
-  if (text.startsWith("~/")) return path.join(os.homedir(), text.slice(2));
-  return path.resolve(text);
-}
-
-async function* multipartBody(boundary, fields, files) {
-  for (const [name, value] of Object.entries(fields)) {
-    yield Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${escapeMultipartName(name)}"\r\n\r\n${String(value)}\r\n`);
-  }
-  for (const file of files) {
-    yield Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${escapeMultipartName(file.field)}"; filename="${escapeMultipartName(file.name)}"\r\nContent-Type: application/octet-stream\r\n\r\n`);
-    yield* fs.createReadStream(file.path);
-    yield Buffer.from("\r\n");
-  }
-  yield Buffer.from(`--${boundary}--\r\n`);
-}
-
-function escapeMultipartName(value) {
-  return String(value).replaceAll("\\", "\\\\").replaceAll("\"", "\\\"");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipermission/mcp",
-  "version": "0.1.14",
+  "version": "0.2.0",
   "mcpName": "io.github.aipermission/aipermission-mcp",
   "description": "Local-first MCP bridge for the aipermission gateway.",
   "license": "AGPL-3.0-only",

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