premanmcp 0.3.5 → 0.4.0

package/README.md

@@ -62,13 +62,14 @@ npm exec -y premanmcp@latest -- install --project
 - Adds API-key auth for PreMan MCP access.
 - Supports hosted MCPs with consumer tokens for customer-facing agent access.
 - Records per-call observability so teams can audit which agent did what.
+- Hands failing-endpoint alerts to your agent as fix tasks (`preman_get_fix_task` → repro curl → `preman_complete_fix_task`).
 
 ## Common Agent Commands
 
 After installing, ask your coding agent:
 
 ```text
-Use the PreMan MCP to scan this codebase, deploy a hosted MCP, and give me the install command.
+Use PreMan to convert the endpoints I choose into a hosted MCP server, then give me the Cursor/Claude install snippet.
 ```
 
 ```text
@@ -87,6 +88,10 @@ Convert these endpoints into an MCP.
 Show me the audit log for this hosted MCP.
 ```
 
+```text
+Pull my pending PreMan fix tasks and fix the failing endpoint.
+```
+
 ## Cursor
 
 The installer targets Cursor by default:
@@ -135,11 +140,43 @@ Options:
 - `--skip-login`: Install config without interactive terminal auth.
 - `--print`: Print the generated MCP config without writing it.
 
+## Run a hosted MCP from the terminal
+
+Installing the package also gives you a `preman` command. Once a selection is published as a
+hosted MCP, you can call its tools straight from a shell — same published selection, same
+consumer token, and same audit trail as an agent calling `POST /h/<id>/mcp`. Updating the
+selection updates the terminal; there is nothing to re-install.
+
+```bash
+preman link https://api.preman.live/h/<id>/mcp --env staging --token pm_hmcp_xxx
+preman tools --env staging
+preman run post_users_id_orders --env staging --arg id=42 --json '{"body":{"sku":"A1"}}'
+```
+
+`link` takes the URL straight from the deploy install snippet (a bare hosted MCP id works too,
+with `--backend`). Profiles are stored in `~/.preman/cli.json` (mode 0600); `--env <name>`
+picks one. Tool names are the ones the runtime publishes — run `preman tools` to see them.
+
+Run options:
+
+- `--env <name>`: Profile to use. Falls back to `PREMAN_MCP_URL`, then the default profile.
+- `--arg key=value`: String argument (repeatable). `--arg key:=json` sends a JSON-typed value.
+- `--json '{...}'`: Full arguments object. `--json -` reads it from stdin.
+- `--timeout <seconds>`: Client-side timeout. Defaults to 60.
+- `--json-out`: Print the raw JSON-RPC result.
+- `<tool>` may be dotted — `preman run staging.get_orders` selects the profile inline.
+
+Exit codes: `0` success, `1` the tool returned an error, `2` usage, `3` authentication,
+`4` JSON-RPC error (e.g. unknown tool), `5` network failure.
+
 ## Environment Variables
 
 - `PREMAN_API_KEY`: PreMan API key.
 - `PREMAN_BACKEND`: PreMan backend URL.
 - `PREMAN_FRONTEND`: PreMan frontend URL.
+- `PREMAN_MCP_URL`: Hosted MCP endpoint (`…/h/<id>/mcp`) for `preman run`/`preman tools` when
+  `--env` is omitted — useful in CI, where no profile file exists.
+- `PREMAN_MCP_TOKEN`: Consumer token for `PREMAN_MCP_URL`.
 
 If `PREMAN_API_KEY` is omitted, the MCP server loads credentials from `~/.preman/credentials.json`.
 

package/bin/cli.js

@@ -17,6 +17,8 @@ import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 
+import { HOSTED_HELP, linkCommand, runCommand, toolsCommand } from "./hosted.js";
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.join(__dirname, "..");
 const DEFAULT_BACKEND = "https://api.preman.live";
@@ -49,6 +51,7 @@ Usage:
   npm exec -y premanmcp@latest -- login              Create/login to PreMan from the terminal
   npm exec -y premanmcp@latest -- install [options]  Install PreMan into Cursor MCP config
   npm exec -y premanmcp@latest --                    Start the PreMan MCP server
+  preman link|tools|run ...                          Drive a published hosted MCP
 
 Login options:
   --email <email>       Pre-fill the email prompt
@@ -69,7 +72,7 @@ Examples:
   npm exec -y premanmcp@latest -- install
   npm exec -y premanmcp@latest -- install --api-key pm_live_xxx
   npm exec -y premanmcp@latest -- install --project --backend http://127.0.0.1:8000
-`);
+${HOSTED_HELP}`);
 }
 
 function readJsonFile(filePath) {
@@ -224,6 +227,43 @@ async function verifyUnconfirmedAccount(email) {
   return verified.access_token;
 }
 
+async function createAccountFromTerminal(email) {
+  const signup = await callBackendJson("POST", "/auth/start-signup", {
+    json: { email },
+  });
+
+  if (signup.ok) {
+    process.stdout.write("Verification code sent. Check your email.\n");
+    const otp = await promptText("Verification code: ");
+    const password = await promptPasswordTwice();
+    const setPassword = await callBackendJson("POST", "/auth/set-password", {
+      json: { email, otp, new_password: password },
+    });
+    assertOk(setPassword, "set password");
+    return String(setPassword.access_token || "");
+  }
+
+  if (signup.status_code !== 404) {
+    assertOk(signup, "start signup");
+  }
+
+  process.stdout.write(
+    "This PreMan backend uses the password-first signup flow. Create your password now, then enter the email code.\n"
+  );
+  const password = await promptPasswordTwice();
+  const legacySignup = await callBackendJson("POST", "/auth/signup", {
+    json: { email, password },
+  });
+  assertOk(legacySignup, "signup");
+  process.stdout.write("Verification code sent. Check your email.\n");
+  const otp = await promptText("Verification code: ");
+  const verified = await callBackendJson("POST", "/auth/verify-otp", {
+    json: { email, otp },
+  });
+  assertOk(verified, "verify OTP");
+  return String(verified.access_token || "");
+}
+
 async function authenticateTerminal() {
   const explicitKey = argValue("--api-key", process.env.PREMAN_API_KEY || "");
   if (explicitKey && explicitKey.startsWith("pm_live_")) {
@@ -249,18 +289,7 @@ async function authenticateTerminal() {
 
   if (!account.exists) {
     process.stdout.write("No PreMan account found. Creating one now.\n");
-    const signup = await callBackendJson("POST", "/auth/start-signup", {
-      json: { email },
-    });
-    assertOk(signup, "start signup");
-    process.stdout.write("Verification code sent. Check your email.\n");
-    const otp = await promptText("Verification code: ");
-    const password = await promptPasswordTwice();
-    const setPassword = await callBackendJson("POST", "/auth/set-password", {
-      json: { email, otp, new_password: password },
-    });
-    assertOk(setPassword, "set password");
-    accessToken = String(setPassword.access_token || "");
+    accessToken = await createAccountFromTerminal(email);
   } else if (account.needs_password) {
     process.stdout.write("This account needs a password. Sending an OTP first.\n");
     const resend = await callBackendJson("POST", "/auth/resend-otp", { json: { email } });
@@ -390,7 +419,8 @@ Backend: ${config.mcpServers[serverName].env.PREMAN_BACKEND}
 Next steps:
 1. ${hasInlineKey ? "Your PreMan API key was written to the MCP config." : hasStoredKey ? `Your PreMan API key is saved in ${CREDENTIALS_FILE}; the MCP server will load it automatically.` : "Run npm exec -y premanmcp@latest -- login to create/connect your account and generate an API key."}
 2. Restart Cursor or toggle the PreMan MCP server off/on.
-3. Ask your agent: "Use the PreMan MCP to scan this codebase, deploy a hosted MCP, and give me the install command."
+3. In your API repo, ask your coding agent:
+   "Use PreMan to convert the endpoints I choose into a hosted MCP server, then give me the Cursor/Claude install snippet."
 `);
 }
 
@@ -426,6 +456,12 @@ async function main() {
     await loginCommand();
   } else if (command === "install") {
     await installCursorMcp();
+  } else if (command === "link") {
+    await linkCommand(commandArgs);
+  } else if (command === "tools") {
+    await toolsCommand(commandArgs);
+  } else if (command === "run") {
+    await runCommand(commandArgs);
   } else if (command === "help" || command === "--help" || command === "-h") {
     printHelp();
   } else if (command === "start") {
@@ -440,5 +476,5 @@ async function main() {
 main().catch((error) => {
   const message = error instanceof Error ? error.message : String(error);
   process.stderr.write(`[preman] ${message}\n`);
-  process.exit(1);
+  process.exit(error?.exitCode || 1);
 });

package/bin/hosted.js

@@ -0,0 +1,455 @@
+/**
+ * Hosted MCP commands: link / tools / run.
+ *
+ * Drives a published PreMan hosted MCP from the terminal over the same surface
+ * agents use — POST /h/{id}/mcp, same selection, same consumer token, same
+ * audit trail. Nothing here talks to a PreMan control-plane API: this is
+ * packaging over the shipped runtime.
+ *
+ * Profiles live in ~/.preman/cli.json so `--env staging` picks a target. The
+ * runtime has no server-side notion of an environment; an env is a named
+ * profile pointing at one published hosted MCP.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+
+const PREMAN_DIR = path.join(os.homedir(), ".preman");
+const CLI_CONFIG_FILE = path.join(PREMAN_DIR, "cli.json");
+const DEFAULT_BACKEND = "https://api.preman.live";
+const CONSUMER_TOKEN_PREFIX = "pm_hmcp_";
+const DEFAULT_TIMEOUT_MS = 60000;
+
+export const EXIT_TOOL_ERROR = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_AUTH = 3;
+export const EXIT_RPC = 4;
+export const EXIT_NETWORK = 5;
+
+export class CliError extends Error {
+  constructor(message, exitCode = EXIT_USAGE) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+// --- arg parsing (mirrors bin/cli.js; no --flag=value form) -----------------
+
+function makeArgs(commandArgs) {
+  return {
+    positional: commandArgs.filter((a, i) => {
+      if (a.startsWith("-")) return false;
+      const prev = commandArgs[i - 1];
+      return !(prev && prev.startsWith("-") && !FLAGS.has(prev));
+    }),
+    value(name, fallback = "") {
+      const index = commandArgs.indexOf(name);
+      if (index === -1) return fallback;
+      return commandArgs[index + 1] || fallback;
+    },
+    all(name) {
+      const out = [];
+      commandArgs.forEach((a, i) => {
+        if (a === name && commandArgs[i + 1]) out.push(commandArgs[i + 1]);
+      });
+      return out;
+    },
+    has(name) {
+      return commandArgs.includes(name);
+    },
+  };
+}
+
+// Boolean flags take no value, so the token after them is still positional.
+const FLAGS = new Set(["--default", "--no-verify", "--json-out", "--quiet"]);
+
+// --- profile store ---------------------------------------------------------
+
+export function readCliConfig() {
+  if (!existsSync(CLI_CONFIG_FILE)) return { version: 1, profiles: {} };
+  const raw = readFileSync(CLI_CONFIG_FILE, "utf8").trim();
+  if (!raw) return { version: 1, profiles: {} };
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new CliError(`Could not parse ${CLI_CONFIG_FILE}: ${error.message}`);
+  }
+  if (!parsed.profiles || typeof parsed.profiles !== "object") parsed.profiles = {};
+  if (!parsed.version) parsed.version = 1;
+  return parsed;
+}
+
+function writeCliConfig(config) {
+  mkdirSync(PREMAN_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(CLI_CONFIG_FILE, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}
+
+export function maskToken(token) {
+  if (!token) return "(none)";
+  return `${CONSUMER_TOKEN_PREFIX}…${String(token).slice(-4)}`;
+}
+
+/** Accept a full /h/<id>/mcp URL or a bare hosted MCP id. */
+export function resolveMcpUrl(target, backend) {
+  const value = String(target || "").trim();
+  if (!value) throw new CliError("Missing hosted MCP URL or id.");
+  if (/^https?:\/\//i.test(value)) {
+    return value.replace(/\/+$/, "");
+  }
+  if (value.includes("/")) {
+    throw new CliError(`Not a hosted MCP id or URL: ${value}`);
+  }
+  const base = (backend || process.env.PREMAN_BACKEND || DEFAULT_BACKEND).replace(/\/+$/, "");
+  return `${base}/h/${value}/mcp`;
+}
+
+/**
+ * Pick the target profile.
+ *
+ * --env wins, then PREMAN_MCP_URL (so CI needs no config file), then the
+ * default profile, then a lone profile. Anything else is ambiguous.
+ */
+export function resolveProfile(config, envName, { toolPrefix = "" } = {}) {
+  const profiles = config.profiles || {};
+  const names = Object.keys(profiles);
+
+  if (envName && toolPrefix) {
+    throw new CliError(
+      `Ambiguous target: --env ${envName} together with the dotted form '${toolPrefix}.…'. Use one.`,
+    );
+  }
+
+  const wanted = envName || toolPrefix;
+  if (wanted) {
+    if (profiles[wanted]) return { name: wanted, ...profiles[wanted] };
+    const byAlias = names.find((n) => profiles[n].alias === wanted);
+    if (byAlias) return { name: byAlias, ...profiles[byAlias] };
+    const known = names.length ? names.join(", ") : "none";
+    throw new CliError(`No profile named '${wanted}'. Linked profiles: ${known}.`);
+  }
+
+  if (process.env.PREMAN_MCP_URL) {
+    return {
+      name: "(env)",
+      mcp_url: process.env.PREMAN_MCP_URL.replace(/\/+$/, ""),
+      token: process.env.PREMAN_MCP_TOKEN || "",
+    };
+  }
+
+  const preferred = config.default_profile;
+  if (preferred && profiles[preferred]) return { name: preferred, ...profiles[preferred] };
+  if (names.length === 1) return { name: names[0], ...profiles[names[0]] };
+
+  if (!names.length) {
+    throw new CliError(
+      "No hosted MCP linked. Run: preman link <mcp-url-or-id> --env <name> [--token pm_hmcp_…]",
+    );
+  }
+  throw new CliError(`Multiple profiles linked (${names.join(", ")}). Pass --env <name>.`);
+}
+
+// --- JSON-RPC over the hosted runtime --------------------------------------
+
+let cachedVersion = null;
+function cliVersion() {
+  if (cachedVersion) return cachedVersion;
+  try {
+    const pkgPath = new URL("../package.json", import.meta.url);
+    cachedVersion = JSON.parse(readFileSync(pkgPath, "utf8")).version || "0.0.0";
+  } catch {
+    cachedVersion = "0.0.0";
+  }
+  return cachedVersion;
+}
+
+/**
+ * The runtime answers HTTP 200 even for errors — the JSON-RPC envelope is the
+ * only source of truth, so never branch on resp.status here.
+ */
+export async function mcpRpc(profile, method, params, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const headers = {
+    "Content-Type": "application/json",
+    Accept: "application/json, text/event-stream",
+  };
+  if (profile.token) headers.Authorization = `Bearer ${profile.token}`;
+
+  let resp;
+  try {
+    resp = await fetch(profile.mcp_url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (error) {
+    const reason = error?.name === "TimeoutError" ? "timed out" : error.message;
+    throw new CliError(`Could not reach ${profile.mcp_url}: ${reason}`, EXIT_NETWORK);
+  }
+
+  const text = await resp.text();
+  let envelope;
+  try {
+    envelope = JSON.parse(text);
+  } catch {
+    throw new CliError(
+      `Unexpected non-JSON response from ${profile.mcp_url} (HTTP ${resp.status}).`,
+      EXIT_NETWORK,
+    );
+  }
+
+  if (envelope.error) {
+    const { code, message } = envelope.error;
+    if (code === -32001) {
+      throw new CliError(
+        `Authentication failed for profile '${profile.name}'. ` +
+          "Re-link with a valid consumer token: preman link <url> --env <name> --token pm_hmcp_…",
+        EXIT_AUTH,
+      );
+    }
+    if (code === -32601 && method === "tools/call") {
+      throw new CliError(
+        `${message || "Unknown tool"}. Run 'preman tools${
+          profile.name && profile.name !== "(env)" ? ` --env ${profile.name}` : ""
+        }' to list available tools.`,
+        EXIT_RPC,
+      );
+    }
+    throw new CliError(message || `JSON-RPC error ${code}`, EXIT_RPC);
+  }
+  return envelope.result;
+}
+
+async function initialize(profile, timeoutMs) {
+  // Sending clientInfo lets the runtime attribute invocations to the CLI.
+  return mcpRpc(
+    profile,
+    "initialize",
+    {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "preman-cli", version: cliVersion() },
+    },
+    { timeoutMs },
+  );
+}
+
+// --- argument assembly -----------------------------------------------------
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/** `key=value` is a string; `key:=value` is parsed as JSON. */
+export function parseArgPairs(pairs, base = {}) {
+  const out = { ...base };
+  for (const pair of pairs) {
+    const jsonIndex = pair.indexOf(":=");
+    const eqIndex = pair.indexOf("=");
+    if (jsonIndex !== -1 && (eqIndex === -1 || jsonIndex < eqIndex)) {
+      const key = pair.slice(0, jsonIndex);
+      const raw = pair.slice(jsonIndex + 2);
+      try {
+        out[key] = JSON.parse(raw);
+      } catch {
+        throw new CliError(`--arg ${key}:= expects JSON, got ${raw === "" ? "(empty)" : raw}`);
+      }
+      continue;
+    }
+    if (eqIndex === -1) {
+      throw new CliError(`--arg expects key=value or key:=json, got '${pair}'`);
+    }
+    out[pair.slice(0, eqIndex)] = pair.slice(eqIndex + 1);
+  }
+  return out;
+}
+
+async function buildToolArguments(args) {
+  let base = {};
+  const jsonArg = args.value("--json", "");
+  if (jsonArg) {
+    const raw = jsonArg === "-" ? await readStdin() : jsonArg;
+    try {
+      base = JSON.parse(raw);
+    } catch (error) {
+      throw new CliError(`--json expects a JSON object: ${error.message}`);
+    }
+    if (base === null || typeof base !== "object" || Array.isArray(base)) {
+      throw new CliError("--json must be a JSON object.");
+    }
+  }
+  return parseArgPairs(args.all("--arg"), base);
+}
+
+async function promptToken() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question("Consumer token (pm_hmcp_…, blank for public MCPs): ")).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+// --- commands --------------------------------------------------------------
+
+export async function linkCommand(commandArgs) {
+  const args = makeArgs(commandArgs);
+  const target = args.positional[0];
+  const envName = args.value("--env", "");
+  if (!target) throw new CliError("Usage: preman link <mcp-url-or-id> --env <name> [--token pm_hmcp_…]");
+  if (!envName) throw new CliError("preman link requires --env <name> to save the profile under.");
+
+  const mcpUrl = resolveMcpUrl(target, args.value("--backend", ""));
+  let token = args.value("--token", "") || process.env.PREMAN_MCP_TOKEN || "";
+  if (!token && process.stdin.isTTY) token = await promptToken();
+
+  if (token && !token.startsWith(CONSUMER_TOKEN_PREFIX)) {
+    process.stderr.write(
+      `[preman] Warning: consumer tokens normally start with ${CONSUMER_TOKEN_PREFIX}.\n`,
+    );
+  }
+
+  const profile = { name: envName, mcp_url: mcpUrl, token };
+  let alias = args.value("--alias", "");
+  let toolCount = null;
+
+  if (!args.has("--no-verify")) {
+    const info = await initialize(profile);
+    if (!alias) alias = info?.serverInfo?.name || "";
+    const listed = await mcpRpc(profile, "tools/list", {});
+    toolCount = (listed?.tools || []).length;
+  }
+
+  const config = readCliConfig();
+  config.profiles[envName] = {
+    mcp_url: mcpUrl,
+    ...(token ? { token } : {}),
+    ...(alias ? { alias } : {}),
+    linked_at: new Date().toISOString(),
+  };
+  if (args.has("--default") || !config.default_profile) config.default_profile = envName;
+  writeCliConfig(config);
+
+  process.stdout.write(
+    `Linked '${envName}' → ${mcpUrl}\n` +
+      `  token: ${token ? maskToken(token) : "(none — public access)"}\n` +
+      (toolCount === null ? "  (verification skipped)\n" : `  tools available: ${toolCount}\n`) +
+      `  saved to ${CLI_CONFIG_FILE}\n`,
+  );
+}
+
+export async function toolsCommand(commandArgs) {
+  const args = makeArgs(commandArgs);
+  const config = readCliConfig();
+  const profile = resolveProfile(config, args.value("--env", ""));
+  const timeoutMs = Number(args.value("--timeout", "")) * 1000 || DEFAULT_TIMEOUT_MS;
+
+  const result = await mcpRpc(profile, "tools/list", {}, { timeoutMs });
+  const tools = result?.tools || [];
+  if (args.has("--json-out")) {
+    process.stdout.write(`${JSON.stringify(tools, null, 2)}\n`);
+    return;
+  }
+  if (!tools.length) {
+    process.stdout.write(`No tools published on '${profile.name}'.\n`);
+    return;
+  }
+  process.stdout.write(`${tools.length} tool(s) on '${profile.name}':\n`);
+  for (const tool of tools) {
+    const required = tool.inputSchema?.required || [];
+    const suffix = required.length ? `  (required: ${required.join(", ")})` : "";
+    process.stdout.write(`  ${tool.name}${suffix}\n`);
+    if (tool.description) process.stdout.write(`      ${tool.description}\n`);
+  }
+}
+
+export async function runCommand(commandArgs) {
+  const args = makeArgs(commandArgs);
+  const selection = args.positional[0];
+  if (!selection) {
+    throw new CliError(
+      "Usage: preman run <tool> [--env <name>] [--arg key=value] [--json '{...}']",
+    );
+  }
+
+  // Dotted form addresses a profile explicitly: <profile-or-alias>.<tool>
+  const dot = selection.indexOf(".");
+  const toolPrefix = dot > 0 ? selection.slice(0, dot) : "";
+  const toolName = dot > 0 ? selection.slice(dot + 1) : selection;
+  if (dot > 0 && !toolName) throw new CliError(`Missing tool name after '${toolPrefix}.'`);
+
+  const config = readCliConfig();
+  const profile = resolveProfile(config, args.value("--env", ""), { toolPrefix });
+  const toolArguments = await buildToolArguments(args);
+  const timeoutMs = Number(args.value("--timeout", "")) * 1000 || DEFAULT_TIMEOUT_MS;
+
+  const result = await mcpRpc(
+    profile,
+    "tools/call",
+    { name: toolName, arguments: toolArguments },
+    { timeoutMs },
+  );
+
+  if (args.has("--json-out")) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    for (const block of result?.content || []) {
+      if (typeof block?.text === "string") process.stdout.write(`${block.text}\n`);
+    }
+    const status = result?._meta?.status;
+    if (status !== undefined && !args.has("--quiet")) {
+      process.stderr.write(`[preman] upstream status ${status}\n`);
+    }
+  }
+
+  if (result?.isError) {
+    // The runtime reports an unmatched tool name as an isError result rather
+    // than a JSON-RPC error, so point at the discovery command from here too.
+    const text = (result.content || []).map((b) => b?.text || "").join(" ");
+    if (/unknown tool/i.test(text)) {
+      process.stderr.write(
+        `[preman] Run 'preman tools${
+          profile.name && profile.name !== "(env)" ? ` --env ${profile.name}` : ""
+        }' to list available tools.\n`,
+      );
+    }
+    process.exitCode = EXIT_TOOL_ERROR;
+  }
+}
+
+export const HOSTED_HELP = `
+Hosted MCP (drive a published selection from the terminal):
+  preman link <mcp-url-or-id> --env <name>   Save a hosted MCP profile and verify it
+  preman tools [--env <name>]                List callable tools on the linked MCP
+  preman run <tool> [--env <name>] [args]    Call a tool and print the result
+
+Link options:
+  --env <name>          Profile name to save under (required)
+  --token <pm_hmcp_…>   Consumer token (or PREMAN_MCP_TOKEN, or prompted; omit for public MCPs)
+  --backend <url>       Backend URL when passing a bare MCP id. Defaults to ${DEFAULT_BACKEND}
+  --alias <name>        Short name usable in the dotted form
+  --default             Make this the default profile
+  --no-verify           Skip the initialize + tools/list check
+
+Run options:
+  --env <name>          Profile to use. Falls back to PREMAN_MCP_URL, then the default profile
+  --arg key=value       String argument (repeatable)
+  --arg key:=json       JSON-typed argument, e.g. --arg qty:=2 (repeatable)
+  --json '{...}'        Full arguments object ('--json -' reads stdin)
+  --timeout <seconds>   Client-side timeout. Defaults to 60
+  --json-out            Print the raw JSON-RPC result
+  <tool> may be dotted: <profile-or-alias>.<tool_name>
+
+Hosted MCP environment:
+  PREMAN_MCP_URL        Hosted MCP endpoint (…/h/<id>/mcp); used when --env is omitted
+  PREMAN_MCP_TOKEN      Consumer token for PREMAN_MCP_URL
+
+Examples:
+  preman link https://api.preman.live/h/2f6c…/mcp --env staging --token pm_hmcp_xxx
+  preman tools --env staging
+  preman run post_users_id_orders --env staging --arg id=42 --json '{"body":{"sku":"A1"}}'
+`;

package/dist/server.js

@@ -42,6 +42,62 @@ applyRepoPremanConfig();
 const BACKEND_URL = process.env.PREMAN_BACKEND || "https://api.preman.live";
 const FRONTEND_URL = process.env.PREMAN_FRONTEND || "https://app.preman.live";
 let API_KEY = process.env.PREMAN_API_KEY || "";
+function detectCodingAgent() {
+    const forced = (process.env.PREMAN_CODING_AGENT || "").trim().toLowerCase();
+    if (forced)
+        return forced.replace("-", "_");
+    if (process.env.CLAUDECODE || process.env.CLAUDE_CODE)
+        return "claude_code";
+    if (process.env.CODEX_HOME || process.env.OPENAI_CODEX)
+        return "codex";
+    if (process.env.CURSOR_AGENT || process.env.CURSOR_TRACE_ID || process.env.CURSOR_SESSION_ID) {
+        return "cursor";
+    }
+    return "cursor";
+}
+/** Prove this MCP session is live to the workbench coding-agent link. */
+async function heartbeatWorkbenchLink() {
+    if (!API_KEY)
+        return null;
+    try {
+        const resp = await fetch(`${BACKEND_URL}/workbench/coding-agent/heartbeat`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${API_KEY}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                pair_code: process.env.PREMAN_PAIR_CODE || undefined,
+                agent: detectCodingAgent(),
+                project_path: process.cwd(),
+                client_label: "premanmcp",
+                source: "preman_status",
+            }),
+        });
+        const text = await resp.text();
+        let data = {};
+        try {
+            data = text ? JSON.parse(text) : {};
+        }
+        catch {
+            data = { detail: text };
+        }
+        if (!resp.ok) {
+            return {
+                ok: false,
+                status: resp.status,
+                detail: data.detail || data.message || text,
+            };
+        }
+        return { ok: true, ...data };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 const PREMAN_CONTROL_PLANE_HOSTS = new Set([
     "api.preman.live",
     "preman.live",
@@ -920,6 +976,7 @@ export function createServer() {
                     }],
             };
         }
+        const workbench = await heartbeatWorkbenchLink();
         return {
             content: [{
                     type: "text",
@@ -930,13 +987,17 @@ export function createServer() {
                         backend_url: BACKEND_URL,
                         frontend_base_url: FRONTEND_BASE,
                         endpoints_page_url: buildAgentDashboardUrl("/endpoints"),
+                        coding_agent: workbench,
                         _agent_hints: {
                             next_actions: [
+                                workbench && workbench.connected
+                                    ? "Coding agent is linked to PreMan workbench — call discover_endpoints_from_codebase or get_endpoints."
+                                    : "If PreMan workbench shows pairing, set PREMAN_PAIR_CODE then call preman_status again.",
                                 "browser_navigate to `endpoints_page_url` (SPA shell + ot_agent_route) to open PreMan on the Endpoints page (sign in if prompted), then call get_endpoints.",
                                 "Call get_endpoints to see registered API endpoints.",
                                 "Call test_api to test an endpoint.",
                             ],
-                            related_tools: ["get_endpoints", "test_api", "import_collection"],
+                            related_tools: ["get_endpoints", "test_api", "import_collection", "discover_endpoints_from_codebase"],
                         },
                     }),
                 }],
@@ -1206,6 +1267,54 @@ export function createServer() {
             return toolError(e.message, inferErrorCode(e.message));
         }
     });
+    // ── preman_get_fix_task ───────────────────────────────────────────
+    server.tool("preman_get_fix_task", "Pull pending coding-agent fix tasks built from fired PreMan alerts. Each task packages a failing endpoint: title, expected vs actual, failure stats, and a reproducible curl (package.repro.curl). Fix the endpoint using the curl, then call preman_complete_fix_task with the fix_task_id. Check package.auto_pr: when eligible is true, push your fix on the branch it names and call preman_open_fix_pr.", {
+        status: z.enum(["open", "delivered", "resolved"]).optional().default("open").describe("'open' (default) hands out new tasks and marks them delivered; 'delivered' re-fetches ones already pulled; 'resolved' for history"),
+        limit: z.number().optional().default(5).describe("Max tasks to return (capped at 20)"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("preman_get_fix_task", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["No open fix tasks means no alerts have been handed off. Create a handoff from a fired alert in the dashboard."],
+            });
+        }
+    });
+    // ── preman_complete_fix_task ──────────────────────────────────────
+    server.tool("preman_complete_fix_task", "Mark a fix task resolved once its endpoint failure is fixed.", {
+        fix_task_id: z.string().describe("The id from a preman_get_fix_task result"),
+        resolution_note: z.string().optional().default("").describe("Optional note on what was fixed"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("preman_complete_fix_task", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                related_tools: ["preman_get_fix_task"],
+            });
+        }
+    });
+    // ── preman_open_fix_pr ────────────────────────────────────────────
+    server.tool("preman_open_fix_pr", "Open a pull request for a fix branch you already pushed (Auto-PR, Tier 2). Only for fix tasks whose package.auto_pr.eligible is true. Patch and push the preman/fix-* branch with your own git credentials first — PreMan never pushes code. PreMan then verifies the branch exists, re-checks the endpoint in production, and opens a PR with that evidence. PreMan never merges: a human reviews and merges.", {
+        fix_task_id: z.string().describe("The id from a preman_get_fix_task result"),
+        branch: z.string().describe("The branch you pushed — must match package.auto_pr.branch"),
+        summary: z.string().optional().default("").describe("Short description of the fix, included in the PR body"),
+        local_rerun: z.string().optional().default("").describe("Your local test/re-run output, included as agent-reported evidence"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("preman_open_fix_pr", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                related_tools: ["preman_get_fix_task", "preman_complete_fix_task"],
+                next_actions: ["Auto-PR requires the repo to have opted in and the fix task to be an API_BUG failure mapped to that repo."],
+            });
+        }
+    });
     return server;
 }
 // ── Start ─────────────────────────────────────────────────────────────

package/dist/user_auth_flow.js

@@ -58,7 +58,7 @@ async function callAuthJson(base, method, path, opts) {
  */
 export function registerUserAuthFlowTools(server, backendUrl) {
     const base = normalizeBase(backendUrl);
-    server.tool("user_auth_start_signup", "Start signup with email only. Sends an OTP; next call user_auth_set_password with email, OTP, and new password. Uses POST /auth/start-signup on PREMAN_BACKEND (no API key).", {
+    server.tool("user_auth_start_signup", "Start signup with email only. Sends an OTP; next call user_auth_set_password with email, OTP, and new password. Uses POST /auth/start-signup on PREMAN_BACKEND (no API key). If the backend does not support this endpoint yet, use user_auth_signup instead.", {
         email: z.string().describe("User email"),
     }, async (args) => {
         try {
@@ -66,6 +66,12 @@ export function registerUserAuthFlowTools(server, backendUrl) {
                 json: { email: args.email },
             });
             if (!r.ok) {
+                if (r.status_code === 404) {
+                    return toolError("This backend does not support email-only signup yet. Use user_auth_signup with email and password, then user_auth_verify_otp.", "backend_error", {
+                        next_actions: ["Call user_auth_signup with email and password.", "Then call user_auth_verify_otp with the email code."],
+                        related_tools: ["user_auth_signup", "user_auth_verify_otp"],
+                    });
+                }
                 return toolError(String(r.detail ?? r.message ?? "start signup failed"), r.status_code === 400 ? "invalid_input" : "backend_error", {
                     next_actions: ["If email exists, use user_auth_login or user_auth_resend_otp."],
                     related_tools: ["user_auth_set_password", "user_auth_login"],

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "premanmcp",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Turn APIs into agent-callable MCP tools with auth, testing, and audit logs",
   "type": "module",
   "bin": {
     "premanmcp": "bin/cli.js",
-    "preman-mcp": "bin/cli.js"
+    "preman-mcp": "bin/cli.js",
+    "preman": "bin/cli.js"
   },
   "scripts": {
     "build": "tsc -p tsconfig.server.json",