@velixir/mcp 0.2.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # @velixir/mcp
 
-Deploy web apps in **any language** to [velixir](https://velixir.net), the European cloud, straight from your AI agent. `deploy` points at a source directory, packs the code, builds it with no Dockerfile, and returns a live URL plus a claim link the human opens to keep the app on a free, card-free account. `logs` fetches the build and runtime logs so the agent can debug what it shipped. No velixir account is needed.
+Deploy web apps in **any language** to [velixir](https://velixir.net), the European cloud, straight from your AI agent. `deploy` points at a source directory, packs the code, builds it with no Dockerfile, and returns a live URL plus a claim link the human opens to keep the app on a free, card-free account. `logs` fetches the build and runtime logs, and `access_logs` the HTTP requests the app served, so the agent can debug what it shipped. No velixir account is needed.
 
 ## Why
 
@@ -39,7 +39,7 @@ Point the editor's MCP settings at the same command (`npx -y @velixir/mcp`).
 | --- | --- | --- |
 | `directory` | yes | Absolute path to the app's source directory. |
 | `name` | no | Short name for the app; becomes part of the URL. |
-| `language` | no | node, python, go, ruby, php, java, elixir, rust, dotnet, deno, fsharp. Auto-detected if omitted. |
+| `language` | no | node, python, go, ruby, php, java, elixir, rust, dotnet, deno, fsharp. Detected from the project files if omitted; pass it when the folder mixes languages. |
 | `port` | no | Only if the app hard-codes a port instead of reading the `PORT` env var. |
 
 It returns the live URL, a claim URL (give this to the user), when the claim window closes, a **deployment ID** (pass it to `logs`), and a status URL to poll.
@@ -57,11 +57,28 @@ Fetch recent build and runtime logs for an app you deployed, so you can debug wi
 
 Works for unclaimed (agent-deployed) apps addressed by deployment ID. Once an app is claimed it moves to the owner's account; use the dashboard or the authenticated API for a claimed app's logs.
 
+## The `access_logs` tool
+
+The HTTP requests an app served, newest first, with a summary of status codes and the slowest request: use it to check the app is getting traffic and to find failing requests.
+
+| Input | Required | Description |
+| --- | --- | --- |
+| `deployment_id` | one of these | From the `deploy` response. Works until the user claims the app. No account needed. |
+| `app_id` | one of these | An app the user owns. Needs `VELIXIR_API_KEY`. |
+| `status` | no | `2xx`, `3xx`, `4xx`, `5xx`, `errors`, or a code like `404`. |
+| `path` | no | Only paths containing this text. |
+| `method` | no | HTTP method, e.g. `POST`. |
+| `since_minutes` | no | Only the last N minutes. |
+| `limit` | no | How many requests (default 50, max 200). |
+
+Once an app is claimed its access logs belong to the owner (they include visitors' IP addresses), so the deployment ID stops working for them; use `app_id` with an API key.
+
 ## Config
 
 | Env var | Default | Description |
 | --- | --- | --- |
 | `VELIXIR_API_URL` | `https://velixir.net` | Override for staging or self-host. |
+| `VELIXIR_API_KEY` | (none) | Optional. Lets `access_logs` read apps the user owns, by `app_id`. Create one at velixir.net under Settings, API keys. |
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velixir/mcp",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Deploy web apps in any language to Velixir (the European cloud) straight from your AI agent: point deploy at a directory for a live URL and claim link, then read logs to debug what you shipped.",
   "type": "module",
   "bin": {

package/src/index.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
-// Velixir MCP server. Exposes two tools:
+// Velixir MCP server. Exposes three tools:
 //   - `deploy`: pack a source directory and POST it to Velixir's account-less deploy
 //     endpoint (POST /api/v1/deploy), returning a live URL + a single-use claim link
 //     the human opens to keep the app on a free, card-free account.
 //   - `logs`: fetch recent build + runtime logs for a deployment by its ID
 //     (GET /api/v1/deploy/{id}/logs), so the agent can debug what it just shipped.
-// No Velixir account is needed for either.
+//   - `access_logs`: the HTTP requests an app served (GET /api/v1/deploy/{id}/access-logs for an
+//     unclaimed deploy, or /api/v1/apps/{id}/access-logs with VELIXIR_API_KEY for an owned app).
+// No Velixir account is needed for deploy, logs, or access_logs on an unclaimed deploy.
 //
 // Zero setup: run with `npx -y @velixir/mcp`. Point VELIXIR_API_URL at a different
 // host for staging/self-host (default https://velixir.net).
@@ -28,25 +30,59 @@ const IGNORED_DIRS = new Set([
   ".venv", "venv", "__pycache__", ".pytest_cache", ".gradle", ".idea", ".vs",
 ]);
 
+// Folders that hold credentials, never source.
+const SECRET_DIRS = new Set([".ssh", ".aws", ".gnupg", ".docker", ".kube", ".azure"]);
+
+// Files that hold secrets. An agent deploys whatever folder it was working in, and that folder
+// usually has the user's .env in it. An unclaimed deploy is public for its whole window, so a
+// secret uploaded here is a secret leaked. Example files (.env.example) are kept: they document
+// variables without values and some apps read them at start-up.
+const SECRET_FILE = [
+  /^\.env$/i,
+  /^\.env\.(?!example$|sample$|template$|dist$|defaults$).+/i,
+  /\.(pem|key|p12|pfx|jks|keystore|kdbx|ppk)$/i,
+  /^id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/i,
+  /^\.(npmrc|pypirc|netrc|git-credentials|pgpass)$/i,
+  /^(credentials|service[-_]?account.*)\.json$/i,
+];
+
+function isSecret(segments) {
+  const file = segments[segments.length - 1] ?? "";
+  return segments.some((seg) => SECRET_DIRS.has(seg)) || SECRET_FILE.some((re) => re.test(file));
+}
+
 async function tarballOf(dir) {
+  const skippedSecrets = [];
   const stream = tarCreate(
     {
       gzip: true,
       cwd: dir,
       portable: true,
       filter: (entryPath) => {
-        const segments = entryPath.split(/[\\/]/).filter(Boolean);
-        return !segments.some((seg) => IGNORED_DIRS.has(seg));
+        const segments = entryPath.split(/[\\/]/).filter((s) => s && s !== ".");
+        if (segments.some((seg) => IGNORED_DIRS.has(seg))) return false;
+        if (isSecret(segments)) {
+          skippedSecrets.push(segments.join("/"));
+          return false;
+        }
+        return true;
       },
     },
     ["."],
   );
   const chunks = [];
   for await (const chunk of stream) chunks.push(chunk);
-  return Buffer.concat(chunks);
+  return { buffer: Buffer.concat(chunks), skippedSecrets };
+}
+
+// Anonymous reads are rate limited per client (a burst, then one every two seconds). Tell the
+// agent to wait instead of handing it a raw 429 it might retry in a tight loop.
+function rateLimited(res) {
+  const wait = Number(res.headers.get("retry-after")) || 60;
+  return { isError: true, content: [{ type: "text", text: `Rate limited by Velixir. Wait about ${wait} seconds before calling this again, and avoid polling in a tight loop.` }] };
 }
 
-const server = new McpServer({ name: "velixir", version: "0.2.0" });
+const server = new McpServer({ name: "velixir", version: "0.3.1" });
 
 server.tool(
   "deploy",
@@ -62,7 +98,7 @@ server.tool(
     language: z
       .string()
       .optional()
-      .describe("Primary language (node, python, go, ruby, php, java, elixir, rust, dotnet, deno, fsharp). Auto-detected from the source if omitted."),
+      .describe("Primary language (node, python, go, ruby, php, java, elixir, rust, dotnet, deno, fsharp). Detected from the project files (package.json, go.mod, *.csproj and so on) if omitted; pass it when the folder mixes languages."),
     port: z
       .number()
       .int()
@@ -76,9 +112,9 @@ server.tool(
       return { isError: true, content: [{ type: "text", text: `Not a directory: ${dir}` }] };
     }
 
-    let tar;
+    let tar, skippedSecrets;
     try {
-      tar = await tarballOf(dir);
+      ({ buffer: tar, skippedSecrets } = await tarballOf(dir));
     } catch (err) {
       return { isError: true, content: [{ type: "text", text: `Could not package the source: ${err?.message ?? err}` }] };
     }
@@ -115,6 +151,9 @@ server.tool(
         ? `Deployment ID: ${data.deployment_id}\n(Use the "logs" tool with this ID to see build/runtime logs and debug if the app doesn't come up.)`
         : null,
       data.status_url ? `Deployment status: ${data.status_url}` : null,
+      skippedSecrets.length
+        ? `Not uploaded, because they look like secrets: ${skippedSecrets.slice(0, 10).join(", ")}${skippedSecrets.length > 10 ? ` and ${skippedSecrets.length - 10} more` : ""}. If the app needs these values, the user can set them as environment variables after claiming it.`
+        : null,
     ].filter(Boolean);
 
     return { content: [{ type: "text", text: lines.join("\n") }] };
@@ -146,6 +185,7 @@ server.tool(
       return { isError: true, content: [{ type: "text", text: `Could not reach Velixir at ${API_URL}: ${err?.message ?? err}` }] };
     }
 
+    if (res.status === 429) return rateLimited(res);
     if (res.status === 404) {
       return { isError: true, content: [{ type: "text", text: `No logs for deployment ${deployment_id}. It may not exist, may already be claimed (use the dashboard for claimed apps), or its unclaimed window may have passed.` }] };
     }
@@ -172,5 +212,100 @@ server.tool(
   },
 );
 
+// Optional: an API key (velixir.net → Settings → API keys) lets `access_logs` read apps the user
+// owns, by app ID. Without it the tool still works for unclaimed deploys, by deployment ID.
+const API_KEY = process.env.VELIXIR_API_KEY || "";
+
+function statusClass(s) {
+  return s >= 500 ? "5xx" : s >= 400 ? "4xx" : s >= 300 ? "3xx" : "2xx";
+}
+
+server.tool(
+  "access_logs",
+  "Read the HTTP access logs for an app on Velixir: one line per request it served (time, status, method, path, duration, size, visitor IP), newest first, with a summary of status codes. Use this to see whether the app is getting traffic and to debug failing requests (filter with status: \"5xx\" or \"errors\"). For an app you deployed with the `deploy` tool, pass its deployment_id (works until the user claims it). For an app the user owns, pass app_id; that needs a VELIXIR_API_KEY in the MCP server's environment.",
+  {
+    deployment_id: z
+      .string()
+      .optional()
+      .describe("The deployment ID returned by the `deploy` tool (unclaimed apps, no account needed)."),
+    app_id: z
+      .string()
+      .optional()
+      .describe("The app's ID, for an app the user owns. Requires VELIXIR_API_KEY."),
+    status: z
+      .string()
+      .optional()
+      .describe("Filter: 2xx, 3xx, 4xx, 5xx, errors (4xx and 5xx), or an exact code like 404."),
+    path: z.string().optional().describe("Filter: only paths containing this text (case-insensitive)."),
+    method: z.string().optional().describe("Filter: HTTP method, e.g. POST."),
+    since_minutes: z.number().int().positive().optional().describe("Only requests from the last N minutes."),
+    limit: z.number().int().optional().describe("How many requests to return (default 50, max 200)."),
+  },
+  async ({ deployment_id, app_id, status, path: pathFilter, method, since_minutes, limit }) => {
+    if (!deployment_id && !app_id) {
+      return { isError: true, content: [{ type: "text", text: "Pass deployment_id (from the deploy tool) or app_id (needs VELIXIR_API_KEY)." }] };
+    }
+    if (!deployment_id && !API_KEY) {
+      return { isError: true, content: [{ type: "text", text: "Reading an owned app by app_id needs VELIXIR_API_KEY set in this MCP server's environment (create one at https://velixir.net under Settings, API keys)." }] };
+    }
+
+    const qs = new URLSearchParams({ limit: String(Math.min(Math.max(limit ?? 50, 1), 200)) });
+    if (status) qs.set("status", status);
+    if (pathFilter) qs.set("path", pathFilter);
+    if (method) qs.set("method", method);
+    if (since_minutes) qs.set("after", new Date(Date.now() - since_minutes * 60_000).toISOString());
+
+    const url = deployment_id
+      ? `${API_URL}/api/v1/deploy/${encodeURIComponent(deployment_id)}/access-logs?${qs}`
+      : `${API_URL}/api/v1/apps/${encodeURIComponent(app_id)}/access-logs?${qs}`;
+    const headers = deployment_id || !API_KEY ? {} : { "X-Api-Key": API_KEY };
+
+    let res, body;
+    try {
+      res = await fetch(url, { headers });
+      body = await res.text();
+    } catch (err) {
+      return { isError: true, content: [{ type: "text", text: `Could not reach Velixir at ${API_URL}: ${err?.message ?? err}` }] };
+    }
+
+    if (res.status === 429) return rateLimited(res);
+    if (res.status === 404) {
+      const why = deployment_id
+        ? `No unclaimed deployment ${deployment_id}. Once the user claims the app, read its access logs by app_id with a VELIXIR_API_KEY, or in the dashboard.`
+        : `App ${app_id} not found, or this API key can't read it.`;
+      return { isError: true, content: [{ type: "text", text: why }] };
+    }
+    if (res.status === 401 || res.status === 403) {
+      return { isError: true, content: [{ type: "text", text: "VELIXIR_API_KEY was rejected. Check the key in this MCP server's environment." }] };
+    }
+    if (!res.ok) {
+      let msg = body;
+      try { msg = JSON.parse(body).error ?? body; } catch { /* plain text */ }
+      return { isError: true, content: [{ type: "text", text: `Could not fetch access logs (HTTP ${res.status}): ${msg}` }] };
+    }
+
+    let data;
+    try { data = JSON.parse(body); } catch { data = {}; }
+    const entries = Array.isArray(data.entries) ? data.entries : [];
+    if (!entries.length) {
+      return { content: [{ type: "text", text: "No requests match yet. If the app was just deployed, open its URL once and try again: lines arrive within a few seconds." }] };
+    }
+
+    const counts = {};
+    for (const e of entries) counts[statusClass(e.status)] = (counts[statusClass(e.status)] ?? 0) + 1;
+    const slowest = entries.reduce((a, b) => (b.requestTimeMs > a.requestTimeMs ? b : a));
+    const out = [
+      `${entries.length} request(s), newest first. Status: ${Object.entries(counts).map(([k, v]) => `${k} ${v}`).join(", ")}.`,
+      `Slowest: ${slowest.method} ${slowest.path} took ${slowest.requestTimeMs} ms (status ${slowest.status}).`,
+      "",
+      ...entries.map(e =>
+        `${e.timestamp} ${e.status} ${e.method} ${e.path}${e.query ? "?" + e.query : ""} ${e.requestTimeMs}ms ${e.bytesSent}B ip=${e.clientIp}` +
+        (e.status >= 400 && e.userAgent ? ` ua="${e.userAgent}"` : "")),
+    ];
+    if (data.nextBefore) out.push("", `More, older requests exist; narrow with since_minutes, status or path.`);
+    return { content: [{ type: "text", text: out.join("\n") }] };
+  },
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);