@odingard/guardian-mcp 0.3.0 → 0.3.3

package/README.md

@@ -31,11 +31,11 @@ npm i -g @odingard/guardian-mcp
 
 ## Tools
 
-| Tool | What it does |
-| --- | --- |
+| Tool                   | What it does                                                                                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `guardian_invoke_tool` | Propose a tool call. ALLOW executes and returns the receipt; ASK returns a `requestId` held for human approval; DENY refuses with a reason code. |
-| `guardian_claim` | Claim an approved ASK by `requestId`, execute, return the receipt. |
-| `guardian_receipt` | Fetch the machine-readable evidence receipts for a request. |
+| `guardian_claim`       | Claim an approved ASK by `requestId`, execute, return the receipt.                                                                               |
+| `guardian_receipt`     | Fetch the machine-readable evidence receipts for a request.                                                                                      |
 
 Nothing executes without a Guardian capability — the model's output is a proposal, never an action.
 
@@ -62,11 +62,11 @@ upstream server's tools unchanged, and every call is decided first:
 }
 ```
 
-| Decision  | What happens                                                                                                                 |
-| --------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| **ALLOW** | The call is forwarded to the upstream server, then the capability is redeemed and the receipt recorded.                      |
+| Decision  | What happens                                                                                                                                 |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| **ALLOW** | The call is forwarded to the upstream server, then the capability is redeemed and the receipt recorded.                                      |
 | **ASK**   | Nothing is forwarded. The exact call is held under a `requestId`; after a human approves, `guardian_claim` forwards exactly that call, once. |
-| **DENY**  | Nothing is forwarded, ever. The same applies if Guardian is unreachable.                                                     |
+| **DENY**  | Nothing is forwarded, ever. The same applies if Guardian is unreachable.                                                                     |
 
 - `guardian_claim` and `guardian_receipt` are added to the tool list.
 - The upstream server never receives `GUARDIAN_*` settings, so it never sees
@@ -74,18 +74,134 @@ upstream server's tools unchanged, and every call is decided first:
 - **Decision-gated:** an allowed call runs upstream before the capability is
   redeemed. A refusal at redemption is reported as an incident
   (`localEffectRan: true`), never as success.
-- **First-run setup:** connect a tool server in the Guardian console whose
-  tools JSON lists each upstream tool as record-only
-  (`{"name":"send_message","transport":"record"}`), and allow those tools
-  for the agent, then set `GUARDIAN_AUTO_REGISTER=false`. Otherwise the proxy
-  proposes an `mcp.install` registration per tool, which is denied unless the
-  agent's grant pins `mcp.install`.
+- **First-run setup:** in the Guardian console, connect a tool server and add
+  each upstream tool as "My own code (record-only)". Then allow those tools
+  for the agent.
+  - Since 0.3.1 the proxy does not try to register tools itself.
+  - `GUARDIAN_AUTO_REGISTER=true` turns that back on, but it is denied unless
+    the agent's grant pins `mcp.install`.
+  - When Guardian refuses, the result says what to fix.
 - Held calls live in the proxy process. Restarting the proxy drops them, and
   nothing is forwarded.
 
 `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:
+
+```bash
+npx -y @odingard/guardian-mcp tools -- npx -y @modelcontextprotocol/server-filesystem ./data
+```
+
+```text
+Tool            Suggested     Why
+read_file       Allow         server marks it read-only
+write_file      Ask me first  "write" may change something
+delete_branch   Ask me first  server marks it destructive
+createIssue     Ask me first  "create" may change something  ⚠ name not accepted by Guardian
+```
+
+How the suggestions are made:
+
+- The server's own MCP annotations (`readOnlyHint`, `destructiveHint`) are used first.
+- Otherwise the tool's verb decides. `get`, `list` and `search` suggest Allow; everything else suggests Ask.
+
+They are suggestions only: you set the real modes in the console. Tool names that break Guardian's naming rule are flagged, because every call to them would be denied. Add `--json` for machine-readable output.
+
 ## 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,35 +16,57 @@ 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
   GUARDIAN_CONNECTION_ID     tool connection id (required for proxy mode)
   GUARDIAN_ADAPTER_ID        optional adapter override
-  GUARDIAN_AUTO_REGISTER     proxy: "false" when the upstream tools are already registered
-                             as record-only on the connection (skips mcp.install)
+  GUARDIAN_AUTO_REGISTER     proxy: "true" to propose registering each upstream tool on first
+                             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" };
   if (argv[0] === "--help" || argv[0] === "-h" || argv[0] === "help") {
     return { ok: false, message: USAGE };
   }
+  if (argv[0] === "tools") {
+    const json = argv[1] === "--json";
+    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", 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,
@@ -76,7 +96,9 @@ ${USAGE}`
       credential: env.GUARDIAN_AGENT_CREDENTIAL,
       ...env.GUARDIAN_CONNECTION_ID ? { connectionId: env.GUARDIAN_CONNECTION_ID } : {},
       ...env.GUARDIAN_ADAPTER_ID ? { adapterId: env.GUARDIAN_ADAPTER_ID } : {},
-      autoRegister: !/^(false|0|no|off)$/i.test(env.GUARDIAN_AUTO_REGISTER ?? ""),
+      // 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
     }
   };
@@ -89,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 = [
@@ -225,6 +397,89 @@ async function handleToolCall(options, name, arguments_) {
   return errorResult(`unknown tool: ${name}`);
 }
 
+// src/presets.ts
+var GUARDIAN_TOOL_NAME = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+var READ_VERBS = /* @__PURE__ */ new Set([
+  "get",
+  "list",
+  "search",
+  "read",
+  "describe",
+  "show",
+  "view",
+  "find",
+  "lookup",
+  "count",
+  "inspect",
+  "status",
+  "fetch"
+]);
+function firstWord(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().split(/[^a-z0-9]+/).find(Boolean) ?? "";
+}
+function suggestTool(tool) {
+  const governable = GUARDIAN_TOOL_NAME.test(tool.name) && tool.name.length <= 64;
+  const annotations = tool.annotations ?? {};
+  if (annotations.destructiveHint === true) {
+    return {
+      name: tool.name,
+      suggestedMode: "ask",
+      why: "server marks it destructive",
+      governable
+    };
+  }
+  if (annotations.readOnlyHint === true) {
+    return {
+      name: tool.name,
+      suggestedMode: "allow",
+      why: "server marks it read-only",
+      governable
+    };
+  }
+  const verb = firstWord(tool.name);
+  if (READ_VERBS.has(verb)) {
+    return {
+      name: tool.name,
+      suggestedMode: "allow",
+      why: `name starts with "${verb}" (not annotated; check it really only reads)`,
+      governable
+    };
+  }
+  return {
+    name: tool.name,
+    suggestedMode: "ask",
+    why: verb ? `"${verb}" may change something` : "unclear what it does",
+    governable
+  };
+}
+function renderSuggestions(serverCommand, tools, remote = false) {
+  const rows = tools.map(suggestTool);
+  const width = Math.max(4, ...rows.map((r) => r.name.length));
+  const lines = [
+    `Tools of: ${serverCommand}`,
+    "",
+    `${"Tool".padEnd(width)}  Suggested     Why`,
+    ...rows.map(
+      (r) => `${r.name.padEnd(width)}  ${(r.suggestedMode === "ask" ? "Ask me first" : "Allow").padEnd(12)}  ${r.why}${r.governable ? "" : "  \u26A0 name not accepted by Guardian"}`
+    ),
+    "",
+    "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",
+    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) {
+    lines.push(
+      "",
+      `\u26A0 ${ungovernable.length} tool name(s) don't match Guardian's naming rule`,
+      "  (lowercase letters/digits, separated by . _ or -; at most 64 chars).",
+      "  Calls to them will be denied. Leave them out, or use a server version",
+      "  with compatible names."
+    );
+  }
+  return lines.join("\n");
+}
+
 // src/proxy.ts
 import {
   createGuardianContext,
@@ -266,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(
       {
@@ -333,7 +627,7 @@ function createGovernedProxy(options) {
     mode: "inProcess",
     onAsk: "result",
     onDeny: "result",
-    installRecordTransport: options.autoRegister ?? true,
+    installRecordTransport: options.autoRegister ?? false,
     ...options.adapterId ? { adapterId: options.adapterId } : {},
     ...options.agentName ? { agentName: options.agentName } : {}
   });
@@ -354,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)) {
@@ -388,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,
@@ -405,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) {
@@ -463,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,
@@ -491,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);
       }
@@ -500,7 +824,7 @@ function createGovernedProxy(options) {
           ctx,
           name,
           args,
-          () => upstream.callTool(name, args)
+          callUpstream(upstream, name, args)
         );
         return toCallResult(name, args, output);
       } catch (err) {
@@ -510,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) {
@@ -519,6 +921,31 @@ if (!parsed.ok) {
   process.exit(parsed.message.startsWith("guardian-mcp \u2014") ? 0 : 2);
 }
 var config = parsed.config;
+if (config.mode.kind === "tools") {
+  const mode = config.mode;
+  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 = describeTarget(mode);
+  process.stdout.write(
+    mode.json ? `${JSON.stringify({ server: serverCommand, tools: tools.map(suggestTool) }, null, 2)}
+` : `${renderSuggestions(serverCommand, tools, "remote" in mode)}
+`
+  );
+  process.exit(0);
+}
 var client = createGuardianClient({
   baseUrl: config.baseUrl,
   credential: config.credential,
@@ -529,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,
@@ -548,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.0",
+  "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

@@ -1,8 +1,8 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
   "name": "io.github.Odingard/guardian-mcp",
-  "description": "MCP server that routes an agent's tool calls through Guardian — Human Authority Infrastructure for Autonomous AI. Every tool call gets a deterministic ALLOW/ASK/DENY decision before anything executes; ASK holds the call until a human approves it, DENY never runs, and every outcome carries a verifiable receipt.",
-  "version": "0.3.0",
+  "description": "Routes agent tool calls through Guardian for ALLOW/ASK/DENY before execution.",
+  "version": "0.3.3",
   "tools": [
     {
       "name": "guardian_invoke_tool",
@@ -26,7 +26,7 @@
     {
       "registryType": "npm",
       "identifier": "@odingard/guardian-mcp",
-      "version": "0.3.0",
+      "version": "0.3.3",
       "transport": {
         "type": "stdio"
       },
@@ -38,7 +38,7 @@
         },
         {
           "name": "GUARDIAN_AGENT_CREDENTIAL",
-          "description": "Agent credential (gac1.…)",
+          "description": "Agent credential (gak_…)",
           "isRequired": true,
           "isSecret": true
         },