@predotdev/mcp 0.0.0-stage → 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pre.dev
+
+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

@@ -1,3 +1,383 @@
-# Temporary Holding Version
+<p align="center">
+  <a href="https://pre.dev/browser-agents">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="assets/predev-logo-white.png">
+      <img alt="pre.dev" src="assets/predev-logo-dark.png" width="240">
+    </picture>
+  </a>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">pre.dev MCP</h1>
+
+<p align="center">
+  <b>pre.dev in every coding agent.</b><br>
+  Browser agents in the Chrome you already have open and in the cloud, plus specs and plans. One command to set up. Free and open source.
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-black"></a>
+  <a href="https://www.npmjs.com/package/@predotdev/mcp"><img alt="npm" src="https://img.shields.io/npm/v/@predotdev/mcp?color=black"></a>
+  <img alt="Node 22+" src="https://img.shields.io/badge/node-22%2B-black">
+  <img alt="macOS" src="https://img.shields.io/badge/macOS-supported-black">
+  <img alt="Zero dependencies" src="https://img.shields.io/badge/dependencies-0-black">
+  <a href="https://pre.dev"><img alt="pre.dev" src="https://img.shields.io/badge/made%20by-pre.dev-black"></a>
+</p>
+
+---
+
+One MCP server gives your coding agent everything pre.dev does:
+
+- **Browser Agents Local: your own Chrome.** Open a tab in your work profile, read a dashboard you are already logged into, fill in a form, click through a flow and screenshot the result, all in the Chrome you use every day. No second browser, nothing to log into again, no cookies copied anywhere.
+- **Browser Agents in the cloud.** Send a URL and a task to pre.dev's browsers and get structured data back, many runs in parallel.
+- **Specs and plans.** Plan an app or feature before building it: architecture, tech stack, milestones and user stories.
+
+It works with **any coding agent that runs MCP servers locally**: Claude Code, Codex, Cursor, Windsurf, VS Code, Gemini CLI, OpenCode, Claude Desktop and more. Run as many agents as you like at the same time. They all share one connection to Chrome, so Chrome only asks you to allow it once.
+
+Built with the [pre.dev CLI](https://docs.pre.dev/cli/overview).
+
+## Quick start
+
+You need **macOS**, **Google Chrome** and **Node.js 22 or newer** (check with `node --version`). Run one command:
+
+```bash
+npx -y @predotdev/mcp setup
+```
+
+It walks you through everything:
+
+1. **Signs you in to pre.dev** in your browser (or creates a free account). Approve, and your key is saved for every agent. Nothing to copy.
+2. **Adds it to every coding agent on your Mac**: Claude Code, Codex, Cursor, Windsurf, VS Code, Gemini CLI, OpenCode and Claude Desktop. Already using the hosted pre.dev MCP? This one includes all of its tools, so setup replaces it.
+3. **Connects to Chrome.** The first time, it asks you to turn on remote debugging at `chrome://inspect/#remote-debugging` (it copies the address for you), and Chrome asks **"Allow remote debugging?"**: click **Allow**.
+
+Then restart your agent and try:
+
+> List my Chrome profiles and the tabs I have open.
+
+> [!TIP]
+> **Or let your agent do it.** Paste this into Claude Code (or any coding agent):
+> *Run `npx -y @predotdev/mcp setup` with a 10 minute timeout and tell me what to click.*
+
+The command is safe to run again at any time, and running it again updates to the latest version. `npx -y @predotdev/mcp check` shows the state of everything, and `uninstall` removes it from every agent.
+
+## Local or cloud?
+
+Both editions of pre.dev Browser Agents are in this server, and your agent picks per task.
+
+| | **Local** (`chrome_*` tools) | **[Cloud](https://docs.pre.dev/browser-agents/overview)** (`browser_agent`) |
+| --- | --- | --- |
+| Runs in | Your own Chrome | pre.dev's browsers |
+| Logged in as | You, in every profile you use | Nobody (public pages) |
+| Driven by | Your coding agent, step by step | One API call with a URL and a task |
+| Best for | Dashboards, internal tools, admin panels, anything behind your login | Structured data from public sites, many runs in parallel |
+| Also available | Only here | The REST API and SDKs |
+
+## What your agent can do
+
+**In your own Chrome** (run on your Mac):
+
+| Tool | What it does |
+| --- | --- |
+| `chrome_profiles` | List your Chrome profiles (name, Google account) and how many tabs each has open |
+| `chrome_tabs` | List open tabs grouped by profile |
+| `chrome_open` | Open a URL in a specific profile, in the background by default so you are not interrupted |
+| `chrome_navigate` | Load a URL in a tab, or go back, forward or reload |
+| `chrome_snapshot` | List the clickable and typeable elements on a page as short refs (`[e1]`, `[e2]`, ...) |
+| `chrome_click` | Click by ref, CSS selector, visible text or coordinates, with real mouse events |
+| `chrome_type` | Type into inputs, text areas, rich editors and dropdowns |
+| `chrome_act` | Click or type into an element described in plain words, in one call ([plain-words actions](#plain-words-actions)) |
+| `chrome_press` | Press keys and shortcuts (`Enter`, `Tab`, `cmd+a`, `shift+Tab`) |
+| `chrome_scroll` | Scroll the page or bring an element into view |
+| `chrome_read` | Read a page's text, paged for long pages |
+| `chrome_screenshot` | Screenshot the visible area or the full page |
+| `chrome_wait` | Wait for text, a selector, a URL change, or a plain-words condition |
+| `chrome_eval` | Run JavaScript in the page and return the result |
+| `chrome_upload` | Attach local files to an upload button or file input |
+| `chrome_show` | Bring a tab to the front so you can see it or take over |
+| `chrome_close` | Close a tab |
+
+**In pre.dev's cloud** (need a pre.dev plan; on the free plan your agent sees them and can open the subscribe page for you):
+
+| Tool | What it does |
+| --- | --- |
+| `browser_agent` | Run one or more tasks in pre.dev's cloud browsers: a URL plus an instruction or a JSON Schema for the output; returns each task's data |
+| `browser_agent_list` / `browser_agent_get` | Earlier cloud runs, and one run with its step-by-step events |
+| `fast_spec` / `deep_spec` | Plan an app or feature: architecture, tech stack, milestones and user stories (`deep_spec` adds subtasks) |
+| `get_spec` / `list_specs` | A spec's status and result, and the specs you have made |
+| `get_plan` | The verified plan of a project you own |
+
+This is what your agent sees when it takes a snapshot:
+
+```
+Tab A137CF · Work <you@company.com> · Create your account
+https://example.com/signup
+Headings: "Create your account"
+Scroll: 0/640px
+[e1] textbox "Full name"
+[e2] textbox "Email" value="you@company.com"
+[e3] select "Plan" selected="Free"
+[e4] checkbox "I agree to the terms" [unchecked]
+[e5] button "Create account"
+```
+
+Every tab is labeled with the profile it belongs to, so the agent always knows which account it is acting as.
+
+## Plain-words actions
+
+Once you are signed in to pre.dev (`setup` or `login` does it, or set `PREDEV_API_KEY`), two things turn on:
+
+- `chrome_act`: click or type into an element described in plain words, like *"the Create button in the dialog"*, in under a second with no snapshot needed. If it isn't sure, it lists the likely matches instead of guessing.
+- `chrome_wait` with `condition`: wait until a plain-words statement about the page is true, like *"the export has finished"*.
+
+**Pricing.** The MCP server is free and open source, and the Chrome tools run free on your Mac. Plain-words actions and the cloud tools use pre.dev credits, the same credits as the rest of pre.dev ([pricing](https://pre.dev/pricing)). Each action costs a small fraction of one credit, and the free trial's credits cover more than a thousand actions. They show up in your usage as `browser-agents-local`, and `check` shows your plan. If the free plan's allowance or your credits run out, your agent tells you and offers to open the [billing page](https://pre.dev/billing) in your Chrome; everything else keeps working. Every other tool runs entirely on your machine and never calls pre.dev.
+
+## Setup for every agent
+
+`setup` does this for you. To add it by hand instead (for example to an agent `setup` doesn't know), every agent runs the same command. Sign in once with `npx -y @predotdev/mcp login` and leave the key out, or put your key from [Integrations → Built-in](https://pre.dev/projects/integrations) in the agent's environment:
+
+```
+npx -y @predotdev/mcp        env: PREDEV_API_KEY=your_key   (optional after login)
+```
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+```bash
+claude mcp add --scope user predev -e PREDEV_API_KEY=your_key -- npx -y @predotdev/mcp
+```
+
+</details>
+
+<details>
+<summary><b>Codex</b></summary>
+
+```bash
+codex mcp add predev --env PREDEV_API_KEY=your_key -- npx -y @predotdev/mcp
+```
+
+Or add this to `~/.codex/config.toml`. The longer timeout gives specs and cloud runs time to finish:
+
+```toml
+[mcp_servers.predev]
+command = "npx"
+args = ["-y", "@predotdev/mcp"]
+env = { PREDEV_API_KEY = "your_key" }
+tool_timeout_sec = 900
+```
+
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+Add to `~/.cursor/mcp.json`, then restart Cursor:
+
+```json
+{
+  "mcpServers": {
+    "predev": {
+      "command": "npx",
+      "args": ["-y", "@predotdev/mcp"],
+      "env": { "PREDEV_API_KEY": "your_key" }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Windsurf</b></summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`, then restart Windsurf:
+
+```json
+{
+  "mcpServers": {
+    "predev": {
+      "command": "npx",
+      "args": ["-y", "@predotdev/mcp"],
+      "env": { "PREDEV_API_KEY": "your_key" }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>VS Code (Copilot agent mode)</b></summary>
+
+Add to `.vscode/mcp.json` in your project, or run **MCP: Open User Configuration** to add it for every project:
+
+```json
+{
+  "servers": {
+    "predev": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@predotdev/mcp"],
+      "env": { "PREDEV_API_KEY": "your_key" }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Gemini CLI</b></summary>
+
+Add to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "predev": {
+      "command": "npx",
+      "args": ["-y", "@predotdev/mcp"],
+      "env": { "PREDEV_API_KEY": "your_key" }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>OpenCode</b></summary>
+
+Add to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "mcp": {
+    "predev": {
+      "type": "local",
+      "command": ["npx", "-y", "@predotdev/mcp"],
+      "environment": { "PREDEV_API_KEY": "your_key" },
+      "enabled": true
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Claude Desktop</b></summary>
+
+Desktop apps don't load your shell's `PATH`, so give them full paths. Install once:
+
+```bash
+npm install -g @predotdev/mcp
+```
+
+Then print the exact entry to paste:
+
+```bash
+echo "\"predev\": {\"command\": \"$(which node)\", \"args\": [\"$(npm root -g)/@predotdev/mcp/src/bridge.mjs\"], \"env\": {\"PREDEV_API_KEY\": \"your_key\"}}"
+```
+
+Put that entry inside `"mcpServers"` in `~/Library/Application Support/Claude/claude_desktop_config.json`, replace `your_key`, then restart Claude Desktop. The same trick works for any app that says it can't find `npx` or `node`.
+
+</details>
+
+<details>
+<summary><b>Any other MCP client</b></summary>
+
+Add a local (stdio) server with command `npx`, arguments `-y @predotdev/mcp`, and the environment variable `PREDEV_API_KEY`. If the client can't find `npx`, use the full-path setup from the Claude Desktop section.
+
+</details>
+
+## How it works
+
+```mermaid
+flowchart LR
+  A["Claude Code"] --> D
+  B["Codex"] --> D
+  C["Cursor"] --> D
+  D["pre.dev MCP background process<br/>(one per Chrome)"] -- "one approved connection" --> E["Your Chrome<br/>(every profile)"]
+  D -. "plain-words actions and cloud tools" .-> F["pre.dev API"]
+```
+
+- Chrome asks you to approve each debugging connection. Instead of every agent opening its own connection (and its own prompt), the first agent starts a small background process that holds **one** connection, and every agent talks to it. You click Allow once each time Chrome starts.
+- Each agent uses its own pre.dev API key, even though they share the connection.
+- The cloud tools are pre.dev's hosted MCP tools, passed through on the same key, so they stay current without updating this package.
+- Tabs open in the background by default and are kept responsive while an agent works in them, so you can keep using Chrome.
+- Snapshots reach into shadow DOM and same-origin iframes, and clicks are real mouse events, so modern web apps behave the way they do for you.
+- It has no dependencies: plain Node.js talking to Chrome's DevTools Protocol.
+
+## Safety
+
+This tool drives your real, logged-in Chrome. Read this before you turn it on.
+
+- **Anything you can do in a tab, the agent can do.** Only connect agents you trust, and keep an eye on what they do on sensitive sites. `chrome_eval` runs JavaScript in the page.
+- **Passwords stay with you.** It refuses to type into password fields (except on `localhost` and `.test` dev sites) and masks password values in snapshots. The agent is told never to enter passwords, payment details or government ID numbers.
+- **It only listens on your machine.** The background process binds to `127.0.0.1` only and rejects requests without a random per-run token, which is stored in a file only you can read. It also rejects any request that comes from a web page.
+- **What leaves your machine.** Plain-words actions send pre.dev the page's interactive elements and visible text for that one action, and the cloud tools send what you ask them to do. The other Chrome tools run locally.
+- **Off switch.** Run `npx -y @predotdev/mcp stop` to stop the background process, or turn remote debugging off at `chrome://inspect/#remote-debugging`.
+
+## Configuration
+
+Set these in your agent's MCP config (`env`).
+
+| Variable | What it does |
+| --- | --- |
+| `PREDEV_API_KEY` | Your pre.dev API key. Overrides the key saved by `login`. |
+| `PREDEV_API_URL` | The pre.dev API to call. Default `https://api.pre.dev`. |
+| `CHROME_MCP_USER_DATA_DIR` | Use a different Chrome data folder, for example Chrome Beta or a separate Chrome you started yourself. Each folder gets its own background process. |
+
+State, logs, the stable copy `setup` installs and the key saved by `login` (readable only by you) are kept in `~/.predev/mcp/`.
+
+## Commands
+
+```bash
+npx -y @predotdev/mcp setup      # sign in, add to every agent, connect to Chrome (also updates)
+npx -y @predotdev/mcp check      # check your setup, list your Chrome profiles, check your key
+npx -y @predotdev/mcp login      # sign in to pre.dev again
+npx -y @predotdev/mcp logout     # forget the saved key
+npx -y @predotdev/mcp stop       # stop the background process (it restarts on the next tool call)
+npx -y @predotdev/mcp uninstall  # remove it from every agent and delete its files
+```
+
+## Troubleshooting
+
+| You see | Do this |
+| --- | --- |
+| `Chrome remote debugging is off` | Open `chrome://inspect/#remote-debugging` in Chrome and turn it on. |
+| `Chrome is asking "Allow remote debugging?"` | Click **Allow** in Chrome, then ask your agent to try again. |
+| Chrome asks to allow again | Normal after Chrome restarts, or after this tool updates to a new version. |
+| `Plain-words actions need a pre.dev account` | Run `npx -y @predotdev/mcp login`. No restart needed. |
+| `pre.dev rejected the saved key` | Run `npx -y @predotdev/mcp login` again. |
+| A message about credits or subscribing | Your workspace is out of trial credits. Subscribe or top up at [pre.dev/billing](https://pre.dev/billing). |
+| Another server is already named `predev` | `setup` leaves it alone and registers this one as `pre-dev`. |
+| You had the hosted pre.dev MCP or an older `chrome` install | `setup` replaced it; this server has all of its tools. |
+| The agent can't start the server, or `npx`/`node` not found | Run `setup`: it registers full paths that work in desktop apps. |
+| Codex says a tool call timed out | Set `tool_timeout_sec = 900` (see the Codex setup). |
+| Anything else | Run `npx -y @predotdev/mcp check`, and look at `~/.predev/mcp/predev-mcp.log`. |
+
+## Platform support
+
+**macOS** is supported and tested. **Linux** and **Windows** are not tested yet. The code looks for Chrome's data in the standard places (`~/.config/google-chrome` and `%LOCALAPPDATA%\Google\Chrome\User Data`), and on those systems a profile needs an open Chrome window before the agent can use it. Reports and pull requests are welcome.
+
+## Development
+
+```bash
+git clone https://github.com/predotdev/mcp
+cd mcp
+node src/bridge.mjs check
+```
+
+Point your agent at `node /path/to/mcp/src/bridge.mjs`. Edits to `src/tools.mjs` reload automatically without dropping Chrome's approved connection. Edits to `src/bridge.mjs` restart the background process, so Chrome asks you to allow again.
+
+## About
+
+Free and open source from [pre.dev](https://pre.dev), built with the pre.dev CLI. Try it on your own project:
+
+```bash
+curl -fsSL https://pre.dev/install | bash
+```
+
+Want the same browser agents from your own code? Use the [REST API and SDKs](https://docs.pre.dev/browser-agents/overview).
+
+MIT licensed. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@predotdev/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.1",
+  "description": "pre.dev in any coding agent: Browser Agents in the Chrome you already use and in the cloud, plus specs and plans. One command to set up. Free and open source.",
+  "type": "module",
+  "bin": {
+    "predev-mcp": "src/bridge.mjs"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "chrome",
+    "browser",
+    "browser-automation",
+    "browser-agents",
+    "coding-agent",
+    "claude-code",
+    "codex",
+    "cursor",
+    "pre.dev",
+    "predev",
+    "specs",
+    "cloud-browser"
+  ],
+  "homepage": "https://github.com/predotdev/mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/predotdev/mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/predotdev/mcp/issues"
+  },
+  "author": "pre.dev (https://pre.dev)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}