@aipermission/mcp 0.2.15 → 0.2.17

package/README.md

@@ -8,8 +8,8 @@ credentials, or other connector secrets.
 
 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, Postgres, Redis, RabbitMQ,
-Docker, and Kubernetes are built-in connectors that use the same
+to host the gateway for LAN or internet users. SSH, Postgres, ClickHouse,
+Redis / Valkey, RabbitMQ, S3, Docker, and Kubernetes are built-in connectors that use the same
 target/profile/action permission model as future connectors.
 
 ![AIPermission demo: AI operates through approval-based connector access](https://raw.githubusercontent.com/aipermission/aipermission/main/docs/assets/demo/aipermission-demo.gif)
@@ -60,9 +60,13 @@ The generated MCP config contains a bearer token. Keep it private. For project-l
 - `get_connector_actions`
 - `call_connector_action`
 - `get_connector_action_request`
+- `list_vault_items`
+- `call_vault_action`
+- `get_vault_action_request`
+- `cancel_vault_action_request`
 
-All integration work goes through connector targets. SSH, Postgres, Redis,
-RabbitMQ, Docker, Kubernetes, and future connectors share the same model: target,
+All integration work goes through connector targets. SSH, Postgres, ClickHouse,
+Redis / Valkey, RabbitMQ, S3, Docker, Kubernetes, and future connectors share the same model: target,
 credential profile, connector action, token action permission, approval,
 history, and audit.
 
@@ -72,6 +76,19 @@ from disabled projects are omitted from discovery and rejected on direct calls;
 their saved action grants are preserved for later re-enablement. Projects are
 not multi-user or hosted RBAC.
 
+Project Vault stores project-scoped secret values in the encrypted local
+database. MCP can list non-secret item metadata only when the token has
+`vault.metadata.read`. Secret generation and supported console-session
+application use explicit Disabled, Prompt, or Always project capabilities.
+Prompt creates a local approval request; Always executes immediately through
+the same tracked context-validation path. Poll `get_vault_action_request` for
+pending requests, which expire after 15 minutes and may be declined, canceled,
+expired, or stale. Raw values are never returned by this package.
+Session item input is strict: only `item_id`, `source_project_id`, and optional
+`replace_existing` are accepted. Lease expiry ends MCP authorization for the
+exact session but cannot guarantee that a remote process erased inherited
+environment values.
+
 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
@@ -82,9 +99,12 @@ table, and bounded read-only query actions. Postgres targets can connect
 directly from the gateway or over an SSH connector profile when the database is
 reachable only from a remote server.
 
-For Redis, call `get_connector_actions(target_ref)` to discover bounded key
-browser actions such as `scan_keys`, `get_key`, `set_string`, `expire_key`, and
-`delete_keys`.
+For Redis or Valkey, call `get_connector_actions(target_ref)` to discover
+bounded key-browser actions such as `scan_keys`, `get_key`, `set_string`,
+`expire_key`, and `delete_keys`. Both products intentionally use the `redis`
+connector kind and target-ref prefix; no separate Valkey MCP tool family is
+required. The current connector uses RESP2 against one configured endpoint and
+does not provide Cluster or Sentinel routing.
 
 For RabbitMQ, call `get_connector_actions(target_ref)` to discover queue
 browser actions such as `overview`, `list_vhosts`, `list_queues`, `get_queue`,

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

@@ -187,3 +187,33 @@ files or environment files.
 
 If a secret appears in output, do not repeat it. Summarize the finding and ask
 the operator how to rotate or redact it.
+
+## Project Vault Practice
+
+Use Project Vault only through its dedicated tools:
+
+1. Call `list_vault_items(project_ref)` to discover names and non-secret
+   metadata. Never ask the gateway to reveal values.
+2. Use `call_vault_action` with `generate_item` only when the operator asked for
+   a new secret. Use a stable, unique `idempotency_key`. Send `tags` as a string
+   array, `shared_project_ids` as an integer array, and `usage_notes` as an
+   array of `{location, notes}` objects containing non-secret context.
+3. Use `restart_session_with_environment` only for the exact target/profile and
+   item assignments needed for the task. This closes the target profile's
+   current console session and starts a replacement session; do not use it
+   during unrelated interactive work without warning the operator. Each item
+   entry may contain only `item_id`, `source_project_id`, and optional
+   `replace_existing`. Cross-project use is allowed only when the token can
+   access both the target and source projects.
+4. If the response is `approval_pending`, wait for local approval and poll
+   `get_vault_action_request`. Prompt approvals expire after 15 minutes. An
+   Always grant may return a terminal result immediately.
+5. Use `cancel_vault_action_request` when an approval is no longer needed.
+
+Vault actions follow the configured Disabled, Prompt, or Always project
+capability. A completed response contains metadata, never the secret. Do not
+try to recover a value by printing the environment. Prompt and Always sessions
+can still send a secret elsewhere, so use the narrowest item set and
+least-privilege service credentials.
+Lease expiry ends agent access to the exact session; it does not guarantee that
+the remote shell or detached child processes erased inherited values.

package/dist/server.js

@@ -10,6 +10,7 @@ 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 { callVaultActionSchema, listVaultItemsSchema, vaultActionRequestSchema } from "./vault-tools.js";
 import { normalizeLocalAPIURL } from "./local-url.js";
 import { jsonToolResult } from "./results.js";
 
@@ -90,6 +91,53 @@ server.tool(
   }
 );
 
+server.tool(
+  "list_vault_items",
+  "List secret names and bounded non-secret Vault metadata for projects this token can read. Secret values are never returned.",
+  listVaultItemsSchema,
+  async ({ project_ref }) => {
+    return jsonToolResult(() => {
+      const params = new URLSearchParams();
+      if (project_ref) params.set("project_ref", project_ref);
+      const query = params.toString();
+      return apiGet(`/api/mcp/vault-items${query ? `?${query}` : ""}`);
+    });
+  }
+);
+
+server.tool(
+  "call_vault_action",
+  "Run a Vault action under the configured project capability. Prompt waits for local approval; Always executes immediately through the same tracked request path. generate_item input accepts name, secret_type, generator_kind, provider, environment, description, expires_at, expiry_warning_days, tags (string array), usage_notes (array of {location, notes}), and shared_project_ids (integer array). restart_session_with_environment input requires target_ref and items with item_id, source_project_id, and optional replace_existing. Never include raw secret values.",
+  callVaultActionSchema,
+  async ({ project_ref, action_name, input, reason, idempotency_key }) => {
+    return jsonToolResult(() => apiPost("/api/mcp/vault-actions/call", {
+      project_ref,
+      action_name,
+      input,
+      reason,
+      idempotency_key,
+    }));
+  }
+);
+
+server.tool(
+  "get_vault_action_request",
+  "Read one Vault action request after call_vault_action returns approval_pending. Responses never include secret values.",
+  vaultActionRequestSchema,
+  async ({ request_id }) => {
+    return jsonToolResult(() => apiGet(`/api/mcp/vault-action-requests/${request_id}`));
+  }
+);
+
+server.tool(
+  "cancel_vault_action_request",
+  "Cancel one approval_pending Vault action request owned by this token. Running or terminal requests cannot be canceled.",
+  vaultActionRequestSchema,
+  async ({ request_id }) => {
+    return jsonToolResult(() => apiPost(`/api/mcp/vault-action-requests/${request_id}/cancel`, {}));
+  }
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);
 

package/dist/vault-tools.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+export const listVaultItemsSchema = {
+  project_ref: z.string().min(1).optional().describe("Optional project id or slug. Omit to list every readable project."),
+};
+
+export const callVaultActionSchema = {
+  project_ref: z.string().min(1).describe("Owning project id or slug."),
+  action_name: z.enum(["generate_item", "restart_session_with_environment"]),
+  input: z.record(z.unknown()).describe("Action input. Never include raw secret values."),
+  reason: z.string().min(1).describe("Why this Vault action is needed."),
+  idempotency_key: z.string().min(1).max(128).describe("Caller-stable key used to prevent duplicate action requests."),
+};
+
+export const vaultActionRequestSchema = {
+  request_id: z.number().int().positive().describe("Request id returned by call_vault_action."),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipermission/mcp",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "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.2.15",
+  "version": "0.2.17",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@aipermission/mcp",
-      "version": "0.2.15",
+      "version": "0.2.17",
       "transport": {
         "type": "stdio"
       }