@odingard/guardian-mcp 0.3.2 → 0.3.3

package/README.md

@@ -87,6 +87,98 @@ upstream server's tools unchanged, and every call is decided first:
 `guardian-mcp --help` prints usage. A missing setting prints a one-line
 message naming it instead of a stack trace.
 
+## Govern a remote MCP server: `guardian-mcp proxy --url` (unreleased)
+
+**Status: not yet proven live.** This is tested against local Streamable
+HTTP and SSE MCP servers and a fake Guardian only. Nothing has run against a
+real Guardian or a real hosted server such as Composio. Composio's
+`x-api-key` header is unconfirmed.
+
+The proxy can also front an MCP server that runs online, such as Composio.
+The agent still starts `guardian-mcp` over stdio like any
+local server; guardian-mcp connects to the remote server over **Streamable
+HTTP** (the default) or **SSE** (`--transport sse`).
+
+```json
+{
+  "mcpServers": {
+    "composio-governed": {
+      "command": "guardian-mcp",
+      "args": [
+        "proxy",
+        "--url",
+        "<the URL Composio's generate step returned>",
+        "--header",
+        "x-api-key: ${COMPOSIO_API_KEY}"
+      ],
+      "env": {
+        "GUARDIAN_BASE_URL": "https://guardian-api.odingard.com",
+        "GUARDIAN_AGENT_CREDENTIAL": "gac1.…",
+        "GUARDIAN_CONNECTION_ID": "pcn_…",
+        "COMPOSIO_API_KEY": "…"
+      }
+    }
+  }
+}
+```
+
+A server that takes a Bearer key: `--url https://mcp.example.com/mcp --header
+'Authorization: Bearer ${REMOTE_MCP_API_KEY}'`.
+
+- Every `tools/call` is decided by Guardian exactly as for a stdio server:
+  ALLOW forwards it, ASK holds it for `guardian_claim`, DENY never sends it.
+  `tools/list` passes through, with `guardian_claim` and `guardian_receipt`
+  added.
+- **Secrets stay in the proxy.** Write header values as `${ENV_VAR}`;
+  guardian-mcp expands them itself, so no shell is needed and the key never
+  appears in the agent's view. In a shell, use single quotes so the shell
+  does not expand it onto the command line. The URL and header values are
+  never printed; error messages show the server's origin only.
+- `${…}` can only name a variable that is set, and never a `GUARDIAN_*`
+  one, so the agent credential cannot be sent to the remote server.
+- The URL must be `https://`; plain `http://` is accepted only for
+  `localhost`. User names or passwords in the URL are refused; send
+  credentials as headers. Redirects to another origin are not followed.
+- **Fails closed.** If the remote server cannot be reached or rejects the key
+  at startup, guardian-mcp exits with a one-line message and serves no tools.
+  If the remote fails after Guardian allowed a call, the result is an error
+  that says the call may or may not have run, and the capability is not
+  redeemed. It is never reported as a success.
+- `guardian-mcp tools --url …` lists a remote server's tools with suggested
+  modes, the same as for a local one.
+- OAuth sign-in flows are not supported; use an API key or bearer token
+  header.
+- **The upstream cannot speak for Guardian.** A remote server's result is
+  passed to the agent as the server's own output, whatever fields it
+  carries. A result that contains a `guardian: {decision, requestId}` field
+  is never read as a Guardian decision, so it cannot hold, swap or hide a
+  call.
+- If `tools/list` fails upstream, the agent gets a generic "tool list is
+  unavailable" error. The upstream's error text (which can quote its URL
+  path, response body or headers) is not shown to the agent or logged;
+  `guardian-mcp tools --url` prints it with the URL, its path identifiers,
+  query values and header values scrubbed.
+
+What is **not** governed: a remote server the agent connects to directly
+(for example an MCP client's own `"url"` entry, or a model provider's hosted
+MCP connector), and anything the agent does without MCP. Also not covered:
+
+- **Lost results after ALLOW.** If the remote times out (the MCP SDK's
+  default request timeout is 60 seconds) or drops the session after
+  Guardian allowed a call, the call may have run, but the capability is not
+  redeemed and no receipt is written. Receipts can then understate what
+  happened; check the remote system itself.
+- **Keys in the same process tree.** guardian-mcp keeps the upstream key out
+  of the agent's MCP view. It cannot stop other code that runs as the same
+  user, in the same container, from reading the key from the environment it
+  was set in and calling the remote server directly. Recipes:
+  [ZeroClaw](../../examples/zeroclaw/README.md) and
+  [your own container (CrewAI, LangGraph, AutoGen)](../../examples/byo/README.md).
+  Runnable example: `examples/remote-mcp.mjs` (SIMULATED by default, LIVE with
+  Guardian settings). It runs inside this repository, where the workspace
+  links the unreleased guardian-mcp; the published `@odingard/guardian-mcp`
+  0.3.2 does not have `--url` yet.
+
 ## See what you are about to govern: `guardian-mcp tools`
 
 Before putting a server behind the proxy, list its tools along with a suggested Guardian mode for each. This needs no Guardian credential:
@@ -112,4 +204,4 @@ They are suggestions only: you set the real modes in the console. Tool names tha
 
 ## License
 
-Apache-2.0. Canonical development happens in the [Odingard Guardian monorepo](https://github.com/Odingard/guardian).
+Apache-2.0.

package/dist/index.js

@@ -2,8 +2,6 @@
 
 // src/index.ts
 import { createRequire } from "node:module";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -18,10 +16,21 @@ var USAGE = `guardian-mcp \u2014 route an agent's tool calls through Guardian (A
 Usage:
   guardian-mcp                               Guardian tools (guardian_invoke_tool, guardian_claim, guardian_receipt)
   guardian-mcp proxy -- <command> [args...]  Govern every tool of an existing stdio MCP server
+  guardian-mcp proxy --url <https-url> [--transport streamable-http|sse] [--header "Name: value"]...
+                                             Govern every tool of a remote MCP server (Streamable
+                                             HTTP by default, or SSE). The agent still talks stdio.
   guardian-mcp tools [--json] -- <command> [args...]
+  guardian-mcp tools [--json] --url <https-url> [--transport ...] [--header ...]
                                              List a server's tools with a suggested Guardian mode
                                              for each (no Guardian credential needed)
 
+Remote upstreams:
+  Write secrets as \${ENV_VAR} references, e.g. --header 'x-api-key: \${COMPOSIO_API_KEY}'
+  (single quotes in a shell, so the key never appears in the process list; JSON configs need
+  no quoting). guardian-mcp expands them itself, refuses a missing variable and any
+  GUARDIAN_* variable, and never prints the URL or header values. The URL must be https://
+  (plain http:// only for localhost).
+
 Environment:
   GUARDIAN_BASE_URL          required, e.g. https://guardian-api.odingard.com
   GUARDIAN_AGENT_CREDENTIAL  required, the agent credential (gac1.\u2026) from the Guardian console
@@ -31,8 +40,9 @@ Environment:
                              use (mcp.install). Default off: register the tools once in the
                              console as "My own code (record-only)" and allow them for the agent
 
-Example (proxy):
+Examples (proxy):
   guardian-mcp proxy -- npx -y @modelcontextprotocol/server-filesystem ./data
+  guardian-mcp proxy --url https://mcp.example.com/mcp --header 'Authorization: Bearer \${REMOTE_MCP_API_KEY}'
 `;
 function parseCli(argv, env) {
   let mode = { kind: "dispatch" };
@@ -41,39 +51,22 @@ function parseCli(argv, env) {
   }
   if (argv[0] === "tools") {
     const json = argv[1] === "--json";
-    const after = argv.slice(json ? 2 : 1);
-    const rest = after[0] === "--" ? after.slice(1) : after;
-    const [command, ...args] = rest;
-    if (!command) {
-      return {
-        ok: false,
-        message: `guardian-mcp tools: missing the MCP server command.
-
-${USAGE}`
-      };
-    }
+    const target = parseTarget("tools", argv.slice(json ? 2 : 1), env);
+    if (!target.ok) return target;
     return {
       ok: true,
       config: {
         baseUrl: "",
         credential: "",
         autoRegister: false,
-        mode: { kind: "tools", command, args, json }
+        mode: { kind: "tools", json, ...target.target }
       }
     };
   }
   if (argv[0] === "proxy") {
-    const rest = argv[1] === "--" ? argv.slice(2) : argv.slice(1);
-    const [command, ...args] = rest;
-    if (!command) {
-      return {
-        ok: false,
-        message: `guardian-mcp proxy: missing the upstream MCP server command.
-
-${USAGE}`
-      };
-    }
-    mode = { kind: "proxy", command, args };
+    const target = parseTarget("proxy", argv.slice(1), env);
+    if (!target.ok) return target;
+    mode = { kind: "proxy", ...target.target };
   } else if (argv.length > 0) {
     return {
       ok: false,
@@ -103,7 +96,7 @@ ${USAGE}`
       credential: env.GUARDIAN_AGENT_CREDENTIAL,
       ...env.GUARDIAN_CONNECTION_ID ? { connectionId: env.GUARDIAN_CONNECTION_ID } : {},
       ...env.GUARDIAN_ADAPTER_ID ? { adapterId: env.GUARDIAN_ADAPTER_ID } : {},
-      // WO-050: off by default — production denies first-use registration
+      // Off by default — production denies first-use registration
       // unless the grant pins mcp.install. Opt in with GUARDIAN_AUTO_REGISTER=true.
       autoRegister: /^(true|1|yes|on)$/i.test(env.GUARDIAN_AUTO_REGISTER ?? ""),
       mode
@@ -118,6 +111,156 @@ function upstreamEnv(env) {
   }
   return out;
 }
+var ENV_REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+var HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+var LOOPBACK = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+function expandEnv(cmd, value, env, where) {
+  for (const match of value.matchAll(ENV_REF)) {
+    const name = match[1];
+    if (name.startsWith("GUARDIAN_")) {
+      return {
+        ok: false,
+        message: `guardian-mcp ${cmd}: ${where} refers to \${${name}}; Guardian settings are never sent to the upstream server.`
+      };
+    }
+    if (!env[name]) {
+      return {
+        ok: false,
+        message: `guardian-mcp ${cmd}: ${where} refers to \${${name}}, which is not set.`
+      };
+    }
+  }
+  return {
+    ok: true,
+    value: value.replace(ENV_REF, (_, name) => env[name])
+  };
+}
+function parseTarget(cmd, argv, env) {
+  const fail = (message) => ({
+    ok: false,
+    message: `guardian-mcp ${cmd}: ${message}
+
+${USAGE}`
+  });
+  if (argv[0] === "--") argv = argv.slice(1);
+  else if (argv[0]?.startsWith("--")) return parseRemote(cmd, argv, env, fail);
+  const [command, ...args] = argv;
+  if (!command) {
+    return fail(
+      cmd === "proxy" ? "missing the upstream MCP server command (or --url for a remote server)." : "missing the MCP server command (or --url for a remote server)."
+    );
+  }
+  return { ok: true, target: { command, args } };
+}
+function parseRemote(cmd, argv, env, fail) {
+  let rawUrl;
+  let transport = "streamable-http";
+  const rawHeaders = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const eq = arg.indexOf("=");
+    const flag = arg.startsWith("--") && eq > 0 ? arg.slice(0, eq) : arg;
+    let value;
+    if (flag !== arg) value = arg.slice(eq + 1);
+    else if (flag === "--url" || flag === "--transport" || flag === "--header") {
+      value = argv[++i];
+    }
+    if (flag === "--url") {
+      if (rawUrl !== void 0) return fail("--url given more than once.");
+      if (!value) return fail("--url needs a value.");
+      rawUrl = value;
+    } else if (flag === "--transport") {
+      if (value !== "streamable-http" && value !== "sse" && value !== "http") {
+        return fail('--transport must be "streamable-http" or "sse".');
+      }
+      transport = value === "sse" ? "sse" : "streamable-http";
+    } else if (flag === "--header") {
+      if (!value) return fail("--header needs a value.");
+      rawHeaders.push(value);
+    } else if (flag === "--") {
+      return fail("give either --url or a command after --, not both.");
+    } else {
+      return fail(
+        `unknown option at position ${i + 1} (expected --url, --transport or --header).`
+      );
+    }
+  }
+  if (!rawUrl) return fail("--url is required with --transport or --header.");
+  const expandedUrl = expandEnv(cmd, rawUrl, env, "--url");
+  if (!expandedUrl.ok) return expandedUrl;
+  let url;
+  try {
+    url = new URL(expandedUrl.value);
+  } catch {
+    return fail("--url is not a valid URL.");
+  }
+  if (url.username || url.password) {
+    return fail(
+      "--url must not carry a user name or password; send credentials with --header."
+    );
+  }
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && LOOPBACK.has(url.hostname))) {
+    return fail(
+      "--url must be https:// (plain http:// is accepted only for localhost)."
+    );
+  }
+  const headers = {};
+  for (const [n, raw] of rawHeaders.entries()) {
+    const colon = raw.indexOf(":");
+    const name = colon > 0 ? raw.slice(0, colon).trim() : "";
+    if (!name || !HEADER_NAME.test(name)) {
+      return fail(`--header #${n + 1} must look like "Name: value".`);
+    }
+    const expanded = expandEnv(
+      cmd,
+      raw.slice(colon + 1).trim(),
+      env,
+      `--header ${name}`
+    );
+    if (!expanded.ok) return expanded;
+    if (!expanded.value) return fail(`--header ${name} has an empty value.`);
+    if (/[\r\n]/.test(expanded.value))
+      return fail(`--header ${name} contains a line break.`);
+    headers[name] = expanded.value;
+  }
+  return {
+    ok: true,
+    target: { remote: { url: url.href, transport, headers } }
+  };
+}
+function secretsOf(target) {
+  if (!("remote" in target)) return [];
+  const { url, headers } = target.remote;
+  const out = /* @__PURE__ */ new Set([url]);
+  const parsed2 = new URL(url);
+  if (parsed2.search) out.add(parsed2.search.slice(1));
+  for (const v of parsed2.searchParams.values()) if (v.length >= 4) out.add(v);
+  for (const segment of parsed2.pathname.split("/")) {
+    if (segment.length >= 16 || segment.length >= 8 && /\d/.test(segment)) {
+      out.add(segment);
+      out.add(decodeURIComponent(segment));
+    }
+  }
+  for (const value of Object.values(headers)) {
+    out.add(value);
+    const parts = value.split(/\s+/);
+    for (const part of parts) if (part.length >= 8) out.add(part);
+  }
+  return [...out].sort((a, b) => b.length - a.length);
+}
+function redact(text, secrets) {
+  let out = text;
+  for (const secret of secrets) {
+    if (secret) out = out.split(secret).join("[redacted]");
+  }
+  return out;
+}
+function describeTarget(target) {
+  if ("remote" in target) {
+    return `${new URL(target.remote.url).origin} (${target.remote.transport})`;
+  }
+  return [target.command, ...target.args].join(" ");
+}
 
 // src/dispatch.ts
 var TOOLS = [
@@ -309,7 +452,7 @@ function suggestTool(tool) {
     governable
   };
 }
-function renderSuggestions(serverCommand, tools) {
+function renderSuggestions(serverCommand, tools, remote = false) {
   const rows = tools.map(suggestTool);
   const width = Math.max(4, ...rows.map((r) => r.name.length));
   const lines = [
@@ -322,7 +465,7 @@ function renderSuggestions(serverCommand, tools) {
     "",
     "Register these in the Guardian console (Connections \u2192 Register a tool server \u2192",
     "record-only), then set each mode for your agent. Run the server through",
-    "`guardian-mcp proxy -- <same command>` so every call is decided first."
+    remote ? "`guardian-mcp proxy --url <same url> --header \u2026` so every call is decided first." : "`guardian-mcp proxy -- <same command>` so every call is decided first."
   ];
   const ungovernable = rows.filter((r) => !r.governable);
   if (ungovernable.length > 0) {
@@ -378,7 +521,46 @@ function jsonResult2(payload, isError = false) {
 function isDecisionResult(value) {
   return typeof value === "object" && value !== null && "guardian" in value && typeof value.guardian === "object";
 }
+var UpstreamCallFailed = class extends Error {
+  constructor(toolName) {
+    super("upstream call failed");
+    this.toolName = toolName;
+    this.name = "UpstreamCallFailed";
+  }
+  toolName;
+};
+var UPSTREAM_RESULT = /* @__PURE__ */ Symbol("guardian-mcp.upstreamResult");
+function upstreamRan(value) {
+  return typeof value === "object" && value !== null && Object.prototype.hasOwnProperty.call(value, UPSTREAM_RESULT);
+}
+var UpstreamListFailed = class extends Error {
+  constructor() {
+    super(
+      "guardian-mcp: the upstream MCP server's tool list is unavailable; no tools are served."
+    );
+    this.name = "UpstreamListFailed";
+  }
+};
+function callUpstream(upstream, name, args) {
+  return async () => {
+    try {
+      return { [UPSTREAM_RESULT]: await upstream.callTool(name, args) };
+    } catch {
+      throw new UpstreamCallFailed(name);
+    }
+  };
+}
 function failure(err, toolName) {
+  if (err instanceof UpstreamCallFailed) {
+    return jsonResult2(
+      {
+        decision: "ALLOW",
+        toolName,
+        error: "Guardian allowed the call but the upstream MCP server did not return a result. It may or may not have run; check before retrying. The capability was not redeemed."
+      },
+      true
+    );
+  }
   if (err instanceof GuardianExecutionFailed) {
     return jsonResult2(
       {
@@ -466,7 +648,16 @@ function createGovernedProxy(options) {
     return tools;
   }
   function toCallResult(toolName, args, output) {
-    if (!isDecisionResult(output)) return output;
+    if (upstreamRan(output)) return output[UPSTREAM_RESULT];
+    if (!isDecisionResult(output)) {
+      return jsonResult2(
+        {
+          toolName,
+          error: "Guardian proxy error; the call was not forwarded."
+        },
+        true
+      );
+    }
     const g = output.guardian;
     if (g.decision === "ASK") {
       if (toolInvokeRequestIds.has(g.requestId)) {
@@ -500,16 +691,19 @@ function createGovernedProxy(options) {
   async function claim(requestId) {
     const held = pendingCalls.get(requestId);
     if (held) {
+      pendingCalls.delete(requestId);
       let claimed;
       try {
         claimed = await options.client.claim(requestId);
       } catch {
+        pendingCalls.set(requestId, held);
         return jsonResult2(
           { requestId, error: "Guardian unreachable; nothing was forwarded." },
           true
         );
       }
       if (claimed.ok && claimed.decision === "ASK" || !claimed.ok && (claimed.reasonCode === "APPROVAL_PENDING" || claimed.reasonCode === "APPROVAL_REQUIRED")) {
+        pendingCalls.set(requestId, held);
         return jsonResult2({
           decision: "ASK",
           toolName: held.name,
@@ -517,14 +711,13 @@ function createGovernedProxy(options) {
           message: "Still awaiting human approval. Nothing was sent."
         });
       }
-      pendingCalls.delete(requestId);
       try {
         const output = await settle(
           ctx,
           held.name,
           held.args,
           claimed,
-          () => upstream.callTool(held.name, held.args)
+          callUpstream(upstream, held.name, held.args)
         );
         return toCallResult(held.name, held.args, output);
       } catch (err) {
@@ -575,7 +768,15 @@ function createGovernedProxy(options) {
   }
   return {
     async listTools() {
-      const tools = await loadTools();
+      let tools;
+      try {
+        tools = await loadTools();
+      } catch {
+        log(
+          "guardian-mcp proxy: the upstream MCP server's tool list is unavailable"
+        );
+        throw new UpstreamListFailed();
+      }
       return [
         ...[...tools.values()].map((tool) => ({
           ...tool,
@@ -603,7 +804,18 @@ function createGovernedProxy(options) {
           !result.ok
         );
       }
-      const tools = await loadTools();
+      let tools;
+      try {
+        tools = await loadTools();
+      } catch {
+        return jsonResult2(
+          {
+            toolName: name,
+            error: "The upstream MCP server's tool list is unavailable; nothing was forwarded."
+          },
+          true
+        );
+      }
       if (!tools.has(name)) {
         return jsonResult2({ error: `unknown tool: ${name}` }, true);
       }
@@ -612,7 +824,7 @@ function createGovernedProxy(options) {
           ctx,
           name,
           args,
-          () => upstream.callTool(name, args)
+          callUpstream(upstream, name, args)
         );
         return toCallResult(name, args, output);
       } catch (err) {
@@ -622,7 +834,85 @@ function createGovernedProxy(options) {
   };
 }
 
+// src/upstream.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+var UpstreamConnectError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UpstreamConnectError";
+  }
+};
+function upstreamTransport(target, env) {
+  if (!("remote" in target)) {
+    return new StdioClientTransport({
+      command: target.command,
+      args: target.args,
+      env: upstreamEnv(env),
+      stderr: "inherit"
+    });
+  }
+  const { url, transport, headers } = target.remote;
+  const options = {
+    requestInit: { headers },
+    redirectPolicy: "same-origin"
+  };
+  return transport === "sse" ? new SSEClientTransport(new URL(url), options) : new StreamableHTTPClientTransport(new URL(url), options);
+}
+async function connectUpstream(target, env, clientInfo, transport = upstreamTransport(target, env)) {
+  const client2 = new Client(clientInfo, { capabilities: {} });
+  try {
+    await client2.connect(transport);
+  } catch (err) {
+    await client2.close().catch(() => {
+    });
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new UpstreamConnectError(
+      `guardian-mcp: could not connect to the upstream MCP server at ${describeTarget(target)}: ${redact(detail, secretsOf(target)).slice(0, 300)}. No tools are served.`
+    );
+  }
+  return client2;
+}
+async function listAllTools(client2) {
+  const tools = [];
+  let cursor;
+  do {
+    const page = await client2.listTools(cursor ? { cursor } : void 0);
+    tools.push(...page.tools);
+    cursor = page.nextCursor;
+  } while (cursor);
+  return tools;
+}
+function toolListFailure(target, err) {
+  const detail = err instanceof Error ? err.message : String(err);
+  return `guardian-mcp: the upstream MCP server at ${describeTarget(target)} did not return its tool list: ${redact(detail, secretsOf(target)).slice(0, 300)}.`;
+}
+function clientUpstream(client2) {
+  return {
+    listTools: () => listAllTools(client2),
+    async callTool(name, args) {
+      return await client2.callTool({
+        name,
+        arguments: args
+      });
+    }
+  };
+}
+
 // src/index.ts
+async function connectOrExit(...args) {
+  try {
+    return await connectUpstream(...args);
+  } catch (err) {
+    process.stderr.write(
+      `${err instanceof UpstreamConnectError ? err.message : "guardian-mcp: could not connect to the upstream MCP server. No tools are served."}
+`
+    );
+    process.exit(1);
+  }
+}
 var VERSION = createRequire(import.meta.url)("../package.json").version;
 var parsed = parseCli(process.argv.slice(2), process.env);
 if (!parsed.ok) {
@@ -633,30 +923,25 @@ if (!parsed.ok) {
 var config = parsed.config;
 if (config.mode.kind === "tools") {
   const mode = config.mode;
-  const lister = new Client(
-    { name: "guardian-mcp-tools", version: VERSION },
-    { capabilities: {} }
-  );
-  await lister.connect(
-    new StdioClientTransport({
-      command: mode.command,
-      args: mode.args,
-      env: upstreamEnv(process.env),
-      stderr: "inherit"
-    })
-  );
-  const tools = [];
-  let cursor;
-  do {
-    const page = await lister.listTools(cursor ? { cursor } : void 0);
-    tools.push(...page.tools);
-    cursor = page.nextCursor;
-  } while (cursor);
+  const lister = await connectOrExit(mode, process.env, {
+    name: "guardian-mcp-tools",
+    version: VERSION
+  });
+  let tools;
+  try {
+    tools = await listAllTools(lister);
+  } catch (err) {
+    process.stderr.write(`${toolListFailure(mode, err)}
+`);
+    await lister.close().catch(() => {
+    });
+    process.exit(1);
+  }
   await lister.close();
-  const serverCommand = [mode.command, ...mode.args].join(" ");
+  const serverCommand = describeTarget(mode);
   process.stdout.write(
     mode.json ? `${JSON.stringify({ server: serverCommand, tools: tools.map(suggestTool) }, null, 2)}
-` : `${renderSuggestions(serverCommand, tools)}
+` : `${renderSuggestions(serverCommand, tools, "remote" in mode)}
 `
   );
   process.exit(0);
@@ -671,18 +956,10 @@ var server = new Server(
   { capabilities: { tools: {} } }
 );
 if (config.mode.kind === "proxy") {
-  const upstreamClient = new Client(
-    { name: "guardian-mcp-proxy", version: VERSION },
-    { capabilities: {} }
-  );
-  await upstreamClient.connect(
-    new StdioClientTransport({
-      command: config.mode.command,
-      args: config.mode.args,
-      env: upstreamEnv(process.env),
-      stderr: "inherit"
-    })
-  );
+  const upstreamClient = await connectOrExit(config.mode, process.env, {
+    name: "guardian-mcp-proxy",
+    version: VERSION
+  });
   const proxy = createGovernedProxy({
     client,
     connectionId: config.connectionId,
@@ -690,26 +967,7 @@ if (config.mode.kind === "proxy") {
     ...config.adapterId ? { adapterId: config.adapterId } : {},
     log: (message) => process.stderr.write(`${message}
 `),
-    upstream: {
-      async listTools() {
-        const tools = [];
-        let cursor;
-        do {
-          const page = await upstreamClient.listTools(
-            cursor ? { cursor } : void 0
-          );
-          tools.push(...page.tools);
-          cursor = page.nextCursor;
-        } while (cursor);
-        return tools;
-      },
-      async callTool(name, args) {
-        return await upstreamClient.callTool({
-          name,
-          arguments: args
-        });
-      }
-    }
+    upstream: clientUpstream(upstreamClient)
   });
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: await proxy.listTools()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odingard/guardian-mcp",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "mcpName": "io.github.Odingard/guardian-mcp",
   "description": "MCP server that routes an agent's tool calls through Guardian — the human authority layer for autonomous AI. Every tool call gets a deterministic ALLOW/ASK/DENY decision before anything executes; ASK holds for human approval, DENY never runs, every outcome carries a verifiable receipt.",
   "license": "Apache-2.0",
@@ -20,17 +20,18 @@
   "scripts": {
     "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node22 --external:@odingard/guardian-sdk --external:@modelcontextprotocol/sdk --outfile=dist/index.js",
     "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.2",
-    "@odingard/guardian-sdk": "^0.3.0"
+    "@odingard/guardian-sdk": "^0.3.8"
   },
   "devDependencies": {
     "@types/node": "^22",
     "esbuild": "^0.28.2",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^5.1.0"
   },
   "publishConfig": {
     "access": "public"
@@ -40,5 +41,5 @@
     "url": "https://github.com/Odingard/guardian-sdk.git",
     "directory": "packages/mcp"
   },
-  "homepage": "https://guardian.odingard.com"
+  "homepage": "https://odingard.com/guardian"
 }

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
   "name": "io.github.Odingard/guardian-mcp",
   "description": "Routes agent tool calls through Guardian for ALLOW/ASK/DENY before execution.",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "tools": [
     {
       "name": "guardian_invoke_tool",
@@ -26,7 +26,7 @@
     {
       "registryType": "npm",
       "identifier": "@odingard/guardian-mcp",
-      "version": "0.3.2",
+      "version": "0.3.3",
       "transport": {
         "type": "stdio"
       },