autorouter-mcp 0.2.4 → 0.2.5

package/README.md

@@ -366,6 +366,7 @@ autorouter restore --target claude                  # undo the most recent adopt
 
 autorouter login                                    # which servers need a grant
 autorouter login remote-server                      # authorize one (opens a browser)
+autorouter login remote-server --device             # headless: enter a code elsewhere
 autorouter logout remote-server                     # forget a stored grant
 ```
 
@@ -391,6 +392,35 @@ fixed port (33418, `--port` or `$AUTOROUTER_OAUTH_PORT` to change it) because th
 redirect URI is baked into the registration a provider stores — a grant obtained
 on one port cannot be refreshed from another.
 
+### Headless machines
+
+The browser flow cannot work over SSH: it binds a loopback listener and expects
+a browser on the same host to redirect into it. Two flows replace it, and on a
+box with no display autorouter picks one of them by itself rather than timing
+out waiting for a browser that was never going to open.
+
+```sh
+autorouter login remote-server --device   # RFC 8628: enter a code on your phone
+autorouter login remote-server --manual   # paste the redirect URL back
+```
+
+`--device` is the better one where the provider offers it. Nothing has to reach
+back into the machine: it prints a short code and a URL, you enter them in a
+browser on any other device, and the headless side polls until you are done.
+Detection is the `device_authorization_endpoint` in the provider's metadata.
+
+`--manual` is the fallback for providers that do not implement RFC 8628. It
+prints the authorization URL, you open it elsewhere, and the browser is then
+redirected to `http://localhost:33418/callback`, which will not load — nothing
+is listening. That is expected: copy the URL out of the address bar and paste it
+back. Pasting the whole URL is worth preferring over just the code, because the
+`state` in it is what proves the code came from the login you started.
+
+Neither flow binds a port. A device login registers a client that also works for
+a later browser login from the same machine, so nothing has to be redone if the
+box grows a display. Set `AUTOROUTER_ASSUME_HEADLESS=1` to force the detection
+on a machine where it guesses wrong.
+
 ### Choosing permissions
 
 A dynamically registered client may default to every scope the provider

package/dist/cli.js

@@ -18556,6 +18556,7 @@ async function clearAuth(server) {
 async function hasAuth(server) {
   return Boolean((await readAuth(server)).tokens?.access_token);
 }
+var DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
 var CLIENT_METADATA = {
   client_name: "autorouter",
   client_uri: "https://github.com/rileywebb/autorouter",
@@ -18583,6 +18584,12 @@ class FileTokenStore {
   get clientMetadata() {
     return { ...CLIENT_METADATA, redirect_uris: [this.redirectUrl] };
   }
+  get deviceClientMetadata() {
+    return {
+      ...this.clientMetadata,
+      grant_types: [...CLIENT_METADATA.grant_types, DEVICE_GRANT_TYPE]
+    };
+  }
   async state() {
     const value = randomUUID();
     await writeAuth(this.server, { state: value });
@@ -22063,6 +22070,166 @@ function truncate2(s, max) {
 import { createServer } from "node:http";
 import { spawn as spawn3 } from "node:child_process";
 
+// src/cli/device.ts
+function deviceEndpoint(metadata) {
+  const endpoint = metadata?.device_authorization_endpoint;
+  return typeof endpoint === "string" && endpoint ? endpoint : undefined;
+}
+function looksHeadless(env = process.env) {
+  if (env.AUTOROUTER_ASSUME_HEADLESS === "1")
+    return true;
+  if (process.platform === "darwin" || process.platform === "win32")
+    return false;
+  return !env.DISPLAY && !env.WAYLAND_DISPLAY;
+}
+function authenticateClient(client, metadata, headers, params) {
+  const method = selectClientAuthMethod(client, metadata?.token_endpoint_auth_methods_supported ?? []);
+  const secret = "client_secret" in client ? client.client_secret : undefined;
+  if (method === "client_secret_basic" && secret) {
+    headers.set("Authorization", `Basic ${btoa(`${client.client_id}:${secret}`)}`);
+    return;
+  }
+  params.set("client_id", client.client_id);
+  if (method === "client_secret_post" && secret)
+    params.set("client_secret", secret);
+}
+async function errorCode(res) {
+  const text = await res.text().catch(() => "");
+  try {
+    const body = JSON.parse(text);
+    if (body.error)
+      return { code: body.error, description: body.error_description };
+  } catch {}
+  return { code: `http_${res.status}`, description: text.slice(0, 200) || undefined };
+}
+async function runDeviceFlow(opts) {
+  const log = opts.log ?? ((line) => console.log(line));
+  const doFetch = opts.fetchFn ?? fetch;
+  const info = opts.info ?? await discoverOAuthServerInfo(opts.url, { fetchFn: doFetch });
+  const metadata = info.authorizationServerMetadata;
+  const endpoint = deviceEndpoint(metadata);
+  if (!endpoint) {
+    return {
+      ok: false,
+      message: `${opts.server} does not advertise a device authorization endpoint, so RFC 8628 is not ` + `available for it.
+` + `  Authorize from a machine with a browser, or use the paste-the-code flow:
+` + `    autorouter login ${opts.server} --manual`
+    };
+  }
+  const store = new FileTokenStore(opts.server, opts.port ?? CALLBACK_PORT, () => {
+    throw new Error("unreachable: the device grant does not redirect");
+  });
+  const resource = await selectResourceURL(opts.url, store, info.resourceMetadata);
+  let client = (await readAuth(opts.server)).clientInformation;
+  const registeredForDevice = (await readAuth(opts.server)).deviceClient === true;
+  if (!client || !registeredForDevice) {
+    if (!metadata?.registration_endpoint && !client) {
+      return {
+        ok: false,
+        message: `${opts.server} supports the device grant but not dynamic client registration, so it ` + `needs an OAuth app you register yourself.
+` + `  Then: autorouter login ${opts.server} --device --client-id <id> [--client-secret <secret>]`
+      };
+    }
+    if (metadata?.registration_endpoint) {
+      try {
+        client = await registerClient(info.authorizationServerUrl, {
+          metadata,
+          clientMetadata: store.deviceClientMetadata,
+          scope: opts.scope,
+          fetchFn: doFetch
+        });
+        await writeAuth(opts.server, { clientInformation: client, deviceClient: true });
+      } catch (err) {
+        if (!client) {
+          return { ok: false, message: `${opts.server}: client registration failed — ${message(err)}` };
+        }
+      }
+    }
+  }
+  if (!client)
+    return { ok: false, message: `${opts.server}: no OAuth client available.` };
+  const deviceParams = new URLSearchParams;
+  const deviceHeaders = new Headers({ "content-type": "application/x-www-form-urlencoded" });
+  authenticateClient(client, metadata, deviceHeaders, deviceParams);
+  if (opts.scope)
+    deviceParams.set("scope", opts.scope);
+  if (resource)
+    deviceParams.set("resource", resource.href);
+  const deviceRes = await doFetch(endpoint, {
+    method: "POST",
+    headers: deviceHeaders,
+    body: deviceParams
+  });
+  if (!deviceRes.ok) {
+    const { code, description } = await errorCode(deviceRes);
+    return {
+      ok: false,
+      message: `${opts.server}: the device authorization request was refused (${code})` + (description ? ` — ${description}` : "") + (code === "unauthorized_client" ? `
+  The provider may not allow this grant for dynamically registered clients.
+` + `  Try: autorouter login ${opts.server} --manual` : "")
+    };
+  }
+  const grant = await deviceRes.json();
+  if (!grant.device_code || !grant.user_code || !grant.verification_uri) {
+    return { ok: false, message: `${opts.server}: the device authorization response was incomplete.` };
+  }
+  log(`
+To authorize ${opts.server}, open this on any device with a browser:
+
+` + `  ${grant.verification_uri_complete ?? grant.verification_uri}
+
+` + `  and enter the code:  ${grant.user_code}
+` + (grant.verification_uri_complete ? `  (that link has the code filled in; the plain URL is ${grant.verification_uri})
+` : "") + `
+Waiting for you to finish${grant.expires_in ? ` — the code expires in ${Math.round(grant.expires_in / 60)} min` : ""}…`);
+  let intervalMs = opts.pollIntervalMs ?? (grant.interval ?? 5) * 1000;
+  const bumpMs = opts.pollIntervalMs ? 0 : 5000;
+  const deadline = Date.now() + (grant.expires_in ?? 900) * 1000;
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+    const params = new URLSearchParams;
+    const headers = new Headers({ "content-type": "application/x-www-form-urlencoded" });
+    authenticateClient(client, metadata, headers, params);
+    params.set("grant_type", DEVICE_GRANT_TYPE);
+    params.set("device_code", grant.device_code);
+    if (resource)
+      params.set("resource", resource.href);
+    const res = await doFetch(metadata.token_endpoint, { method: "POST", headers, body: params });
+    if (res.ok) {
+      const tokens = await res.json();
+      await writeAuth(opts.server, {
+        tokens,
+        ...opts.scope ? { requestedScope: opts.scope } : {}
+      });
+      return { ok: true, message: "", grantedScope: tokens.scope ?? opts.scope };
+    }
+    const { code, description } = await errorCode(res);
+    if (code === "authorization_pending")
+      continue;
+    if (code === "slow_down") {
+      intervalMs += bumpMs;
+      continue;
+    }
+    if (code === "access_denied") {
+      return { ok: false, message: `${opts.server}: authorization was denied.` };
+    }
+    if (code === "expired_token") {
+      return { ok: false, message: `${opts.server}: the code expired before it was entered. Run the command again.` };
+    }
+    return {
+      ok: false,
+      message: `${opts.server}: token request failed (${code})${description ? ` — ${description}` : ""}`
+    };
+  }
+  return { ok: false, message: `${opts.server}: timed out waiting for the code to be entered.` };
+}
+function sleep(ms) {
+  return new Promise((res) => setTimeout(res, ms));
+}
+function message(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
 // src/config/scopes.ts
 var MUTATING = /(^|[:._\-\/])(write|admin|manage|delete|destroy|create|update|modify|readwrite|rw|full|all)([:._\-\/]|$)/i;
 function isReadOnlyScope(scope) {
@@ -22110,6 +22277,9 @@ async function runLogin(opts) {
   Scopes: ${previousScope.split(/\s+/).join(", ")}` : "")
     };
   }
+  if (opts.device && opts.manual) {
+    return { ok: false, message: "--device and --manual are different flows; pick one." };
+  }
   const port = opts.port ?? CALLBACK_PORT;
   if (opts.clientId) {
     await setClientInformation(entry.name, {
@@ -22117,12 +22287,67 @@ async function runLogin(opts) {
       ...opts.clientSecret ? { client_secret: opts.clientSecret } : {}
     });
   }
-  return await authorize(entry, port, {
+  const want = {
     scopes: opts.scopes,
     readOnly: opts.readOnly,
     allScopes: opts.allScopes,
     previous: previousScope
+  };
+  const mode = await resolveMode(entry, opts);
+  if (mode.kind === "device") {
+    const chosen = chooseScopes(mode.advertised, want);
+    if ("error" in chosen)
+      return { ok: false, message: `${entry.name}: ${chosen.error}` };
+    if (mode.announce)
+      console.log(mode.announce);
+    const result = await runDeviceFlow({
+      server: entry.name,
+      url: entry.url,
+      scope: chosen.scope,
+      info: mode.info,
+      port
+    });
+    if (!result.ok)
+      return result;
+    return {
+      ok: true,
+      message: `${entry.name}: authorized.` + (result.grantedScope ? `
+  ${summarizeScopes(result.grantedScope)}` : "")
+    };
+  }
+  if (mode.announce)
+    console.log(mode.announce);
+  return await authorize(entry, port, want, mode.kind);
+}
+async function resolveMode(entry, opts) {
+  if (opts.manual)
+    return { kind: "manual" };
+  if (opts.device) {
+    const info = await discoverOAuthServerInfo(entry.url).catch(() => {
+      return;
+    });
+    return { kind: "device", info, advertised: advertisedFrom(info) };
+  }
+  if (!looksHeadless())
+    return { kind: "browser" };
+  const info = await discoverOAuthServerInfo(entry.url).catch(() => {
+    return;
   });
+  if (info && deviceEndpoint(info.authorizationServerMetadata)) {
+    return {
+      kind: "device",
+      info,
+      advertised: advertisedFrom(info),
+      announce: `No display detected, so this is using the device flow instead of opening a browser.
+` + `  Pass --manual to paste a redirect URL instead, or --port with X11/SSH forwarding to
+` + `  use the browser flow anyway.`
+    };
+  }
+  return {
+    kind: "manual",
+    announce: `No display detected, and ${entry.name} does not offer the device flow — falling back to
+` + `  the paste-the-code flow. Open the URL below on any machine with a browser.`
+  };
 }
 async function describeScopes(entry) {
   const advertised = await advertisedScopes(entry.url);
@@ -22144,6 +22369,9 @@ ${lines.join(`
 ` : "") + `  autorouter login ${entry.name} --scopes "${(ro.length ? ro : advertised).slice(0, 2).join(",")}"`
   };
 }
+function advertisedFrom(info) {
+  return requestableScopes(info?.resourceMetadata?.scopes_supported, info?.authorizationServerMetadata?.scopes_supported);
+}
 async function advertisedScopes(url) {
   try {
     const info = await discoverOAuthServerInfo(url);
@@ -22152,7 +22380,7 @@ async function advertisedScopes(url) {
     return [];
   }
 }
-async function authorize(entry, port, want) {
+async function authorize(entry, port, want, mode = "browser") {
   let pendingState;
   let resolveCode;
   let rejectCode;
@@ -22174,12 +22402,14 @@ async function authorize(entry, port, want) {
     else
       resolveCode(code);
   });
-  await new Promise((res, rej) => {
-    server.once("error", rej);
-    server.listen(port, "127.0.0.1", res);
-  }).catch((err) => {
-    throw err.code === "EADDRINUSE" ? new Error(`Port ${port} is in use. Pass --port to pick another (it must stay the same across logins).`) : err;
-  });
+  if (mode === "browser") {
+    await new Promise((res, rej) => {
+      server.once("error", rej);
+      server.listen(port, "127.0.0.1", res);
+    }).catch((err) => {
+      throw err.code === "EADDRINUSE" ? new Error(`Port ${port} is in use. Pass --port to pick another (it must stay the same across logins).`) : err;
+    });
+  }
   let advertised = [];
   let canRegister = true;
   try {
@@ -22203,6 +22433,18 @@ async function authorize(entry, port, want) {
     };
   }
   const provider = new FileTokenStore(entry.name, port, (url) => {
+    if (mode === "manual") {
+      console.log(`
+Open this on any machine with a browser and authorize ${entry.name}:
+
+  ${url}
+
+` + `The browser will then be redirected to ${`http://localhost:${port}/callback`}, which
+` + `will not load — that is expected, nothing is listening there. Copy the full URL out of
+` + `the address bar and paste it below.
+`);
+      return;
+    }
     console.log(`
 Opening your browser to authorize ${entry.name}:
   ${url}
@@ -22215,7 +22457,7 @@ Opening your browser to authorize ${entry.name}:
       return { ok: true, message: `${entry.name}: already authorized (existing grant is still valid).` };
     }
     pendingState = (await readAuth(entry.name)).state;
-    const code = await withTimeout2(codePromise, 5 * 60000, "waiting for the browser callback");
+    const code = mode === "manual" ? await readPastedCode(pendingState) : await withTimeout2(codePromise, 5 * 60000, "waiting for the browser callback");
     const result = await auth(provider, { serverUrl: entry.url, authorizationCode: code, scope });
     if (result !== "AUTHORIZED") {
       return { ok: false, message: `${entry.name}: token exchange did not complete (${result}).` };
@@ -22246,6 +22488,40 @@ function evaluateCallback(params, expectedState) {
     failure: description ? `${error ?? "error"}: ${description}` : error ?? "no code returned"
   };
 }
+async function readPastedCode(expectedState) {
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    for (let attempt = 0;attempt < 3; attempt++) {
+      const answer = (await rl.question("Paste the full redirect URL (or just the code): ")).trim();
+      if (!answer)
+        continue;
+      const parsed = parsePastedRedirect(answer, expectedState);
+      if ("code" in parsed)
+        return parsed.code;
+      console.log(`  ${parsed.error}`);
+    }
+    throw new Error("no usable authorization code was pasted");
+  } finally {
+    rl.close();
+  }
+}
+function parsePastedRedirect(input, expectedState) {
+  const trimmed = input.trim();
+  if (!/^https?:\/\//i.test(trimmed)) {
+    if (/[\s?&]/.test(trimmed))
+      return { error: "that does not look like a URL or a code — try again" };
+    return { code: trimmed };
+  }
+  let params;
+  try {
+    params = new URL(trimmed).searchParams;
+  } catch {
+    return { error: "that URL could not be parsed — paste the whole address bar" };
+  }
+  const { code, failure } = evaluateCallback(params, expectedState);
+  return code ? { code } : { error: failure ?? "no code in that URL" };
+}
 function openBrowser(url) {
   const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
   try {
@@ -22289,7 +22565,7 @@ function chooseScopes(advertised, want) {
     if (!ro.length) {
       return {
         error: `no read-only scopes are offered (available: ${advertised.join(", ")}).
-` + `  Authorize with full access, or pick explicitly with --scopes.`
+  Authorize with full access, or pick explicitly with --scopes.`
       };
     }
     return { scope: ro.join(" ") };
@@ -22306,11 +22582,11 @@ function summarizeScopes(scope, limit = 6) {
   if (all.length <= limit) {
     return `scope: ${all.join(", ")}${writes.length ? "" : "  (read-only)"}`;
   }
-  return `scope: ${all.length} granted, ${writes.length} of them write ` + `(${writes.slice(0, 3).join(", ") || "none"}${writes.length > 3 ? ", …" : ""})`;
+  return `scope: ${all.length} granted, ${writes.length} of them write (${writes.slice(0, 3).join(", ") || "none"}${writes.length > 3 ? ", …" : ""})`;
 }
 
 // src/cli.ts
-var VERSION2 = "0.2.4";
+var VERSION2 = "0.2.5";
 var USAGE = `autorouter — one search tool instead of every tool
 
   autorouter serve                     Run as an MCP server over stdio (default)
@@ -22320,7 +22596,8 @@ var USAGE = `autorouter — one search tool instead of every tool
   autorouter list [--kind K]           List everything in the catalog
   autorouter reindex                   Rebuild the catalog now
   autorouter doctor                    Show what is reachable and what it saves
-  autorouter login [server]            Authorize an OAuth server (opens a browser);
+  autorouter login [server]            Authorize an OAuth server (opens a browser,
+                                       or prints a code on a headless box);
                                        with no argument, lists what needs one
   autorouter logout <server>           Forget a stored grant
   autorouter add <name> --url URL      Register a server with the router directly
@@ -22360,6 +22637,10 @@ Options
                  any narrowing the previous grant carried
   --scopes S     login: request exactly these scopes (comma or space separated)
   --list-scopes  login: show what the server offers, authorize nothing
+  --device       login: RFC 8628 — print a code to enter on another device and
+                 poll for the result. No browser or open port needed here.
+  --manual       login: print the authorization URL, then read the redirect you
+                 paste back. Works where the provider has no device endpoint.
 
 \`add\` registers behind the router, so a new server never enters your context.
 Servers added to a harness the normal way (\`claude mcp add\`) are moved behind
@@ -22481,6 +22762,8 @@ async function cmdLogin(server, flags) {
       };
     }));
     console.log(`Usage: autorouter login <server> [--read-only | --all-scopes | --scopes a,b]
+`);
+    console.log(`  On a machine with no browser, add --device (or --manual).
 `);
     for (const s of states) {
       const scope = s.ok && s.scope ? `  ${summarizeScopes(s.scope)}` : "";
@@ -22506,7 +22789,9 @@ ${pending.length} need a grant; each is a separate authorization:`);
     scopes: flags.scopes,
     readOnly: Boolean(flags["read-only"]),
     allScopes: Boolean(flags["all-scopes"]),
-    listScopes: Boolean(flags["list-scopes"])
+    listScopes: Boolean(flags["list-scopes"]),
+    device: Boolean(flags.device),
+    manual: Boolean(flags.manual)
   });
   console.log(result.message);
   if (result.ok && !flags["list-scopes"]) {
@@ -22797,7 +23082,7 @@ function parseArgs(argv) {
         command = `--${name}`;
         continue;
       }
-      const boolean = ["raw", "json", "yes", "dry-run", "force", "servers-only", "read-only", "all-scopes", "list-scopes"].includes(name) && !(name === "json" && command === "add");
+      const boolean = ["raw", "json", "yes", "dry-run", "force", "servers-only", "read-only", "all-scopes", "list-scopes", "device", "manual"].includes(name) && !(name === "json" && command === "add");
       if (boolean) {
         flags[name] = true;
       } else if (inline !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autorouter-mcp",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "One search tool instead of every tool: an MCP capability router for Claude Code, Codex, Cursor and anything else that speaks MCP.",
   "mcpName": "io.github.Webb-Ventures/autorouter",
   "license": "MIT",

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.Webb-Ventures/autorouter",
   "title": "autorouter",
   "description": "An MCP capability router: one search tool instead of every server's tool schema.",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "websiteUrl": "https://github.com/Webb-Ventures/autorouter",
   "repository": {
     "url": "https://github.com/Webb-Ventures/autorouter",
@@ -14,7 +14,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "autorouter-mcp",
-      "version": "0.2.4",
+      "version": "0.2.5",
       "transport": { "type": "stdio" },
       "packageArguments": [{ "type": "positional", "value": "serve" }],
       "environmentVariables": [