premanmcp 0.16.3 → 1.0.0

package/README.md

@@ -1,223 +1,38 @@
-# PreMan MCP
+# `premanmcp` 1.0
 
-Turn your APIs into MCP tools that coding agents can discover, call, test, and audit.
-
-PreMan is agent-first API infrastructure. It lets backend teams expose endpoints to AI coding agents through MCP, add an auth layer around those tools, and see exactly which agent called what.
-
-## Start
-
-```bash
-npm exec -y premanmcp@latest -- onboard
-```
-
-Create the account, verify the email, get the PreMan app installed and opened already
-signed in, and hook this repo so `git push` checks the endpoints you touched. A bare
-`preman` in a terminal does the same thing.
-
-## Connect a coding agent
-
-```bash
-npm exec -y premanmcp@latest -- connect
-```
-
-Optional, and separate from starting out. Pick your coding agent from the list — Cursor,
-Claude Code, or Codex — and PreMan writes that agent's MCP config for you. No hand-edited
-config anywhere.
-
-Local development form:
-
-```bash
-node bin/cli.js connect
-```
-
-First-time users are asked for an email and the code sent to it — no password: the
-terminal's credential is the `pm_live_` key. Pass `--password` to also set one for
-dashboard sign-in, or set it later from the dashboard. PreMan creates or connects the
-account, generates an API key, saves it to `~/.preman/credentials.json`, then writes a
-`preman` MCP server into the config your agent actually reads (`~/.cursor/mcp.json`,
-Claude Code's MCP config, or `~/.codex/config.toml`):
-
-```json
-{
-  "mcpServers": {
-    "preman": {
-      "command": "npm",
-      "args": ["exec", "-y", "premanmcp@latest", "--"],
-      "env": {
-        "PREMAN_BACKEND": "https://api.preman.live",
-        "PREMAN_FRONTEND": "https://app.preman.live"
-      }
-    }
-  }
-}
-```
-
-`connect` reads the config back after writing it, and prints a copy-paste snippet if it
-cannot confirm the entry landed. Then it finishes the link itself rather than asking you
-to go restart anything, in cheapest-first order:
-
-1. **Self-test.** It starts the MCP server exactly as your agent will and calls
-   `preman_status` over stdio. That both completes the link and proves the whole chain —
-   launcher, package, key, backend. `--no-self-test` turns it off.
-2. **Agent run**, which also proves your agent can load what was written. For Cursor it
-   runs `cursor-agent mcp enable` after writing `mcp.json` (new servers stay off the CLI
-   approved list otherwise) and launches the agent with `--approve-mcps` so the check-in
-   can actually call `preman_status`. It opens your agent interactively in a new terminal
-   window — the session you go on to use — and falls back to a headless run (`claude -p`,
-   `cursor-agent --approve-mcps -p`, `codex exec`) where no window can be opened, such as
-   CI or SSH. `--no-auto-checkin` turns it off, `PREMAN_NO_TERMINAL=1` keeps it headless.
-3. **Wait**, if neither is possible: restart your agent and it links on its first call.
-
-A self-test that answers from an unexpected backend is reported with the file that
-redirected it — a repo-local `preman-mcp.config.json` with `"PREMAN_CONFIG_OVERRIDE": true`
-wins over the MCP config env, and otherwise only fills in what the env leaves unset. When
-that file overrides `PREMAN_BACKEND`, the config `connect` wrote is still correct: the
-server reads that file only from the directory it starts in, so `connect` names the file
-and then retries from your home directory, where the override cannot reach it — self-test
-first, then your agent. Agents you start in the overriding directory keep using its
-backend, which is the point of the file.
-
-Once linked, `connect` installs the git pre-push hook — so `git push` checks the endpoints
-you touched — prints what is left, and stops. It asks nothing. Everything else it used to
-run is its own command, because each one can fail on its own and none of them should hold
-up a link that already worked:
-
-```bash
-preman endpoints discover          # map this repo's endpoints
-preman tests generate              # heuristic suites on saved Collections requests
-preman tests review                # list flagged suites; --approve <id> enables schedule
-preman tests setup                 # harvest path-param fixture IDs into a .env snippet
-preman tests enrich                # optional LLM cases on remaining heuristic suites
-preman runner start --background   # let PreMan apply fixes on this machine
-preman github                      # or connect it in the dashboard
-preman status                      # which of those are done
-```
-
-`preman onboard` (or `setup`, or a bare `preman` in a terminal) is what someone starting
-out runs: create the account and verify the email, install the PreMan app and open it
-already signed in, then write the pre-push hook into this repo — one question per step, `b`
-to go back, and a summary at the end. GitHub, AWS and Slack are their own commands now.
-Onboarding outside a git repository skips the hook rather than failing; run `preman hook
-install` in the repo you meant. Connecting a coding agent is no longer part of starting out; run
-`preman connect` when you actually want one wired into an IDE. `connect --guide` still runs
-the full pass inside connect itself: discovery, a first test, the runner, the desktop app
-and the integration prompts.
-
-The app opens signed in because the CLI leaves the key it just minted in
-`~/.preman/desktop-session.json`, which the app reads once and deletes. An app too old to
-look for it, or a machine that is not macOS, falls back to signing in on the app's own
-login screen with the account you just created.
-
-Useful flags: `--agent cursor|claude-code|codex` skips the picker, `--project` writes
-project-local config, `--print` shows the config without writing it, `--no-hook` leaves
-push testing alone, and `--no-guide` connects and nothing else. With `--guide`, `--yes`
-takes every step's default without asking and `--no-runner` / `--no-desktop` /
-`--no-integrations` skip one each.
-
-The desktop app is installed rather than offered. It was a question for a while, defaulted
-to no on the grounds that nobody should get a 150MB download by pressing Enter, and what
-that produced was a setup whose last act was to describe the app and decline to install
-it. The build is Developer ID signed and notarized, it is checked against the sha512
-published with the release before anything is copied into `/Applications`, and nothing
-arrives through a browser so there is no quarantine flag and no Gatekeeper warning on
-first launch. `--no-desktop`, or `PREMAN_NO_DESKTOP=1` where no flag can be passed, skips
-it; `install-desktop` does it on its own.
-
-In CI or any non-interactive shell, run `connect --agent <name> --api-key pm_live_…`.
-Without `--agent` there is nothing to prompt on, so `connect` prints ready-to-paste
-setup blocks for all three agents and exits 2.
-
-`preman install` still exists and does the Cursor-only half of this.
-
-### Cloud dispatch (optional)
-
-With a coding-agent credential saved — a Cursor API key from
-`cursor.com/dashboard → Integrations → API Keys`, or a Claude Code routine token and id
-from `claude.ai/code/routines → your routine → Add API trigger` — PreMan can start an
-agent run for you when it finds a failing endpoint, instead of handing back a prompt to
-paste.
-
-`connect` asks for it once you are already set up, so skipping costs nothing. Come back
-to it any time:
-
-```bash
-npm exec -y premanmcp@latest -- dispatch
-```
-
-You can also create or connect your account first:
-
-```bash
-npm exec -y premanmcp@latest -- login
-```
-
-You can also pass the key directly:
-
-```bash
-npm exec -y premanmcp@latest -- connect --api-key pm_live_xxx
-```
-
-For project-local config:
-
-```bash
-npm exec -y premanmcp@latest -- connect --project
-```
-
-## What It Does
-
-- Converts API endpoints into agent-callable MCP tools.
-- Migrates a Postman collection in one call (`migrate_from_postman`): keeps the assertions your `pm.test` blocks declared, splits the environment into shared variables and encrypted secrets, and schedules a monitored test suite per request.
-- Creates/connects a PreMan account from the terminal or IDE agent.
-- Lets agents test real backend endpoints from the IDE.
-- Syncs endpoint inventory across backend and frontend workflows.
-- 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`).
-- Connects your production logs from the terminal (`connect_logs`): your agent asks where the logs live, then deploys a read-only CloudFormation role for AWS, or wires a shipper to the ingest endpoint for everything else.
-
-## Common Agent Commands
-
-After installing, ask your coding agent:
-
-```text
-Use PreMan to convert the endpoints I choose into a hosted MCP server, then give me the Cursor/Claude install snippet.
-```
+`premanmcp` is the compatibility client for agents that can start only a local
+stdio MCP process. It forwards MCP initialization, discovery, notifications,
+and tool calls to PreMan's authoritative hosted server at:
 
 ```text
-Use PreMan to sign me up, verify my email OTP, create my API key, then scan this project.
+https://api.preman.live/mcp
 ```
 
-```text
-Use PreMan to test POST /auth/login.
-```
+It defines no tools or schemas locally. The hosted service exposes the stable
+four-tool PreMan conversation protocol:
 
-```text
-Convert these endpoints into an MCP.
-```
+- `preman_chat`
+- `preman_get_turn`
+- `preman_confirm_action`
+- `preman_cancel_turn`
 
-```text
-Show me the audit log for this hosted MCP.
-```
+PreMan can add private agent capabilities without publishing a new npm package.
 
-```text
-Move my Postman collection over to PreMan.
-```
+## Marketplace users
 
-```text
-Pull my pending PreMan fix tasks and fix the failing endpoint.
-```
+Do not install this package. The PreMan Codex/ChatGPT plugin connects directly
+to the hosted Streamable HTTP MCP server with OAuth.
 
-```text
-Connect my production logs to PreMan.
-```
+## Local-agent compatibility
 
-## Cursor
+Create a PreMan API key in the app, then export it or store it locally:
 
 ```bash
-npm exec -y premanmcp@latest -- connect --agent cursor
+export PREMAN_API_KEY=pm_live_xxx
+# or: ~/.preman/credentials.json -> {"api_key":"pm_live_xxx"}
 ```
 
-Manual Cursor config, if you would rather write it yourself:
+Then configure an agent that requires stdio:
 
 ```json
 {
@@ -230,179 +45,33 @@ Manual Cursor config, if you would rather write it yourself:
 }
 ```
 
-## Claude Code
-
-```bash
-npm exec -y premanmcp@latest -- connect --agent claude-code
-```
-
-Equivalent manual command:
-
-```bash
-claude mcp add preman -- npm exec -y premanmcp@latest --
-```
-
-## Codex
-
-```bash
-npm exec -y premanmcp@latest -- connect --agent codex
-```
-
-Writes an `[mcp_servers.preman]` block into `~/.codex/config.toml`.
-
-## CLI
-
-```bash
-npm exec -y premanmcp@latest -- connect            # Pick an agent and connect it
-npm exec -y premanmcp@latest -- connect --agent codex   # Skip the picker
-npm exec -y premanmcp@latest -- connect --project  # Write project-local config
-npm exec -y premanmcp@latest -- connect --print    # Print config without writing
-npm exec -y premanmcp@latest --         # Start the MCP server
-npm exec -y premanmcp@latest -- login   # Create/login and generate a PreMan API key
-npm exec -y premanmcp@latest -- install # Cursor-only installer (legacy)
-```
-
-### Push testing
+The proxy reads `PREMAN_API_KEY` or `~/.preman/credentials.json`. Optional
+transport overrides are `PREMAN_MCP_URL` and `PREMAN_BACKEND`.
 
-```bash
-preman hook install         # Write the pre-push hook (onboard and connect do this too)
-preman hook status          # Installed? And does the command in it still answer?
-preman hook repair          # Rewrite it if it stopped working (usually automatic)
-preman hook uninstall       # Remove it, restoring any hook it replaced
-```
-
-The hook is generated shell that runs `preman verify --pre-push` and can only ever be
-advisory: no backend, no credentials, a crash or a timeout all exit 0 with a notice. Before
-writing it, `install` runs the command it is about to embed and requires an answer — a hook
-holding a `preman` that belongs to another package prints `checks skipped` at every push and
-looks installed forever. The embedded command is pinned to the version that wrote it rather
-than `@latest`, so upgrading us never changes what your pushes run; re-run `hook install`
-to move it. Set `PREMAN_HOOK_INVOCATION` to write a command of your own instead, and
-`PREMAN_SKIP_HOOK=1` to silence the hook for a push.
-
-You should not have to run `repair`. A hook of ours that stops answering is rewritten in the
-background by anything that proves PreMan runs here — any command, or your agent starting the
-MCP server — because nothing re-runs `connect` after an upgrade to notice, and the broken
-state is silent. It is narrow on purpose: a hook that still works keeps the version it pins, a
-hook we did not write is never touched, and no hook is installed where you never asked for
-one. The answer is remembered for an hour per directory, and `PREMAN_NO_HOOK_REPAIR=1` turns
-it off.
-
-#### The link a push leaves behind
-
-Once runs are stored, the hook prints a line you can click straight through to that push:
-
-```
-◆ PreMan · check #a3f21c passed — view results
-  https://app.preman.live/observability/endpoints?batch=a3f21c9e-…
-```
-
-Where the click lands is decided before anything is printed, because a terminal hands the
-URL it was given to the OS and there is nothing left of the hook by then:
-
-| What is true when the hook runs | What the link opens |
-| --- | --- |
-| A frontend other than `app.preman.live` | That frontend, in the browser |
-| PreMan.app installed and new enough to route | The desktop app, via `preman://` |
-| Anything else | `app.preman.live`, in the browser |
-
-The frontend is read from `--frontend`, then `PREMAN_FRONTEND`, then the one saved at login
-in `~/.preman/credentials.json`. That last fallback is what makes a local setup work from a
-hook at all: `git push` does not carry the shell that exported the variable, and a `dev.env`
-file is not an environment.
+## Security model
 
-The bare URL is always printed underneath, because macOS Terminal.app renders no hyperlink.
-Piped output — a GUI git client, CI — gets the plain line with no escapes at all, and
-`NO_COLOR` drops the colour but keeps the link.
+- OAuth is used by marketplace clients; API keys remain for CLI compatibility.
+- Risky actions are stored server-side as exact, expiring proposals.
+- Chat text never approves an action. Approval uses
+  `preman_confirm_action` or the matching control in the PreMan app.
+- The proxy never receives private PreMan tool schemas or raw proposal payloads.
 
-Desktop builds from `MIN_ROUTE_VERSION` in `bin/link.js` onward are expected to read
-`preman://open?source=push&route=<url-encoded path>` and navigate to that path. Older builds
-raise the window and ignore the query, so the CLI reads `CFBundleShortVersionString` out of
-the installed bundle and falls back to https rather than sending them somewhere they cannot
-follow.
-
-### Runner
-
-`preman onboard` and `connect --guide` set this up for you; these are for managing it
-afterwards.
+## Development
 
 ```bash
-preman runner status              # Paired? Running?
-preman runner start --background  # Hold the job stream, log to ~/.preman/runner.log
-preman runner stop                # Stop it and report offline
-preman runner register --agent claude-code   # Pair without starting
+npm ci
+npm test
+npm pack --dry-run
 ```
 
-`start` pairs this machine itself when it is not paired yet, and re-pairs it when the
-backend has revoked the token it held, so neither is a command you have to be told to run.
-It works out which agent to pair as from the session it is running in, then from the agent
-PreMan is already configured in, then from the only one installed — and asks only when
-those disagree. Pass `--agent cursor|claude-code|codex` to settle it yourself, which is
-also what a machine with no terminal to ask in needs.
-
-The runner holds one outbound connection to PreMan and runs the work PreMan queues for
-this machine — a failing endpoint becomes an agent run in your own repo instead of a
-prompt you have to paste. It is bound to the agent and directory it was registered with
-and refuses any job that names a different one. The agent may edit files; running commands
-needs `--full-access` (or `PREMAN_RUNNER_FULL_ACCESS=1`). Nothing runs until PreMan has
-something to fix, and `preman runner stop` ends it.
-
-Options:
-
-- `--api-key <key>`: PreMan API key.
-- `--backend <url>`: PreMan backend URL. Defaults to `https://api.preman.live`.
-- `--frontend <url>`: PreMan frontend URL. Defaults to `https://app.preman.live`.
-- `--name <name>`: MCP server name. Defaults to `preman`.
-- `--project`: Write `.cursor/mcp.json` in the current project.
-- `--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`.
-
-## Product
-
-PreMan helps teams make APIs usable by agents without giving up control. Developers can turn endpoints into MCP servers, hand customers an install snippet or hosted MCP URL, and audit every tool call through PreMan.
+`npm test` builds the TypeScript proxy and checks transparent forwarding against
+a mock Streamable HTTP MCP server.
 
-Dashboard: [https://app.preman.live](https://app.preman.live)
+## Links
 
-## License
+- Documentation: https://app.preman.live/docs/preman-plugin
+- Support: https://app.preman.live/support
+- Privacy: https://app.preman.live/privacy
+- Terms: https://app.preman.live/terms
 
-MIT
+License: MIT

package/bin/api_tools.js

@@ -1,9 +1,10 @@
 /**
  * `preman endpoints` and `preman test` — the API-testing surface of the CLI.
  *
- * Both are thin proxies over `POST /mcp/call-tool`, exactly like the MCP
- * server's tools, so the CLI and an agent calling the same tool see identical
- * behaviour. Requires a pm_live_ key (flag, env, or stored credentials).
+ * Both are thin proxies over the `/cli` REST routes, which call the same
+ * implementations the MCP tools did, so the CLI and an agent asking for the
+ * same thing see identical data. Requires a pm_live_ key (flag, env, or stored
+ * credentials).
  */
 
 import { readFileSync } from "node:fs";
@@ -42,6 +43,40 @@ class CliError extends Error {
   }
 }
 
+/**
+ * Where each tool's data comes from now.
+ *
+ * These were one POST to `/mcp/call-tool` until the four-tool chat gateway
+ * retired that catalog. `/mcp` is now a conversation, which is the wrong shape
+ * for a CLI that wants a list of endpoints and an exit code. The `/cli` routes
+ * call the same implementations the tools did, so the two surfaces cannot
+ * drift apart. A tool absent from this table is one the CLI cannot reach.
+ */
+const TOOL_ROUTES = {
+  get_endpoints: { method: "GET", path: "/cli/endpoints" },
+  discover_endpoints_from_codebase: { method: "POST", path: "/cli/discovery-brief" },
+  register_discovered_endpoints: { method: "POST", path: "/cli/endpoints/register" },
+  generate_endpoint_tests: { method: "POST", path: "/cli/tests/generate" },
+  run_stress_test: { method: "POST", path: "/cli/stress-test" },
+  share_endpoints_with_ui: { method: "POST", path: "/cli/playground-session" },
+};
+
+/**
+ * A failure a person can act on.
+ *
+ * FastAPI's `detail` is often an object, and interpolating one straight into a
+ * template gives `[object Object]` — which is what a retired route reported for
+ * a day, hiding both its status and its remedy.
+ */
+function describeFailure(result) {
+  const detail = result.detail ?? result.message ?? result.raw;
+  if (typeof detail === "string" && detail) return detail;
+  if (detail && typeof detail === "object") {
+    return detail.message || detail.code || JSON.stringify(detail);
+  }
+  return "backend error";
+}
+
 export async function callTool(args, tool, toolArguments) {
   const token = resolveApiKey(args);
   if (!token) {
@@ -50,13 +85,17 @@ export async function callTool(args, tool, toolArguments) {
       2,
     );
   }
-  const result = await callBackendJson(args, "POST", "/mcp/call-tool", {
-    json: { tool, arguments: toolArguments },
+  const route = TOOL_ROUTES[tool];
+  if (!route) {
+    throw new CliError(`${tool} is not reachable from the CLI`);
+  }
+  const payload = toolArguments || {};
+  const result = await callBackendJson(args, route.method, route.path, {
     token,
+    ...(route.method === "GET" ? { query: payload } : { json: payload }),
   });
   if (!result.ok) {
-    const detail = result.detail || result.message || result.raw || "backend error";
-    throw new CliError(`${tool} failed: ${result.status_code} ${detail}`);
+    throw new CliError(`${tool} failed: ${result.status_code} ${describeFailure(result)}`);
   }
   return result;
 }

package/bin/cli.js

@@ -91,7 +91,7 @@ function printHelp() {
     ["runner start|status|stop", "Run PreMan's queued agent work on this machine"],
     ["doctor", "Diagnose credentials, backend, target, integrations"],
     ["install-desktop", "Download and install the PreMan desktop app"],
-    ["onboard", "Sign in, map this repo's endpoints, connect it, test on push"],
+    ["onboard", "Create an account, install the app signed in, then integrations"],
     ["connect [options]", "Pick a coding agent and connect it (optional)"],
     ["dispatch [options]", "Let PreMan start agent runs for you"],
     ["aws | github | slack", "Connect one integration on its own"],