toolstile 0.1.1 → 0.2.0

package/README.md

@@ -6,8 +6,6 @@ Check the MCP server configs your AI agents use, in one command:
 npx toolstile audit
 ```
 
-The same package is also published as `@toolstile/cli` (`npx @toolstile/cli audit`).
-
 It reads the configs of Claude Code, Claude Desktop, Cursor, Codex, VS Code,
 Windsurf, Gemini CLI and Cline and grades them for:
 
@@ -40,13 +38,16 @@ HIGH   Plaintext secret in github (Cursor)
        Fix: Reference an environment variable instead (for example ${API_TOKEN}) …
 ```
 
-## It only reads
+## The audit only reads
 
 - Reads config files on your machine. Writes nothing unless you ask for a card.
-- Makes no network requests and collects no telemetry.
+- Makes no network requests and collects no telemetry. (Only the separate
+  `auth` and `mcp` commands below talk to Toolstile, and only when you run them.)
 - Never prints, stores or sends secret values. Findings name the file and key,
   for example `mcpServers.github.env.GITHUB_TOKEN`, and the kind of secret.
-- About 1,100 lines of TypeScript with one runtime dependency
+- Never quotes a config file: one that cannot be read or parsed is listed with a
+  reason and position only, for example `invalid TOML at line 3, column 12`.
+- About 2,500 lines of TypeScript with one runtime dependency
   ([smol-toml](https://github.com/squirrelchat/smol-toml), for Codex's TOML
   config) and an optional one ([resvg-js](https://github.com/thx/resvg-js), only
   to render `--card` as PNG). Read it before you run it.
@@ -66,6 +67,14 @@ HIGH   Plaintext secret in github (Cursor)
 `--fail-on high` makes it usable in CI or a pre-commit hook for repositories that
 check in `.mcp.json`, `.cursor/mcp.json` or `.vscode/mcp.json`.
 
+Exit codes:
+
+| Code | Meaning |
+| --- | --- |
+| 0 | The audit ran, and no finding reached the `--fail-on` level (or `--fail-on` was not set) |
+| 1 | A finding is at or above the `--fail-on` level |
+| 2 | Invalid options, or the audit itself failed |
+
 ## Scoring
 
 Each distinct problem has a weight: 10 for a leaked secret, plain-http remote or
@@ -98,6 +107,59 @@ values) and prints a ready-to-post link. To post the text report instead, add
 | Gemini CLI | `~/.gemini/settings.json` | `.gemini/settings.json` |
 | Cline | `cline_mcp_settings.json` in VS Code or Cursor storage | |
 
+## Connect your agents to Toolstile
+
+If you use [Toolstile](https://toolstile.com), the CLI can also sign in and set
+up the agents on a machine for you:
+
+```sh
+npx toolstile auth login
+npx toolstile mcp setup
+```
+
+`auth login` prints a link and a code. Open the link on any device with a
+browser (your laptop or phone), sign in and approve the code. Nothing has to
+reach the machine you are signing in, so it works over SSH, in containers and on
+servers without a browser.
+
+`mcp setup` lists the agents it finds (Claude Code, Claude Desktop, Cursor,
+Codex, VS Code, Windsurf, Gemini CLI, Cline) and lets you turn each one on or
+off. Run it again any time to change the selection. Each enabled agent appears
+under this machine in the Toolstile dashboard with its own access, so you can
+grant, limit or revoke it there; then choose which MCP servers it can use.
+
+```text
+Which agents on this machine should use Toolstile?
+› ◉ Claude Code  ~/.claude.json
+  ○ Cursor  ~/.cursor/mcp.json
+  ◉ Codex  ~/.codex/config.toml
+↑/↓ move · space toggle · a all · enter save · esc cancel
+```
+
+Without a terminal, pass the choice as flags:
+`npx toolstile mcp setup --enable claude-code,codex --disable cursor`.
+
+How it stays out of your configs: an enabled agent's config gets a `toolstile`
+server that runs `npx -y toolstile@<version> mcp proxy --agent <agent>`. The proxy
+relays the agent's MCP messages to Toolstile using that agent's own token, which
+lives only in the CLI's credentials file (`~/.config/toolstile/credentials.json`,
+readable by you alone; `%APPDATA%\toolstile` on Windows). No token is written
+into the agent's config, so `toolstile audit` has nothing to flag. JSON configs
+with comments are not rewritten; setup prints the entry to add yourself.
+
+`npx toolstile auth logout` ends the CLI's sign-in. Agents you enabled keep
+working until you turn them off with `mcp setup` or delete the device in the
+dashboard.
+
+| Option | Command | Meaning |
+| --- | --- | --- |
+| `--server <url>` | `auth login` | Toolstile address (default `https://toolstile.com`, or `TOOLSTILE_URL`) |
+| `--no-browser` | `auth login` | Do not try to open a browser on this machine |
+| `--enable <agents>` | `mcp setup` | Turn these on without prompting (comma-separated) |
+| `--disable <agents>` | `mcp setup` | Turn these off without prompting |
+| `--workspace <slug>` | `mcp setup` | Workspace the agents use (default: the last one, or personal) |
+| `--device-name <name>` | `mcp setup` | Name for this machine in the dashboard (default: its hostname) |
+
 ## Use it from code
 
 ```ts
@@ -117,7 +179,7 @@ Questions and reports: support@toolstile.com.
 
 ## Releases
 
-Both npm packages are published by [GitHub Actions](.github/workflows/publish.yml)
+The npm package is published by [GitHub Actions](.github/workflows/publish.yml)
 with npm trusted publishing and provenance, so each release links back to the
 commit and workflow that built it. No npm token is stored anywhere.
 

package/dist/agents.d.ts

@@ -0,0 +1,43 @@
+import type { ClientId } from "./types.js";
+/** The server name `toolstile mcp setup` adds to each agent's config. */
+export declare const ENTRY = "toolstile";
+type Format = "mcpServers" | "vscode" | "codex";
+export interface Target {
+    client: ClientId;
+    name: string;
+    /** User-level config file that gets the entry. */
+    path: string;
+    format: Format;
+    /** Whether the app looks installed: its config file or folder exists. */
+    detected: boolean;
+}
+export interface TargetEnv {
+    home: string;
+    platform: NodeJS.Platform;
+    env: Record<string, string | undefined>;
+}
+export declare function targets(opts: TargetEnv): Target[];
+/** How the agent starts the proxy. Pinned, so the config runs the version that wrote it. */
+export declare function proxyCommand(client: ClientId, version: string, platform: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
+/** A config entry for a different, hand-written `toolstile` server is left alone. */
+export declare function isProxyEntry(value: unknown): boolean;
+export declare class ManualEditError extends Error {
+    readonly target: Target;
+    readonly snippet: string;
+    constructor(target: Target, reason: string, snippet: string);
+}
+/** The current entry, if the agent's config has one. */
+export declare function readEntry(target: Target): unknown;
+/**
+ * Adds (or, with `command` null, removes) the `toolstile` entry. JSON files with comments are
+ * not rewritten, since that would drop the comments; the caller shows the snippet instead.
+ */
+export type WriteResult = "added" | "updated" | "replaced" | "removed" | "unchanged";
+export declare function writeEntry(target: Target, command: {
+    command: string;
+    args: string[];
+} | null): WriteResult;
+export {};

package/dist/agents.js

@@ -0,0 +1,192 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { parseJsonc } from "./parse.js";
+import { appData, CLIENT_NAMES } from "./sources.js";
+/** The server name `toolstile mcp setup` adds to each agent's config. */
+export const ENTRY = "toolstile";
+export function targets(opts) {
+    const { home, env } = opts;
+    const data = appData(opts);
+    const codexHome = env.CODEX_HOME ?? join(home, ".codex");
+    const code = ["Code", "Code - Insiders"].map((edition) => join(data, edition, "User")).find((dir) => existsSync(dir)) ??
+        join(data, "Code", "User");
+    const cline = join(code, "globalStorage", "saoudrizwan.claude-dev");
+    const list = [
+        ["claude-code", join(home, ".claude.json"), "mcpServers", join(home, ".claude")],
+        ["claude-desktop", join(data, "Claude", "claude_desktop_config.json"), "mcpServers", join(data, "Claude")],
+        ["cursor", join(home, ".cursor", "mcp.json"), "mcpServers", join(home, ".cursor")],
+        ["codex", join(codexHome, "config.toml"), "codex", codexHome],
+        ["vscode", join(code, "mcp.json"), "vscode", code],
+        ["windsurf", join(home, ".codeium", "windsurf", "mcp_config.json"), "mcpServers", join(home, ".codeium", "windsurf")],
+        ["gemini", join(home, ".gemini", "settings.json"), "mcpServers", join(home, ".gemini")],
+        ["cline", join(cline, "settings", "cline_mcp_settings.json"), "mcpServers", cline],
+    ];
+    return list.map(([client, path, format, folder]) => ({
+        client,
+        name: CLIENT_NAMES[client],
+        path,
+        format,
+        detected: existsSync(path) || existsSync(folder),
+    }));
+}
+/** How the agent starts the proxy. Pinned, so the config runs the version that wrote it. */
+export function proxyCommand(client, version, platform) {
+    const args = ["-y", `toolstile@${version}`, "mcp", "proxy", "--agent", client];
+    // Windows apps start commands without a shell, and npx is a .cmd script there.
+    return platform === "win32" ? { command: "cmd", args: ["/c", "npx", ...args] } : { command: "npx", args };
+}
+/** A config entry for a different, hand-written `toolstile` server is left alone. */
+export function isProxyEntry(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const args = value.args;
+    return Array.isArray(args) && args.some((a) => typeof a === "string" && /^toolstile(@|$)/.test(a)) &&
+        args.includes("proxy");
+}
+export class ManualEditError extends Error {
+    target;
+    snippet;
+    constructor(target, reason, snippet) {
+        super(reason);
+        this.target = target;
+        this.snippet = snippet;
+        this.name = "ManualEditError";
+    }
+}
+function readText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+/** Replaces the file in one step and keeps its permission bits; a symlink keeps pointing at it. */
+function writeText(link, text) {
+    let path = link;
+    let mode = 0o600;
+    try {
+        path = realpathSync(link);
+        mode = statSync(path).mode & 0o777;
+    }
+    catch {
+        mkdirSync(dirname(path), { recursive: true });
+    }
+    const temp = `${path}.toolstile-${process.pid}.tmp`;
+    try {
+        writeFileSync(temp, text, { mode });
+        chmodSync(temp, mode);
+        renameSync(temp, path);
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+const serversKey = (format) => (format === "vscode" ? "servers" : "mcpServers");
+function jsonEntry(target, command) {
+    return target.format === "vscode" || target.client === "claude-code" ? { type: "stdio", ...command } : command;
+}
+function tomlEntry(command) {
+    return `[mcp_servers.${ENTRY}]\ncommand = ${JSON.stringify(command.command)}\nargs = [${command.args.map((a) => JSON.stringify(a)).join(", ")}]\n`;
+}
+/** Drops `[mcp_servers.toolstile]` and its sub-tables, keeping every other line and comment. */
+function withoutTomlEntry(text) {
+    const lines = text.split("\n");
+    const out = [];
+    let skipping = false;
+    for (const line of lines) {
+        const header = line.match(/^\s*\[\s*([^\]]+?)\s*\]\s*(#.*)?$/)?.[1];
+        if (header !== undefined) {
+            const name = header.replace(/\s+/g, "").replace(/"/g, "");
+            skipping = name === `mcp_servers.${ENTRY}` || name.startsWith(`mcp_servers.${ENTRY}.`);
+        }
+        if (!skipping)
+            out.push(line);
+    }
+    return out.join("\n").replace(/\n{3,}$/, "\n\n");
+}
+/** The current entry, if the agent's config has one. */
+export function readEntry(target) {
+    const text = readText(target.path);
+    if (!text?.trim())
+        return undefined;
+    try {
+        if (target.format === "codex") {
+            const servers = parseToml(text).mcp_servers;
+            return servers?.[ENTRY];
+        }
+        const data = parseJsonc(text);
+        return data?.[serversKey(target.format)]?.[ENTRY];
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `replaced` means a hand-written `toolstile` server (not the proxy) was swapped out. */
+const outcome = (command, existing) => !command ? "removed" : existing === undefined ? "added" : isProxyEntry(existing) ? "updated" : "replaced";
+export function writeEntry(target, command) {
+    const text = readText(target.path) ?? "";
+    if (target.format === "codex") {
+        let current;
+        try {
+            current = parseToml(text).mcp_servers;
+        }
+        catch {
+            throw new ManualEditError(target, "its TOML could not be parsed", command ? tomlEntry(command) : "");
+        }
+        const existing = current?.[ENTRY];
+        if (!command && (existing === undefined || !isProxyEntry(existing)))
+            return "unchanged";
+        let next = withoutTomlEntry(text);
+        if (command)
+            next = `${next.replace(/\s*$/, "")}${next.trim() ? "\n\n" : ""}${tomlEntry(command)}`;
+        let parsed;
+        try {
+            parsed = parseToml(next).mcp_servers?.[ENTRY];
+        }
+        catch {
+            parsed = null;
+        }
+        if (command ? !isProxyEntry(parsed) : parsed !== undefined)
+            throw new ManualEditError(target, "its toolstile server is written in a form setup cannot edit", command ? tomlEntry(command) : "");
+        if (next === text)
+            return "unchanged";
+        writeText(target.path, next);
+        return outcome(command, existing);
+    }
+    const key = serversKey(target.format);
+    const entry = command ? jsonEntry(target, command) : undefined;
+    const snippet = entry ? JSON.stringify({ [key]: { [ENTRY]: entry } }, null, 2) : "";
+    let data;
+    try {
+        data = text.trim() ? parseJsonc(text) : {};
+    }
+    catch {
+        throw new ManualEditError(target, "its JSON could not be parsed", snippet);
+    }
+    if (typeof data !== "object" || data === null || Array.isArray(data))
+        throw new ManualEditError(target, "it is not a JSON object", snippet);
+    const object = data;
+    const servers = (typeof object[key] === "object" && object[key] !== null ? object[key] : {});
+    const existing = servers[ENTRY];
+    if (entry ? JSON.stringify(existing) === JSON.stringify(entry) : existing === undefined || !isProxyEntry(existing))
+        return "unchanged";
+    // Rewriting would drop comments and trailing commas, so such files are left to the user.
+    try {
+        JSON.parse(text || "{}");
+    }
+    catch {
+        throw new ManualEditError(target, "it contains comments", snippet);
+    }
+    if (entry)
+        servers[ENTRY] = entry;
+    else
+        delete servers[ENTRY];
+    object[key] = servers;
+    const indent = text.match(/\n([ \t]+)"/)?.[1] ?? "  ";
+    writeText(target.path, `${JSON.stringify(object, null, indent)}\n`);
+    return outcome(entry, existing);
+}

package/dist/api.d.ts

@@ -0,0 +1,64 @@
+export declare const CLIENT_ID = "toolstile-cli";
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}
+export interface Workspace {
+    id: string;
+    slug: string;
+    name: string;
+    personal: boolean;
+}
+export interface Account {
+    email: string;
+    name: string;
+    expiresAt: string;
+    workspaces: Workspace[];
+}
+export interface DeviceCode {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+}
+type Fetch = typeof fetch;
+/** The Toolstile endpoints the CLI uses. Session calls carry the device-flow session token. */
+export declare function createApi(server: string, fetcher?: Fetch): {
+    deviceCode: () => Promise<DeviceCode>;
+    deviceToken: (deviceCode: string) => Promise<{
+        access_token: string;
+        expires_in: number;
+    }>;
+    account: (token: string) => Promise<Account>;
+    signOut: (token: string) => Promise<void>;
+    device: (token: string, input: {
+        workspaceId: string;
+        id?: string;
+        label: string;
+        rename?: boolean;
+    }) => Promise<{
+        id: string;
+        label: string;
+    }>;
+    agents: (token: string, workspaceId: string, deviceId: string) => Promise<{
+        agents: {
+            id: string;
+            label: string;
+        }[];
+    }>;
+    addAgent: (token: string, input: {
+        workspaceId: string;
+        deviceId: string;
+        label: string;
+    }) => Promise<{
+        id: string;
+        label: string;
+        token: string;
+    }>;
+    removeAgent: (token: string, workspaceId: string, id: string) => Promise<void>;
+};
+export type Api = ReturnType<typeof createApi>;
+export {};

package/dist/api.js

@@ -0,0 +1,61 @@
+export const CLIENT_ID = "toolstile-cli";
+export class ApiError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "ApiError";
+    }
+}
+async function request(fetcher, url, init = {}) {
+    let response;
+    try {
+        response = await fetcher(url, {
+            ...init,
+            // Never follow a redirect with a session token to another address.
+            redirect: "error",
+            headers: { "Content-Type": "application/json", Accept: "application/json", ...init.headers },
+        });
+    }
+    catch {
+        throw new ApiError(0, `Could not reach ${new URL(url).origin}. Check your connection.`);
+    }
+    if (response.status === 204)
+        return undefined;
+    const body = (await response.json().catch(() => null));
+    if (!response.ok) {
+        const message = body?.error_description ?? body?.message;
+        throw new ApiError(response.status, typeof message === "string" ? message : `Request failed (${response.status})`, typeof body?.error === "string" ? body.error : undefined);
+    }
+    return body;
+}
+/** The Toolstile endpoints the CLI uses. Session calls carry the device-flow session token. */
+export function createApi(server, fetcher = fetch) {
+    const base = server.replace(/\/+$/, "");
+    const session = (token, init = {}) => ({
+        ...init,
+        headers: { ...init.headers, Authorization: `Bearer ${token}` },
+    });
+    return {
+        deviceCode: () => request(fetcher, `${base}/api/auth/device/code`, {
+            method: "POST",
+            body: JSON.stringify({ client_id: CLIENT_ID }),
+        }),
+        deviceToken: (deviceCode) => request(fetcher, `${base}/api/auth/device/token`, {
+            method: "POST",
+            body: JSON.stringify({
+                grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                device_code: deviceCode,
+                client_id: CLIENT_ID,
+            }),
+        }),
+        account: (token) => request(fetcher, `${base}/api/cli/account`, session(token)),
+        signOut: (token) => request(fetcher, `${base}/api/cli/sign-out`, session(token, { method: "POST" })),
+        device: (token, input) => request(fetcher, `${base}/api/cli/device`, session(token, { method: "POST", body: JSON.stringify(input) })),
+        agents: (token, workspaceId, deviceId) => request(fetcher, `${base}/api/cli/agents?${new URLSearchParams({ workspaceId, deviceId })}`, session(token)),
+        addAgent: (token, input) => request(fetcher, `${base}/api/cli/agents`, session(token, { method: "POST", body: JSON.stringify(input) })),
+        removeAgent: (token, workspaceId, id) => request(fetcher, `${base}/api/cli/agents/${encodeURIComponent(id)}?${new URLSearchParams({ workspaceId })}`, session(token, { method: "DELETE" })),
+    };
+}

package/dist/checks.d.ts

@@ -4,6 +4,9 @@ interface Package {
     registry: "npm" | "pypi" | "docker";
     name: string;
     version: string | null;
+    /** Index of the package in the unwrapped words. */
+    wordIndex: number;
+    /** Index of the package in `args`, or -1 when it is inside `command`. */
     argIndex: number;
 }
 /** Finds the package a launcher such as npx, uvx or docker runs. */

package/dist/checks.js

@@ -41,20 +41,67 @@ const LAUNCHERS = {
     pnpx: "npm",
     uvx: "pypi",
 };
-/** Splits `command` and `args` into words, handling configs that put the whole command in one string. */
+const base = (p) => win32.basename(posix.basename(p)).replace(/\.(cmd|exe)$/i, "");
+const split = (text) => text.trim().split(/\s+/).filter(Boolean);
+/** WSL options that take a value. */
+const WSL_VALUED = new Set(["-d", "--distribution", "--distribution-id", "-u", "--user", "--cd", "--shell-type"]);
+/** Index of the first word after a `cmd /c` or `wsl` wrapper at `start`, or `start` when there is none. */
+function afterWrapper(list, start) {
+    const name = base(list[start] ?? "").toLowerCase();
+    let j = start + 1;
+    if (name === "cmd") {
+        // cmd [/d] [/s] [/q] … /c|/k command
+        while (j < list.length && /^\/[a-z]$/i.test(list[j]) && !/^\/[ck]$/i.test(list[j]))
+            j++;
+        return /^\/[ck]$/i.test(list[j] ?? "") ? j + 1 : start;
+    }
+    if (name === "wsl") {
+        while (j < list.length) {
+            const a = list[j];
+            if (WSL_VALUED.has(a))
+                j += 2;
+            else if (a === "-e" || a === "--exec" || a === "--")
+                return j + 1;
+            else if (a.startsWith("-"))
+                j++;
+            else
+                break;
+        }
+        return j;
+    }
+    return start;
+}
+/**
+ * Splits `command` and `args` into words, handling configs that put the whole command in one string,
+ * and skips Windows wrappers (`cmd /c npx …`, `wsl npx …`) so the real launcher comes first.
+ */
 function words(s) {
     if (!s.command)
-        return [];
-    const command = s.args.length === 0 && /\s/.test(s.command.trim()) ? s.command.trim().split(/\s+/) : [s.command];
-    return [...command, ...s.args];
+        return { list: [], arg: [] };
+    const oneString = s.args.length === 0 && /\s/.test(s.command.trim());
+    let list = oneString ? split(s.command) : [s.command, ...s.args];
+    let arg = oneString ? list.map(() => -1) : list.map((_, i) => i - 1);
+    for (;;) {
+        const start = afterWrapper(list, 0);
+        if (start === 0 || start >= list.length)
+            break;
+        list = list.slice(start);
+        arg = arg.slice(start);
+        // `cmd /c "npx -y pkg"` passes the inner command as one argument.
+        if (list.length === 1 && /\s/.test(list[0].trim())) {
+            const from = arg[0];
+            list = split(list[0]);
+            arg = list.map(() => from);
+        }
+    }
+    return { list, arg };
 }
-const base = (p) => win32.basename(posix.basename(p)).replace(/\.(cmd|exe)$/i, "");
 /** Finds the package a launcher such as npx, uvx or docker runs. */
 export function packageOf(s) {
-    const w = words(s);
+    const { list: w, arg } = words(s);
     if (w.length === 0)
         return null;
-    const cmd = base(w[0]);
+    const cmd = base(w[0]).toLowerCase();
     const sub = w.slice(1);
     let registry = LAUNCHERS[cmd];
     let skip = 0;
@@ -74,6 +121,7 @@ export function packageOf(s) {
         return null;
     const rest = sub.slice(skip);
     const offset = 1 + skip;
+    const at = (spec, i) => parsePackage(registry, spec, i, arg[i] ?? -1);
     // Flags that take a value; their value is not the package.
     const valued = new Set(["-p", "--package", "--from", "--with", "-e", "--env", "-v", "--volume", "--name", "--network", "--mount", "--env-file", "-w", "--workdir", "--entrypoint", "-u", "--user", "--python"]);
     for (let i = 0; i < rest.length; i++) {
@@ -83,41 +131,42 @@ export function packageOf(s) {
         if (a.startsWith("-")) {
             if (valued.has(a)) {
                 if ((a === "--package" || a === "-p" || a === "--from") && registry !== "docker") {
-                    return parsePackage(registry, rest[i + 1] ?? "", offset + i + 1);
+                    return at(rest[i + 1] ?? "", offset + i + 1);
                 }
                 i++;
             }
             continue;
         }
-        return parsePackage(registry, a, offset + i);
+        return at(a, offset + i);
     }
     return null;
 }
-function parsePackage(registry, spec, argIndex) {
+function parsePackage(registry, spec, wordIndex, argIndex) {
     if (!spec)
         return null;
+    const where = { wordIndex, argIndex };
     if (registry === "docker") {
         const at = spec.indexOf("@sha256:");
         if (at > 0)
-            return { registry, name: spec.slice(0, at), version: spec.slice(at + 1), argIndex };
+            return { registry, name: spec.slice(0, at), version: spec.slice(at + 1), ...where };
         const slash = spec.lastIndexOf("/");
         const colon = spec.lastIndexOf(":");
         return colon > slash
-            ? { registry, name: spec.slice(0, colon), version: spec.slice(colon + 1), argIndex }
-            : { registry, name: spec, version: null, argIndex };
+            ? { registry, name: spec.slice(0, colon), version: spec.slice(colon + 1), ...where }
+            : { registry, name: spec, version: null, ...where };
     }
     if (registry === "pypi") {
         const m = /^([A-Za-z0-9._\-[\],]+?)(?:(==|@|>=|~=)(.+))?$/.exec(spec);
         if (!m)
             return null;
-        return { registry, name: m[1], version: m[2] === "==" || m[2] === "@" ? m[3] : null, argIndex };
+        return { registry, name: m[1], version: m[2] === "==" || m[2] === "@" ? m[3] : null, ...where };
     }
     if (/^(https?:|git\+|file:|\.|\/)/.test(spec))
         return null;
     const at = spec.indexOf("@", spec.startsWith("@") ? 1 : 0);
     return at > 0
-        ? { registry, name: spec.slice(0, at), version: spec.slice(at + 1), argIndex }
-        : { registry, name: spec, version: null, argIndex };
+        ? { registry, name: spec.slice(0, at), version: spec.slice(at + 1), ...where }
+        : { registry, name: spec, version: null, ...where };
 }
 const isPinned = (p) => p.version !== null &&
     p.version !== "latest" &&
@@ -138,7 +187,7 @@ export function identityOf(s) {
     const pkg = packageOf(s);
     if (pkg)
         return `${pkg.registry}:${pkg.name.toLowerCase()}`;
-    const w = words(s);
+    const w = words(s).list;
     return w.length ? `cmd:${w.join(" ")}` : null;
 }
 const LOOPBACK = /^(localhost|127\.\d+\.\d+\.\d+|\[::1\]|0\.0\.0\.0)$/i;
@@ -149,12 +198,12 @@ function broadRoots(s, home) {
         return [];
     const homes = new Set([home, home.replace(/\/+$/, ""), "~", "~/", "$HOME", "${HOME}", "%USERPROFILE%"]);
     return words(s)
-        .slice(pkg.argIndex + 1)
+        .list.slice(pkg.wordIndex + 1)
         .filter((a) => a === "/" || /^[A-Za-z]:\\?$/.test(a) || homes.has(a) || homes.has(a.replace(/\/+$/, "")));
 }
 const SEVERITY_ORDER = { high: 0, medium: 1, low: 2, info: 3 };
-/** Toolstile's own gateway is meant to be added to every client. */
-const TOOLSTILE = /^url:([a-z0-9-]+\.)*toolstile\.com\//i;
+/** Toolstile's own gateway, directly or through `toolstile mcp proxy`, is meant to be added to every client. */
+const TOOLSTILE = /^(url:([a-z0-9-]+\.)*toolstile\.com\/|npm:toolstile$)/i;
 /** A path for a shell command: `~/...` under the home folder, single-quoted when needed. */
 export function shellPath(path, home) {
     const quote = (p) => (/^[\w@%+=:,./-]+$/.test(p) ? p : `'${p.replace(/'/g, "'\\''")}'`);
@@ -250,11 +299,11 @@ export function runChecks(d, home) {
                 fix: pkg.registry === "docker"
                     ? `Pin an image digest or exact tag, for example ${pkg.name}:<version>.`
                     : `Pin an exact version, for example ${pkg.name}${pkg.registry === "pypi" ? "==" : "@"}<version>.`,
-                locations: [at(s, "args", String(Math.max(0, pkg.argIndex - 1)))],
+                locations: [pkg.argIndex >= 0 ? at(s, "args", String(pkg.argIndex)) : at(s, "command")],
                 weight: 4,
             });
         }
-        const w = words(s);
+        const w = words(s).list;
         if (pkg?.registry === "docker") {
             const risky = w.filter((a) => a === "--privileged" || /\/var\/run\/docker\.sock/.test(a) || a === "--net=host" || a === "--network=host");
             if (risky.length) {