opentestmcp 0.3.0 → 0.3.1

package/README.md

@@ -1,54 +1,16 @@
 # OpenTest MCP
 
-AI QA engineer for your IDE. Test UI flows and API endpoints from Cursor, Claude Code, or any MCP-compatible coding agent.
+Turn your APIs into MCP tools that coding agents can discover, call, test, and audit.
 
-## What it does
+OpenTest 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.
 
-- **Test UI flows** in your real Chrome browser -- already logged in, no credential hassle
-- **Test API endpoints** with assertions and variable chaining
-- **Fullstack testing** -- run UI and API tests in parallel
-- **Endpoint registry** -- tested endpoints are automatically shared between backend and frontend agents
-- **`test_endpoint_by_id`** -- run a saved registry endpoint by UUID from `get_endpoints` (no manual URL assembly); optional `body` for login payloads
-
-### Monorepo (Flow backend in this repo)
-
-See repo root **`AGENTS.md`** for **`ot_live_`** API keys, **`POST /mcp/call-tool`**, the **golden path** (`get_endpoints` → `test_api` or `test_endpoint_by_id`), MCP **Apps** / iframe dashboard, and smoke scripts: [`scripts/smoke-call-tool.mjs`](scripts/smoke-call-tool.mjs), [`scripts/smoke-mcp-flow.mjs`](scripts/smoke-mcp-flow.mjs), [`scripts/smoke-local-endpoint-and-mcp.mjs`](scripts/smoke-local-endpoint-and-mcp.mjs).
-
-### Local debug: prove MCP hit your endpoint
-
-If you want to verify local end-to-end behavior (direct endpoint call + MCP `test_api` call against the same URL), run:
-
-```bash
-OPENTEST_BACKEND=http://127.0.0.1:8000 \
-OPENTEST_API_KEY=ot_live_xxx \
-LOGIN_EMAIL=you@example.com \
-LOGIN_PASSWORD=your-password \
-node opentest-mcp/scripts/smoke-local-endpoint-and-mcp.mjs
-```
-
-It prints both responses and a `debug_run` id so you can match backend logs for:
-1. `POST /mcp/call-tool` (tool dispatch)
-2. the target endpoint hit by the MCP tool
-
-### Real endpoints, not fake servers
-
-OpenTest tools hit **your real HTTP APIs** (localhost or deployed). The **`preview_login_mock`** name means a **login-shaped form UI** (Postman-style), not a mocked backend: the browser runs `fetch()` to whatever **`api_base` + path** you set. In **Cursor**, the agent opens that URL in the **Agent Browser tab**, runs the same request you would in Postman, and you see **status + body** in the panel. **`test_api`** is the headless path without a browser tab.
-
-### Deprecation: `preview_login_mock` / mock-login UI (**~2 days**)
-
-**Removal target: 2026-04-08.** This login panel and `preview_login_mock` are in a short deprecation window so we can finish testing **hosted OpenTest MCP** (`OPENTEST_BACKEND`, `POST /mcp/call-tool`, **`test_api`** / **`get_endpoints`** without the local lite server). After that date, migrate to the hosted flow and headless tools; do not extend the mock-login stack.
-
-## Quick Start
-
-### 1. Install in Cursor
-
-Run this once:
+## Install
 
 ```bash
 npx opentestmcp install
 ```
 
-That writes an `opentest` MCP server into `~/.cursor/mcp.json`:
+This writes an `opentest` MCP server into `~/.cursor/mcp.json`:
 
 ```json
 {
@@ -66,7 +28,7 @@ That writes an `opentest` MCP server into `~/.cursor/mcp.json`:
 }
 ```
 
-Replace `ot_live_YOUR_API_KEY_HERE` with your OpenTest API key, then restart Cursor or toggle the MCP server off/on.
+Replace `ot_live_YOUR_API_KEY_HERE` with an API key from OpenTest, then restart Cursor or toggle the MCP server off/on.
 
 You can also pass the key directly:
 
@@ -74,21 +36,50 @@ You can also pass the key directly:
 npx opentestmcp install --api-key ot_live_xxx
 ```
 
-For a project-local config, run:
+For project-local installation:
 
 ```bash
 npx opentestmcp install --project
 ```
 
-### 2. Add to Claude Code
+## What It Does
 
-```bash
-claude mcp add opentest -- npx -y opentest
+- 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 OpenTest 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 OpenTest to list my endpoints.
+```
+
+```text
+Use OpenTest to test POST /auth/login.
+```
+
+```text
+Convert these endpoints into an MCP.
+```
+
+```text
+Show me the audit log for this hosted MCP.
 ```
 
-### 3. Add to Cursor manually
+## Cursor
 
-Add to `.cursor/mcp.json`:
+The installer targets Cursor by default:
+
+```bash
+npx opentestmcp install
+```
+
+Manual Cursor config:
 
 ```json
 {
@@ -104,127 +95,42 @@ Add to `.cursor/mcp.json`:
 }
 ```
 
-### 4. Authenticate (one time)
-
-No manual API key needed. Just ask your agent:
-
-> "Log in to OpenTest"
-
-This runs the `opentest_login` tool which:
-1. Starts a device authorization flow
-2. Opens a browser link where you approve access
-3. Stores the API key locally at `~/.opentest/credentials.json`
+## Claude Code
 
-You only need to do this once — credentials persist across sessions. You can also set `OPENTEST_API_KEY` in the env config if you prefer manual key management.
-
-### 5. Install the Chrome extension (optional)
-
-For browser testing, load the extension:
-
-1. Open `chrome://extensions`
-2. Enable "Developer mode"
-3. Click "Load unpacked"
-4. Select the `browser/` folder from this package
-
-### 6. Start testing
-
-In your IDE, just ask:
-
-> "Test the signup flow on localhost:3000"
-
-> "Test POST /api/users with email test@example.com"
-
-> "Run fullstack test: signup UI + POST /api/users in parallel"
-
-## Inline Visual Results (MCP Apps)
-
-When you call OpenTest tools from supported clients (Claude, VS Code, Goose), you'll see interactive results rendered directly in the conversation:
-
-- **test_api** -- Editable API console in the IDE: method, full URL, headers/body JSON, response, inferred schema, and re-send without a new chat message
-- **test_endpoint_by_id** -- Same as test_api but keyed by registry UUID from get_endpoints; optional body for login payloads
-- **get_endpoints** -- Structured JSON endpoint registry; use `open_endpoints_ui` for the visual dashboard (grouped by tested/needed/draft where the client shows the inline panel)
-- **test_flow** -- Step-by-step browser test progress; the MCP server also opens the **starting URL** in your default browser so you can watch the live tab (Hanzi extension). Inline panel shows task + results.
-- **import_collection** (Postman / OpenAPI / Bruno / curl) -- Inline panel: generated `.ot.yaml`, per-endpoint request/response schemas when present, dashboard id when saved
-- **generate_tests** -- Generated YAML, scenario counts, and save instructions
-- **get_coverage** -- Coverage score, top gaps, and summary
-- **detect_drift** -- Drift rows with severity and assertion/connection details
-
-These tools attach `_meta` with a `ui://` resource (`collection-inspector.html`) so the IDE can render the panel (same MCP Apps pattern as `test_api`).
-
-- **preview_login_mock** — **IDE login / Postman panel** (real `fetch` to your API): set **`api_base`** + **`login_path`**, POST JSON `{ email, password }`, see status/body and inferred shape. Not a mock server—only the form is a small static page. Pair with **`test_api`** for headless-only. Example: `api_base: "http://127.0.0.1:8000"`, `login_path: "/auth/login"`, then **Send login request** or let the agent navigate + click in **Agent Browser**.
-
-**Cursor — inline browser (recommended):** Enable **Agent Browser** ([Cursor docs: Agent → Browser](https://cursor.com/docs/agent/browser)). After `preview_login_mock`, the tool returns **`mock_login_http_url`**; the agent should use **Browser → navigate** to that URL so the mock login opens **inside Cursor** (tab/pane), not only in external Chrome.
-
-**If Browser tools do not appear:** Open **Cursor Settings**, enable the **Browser / Agent Browser** integration (enterprise: admins may need to toggle Browser under MCP). Then ask again to navigate to `mock_login_http_url`.
-
-**Cursor:** `preview_login_mock` does **not** open Safari/Chrome by default (only the **Agent Browser** via `browser_navigate` to `mock_login_http_url`). Set **`OPENTEST_OPEN_MOCK_LOGIN=1`** if you also want the **OS default browser** tab. Or run `npm run open-mock-login` / open `dist/ui/src/ui/mock-login-lite.html` manually after `npm run build`.
-
-The inline MCP UI panel and Cursor Agent Browser (`browser_navigate` on `ui.url`) are the supported surfaces — the MCP server no longer auto-opens system or Playwright browser windows.
-
-Click **Re-send from editor** (or **Send**) to re-run API tests without typing a new message.
-
-### Supported Clients
-- Claude (web + desktop)
-- VS Code (GitHub Copilot)
-- Goose
-- ChatGPT
-
-## MCP Tools
-
-| Tool | What it does |
-|------|-------------|
-| `opentest_login` | One-time device auth — opens browser link, stores API key locally |
-| `opentest_login_complete` | Finishes the login flow after browser approval |
-| `opentest_status` | Check authentication status and connection info |
-| `opentest_logout` | Clear stored credentials and log out |
-| `test_flow` | Test a UI flow in your real Chrome browser |
-| `test_api` | Test an API endpoint with assertions |
-| `test_fullstack` | Run UI + API tests in parallel |
-| `get_endpoints` | Structured JSON inventory of endpoints (registry, sessions, collections) |
-| `endpoints_dashboard` | Aggregated endpoint summary from all sources (structured JSON) |
-| `open_endpoints_ui` | Open the visual endpoints dashboard in the browser |
-| `need_endpoint` | Declare an endpoint the frontend needs |
-| `browser_screenshot` | Capture the current browser page |
-| `import_api_spec` | Import OpenAPI/Swagger/Postman specs |
-| `auto_test` | Auto-discover and test all API endpoints |
+```bash
+claude mcp add opentest -- npx -y opentestmcp
+```
 
-## CLI Options
+## CLI
 
-```
-npx opentestmcp                         # Start — uses stored credentials or OPENTEST_API_KEY
-npx opentestmcp --local                 # Local only, no dashboard sync
+```bash
+npx opentestmcp                         # Start the MCP server
 npx opentestmcp install                 # Install Cursor MCP config
+npx opentestmcp install --print         # Print config without writing
+npx opentestmcp install --project       # Write .cursor/mcp.json in current repo
+npx opentestmcp install --api-key KEY   # Install with your OpenTest API key
 ```
 
-Environment variables:
-
-- `OPENTEST_API_KEY` -- Manual API key override (skips device auth / stored credentials)
-- `OPENTEST_BACKEND` -- Backend URL (default: `https://flow.opentest.live`)
-- `OPENTEST_FRONTEND` -- Frontend URL (default: `https://www.flowtest.opentest.live`; use `www` to match the live site and avoid apex/`www` redirect issues in embedded browsers)
-
-Tool responses and **`endpoints_page_url`** use the SPA entry: `/?agent_session=<uuid>&ot_agent_route=/endpoints` (and similar routes) so the first request always loads `index.html` on static hosting. The Flow app should read **`ot_agent_route`** on boot and run client-side **`navigate()`** to that path.
-
-## Dashboard (Optional)
+Options:
 
-Sign up at [flow.opentest.live](https://flow.opentest.live) for:
-- Team endpoint registry
-- Test history and video recordings
-- Jira/Slack integration
-- Scheduled test runs
+- `--api-key <key>`: OpenTest API key.
+- `--backend <url>`: OpenTest backend URL. Defaults to `https://flow.opentest.live`.
+- `--frontend <url>`: OpenTest frontend URL. Defaults to `https://www.flowtest.opentest.live`.
+- `--name <name>`: MCP server name. Defaults to `opentest`.
+- `--project`: Write `.cursor/mcp.json` in the current project.
+- `--print`: Print the generated MCP config without writing it.
 
-```bash
-OPENTEST_API_KEY=ot_live_your_api_key npx opentestmcp
-```
+## Environment Variables
 
-## Python MCP Server
+- `OPENTEST_API_KEY`: OpenTest API key.
+- `OPENTEST_BACKEND`: OpenTest backend URL.
+- `OPENTEST_FRONTEND`: OpenTest frontend URL.
 
-This package also includes a Python MCP server for API-only testing via `uvx`:
+## Product
 
-```bash
-uvx opentest-mcp --project-dir ./
-```
+OpenTest 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 OpenTest.
 
-See `pyproject.toml` for Python package details.
+Dashboard: [https://flowtest.opentest.live](https://flowtest.opentest.live)
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opentestmcp",
-  "version": "0.3.0",
-  "description": "AI QA engineer for your IDE — test UI flows and API endpoints with inline visual results",
+  "version": "0.3.1",
+  "description": "Turn APIs into agent-callable MCP tools with auth, testing, and audit logs",
   "type": "module",
   "bin": {
     "opentestmcp": "bin/cli.js",
@@ -24,20 +24,22 @@
   },
   "keywords": [
     "mcp",
-    "testing",
-    "qa",
-    "mcp-apps",
-    "playwright",
-    "browser-automation",
     "api-testing",
+    "api",
+    "agents",
+    "agent-tools",
+    "audit",
+    "auth",
+    "hosted-mcp",
     "cursor",
     "claude-code"
   ],
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/anthropics/opentest-mcp.git"
+    "url": "git+https://github.com/Watcher1223/YC-Hackathon-Backend.git"
   },
+  "homepage": "https://flowtest.opentest.live",
   "engines": {
     "node": ">=18"
   },