@velixir/mcp 0.2.0 → 0.3.0

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
 
@@ -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.0",
   "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).
@@ -46,7 +48,14 @@ async function tarballOf(dir) {
   return Buffer.concat(chunks);
 }
 
-const server = new McpServer({ name: "velixir", version: "0.2.0" });
+// 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.3.0" });
 
 server.tool(
   "deploy",
@@ -146,6 +155,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 +182,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);