@mcpjam/inspector 3.12.3 → 3.12.5

package/README.md

@@ -78,32 +78,40 @@ Network access requires **Docker**. A native (`npx`) install binds to
 `127.0.0.1` (localhost only) and has no bind-address override, so it is not
 reachable from another machine. The Docker image binds `0.0.0.0`, so it is.
 
-For security, the inspector only issues its session token to `localhost`. When
-you open a Docker install from another machine (e.g. `http://192.168.1.50:6274`),
-it will otherwise dead-end on an authentication error. To allow a specific host,
-set `MCPJAM_ALLOWED_HOSTS` to that hostname (or a comma-separated list; wildcards
-like `*.example.com` are supported), and publish the port on your network
-interface (drop the `127.0.0.1:` prefix from `-p`):
+Open the private link printed in the terminal (or `docker logs <container>`) to
+sign this browser in. A plain address displays instructions to open that link.
+The browser remembers access for this origin until the Inspector restarts.
+Keep the link private: it grants control of the local Inspector and its tools.
+
+For another computer, set `MCPJAM_ALLOWED_HOSTS` to the hostname or IP you use,
+and publish the port on your network interface (this exposes the port on all interfaces):
 
 ```bash
 docker run -p 6274:6274 -e MCPJAM_ALLOWED_HOSTS=192.168.1.50 mcpjam/mcp-inspector:local
 ```
 
-For an IPv6 host, bracket the entry: `MCPJAM_ALLOWED_HOSTS=[fd00::50]`.
-
-If you use a **wildcard** entry (e.g. `MCPJAM_ALLOWED_HOSTS=*.lan`), also set
-`MCPJAM_ALLOW_WILDCARD_ORIGINS=true`. Wildcards deliver the session token on
-their own, but for security the request-origin check ignores wildcard hosts
-unless you opt in with that variable — without it, API calls still 403. A
-single exact host (like the IP above) needs no extra flag.
-
-Only add hosts you trust. Allowlisting a host does more than expose the session
-token: the same host is accepted as a request Origin, which also reaches the
-local shell and agent-browser tools that are enabled by default in self-hosted
-mode. Any client that can reach an allowlisted host can obtain the session token
-and drive those tools. Set `MCPJAM_LOCAL_COMPUTER_ENABLED=false` and
-`MCPJAM_LOCAL_BROWSER_ENABLED=false` if you don't want that. Tunnel/relay domains
-are never allowed, even if listed.
+Alternatively, keep the remote port bound to loopback and use
+`ssh -L 6274:127.0.0.1:6274 user@host`; open the terminal link at the forwarded address.
+
+Open the printed Network link, or paste the link/code into the access screen at
+that address. If ports are remapped, keep the `#token=…` fragment and change the
+address. `MCPJAM_INSPECTOR_FRONTEND_URL=http://devbox.local:8080` sets the printed
+browser address explicitly. Cross-tab continuation works only on the same origin.
+
+For IPv6, bracket the allowlist entry: `MCPJAM_ALLOWED_HOSTS=[fd00::50]`.
+Wildcards such as `*.lan` additionally require
+`MCPJAM_ALLOW_WILDCARD_ORIGINS=true` for the request-origin check. The allowlist
+never grants credentials by itself.
+
+Optionally set `MCPJAM_SESSION_TOKEN` to a strong random URL-safe secret (at least
+24 characters) to keep a link across restarts. Generate one with
+`node -e "process.stdout.write(require('crypto').randomBytes(24).toString('base64url'))"`.
+The default is a new random credential on each launch. Local CLI attachment reads
+a same-user discovery file under `~/.mcpjam/inspector/`, readable only by its owner;
+update `@mcpjam/cli` alongside the Inspector.
+
+Set `MCPJAM_LOCAL_COMPUTER_ENABLED=false` and
+`MCPJAM_LOCAL_BROWSER_ENABLED=false` to disable the local computer/browser tools.
 
 # Key features
 

package/bin/access-link.mjs

@@ -0,0 +1,53 @@
+import { randomBytes } from "node:crypto";
+
+export function createLaunchToken(env = process.env) {
+  if (env.VITE_MCPJAM_HOSTED_MODE === "true") return undefined;
+  const token =
+    env.MCPJAM_SESSION_TOKEN ?? randomBytes(24).toString("base64url");
+  if (!/^[A-Za-z0-9_-]{24,}$/.test(token))
+    throw new Error(
+      "MCPJAM_SESSION_TOKEN must contain at least 24 URL-safe letters, digits, underscores or hyphens",
+    );
+  return token;
+}
+export function createAccessLink(base, token, tab) {
+  const url = new URL(base);
+  if (token)
+    url.hash = new URLSearchParams({
+      token,
+      ...(tab ? { tab } : {}),
+    }).toString();
+  else if (tab) url.hash = tab;
+  return url.href;
+}
+export function networkAccessLinks(base, token, allowedHosts = "", tab) {
+  return allowedHosts
+    .split(",")
+    .map((host) => host.trim())
+    .filter((host) => host && !host.includes("*"))
+    .flatMap((host) => {
+      try {
+        // Configuration names hosts, not schemes, paths or credentials.
+        const authority = new URL(`http://${host}`);
+        if (
+          authority.username ||
+          authority.password ||
+          authority.pathname !== "/" ||
+          authority.search ||
+          authority.hash
+        )
+          return [];
+        const url = new URL(base);
+        url.hostname = authority.hostname;
+        if (authority.port) url.port = authority.port;
+        return [createAccessLink(url.href, token, tab)];
+      } catch {
+        return [];
+      }
+    });
+}
+
+/** CLI-owned launches open their own link; redirected launcher logs stay credential-free. */
+export function shouldPrintAccessLink(token, env = process.env) {
+  return Boolean(token) && env.MCPJAM_INSPECTOR_SUPPRESS_AUTO_OPEN !== "1";
+}

package/bin/start.js

@@ -7,6 +7,12 @@ import { createServer, createConnection } from "net";
 import { execSync } from "child_process";
 import { existsSync, readFileSync } from "fs";
 import open from "open";
+import {
+  createLaunchToken,
+  shouldPrintAccessLink,
+  createAccessLink,
+  networkAccessLinks,
+} from "./access-link.mjs";
 import { launchWorkspaceCandidate } from "./launch-workspace.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -1003,13 +1009,17 @@ async function main() {
     // to become the installed package's root and the server would otherwise
     // have no way back to where the user actually was.
     const launchWorkspace = launchWorkspaceCandidate({ projectRoot });
+    const launchToken = createLaunchToken();
     const serverProcess = spawn("node", [distServerPath], {
       env: {
         ...process.env,
+        ...(launchToken ? { MCPJAM_SESSION_TOKEN: launchToken } : {}),
         MCPJAM_INSPECTOR_PARENT_PID: process.pid.toString(),
         NODE_ENV: "production",
         PORT: PORT,
-        ...(launchWorkspace ? { MCPJAM_LAUNCH_WORKSPACE: launchWorkspace } : {}),
+        ...(launchWorkspace
+          ? { MCPJAM_LAUNCH_WORKSPACE: launchWorkspace }
+          : {}),
         ...(verboseLogs && { VERBOSE_LOGS: "true" }),
       },
       cwd: projectRoot,
@@ -1095,21 +1105,44 @@ async function main() {
         logWarning(
           `Server did not become ready within 30s. Please visit ${apiBaseUrl} manually.`,
         );
-      } else if (!cancelled && openBrowser) {
-        let url = await resolveBrowserBaseUrl(apiBaseUrl);
-
-        // Append initial tab hash if specified
-        if (initialTab) {
-          url = `${url}#${initialTab}`;
+      } else if (!cancelled) {
+        const base = await resolveBrowserBaseUrl(apiBaseUrl);
+        const url = createAccessLink(base, launchToken, initialTab);
+        const docker = process.env.DOCKER_CONTAINER === "true";
+        let opened = false;
+        if (openBrowser && !docker) {
+          try {
+            await open(url);
+            opened = true;
+          } catch {
+            logWarning("Could not open your browser automatically.");
+          }
         }
-
-        try {
-          await open(url);
-          logSuccess(`🌐 Browser opened at ${url}`);
-        } catch (error) {
-          logWarning(
-            `Could not open browser automatically. Please visit ${url} manually.`,
+        if (shouldPrintAccessLink(launchToken)) {
+          logSuccess("MCPJam Inspector is ready");
+          log("");
+          const printLink = (label, link) => {
+            log(`  ${colors.green}➜ ${colors.bright}${label}${colors.reset}`);
+            log(link, colors.primary);
+          };
+          printLink(docker ? "Open MCPJam" : "Local", url);
+          for (const link of networkAccessLinks(
+            base,
+            launchToken,
+            process.env.MCPJAM_ALLOWED_HOSTS,
+            initialTab,
+          ))
+            printLink("Network", link);
+          log("");
+          log(
+            opened
+              ? "Opened in your browser. Keep this link private: it signs a browser in."
+              : "Open this link in your browser. Keep it private: it signs a browser in.",
           );
+          if (docker)
+            log(
+              "Using another port or computer? Keep the #token=… part and change the address.",
+            );
         }
       }
     }