@odingard/guardian-mcp 0.3.0 → 0.3.2

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,42 @@ 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.
 
+## 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).

package/dist/index.js

@@ -18,14 +18,18 @@ 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 tools [--json] -- <command> [args...]
+                                             List a server's tools with a suggested Guardian mode
+                                             for each (no Guardian credential needed)
 
 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):
   guardian-mcp proxy -- npx -y @modelcontextprotocol/server-filesystem ./data
@@ -35,6 +39,29 @@ function parseCli(argv, env) {
   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 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}`
+      };
+    }
+    return {
+      ok: true,
+      config: {
+        baseUrl: "",
+        credential: "",
+        autoRegister: false,
+        mode: { kind: "tools", command, args, json }
+      }
+    };
+  }
   if (argv[0] === "proxy") {
     const rest = argv[1] === "--" ? argv.slice(2) : argv.slice(1);
     const [command, ...args] = rest;
@@ -76,7 +103,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 ?? ""),
+      // WO-050: 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
     }
   };
@@ -225,6 +254,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) {
+  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",
+    "`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,
@@ -333,7 +445,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 } : {}
   });
@@ -519,6 +631,36 @@ 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 = 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);
+  await lister.close();
+  const serverCommand = [mode.command, ...mode.args].join(" ");
+  process.stdout.write(
+    mode.json ? `${JSON.stringify({ server: serverCommand, tools: tools.map(suggestTool) }, null, 2)}
+` : `${renderSuggestions(serverCommand, tools)}
+`
+  );
+  process.exit(0);
+}
 var client = createGuardianClient({
   baseUrl: config.baseUrl,
   credential: config.credential,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odingard/guardian-mcp",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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",

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.2",
   "tools": [
     {
       "name": "guardian_invoke_tool",
@@ -26,7 +26,7 @@
     {
       "registryType": "npm",
       "identifier": "@odingard/guardian-mcp",
-      "version": "0.3.0",
+      "version": "0.3.2",
       "transport": {
         "type": "stdio"
       },
@@ -38,7 +38,7 @@
         },
         {
           "name": "GUARDIAN_AGENT_CREDENTIAL",
-          "description": "Agent credential (gac1.…)",
+          "description": "Agent credential (gak_…)",
           "isRequired": true,
           "isSecret": true
         },