@spacelr/mcp 0.0.6 → 0.0.8

package/dist/index.mjs

@@ -5,21 +5,89 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // libs/mcp-server/src/config.ts
+import * as crypto from "crypto";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 var REFRESH_TIMEOUT_MS = 1e4;
-function getCredentialsFile() {
-  const home = os.homedir();
+var SPACELR_CONFIG_FILENAME = "spacelr.json";
+function getGlobalCredentialsFile() {
+  const home = process.env["HOME"] ?? process.env["USERPROFILE"] ?? os.homedir();
   return path.join(home, ".spacelr", "credentials.json");
 }
-function readStoredCredentials() {
+function findSpacelrConfigPath(startDir) {
+  let dir = startDir ?? process.cwd();
+  while (true) {
+    const candidate = path.join(dir, SPACELR_CONFIG_FILENAME);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function resolveCredentialsFile() {
+  const configPath = findSpacelrConfigPath();
+  if (configPath) {
+    const projectDir = path.dirname(configPath);
+    return {
+      path: path.join(projectDir, ".spacelr", "credentials.json"),
+      scope: "project",
+      projectDir
+    };
+  }
+  return { path: getGlobalCredentialsFile(), scope: "global" };
+}
+function ensureGitignored(projectDir) {
+  const gitignorePath = path.join(projectDir, ".gitignore");
+  const entry = ".spacelr/";
+  const matchesExisting = (line) => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) return false;
+    return trimmed === ".spacelr" || trimmed === ".spacelr/" || trimmed === ".spacelr/*" || trimmed === ".spacelr/**" || trimmed === ".spacelr/credentials.json" || // Leading-slash forms anchor the pattern to the repo root
+    trimmed === "/.spacelr" || trimmed === "/.spacelr/" || trimmed === "/.spacelr/*" || trimmed === "/.spacelr/**" || trimmed === "/.spacelr/credentials.json";
+  };
+  const hasNegation = (line) => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) return false;
+    return trimmed.startsWith("!") && trimmed.includes(".spacelr");
+  };
+  let content = "";
+  let existed = false;
   try {
-    const file = getCredentialsFile();
-    if (!fs.existsSync(file)) return null;
-    const content = fs.readFileSync(file, "utf-8");
+    content = fs.readFileSync(gitignorePath, "utf-8");
+    existed = true;
+  } catch (err) {
+    if (err.code !== "ENOENT") return { safe: true };
+  }
+  const lines = content.split(/\r?\n/);
+  if (lines.some(hasNegation)) {
+    const alreadyHasMatch = lines.some(matchesExisting);
+    console.error(
+      alreadyHasMatch ? ".gitignore already contains .spacelr/ but ALSO contains a negation pattern that un-ignores credentials. Remove the negation or store credentials globally." : ".gitignore contains a negation pattern for .spacelr/ \u2014 refusing to write credentials safety entry. Remove the negation or store credentials globally."
+    );
+    return { safe: false };
+  }
+  if (lines.some(matchesExisting)) return { safe: true };
+  const needsLeadingNewline = existed && content.length > 0 && !content.endsWith("\n");
+  const newContent = (existed ? content : "") + (needsLeadingNewline ? "\n" : "") + entry + "\n";
+  try {
+    writeFileAtomic(gitignorePath, newContent, 420);
+    console.error(`Added ${entry} to .gitignore (credentials must never be committed)`);
+    return { safe: true };
+  } catch {
+    return { safe: true };
+  }
+}
+function readCredentialsFromDisk(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
     const parsed = JSON.parse(content);
-    if (typeof parsed !== "object" || parsed === null || typeof parsed.accessToken !== "string" || !Number.isFinite(parsed.expiresAt) || typeof parsed.apiUrl !== "string") {
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const obj = parsed;
+    if (typeof obj["accessToken"] !== "string" || obj["accessToken"].length === 0 || !Number.isFinite(obj["expiresAt"]) || typeof obj["apiUrl"] !== "string" || obj["apiUrl"].length === 0) {
+      return null;
+    }
+    if ("refreshToken" in obj && typeof obj["refreshToken"] !== "string") {
       return null;
     }
     return parsed;
@@ -27,15 +95,72 @@ function readStoredCredentials() {
     return null;
   }
 }
-function storeCredentials(credentials) {
-  const file = getCredentialsFile();
-  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 448 });
-  fs.writeFileSync(file, JSON.stringify(credentials, null, 2), {
-    mode: 384
-  });
+function readStoredCredentials() {
+  return readStoredCredentialsWithLocation()?.credentials ?? null;
 }
-async function refreshToken(credentials) {
-  if (!credentials.refreshToken || !credentials.apiUrl) return null;
+function readStoredCredentialsWithLocation() {
+  const primary = resolveCredentialsFile();
+  const fromPrimary = readCredentialsFromDisk(primary.path);
+  if (fromPrimary) return { credentials: fromPrimary, location: primary };
+  if (primary.scope === "project") {
+    const globalPath = getGlobalCredentialsFile();
+    const fromGlobal = readCredentialsFromDisk(globalPath);
+    if (fromGlobal) {
+      return {
+        credentials: fromGlobal,
+        location: { path: globalPath, scope: "global" }
+      };
+    }
+  }
+  return null;
+}
+function writeFileAtomic(filePath, data, mode) {
+  const tmpPath = `${filePath}.tmp.${process.pid}.${crypto.randomBytes(6).toString("hex")}`;
+  try {
+    fs.writeFileSync(tmpPath, data, { mode });
+    fs.renameSync(tmpPath, filePath);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch {
+    }
+    throw err;
+  }
+}
+function storeCredentials(credentials, location) {
+  if (location.scope === "project" && location.projectDir) {
+    const { safe } = ensureGitignored(location.projectDir);
+    if (!safe) {
+      throw new Error(
+        "Refusing to write project-local credentials: .gitignore contains a negation pattern that would un-ignore .spacelr/."
+      );
+    }
+  }
+  const dir = path.dirname(location.path);
+  fs.mkdirSync(dir, { recursive: true, mode: 448 });
+  try {
+    fs.chmodSync(dir, 448);
+  } catch {
+  }
+  writeFileAtomic(location.path, JSON.stringify(credentials, null, 2), 384);
+}
+function isTokenStillValid(credentials) {
+  return Date.now() < credentials.expiresAt - 6e4;
+}
+async function refreshToken(credentials, sourceLocation) {
+  if (!credentials.refreshToken) return null;
+  try {
+    const parsed = new URL(credentials.apiUrl);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      console.error(
+        `Refusing to refresh against non-http(s) URL: ${parsed.protocol}`
+      );
+      return null;
+    }
+  } catch {
+    console.error("Refusing to refresh: stored apiUrl is not a valid URL");
+    return null;
+  }
   const apiUrl = credentials.apiUrl.replace(/\/+$/, "");
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), REFRESH_TIMEOUT_MS);
@@ -49,6 +174,13 @@ async function refreshToken(credentials) {
     });
     if (!response.ok) {
       console.error(`Token refresh failed (HTTP ${response.status})`);
+      if (response.status === 401) {
+        const fresh = readCredentialsFromDisk(sourceLocation.path);
+        if (fresh && (fresh.accessToken !== credentials.accessToken || fresh.refreshToken !== credentials.refreshToken) && isTokenStillValid(fresh)) {
+          console.error("Using credentials refreshed by concurrent process");
+          return fresh.accessToken;
+        }
+      }
       return null;
     }
     const data = await response.json();
@@ -56,13 +188,15 @@ async function refreshToken(credentials) {
       console.error("Token refresh returned unexpected response shape");
       return null;
     }
+    const expiresInRaw = data.expires_in;
+    const expiresIn = typeof expiresInRaw === "number" && Number.isFinite(expiresInRaw) && expiresInRaw > 0 ? expiresInRaw : 3600;
     const updated = {
       accessToken: data.access_token,
       refreshToken: data.refresh_token ?? credentials.refreshToken,
-      expiresAt: Date.now() + (data.expires_in ?? 3600) * 1e3,
+      expiresAt: Date.now() + expiresIn * 1e3,
       apiUrl: credentials.apiUrl
     };
-    storeCredentials(updated);
+    storeCredentials(updated, sourceLocation);
     console.error("Token refreshed successfully");
     return data.access_token;
   } catch (err) {
@@ -79,14 +213,19 @@ async function refreshToken(credentials) {
 async function resolveAuthToken(forceRefresh = false) {
   const envToken = process.env["SPACELR_AUTH_TOKEN"];
   if (envToken) return envToken;
-  const credentials = readStoredCredentials();
-  if (!credentials) return null;
-  const isExpired = Date.now() >= credentials.expiresAt - 6e4;
-  if (!forceRefresh && !isExpired) return credentials.accessToken;
-  return refreshToken(credentials);
+  const loaded = readStoredCredentialsWithLocation();
+  if (!loaded) return null;
+  return resolveAuthTokenFromLoaded(loaded, forceRefresh);
+}
+async function resolveAuthTokenFromLoaded(loaded, forceRefresh) {
+  const { credentials, location } = loaded;
+  if (!forceRefresh && isTokenStillValid(credentials)) {
+    return credentials.accessToken;
+  }
+  return refreshToken(credentials, location);
 }
 function warnIfInsecureUrl(url) {
-  if (url.startsWith("http://") && !url.includes("localhost") && !/^http:\/\/(127\.|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|0\.0\.0\.0|(\[::1\]))(\/|:|$)/.test(url)) {
+  if (url.startsWith("http://") && !url.includes("localhost") && !/^http:\/\/(127\.|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|(\[::1\])|::1)(\/|:|$)/.test(url)) {
     console.error(`Warning: API URL uses plain HTTP (${url}). Credentials will be transmitted unencrypted.`);
   }
 }
@@ -123,20 +262,24 @@ function resolveApiBaseUrl() {
   try {
     const credentials = readStoredCredentials();
     return resolveApiUrl(credentials);
-  } catch {
+  } catch (err) {
+    console.error(
+      `Failed to resolve admin API URL: ${err instanceof Error ? err.message : String(err)}`
+    );
     return null;
   }
 }
 async function loadConfig() {
-  const credentials = readStoredCredentials();
-  const authToken = await resolveAuthToken();
+  const envToken = process.env["SPACELR_AUTH_TOKEN"];
+  const loaded = readStoredCredentialsWithLocation();
+  const authToken = envToken ?? (loaded ? await resolveAuthTokenFromLoaded(loaded, false) : null);
   if (!authToken) {
     throw new Error(
       'No auth token found. Either set SPACELR_AUTH_TOKEN or run "spacelr login" first.'
     );
   }
   return {
-    apiBaseUrl: resolveApiUrl(credentials),
+    apiBaseUrl: resolveApiUrl(loaded?.credentials ?? null),
     authToken,
     clientId: process.env["SPACELR_CLIENT_ID"],
     projectId: process.env["SPACELR_PROJECT_ID"]
@@ -145,6 +288,7 @@ async function loadConfig() {
 
 // libs/mcp-server/src/api-client.ts
 var REQUEST_TIMEOUT_MS = 3e4;
+var UPLOAD_TIMEOUT_MS = 12e4;
 var ApiError = class extends Error {
   constructor(status, statusText, responseBody) {
     const truncated = responseBody.length > 500 ? responseBody.slice(0, 500) + "..." : responseBody;
@@ -183,6 +327,77 @@ var ApiClient = class {
   async delete(path2, opts) {
     return this.requestWithRetry("DELETE", path2, opts);
   }
+  /**
+   * Upload a file as multipart/form-data.
+   * Includes the same 401-retry logic as regular requests.
+   *
+   * @param path     - API path (e.g. `/projects/:id/functions/:id/deploy`)
+   * @param buffer   - Raw file content
+   * @param filename - Name sent in the Content-Disposition header (e.g. "bundle.zip")
+   */
+  async uploadFile(path2, buffer, filename) {
+    try {
+      return await this.sendMultipart(path2, buffer, filename);
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 401) {
+        const currentToken = this.headers["Authorization"];
+        let newToken = await this.refreshAuthToken();
+        const newBaseUrl = resolveApiBaseUrl();
+        if (newBaseUrl && newBaseUrl !== this.baseUrl) {
+          this.baseUrl = newBaseUrl;
+        }
+        if (newToken && `Bearer ${newToken}` === currentToken) {
+          newToken = await resolveAuthToken(true);
+        }
+        if (newToken && `Bearer ${newToken}` !== currentToken) {
+          this.headers["Authorization"] = `Bearer ${newToken}`;
+          return this.sendMultipart(path2, buffer, filename);
+        }
+      }
+      throw error;
+    }
+  }
+  async sendMultipart(path2, buffer, filename) {
+    const boundary = `----MCP${Date.now()}${Math.random().toString(36).slice(2)}`;
+    const header = Buffer.from(
+      `--${boundary}\r
+Content-Disposition: form-data; name="file"; filename="${filename}"\r
+Content-Type: application/zip\r
+\r
+`
+    );
+    const footer = Buffer.from(`\r
+--${boundary}--\r
+`);
+    const body = Buffer.concat([header, buffer, footer]);
+    const url = `${this.baseUrl}${path2}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), UPLOAD_TIMEOUT_MS);
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          ...this.headers,
+          "Content-Type": `multipart/form-data; boundary=${boundary}`,
+          "Content-Length": String(body.length)
+        },
+        body,
+        signal: controller.signal
+      });
+      const text = await response.text();
+      if (!response.ok) {
+        throw new ApiError(response.status, response.statusText, text);
+      }
+      if (!text) return void 0;
+      try {
+        return JSON.parse(text);
+      } catch {
+        return text;
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
   async refreshAuthToken(force = false) {
     if (!this.refreshPromise) {
       this.refreshPromise = resolveAuthToken(force).finally(() => {
@@ -1344,6 +1559,104 @@ function registerDatabaseTools(server, api) {
 
 // libs/mcp-server/src/tools/hosting.ts
 import { z as z5 } from "zod";
+
+// libs/mcp-server/src/zip.ts
+import { deflateRawSync } from "zlib";
+var ZipBuilder = class {
+  constructor() {
+    this.files = [];
+  }
+  /**
+   * Add a text file to the archive.
+   *
+   * @param name - File path inside the ZIP (e.g. "index.js" or "src/utils.ts")
+   * @param content - UTF-8 text content of the file
+   */
+  addFile(name, content) {
+    const nameBuffer = Buffer.from(name, "utf-8");
+    const contentBuffer = Buffer.from(content, "utf-8");
+    const compressed = deflateRawSync(contentBuffer, { level: 9 });
+    const crc32 = computeCrc32(contentBuffer);
+    this.files.push({
+      name: nameBuffer,
+      content: contentBuffer,
+      compressed,
+      crc32
+    });
+  }
+  /** Generate the complete ZIP archive as a Buffer. */
+  toBuffer() {
+    const localHeaders = [];
+    const centralHeaders = [];
+    let offset = 0;
+    for (const file of this.files) {
+      const local = Buffer.alloc(30);
+      local.writeUInt32LE(67324752, 0);
+      local.writeUInt16LE(20, 4);
+      local.writeUInt16LE(0, 6);
+      local.writeUInt16LE(8, 8);
+      local.writeUInt16LE(0, 10);
+      local.writeUInt16LE(0, 12);
+      local.writeUInt32LE(file.crc32, 14);
+      local.writeUInt32LE(file.compressed.length, 18);
+      local.writeUInt32LE(file.content.length, 22);
+      local.writeUInt16LE(file.name.length, 26);
+      local.writeUInt16LE(0, 28);
+      localHeaders.push(local, file.name, file.compressed);
+      const central = Buffer.alloc(46);
+      central.writeUInt32LE(33639248, 0);
+      central.writeUInt16LE(20, 4);
+      central.writeUInt16LE(20, 6);
+      central.writeUInt16LE(0, 8);
+      central.writeUInt16LE(8, 10);
+      central.writeUInt16LE(0, 12);
+      central.writeUInt16LE(0, 14);
+      central.writeUInt32LE(file.crc32, 16);
+      central.writeUInt32LE(file.compressed.length, 20);
+      central.writeUInt32LE(file.content.length, 24);
+      central.writeUInt16LE(file.name.length, 28);
+      central.writeUInt16LE(0, 30);
+      central.writeUInt16LE(0, 32);
+      central.writeUInt16LE(0, 34);
+      central.writeUInt16LE(0, 36);
+      central.writeUInt32LE(0, 38);
+      central.writeUInt32LE(offset, 42);
+      centralHeaders.push(central, file.name);
+      offset += 30 + file.name.length + file.compressed.length;
+    }
+    const centralDirSize = centralHeaders.reduce((sum, b) => sum + b.length, 0);
+    const eocd = Buffer.alloc(22);
+    eocd.writeUInt32LE(101010256, 0);
+    eocd.writeUInt16LE(0, 4);
+    eocd.writeUInt16LE(0, 6);
+    eocd.writeUInt16LE(this.files.length, 8);
+    eocd.writeUInt16LE(this.files.length, 10);
+    eocd.writeUInt32LE(centralDirSize, 12);
+    eocd.writeUInt32LE(offset, 16);
+    eocd.writeUInt16LE(0, 20);
+    return Buffer.concat([...localHeaders, ...centralHeaders, eocd]);
+  }
+};
+var crcTable = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) {
+      c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+    }
+    table[n] = c;
+  }
+  return table;
+})();
+function computeCrc32(data) {
+  let crc = 4294967295;
+  for (let i = 0; i < data.length; i++) {
+    crc = crcTable[(crc ^ data[i]) & 255] ^ crc >>> 8;
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+
+// libs/mcp-server/src/tools/hosting.ts
 function registerHostingTools(server, api) {
   server.registerTool(
     "hosting_deployments_list",
@@ -1424,6 +1737,57 @@ function registerHostingTools(server, api) {
       }
     }
   );
+  server.registerTool(
+    "hosting_deployments_upload",
+    {
+      description: 'Upload files to an existing hosting deployment. Accepts a record of filename \u2192 content, bundles them into a ZIP archive, and uploads it.\n\nTypical workflow:\n  1. hosting_deployments_create  \u2192 get deploymentId\n  2. hosting_deployments_upload  \u2192 upload site files\n  3. hosting_deployments_activate \u2192 make the deployment live\n\nExample:\n  files: { "index.html": "<!DOCTYPE html>...", "style.css": "body { ... }", "app.js": "..." }',
+      inputSchema: {
+        projectId: z5.string().describe("Project ID"),
+        deploymentId: z5.string().describe("Deployment ID (from hosting_deployments_create)"),
+        files: z5.record(z5.string(), z5.string()).describe(
+          'Map of filename \u2192 file content. Keys are file paths inside the archive (e.g. "index.html", "assets/style.css"). Values are the UTF-8 file contents.'
+        )
+      }
+    },
+    async ({ projectId, deploymentId, files }) => {
+      try {
+        const fileEntries = Object.entries(files);
+        if (fileEntries.length === 0) {
+          return {
+            content: [{ type: "text", text: "files must contain at least one entry" }],
+            isError: true
+          };
+        }
+        const zip = new ZipBuilder();
+        for (const [name, content] of fileEntries) {
+          zip.addFile(name, content);
+        }
+        const zipBuffer = zip.toBuffer();
+        const result = await api.uploadFile(
+          `/hosting/projects/${encodeURIComponent(projectId)}/deployments/${encodeURIComponent(deploymentId)}/upload`,
+          zipBuffer,
+          "site.zip"
+        );
+        const response = {
+          success: true,
+          filesUploaded: fileEntries.map(([name]) => name),
+          bundleSizeBytes: zipBuffer.length
+        };
+        if (result && typeof result === "object") {
+          Object.assign(response, result);
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text", text: `Failed to upload deployment: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
   server.registerTool(
     "hosting_deployments_activate",
     {
@@ -2138,6 +2502,70 @@ function registerFunctionTools(server, api) {
       }
     }
   );
+  server.registerTool(
+    "functions_deploy",
+    {
+      description: `Deploy code to a serverless function. Accepts one or more files as a record of filename \u2192 content. The files are bundled into a ZIP archive and uploaded. Use this after creating a function with functions_create.
+
+Example \u2013 single file:
+  files: { "index.js": "export default async function handler(ctx) { ... }" }
+
+Example \u2013 multiple files:
+  files: { "index.js": "import {hello} from './lib.js'; ...", "lib.js": "export const hello = () => ..." }`,
+      inputSchema: {
+        projectId: z7.string().describe("Project ID"),
+        functionId: z7.string().describe("Function ID (from functions_create or functions_list)"),
+        files: z7.record(z7.string(), z7.string()).describe(
+          'Map of filename \u2192 file content. Keys are file paths inside the bundle (e.g. "index.js", "src/helper.ts"). Values are the UTF-8 source code.'
+        ),
+        entryPoint: z7.string().max(255).optional().describe('Entry point file inside the bundle (default: "index.js"). Must match a key in files.')
+      }
+    },
+    async ({ projectId, functionId, files, entryPoint }) => {
+      try {
+        const fileEntries = Object.entries(files);
+        if (fileEntries.length === 0) {
+          return {
+            content: [{ type: "text", text: "files must contain at least one entry" }],
+            isError: true
+          };
+        }
+        if (entryPoint) {
+          await api.patch(
+            `/projects/${encodeURIComponent(projectId)}/functions/${encodeURIComponent(functionId)}`,
+            { body: { entryPoint } }
+          );
+        }
+        const zip = new ZipBuilder();
+        for (const [name, content] of fileEntries) {
+          zip.addFile(name, content);
+        }
+        const zipBuffer = zip.toBuffer();
+        const result = await api.uploadFile(
+          `/projects/${encodeURIComponent(projectId)}/functions/${encodeURIComponent(functionId)}/deploy`,
+          zipBuffer,
+          "bundle.zip"
+        );
+        const response = {
+          success: true,
+          filesDeployed: fileEntries.map(([name]) => name),
+          bundleSizeBytes: zipBuffer.length
+        };
+        if (result && typeof result === "object") {
+          Object.assign(response, result);
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text", text: `Failed to deploy function: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
   server.registerTool(
     "functions_deployments_list",
     {
@@ -3679,7 +4107,10 @@ function registerFunctionPrompts(server) {
                 "   Optional: cronExpression for scheduled execution",
                 "",
                 "2. WRITE the code:",
-                "   Create an index.js file. Available APIs inside the sandbox:",
+                "   Create an index.js file with plain JavaScript (ES2022).",
+                "   The runtime is an isolated V8 sandbox \u2014 NOT Node.js.",
+                "   No require/import, no Node.js built-ins (fs, path, crypto, Buffer, process).",
+                "   Top-level await is supported. Available APIs inside the sandbox:",
                 "",
                 "   - console.log/warn/error/info() \u2014 captured to execution logs",
                 "   - await fetch(url, options) \u2014 HTTP client (10s timeout, 5MB limit)",
@@ -3692,6 +4123,10 @@ function registerFunctionPrompts(server) {
                 "   - await spacelr.email.send/sendRaw() \u2014 send template or raw emails",
                 "   - await spacelr.notifications.send/sendMany() \u2014 push notifications",
                 "",
+                "   Trigger context globals (depending on trigger type):",
+                "   - event: { type, data, timestamp } \u2014 for event-triggered executions",
+                "   - payload: { ... } \u2014 for webhook-triggered executions (the POST body)",
+                "",
                 "   IMPORTANT: Top-level await is supported. No imports/require available.",
                 "",
                 "3. IF USING spacelr.db:",
@@ -3700,9 +4135,11 @@ function registerFunctionPrompts(server) {
                 '   Without rules, inserts will fail with "Rule denied".',
                 "",
                 "4. DEPLOY the code:",
-                "   Zip the file(s) and upload via the CLI:",
-                "   spacelr functions deploy ./my-function --name " + name,
-                "   Or use the admin API: POST /projects/{projectId}/functions/{id}/deploy",
+                "   Use the functions_deploy tool to upload code directly:",
+                '   functions_deploy({ projectId, functionId, files: { "index.js": "..." } })',
+                "   This bundles the files into a ZIP and uploads them automatically.",
+                '   You can deploy multiple files: { "index.js": "...", "lib.js": "..." }',
+                "   Optionally set entryPoint if your main file is not index.js.",
                 "",
                 "5. TRIGGER:",
                 "   Functions support multiple trigger types:",
@@ -3745,6 +4182,31 @@ function registerFunctionPrompts(server) {
               text: [
                 "Show me the complete API reference for the Spacelr function sandbox.",
                 "",
+                "\u2550\u2550\u2550 RUNTIME ENVIRONMENT \u2550\u2550\u2550",
+                "Functions run in an isolated V8 sandbox (via isolated-vm), NOT in Node.js.",
+                "This means:",
+                "  - No require() or import statements \u2014 all APIs are pre-injected globals",
+                "  - No Node.js built-ins (fs, path, crypto, Buffer, process, etc.)",
+                "  - No setTimeout, setInterval, or Promise.race",
+                "  - No Function constructor, eval(), WebAssembly, or Proxy",
+                "  - Top-level await IS supported (code runs in an async IIFE)",
+                "  - Standard JS built-ins work: JSON, Math, Date, Array, Map, Set, RegExp, etc.",
+                "  - Use the built-in fetch() for HTTP calls (not node-fetch or axios)",
+                "  - Use env.get() for secrets (not process.env)",
+                "  - Use kv.get/set() for persistence across executions (not file system)",
+                "",
+                "Write plain JavaScript (ES2022). The code structure is simple:",
+                "  // Top-level code runs immediately",
+                '  const data = await fetch("https://api.example.com/data");',
+                "  const json = JSON.parse(data.body);",
+                '  console.log("Fetched", json.length, "items");',
+                "",
+                "\u2550\u2550\u2550 TRIGGER CONTEXT \u2550\u2550\u2550",
+                "Depending on how the function was triggered, these globals may be available:",
+                "  - event: { type, data, timestamp } \u2014 for event-triggered executions",
+                "  - payload: { ... } \u2014 for webhook-triggered executions (the POST body)",
+                "For manual and cron triggers, neither is set.",
+                "",
                 "\u2550\u2550\u2550 CONSOLE \u2550\u2550\u2550",
                 "console.log(...args)    \u2014 log level",
                 "console.info(...args)   \u2014 info level",
@@ -3777,11 +4239,26 @@ function registerFunctionPrompts(server) {
                 "",
                 "\u2550\u2550\u2550 DATABASE \u2550\u2550\u2550",
                 "const docs = await spacelr.db.collection(name).find(filter?, options?)",
-                "  options: { sort, limit, offset }",
+                '  filter: MongoDB-style query (e.g. { status: "active", age: { $gt: 18 } })',
+                "  options: { sort: { createdAt: -1 }, limit: 10, offset: 0 }",
+                "  returns: array of documents",
+                "",
                 "await spacelr.db.collection(name).insertOne(doc)",
+                '  doc: plain object (e.g. { name: "Max", email: "max@example.com" })',
+                "  returns: the inserted document with _id",
+                "",
                 "await spacelr.db.collection(name).insertMany(docs)",
+                "  docs: array of objects",
+                "  returns: array of inserted documents",
+                "",
+                "Collection names: alphanumeric + underscore only, max 128 chars.",
                 "Scoped to the function's project. Requires database rules to be set first.",
                 "",
+                "Example \u2014 read and write:",
+                '  const users = await spacelr.db.collection("users").find({ status: "active" }, { limit: 5 });',
+                '  console.log("Found", users.length, "active users");',
+                '  await spacelr.db.collection("logs").insertOne({ action: "check", count: users.length, at: new Date().toISOString() });',
+                "",
                 "\u2550\u2550\u2550 STORAGE \u2550\u2550\u2550",
                 "await spacelr.storage.list(options?) \u2192 FileInfo[]",
                 "await spacelr.storage.getInfo(fileId) \u2192 FileInfo",