@aipermission/mcp 0.1.1 → 0.1.7

package/README.md

@@ -55,9 +55,29 @@ The generated MCP config contains a bearer token. Keep it private. For project-l
 - `list_requests`
 - `read_console`
 - `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.
 
+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.
+
 ## Operator Skill
 
 Install the optional AIPermission operator instructions for your AI client:
@@ -77,7 +97,7 @@ Supported clients:
 - `gemini`: `GEMINI.md`
 - `custom`: prints portable Markdown to stdout
 
-These instructions teach the agent how to poll `approval_pending` and `running` requests, read live console output, write short reasons, 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, 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.
 
 ## Security Boundary
 

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

@@ -91,6 +91,37 @@ The command is still running; reading console output before next step.
 
 When a response includes `user_note`, treat it as live operator guidance. Apply it before continuing.
 
+## File Transfer Flow
+
+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:

package/dist/server.js

@@ -6,6 +6,12 @@ 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 { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -15,10 +21,11 @@ import { jsonToolResult } from "./results.js";
 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.1",
+  version: "0.1.2",
 });
 
 server.tool(
@@ -111,6 +118,195 @@ server.tool(
   }
 );
 
+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.",
+  {
+    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}/cancel`, {}));
+  }
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);
 
@@ -123,26 +319,76 @@ async function apiGet(path) {
 async function apiPost(path, body) {
   return apiRequest(path, {
     method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
     body: JSON.stringify(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}`);
+  }
+  return data;
+}
+
+async function apiFetch(path, options) {
   if (!apiToken) {
     throw new Error("AIPERMISSION_API_TOKEN is required.");
   }
-  const timeout = Number.isFinite(apiTimeoutMs) && apiTimeoutMs > 0 ? apiTimeoutMs : 60000;
+  const timeoutValue = options.timeoutMs || apiTimeoutMs;
+  const timeout = Number.isFinite(timeoutValue) && timeoutValue > 0 ? timeoutValue : 60000;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeout);
+  const { timeoutMs: _timeoutMs, ...requestOptions } = options;
   let response;
   try {
     response = await fetch(`${apiUrl}${path}`, {
-      ...options,
+      ...requestOptions,
       signal: controller.signal,
       headers: {
-        "Content-Type": "application/json",
         Authorization: `Bearer ${apiToken}`,
-        ...(options.headers || {}),
+        ...(requestOptions.headers || {}),
       },
     });
   } catch (error) {
@@ -153,12 +399,7 @@ async function apiRequest(path, options) {
   } finally {
     clearTimeout(timer);
   }
-  const text = await response.text();
-  const data = parseResponseBody(text);
-  if (!response.ok) {
-    throw new Error(data?.error || `aipermission API request failed with ${response.status}`);
-  }
-  return data;
+  return response;
 }
 
 function parseResponseBody(text) {
@@ -171,3 +412,88 @@ function parseResponseBody(text) {
     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}`);
+  }
+  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.1",
+  "version": "0.1.7",
   "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.1",
+  "version": "0.1.7",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@aipermission/mcp",
-      "version": "0.1.1",
+      "version": "0.1.7",
       "transport": {
         "type": "stdio"
       }