@aipermission/mcp 0.1.13 → 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,12 +94,28 @@ 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
 
-MIT
+AGPL-3.0-only from v0.1.14 onward.
+
+Versions up to and including v0.1.13 were released under MIT and remain
+available under their original MIT 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.