premanmcp 0.3.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PreMan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# PreMan MCP
+
+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.
+
+## Install
+
+```bash
+npx premanmcp install
+```
+
+This writes an `preman` MCP server into `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "preman": {
+      "command": "npx",
+      "args": ["-y", "premanmcp"],
+      "env": {
+        "PREMAN_API_KEY": "pm_live_YOUR_API_KEY_HERE",
+        "PREMAN_BACKEND": "https://api.preman.live",
+        "PREMAN_FRONTEND": "https://app.preman.live"
+      }
+    }
+  }
+}
+```
+
+Replace `pm_live_YOUR_API_KEY_HERE` with an API key from [PreMan settings](https://app.preman.live/settings/), then restart Cursor or toggle the MCP server off/on.
+
+You can also pass the key directly:
+
+```bash
+npx premanmcp install --api-key pm_live_xxx
+```
+
+For project-local installation:
+
+```bash
+npx premanmcp install --project
+```
+
+## What It Does
+
+- Converts API endpoints into agent-callable MCP tools.
+- 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.
+
+## Common Agent Commands
+
+After installing, ask your coding agent:
+
+```text
+Use the PreMan MCP to convert my login endpoint into an MCP tool.
+```
+
+```text
+Use PreMan to test POST /auth/login.
+```
+
+```text
+Convert these endpoints into an MCP.
+```
+
+```text
+Show me the audit log for this hosted MCP.
+```
+
+## Cursor
+
+The installer targets Cursor by default:
+
+```bash
+npx premanmcp install
+```
+
+Manual Cursor config:
+
+```json
+{
+  "mcpServers": {
+    "preman": {
+      "command": "npx",
+      "args": ["-y", "premanmcp"],
+      "env": {
+        "PREMAN_API_KEY": "pm_live_YOUR_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+## Claude Code
+
+```bash
+claude mcp add preman -- npx -y premanmcp
+```
+
+## CLI
+
+```bash
+npx premanmcp                         # Start the MCP server
+npx premanmcp install                 # Install Cursor MCP config
+npx premanmcp install --print         # Print config without writing
+npx premanmcp install --project       # Write .cursor/mcp.json in current repo
+npx premanmcp install --api-key KEY   # Install with your PreMan API key
+```
+
+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.
+- `--print`: Print the generated MCP config without writing it.
+
+## Environment Variables
+
+- `PREMAN_API_KEY`: PreMan API key.
+- `PREMAN_BACKEND`: PreMan backend URL.
+- `PREMAN_FRONTEND`: PreMan frontend URL.
+
+## 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.
+
+Dashboard: [https://app.preman.live](https://app.preman.live)
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+/**
+ * PreMan CLI.
+ *
+ * Usage:
+ *   npx premanmcp install
+ *   npx premanmcp install --api-key pm_live_xxx
+ *   npx premanmcp
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.join(__dirname, "..");
+const DEFAULT_BACKEND = "https://api.preman.live";
+const DEFAULT_FRONTEND = "https://app.preman.live";
+const API_KEY_PLACEHOLDER = "pm_live_YOUR_API_KEY_HERE";
+
+const args = process.argv.slice(2);
+const command = args[0] === "--help" || args[0] === "-h"
+  ? "help"
+  : args[0] && !args[0].startsWith("-")
+    ? args[0]
+    : "start";
+const commandArgs = command === "start" ? args : args.slice(1);
+
+function argValue(name, fallback = "") {
+  const index = commandArgs.indexOf(name);
+  if (index === -1) return fallback;
+  return commandArgs[index + 1] || fallback;
+}
+
+function hasFlag(name) {
+  return commandArgs.includes(name);
+}
+
+function printHelp() {
+  process.stdout.write(`PreMan MCP
+
+Usage:
+  npx premanmcp install [options]  Install PreMan into Cursor MCP config
+  npx premanmcp                   Start the PreMan MCP server
+
+Install options:
+  --api-key <key>       PreMan API key. Defaults to ${API_KEY_PLACEHOLDER}
+  --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
+  --frontend <url>      PreMan frontend URL. Defaults to ${DEFAULT_FRONTEND}
+  --name <name>         MCP server name. Defaults to preman
+  --project             Write .cursor/mcp.json in the current project
+  --global              Write ~/.cursor/mcp.json (default)
+  --print               Print the config instead of writing it
+
+Examples:
+  npx premanmcp install
+  npx premanmcp install --api-key pm_live_xxx
+  npx premanmcp install --project --backend http://127.0.0.1:8000
+`);
+}
+
+function readJsonFile(filePath) {
+  if (!existsSync(filePath)) return {};
+  const raw = readFileSync(filePath, "utf8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`Could not parse ${filePath}: ${error.message}`);
+  }
+}
+
+function buildServerConfig() {
+  const apiKey = argValue("--api-key", process.env.PREMAN_API_KEY || API_KEY_PLACEHOLDER);
+  const backend = argValue("--backend", process.env.PREMAN_BACKEND || DEFAULT_BACKEND);
+  const frontend = argValue("--frontend", process.env.PREMAN_FRONTEND || DEFAULT_FRONTEND);
+
+  return {
+    command: "npx",
+    args: ["-y", "premanmcp"],
+    env: {
+      PREMAN_API_KEY: apiKey,
+      PREMAN_BACKEND: backend,
+      PREMAN_FRONTEND: frontend,
+    },
+  };
+}
+
+function installCursorMcp() {
+  const serverName = argValue("--name", "preman");
+  const projectInstall = hasFlag("--project");
+  const serverConfig = buildServerConfig();
+
+  if (hasFlag("--print")) {
+    process.stdout.write(`${JSON.stringify({ mcpServers: { [serverName]: serverConfig } }, null, 2)}\n`);
+    return;
+  }
+
+  const configPath = projectInstall
+    ? path.join(process.cwd(), ".cursor", "mcp.json")
+    : path.join(os.homedir(), ".cursor", "mcp.json");
+
+  const config = {
+    ...readJsonFile(configPath),
+  };
+  config.mcpServers = {
+    ...(config.mcpServers || {}),
+    [serverName]: serverConfig,
+  };
+
+  const rendered = `${JSON.stringify(config, null, 2)}\n`;
+  mkdirSync(path.dirname(configPath), { recursive: true });
+  writeFileSync(configPath, rendered, { mode: 0o600 });
+
+  const usedPlaceholder = config.mcpServers[serverName].env.PREMAN_API_KEY === API_KEY_PLACEHOLDER;
+  process.stdout.write(`PreMan MCP installed in ${configPath}
+
+Server name: ${serverName}
+Backend: ${config.mcpServers[serverName].env.PREMAN_BACKEND}
+
+Next steps:
+1. ${usedPlaceholder ? `Replace ${API_KEY_PLACEHOLDER} with your PreMan API key in ${configPath}. Find or create one at https://app.preman.live/settings/.` : "Your PreMan API key was written to the MCP config."}
+2. Restart Cursor or toggle the PreMan MCP server off/on.
+3. Ask your agent: "Use the PreMan MCP to convert my login endpoint into an MCP tool." Then open https://app.preman.live/ to see the session and generated MCP.
+`);
+}
+
+function startServer() {
+  const serverPath = path.join(ROOT, "dist", "server.js");
+  if (!existsSync(serverPath)) {
+    process.stderr.write(`[preman] MCP server not found at ${serverPath}. Run npm run build before publishing.\n`);
+    process.exit(1);
+  }
+
+  const env = { ...process.env };
+  const apiKey = argValue("--api-key", argValue("--key", ""));
+  const backend = argValue("--backend", "");
+  const frontend = argValue("--frontend", "");
+  if (apiKey) env.PREMAN_API_KEY = apiKey;
+  if (backend) env.PREMAN_BACKEND = backend;
+  if (frontend) env.PREMAN_FRONTEND = frontend;
+  if (hasFlag("--local")) env.PREMAN_BACKEND = "";
+
+  const child = spawn(process.execPath, [serverPath, ...commandArgs], {
+    env,
+    stdio: "inherit",
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) process.kill(process.pid, signal);
+    process.exit(code || 0);
+  });
+}
+
+if (command === "install") {
+  installCursorMcp();
+} else if (command === "help" || command === "--help" || command === "-h") {
+  printHelp();
+} else if (command === "start") {
+  startServer();
+} else {
+  process.stderr.write(`Unknown command: ${command}\n\n`);
+  printHelp();
+  process.exit(1);
+}

package/dist/auth_flow_ui.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Auth flow endpoints (signup, verify OTP, login, resend OTP) with JSON schemas
+ * for share_endpoints_with_ui / agent-sessions push.
+ */
+export type AuthFlowEndpoint = {
+    method: string;
+    path_template: string;
+    description: string;
+    tags: string[];
+    source_file: string;
+    request_body_schema: Record<string, unknown>;
+    response_schema: Record<string, unknown>;
+    mcp_tool?: string;
+};
+/** Core auth endpoints aligned with routes/auth/routes.py and user_auth_* MCP tools. */
+export declare function buildAuthFlowEndpoints(): AuthFlowEndpoint[];
+export type ShareAuthFlowResult = {
+    session_id: string;
+    url: string;
+    endpoint_count: number;
+    upstream_base_url: string;
+    endpoints: AuthFlowEndpoint[];
+    ui: {
+        url: string;
+        note: string;
+    };
+    related_tools: string[];
+};
+export declare function shareAuthFlowToUi(opts: {
+    backendUrl: string;
+    frontendUrl: string;
+    upstreamBaseUrl?: string;
+    sessionId?: string;
+    intent?: string;
+}): Promise<ShareAuthFlowResult>;

package/dist/auth_flow_ui.js

@@ -0,0 +1,159 @@
+/**
+ * Auth flow endpoints (signup, verify OTP, login, resend OTP) with JSON schemas
+ * for share_endpoints_with_ui / agent-sessions push.
+ */
+const EMAIL_PROP = { type: "string", format: "email", description: "User email" };
+const PASSWORD_PROP = {
+    type: "string",
+    minLength: 6,
+    description: "Password (min 6 characters on the server)",
+};
+const OTP_PROP = { type: "string", description: "6-digit code from email" };
+const TOKEN_RESPONSE = {
+    type: "object",
+    properties: {
+        access_token: { type: "string", description: "JWT bearer token" },
+        token_type: { type: "string", enum: ["bearer"] },
+        user: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                email: { type: "string", format: "email" },
+            },
+            required: ["id", "email"],
+        },
+    },
+    required: ["access_token", "token_type", "user"],
+};
+const OTP_SENT_RESPONSE = {
+    type: "object",
+    properties: {
+        message: { type: "string" },
+        email_sent: { type: "boolean" },
+    },
+    required: ["message", "email_sent"],
+};
+/** Core auth endpoints aligned with routes/auth/routes.py and user_auth_* MCP tools. */
+export function buildAuthFlowEndpoints() {
+    return [
+        {
+            method: "POST",
+            path_template: "/auth/signup",
+            description: "Register with email and password. Sends OTP to email; next: verify-otp.",
+            tags: ["auth", "signup"],
+            source_file: "routes/auth/routes.py",
+            mcp_tool: "user_auth_signup",
+            request_body_schema: {
+                type: "object",
+                properties: { email: EMAIL_PROP, password: PASSWORD_PROP },
+                required: ["email", "password"],
+                additionalProperties: false,
+            },
+            response_schema: {
+                type: "object",
+                properties: {
+                    message: { type: "string" },
+                    user_id: { type: "string" },
+                    email: { type: "string", format: "email" },
+                    email_sent: { type: "boolean" },
+                },
+                required: ["message", "user_id", "email", "email_sent"],
+            },
+        },
+        {
+            method: "POST",
+            path_template: "/auth/verify-otp",
+            description: "Verify email OTP after signup; returns JWT access_token.",
+            tags: ["auth", "otp"],
+            source_file: "routes/auth/routes.py",
+            mcp_tool: "user_auth_verify_otp",
+            request_body_schema: {
+                type: "object",
+                properties: { email: EMAIL_PROP, otp: OTP_PROP },
+                required: ["email", "otp"],
+                additionalProperties: false,
+            },
+            response_schema: TOKEN_RESPONSE,
+        },
+        {
+            method: "POST",
+            path_template: "/auth/login",
+            description: "Login with email and password. Returns access_token if email is verified.",
+            tags: ["auth", "login"],
+            source_file: "routes/auth/routes.py",
+            mcp_tool: "user_auth_login",
+            request_body_schema: {
+                type: "object",
+                properties: { email: EMAIL_PROP, password: PASSWORD_PROP },
+                required: ["email", "password"],
+                additionalProperties: false,
+            },
+            response_schema: TOKEN_RESPONSE,
+        },
+        {
+            method: "POST",
+            path_template: "/auth/resend-otp",
+            description: "Send (resend) verification OTP to email.",
+            tags: ["auth", "otp"],
+            source_file: "routes/auth/routes.py",
+            mcp_tool: "user_auth_resend_otp",
+            request_body_schema: {
+                type: "object",
+                properties: { email: EMAIL_PROP },
+                required: ["email"],
+                additionalProperties: false,
+            },
+            response_schema: OTP_SENT_RESPONSE,
+        },
+    ];
+}
+export async function shareAuthFlowToUi(opts) {
+    const backend = opts.backendUrl.replace(/\/+$/, "");
+    const frontend = opts.frontendUrl.replace(/\/+$/, "");
+    const upstream = (opts.upstreamBaseUrl || backend).replace(/\/+$/, "") || backend;
+    const sessionId = opts.sessionId?.trim() || crypto.randomUUID();
+    const endpoints = buildAuthFlowEndpoints().map((ep) => ({
+        ...ep,
+        base_url: upstream,
+    }));
+    const resp = await fetch(`${backend}/agent-sessions/${encodeURIComponent(sessionId)}/endpoints`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({
+            endpoints,
+            upstream_base_url: upstream,
+            intent: opts.intent || "Auth flow: signup, verify OTP, login, resend OTP",
+        }),
+    });
+    const text = await resp.text();
+    let body = {};
+    try {
+        body = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new Error(`Agent session push failed: ${resp.status} ${text.slice(0, 500)}`);
+    }
+    if (!resp.ok) {
+        throw new Error(String(body.detail ?? body.error ?? `Agent session push failed: ${resp.status}`));
+    }
+    const sid = String(body.id ?? sessionId);
+    const url = `${frontend}/try?session=${encodeURIComponent(sid)}`;
+    return {
+        session_id: sid,
+        url,
+        endpoint_count: Number(body.endpoint_count ?? endpoints.length),
+        upstream_base_url: upstream,
+        endpoints: buildAuthFlowEndpoints(),
+        ui: {
+            url,
+            note: "Open in Cursor Agent Browser. Test signup → verify-otp → login, or resend-otp. " +
+                "Schemas are prefilled from routes/auth Pydantic models.",
+        },
+        related_tools: [
+            "user_auth_signup",
+            "user_auth_verify_otp",
+            "user_auth_login",
+            "user_auth_resend_otp",
+        ],
+    };
+}

package/dist/mcp-preview-panel.d.ts

@@ -0,0 +1,30 @@
+export declare const MCP_PREVIEW_RESOURCE_URI = "ui://preman/mcp-preview";
+export declare const RESOURCE_URI_META_KEY = "ui/resourceUri";
+export declare function escapeHtmlAttr(s: string): string;
+export declare function escapeHtmlText(s: string): string;
+export interface PreviewTool {
+    name?: string;
+    description?: string;
+    inputSchema?: unknown;
+    _endpoint_ref?: {
+        method?: string;
+        path_template?: string;
+        tags?: string[];
+        source?: string;
+    };
+}
+export interface PreviewPayload {
+    intent?: string | string[];
+    selection_method?: string | string[];
+    rationale?: string | string[] | Record<string, string>;
+    selected_count?: number;
+    spec_preview?: {
+        upstream_base_url?: string | string[];
+        tools?: PreviewTool[];
+    };
+}
+export declare function buildConversionPanelHtml(data: PreviewPayload): string;
+export declare function writeMcpPreviewFile(panelHtml: string): Promise<{
+    absolutePath: string;
+    fileUrl: string;
+}>;