projectionlab-mcp 0.0.0-stage → 1.0.0

package/HOW-IT-WORKS.md

@@ -0,0 +1,67 @@
+# How the ProjectionLab MCP Works
+
+Here is a breakdown of exactly how the ProjectionLab Model Context Protocol (MCP) server works, from the underlying problem it solves to the step-by-step data flow.
+
+## 1. The Core Problem It Solves
+
+ProjectionLab exposes its supported automation surface through a JavaScript object (`window.projectionlabPluginAPI`) inside the logged-in browser tab rather than through a public REST API or webhook endpoint.
+
+Because an MCP host runs outside that page, it cannot directly call a JavaScript object inside the browser. This MCP server bridges that gap.
+
+## 2. The Architecture
+
+The server speaks the Model Context Protocol (MCP) over `stdio` to its host and exposes tools (`projectionlab_update_account`, `projectionlab_export_data`, …), resources, and prompts. Everything above the browser transport depends only on the `Bridge` interface (`src/bridge.ts`), which `ExtensionBridge` implements.
+
+The server opens a WebSocket listener on `127.0.0.1:<PL_WS_PORT>`. A browser-side **executor** (either the packaged browser extension or a pasted bootstrap snippet) connects *out* to it, receives command frames, calls `window.projectionlabPluginAPI` in the real, already-logged-in ProjectionLab tab, and returns results. No second browser, no second login.
+
+### The wire protocol
+
+`src/types/wire.ts` is the contract shared by the server and every executor:
+
+- The executor connects and sends a `hello` frame with a shared token and protocol version. The server validates the `Origin` header (extension or app origin only), checks the token, and replies `helloAck`, or closes with code `4001` (auth), `4002` (version), or `4003` (a newer executor replaced this one).
+- Requests are `{ id, method, params }`; responses are `{ id, ok, result | error }`. Methods map directly to Plugin API calls plus `describeApi`/`waitForApi`.
+- A ~20 s `ping`/`pong` heartbeat keeps the connection healthy (and keeps a Manifest V3 service worker from being suspended).
+
+### The browser extension
+
+Manifest V3, in `extension/`. A background service worker owns the WebSocket, reconnects with exponential backoff, and uses an `alarms` wake after suspension. For each request it locates a ProjectionLab tab (opening one in the background when configured to do so) and uses `scripting.executeScript` to run the operation directly in the page's **MAIN world**, where `window.projectionlabPluginAPI` is visible. The structured result returns through the scripting API without a content-script relay. Chrome/Edge/Brave use the service-worker manifest; Firefox 128 or newer uses an event-page manifest with MAIN-world scripting support.
+
+### The bootstrap snippet
+
+`src/bootstrap.ts` generates a self-contained snippet (returned by the `projectionlab_get_bootstrap` tool) that plays the same executor role from the page's console, with the same protocol and methods. It's the zero-install path and a handy debugging harness, but it lives only until the tab reloads.
+
+## 3. Step-by-Step Execution Lifecycle
+
+### A. Initialization
+
+The server starts listening immediately. Tool calls made before an executor connects return an actionable `EXTENSION_NOT_CONNECTED` error. Once the extension (or snippet) connects and authenticates, requests flow.
+
+### B. Read Operations (`export_data`, `get_plan`, `get_summary`, …)
+
+1. The MCP tool validates input with Zod.
+2. The bridge sends an `exportData({ key })` request over the WebSocket to the executor, which calls it in the browser context.
+3. The browser serializes your financial state to JSON and returns it.
+4. The server selects or summarizes the requested data, redacts secrets where appropriate, and returns it to the MCP host. Results above the inline size limit are written to a protected local export file and returned as a file pointer. A short-lived export cache avoids re-serializing the complete state on every read; every write invalidates it.
+
+### C. Write Operations & Safety Flow (`update_*`, `restore_*`, `clone_plan`)
+
+The Plugin API provides a targeted `updateAccount` operation for Current Finances and whole-area restore operations (`restorePlans` and the others) for everything else. Plan edits, including `clone_plan`, are built as a complete new plans array and written with `restorePlans`. The server builds safe patches on top of those primitives and enforces a multi-layered safety net:
+
+1. **Dry-Run by Default:** without `confirm: true`, the tool returns a structured diff preview instead of mutating anything.
+2. **Fresh State:** the tool requests an uncached export and validates the requested change against the current data.
+3. **Auto-Snapshotting:** on `confirm: true`, the tool passes the affected current section to `SnapshotManager`, which writes a restore-safe local JSON snapshot with an ID and timestamp.
+4. **Conflict Check:** because `restorePlans` replaces every plan, a plan write re-reads the plans just before writing and refuses with `PLAN_CONFLICT` if any plan was added, removed, or saved in ProjectionLab since the tool read them (`assertPlansUnchanged` in `src/planVersion.ts`). `projectionlab_update_plan_section` also accepts the dry run's `planVersion` as `expectedPlanVersion` and refuses if the plan was saved after the preview.
+5. **Execution:** only then does the bridge call `updateAccount()` or the appropriate `restore*()` method.
+6. **Verification:** the tool performs a fresh re-read and checks that the requested change landed. A verification failure is reported with the snapshot retained for recovery.
+
+### D. Rollbacks & Recovery
+
+`projectionlab_rollback` reads a saved snapshot and pipes it back through the matching `restore_*` method, reverting the tab's state. A pre-rollback snapshot is also saved.
+
+## 4. Security
+
+- The Plugin API key is read only from the MCP host's `env` block, `~/.projectionlab-mcp/.env`, or a development `.env` (gitignored). It is never logged. It stays in the server process and is passed to the page only as an argument to Plugin API calls; the extension does not persist it.
+- The WebSocket binds to `127.0.0.1` only, accepts only the ProjectionLab app and browser-extension origins, and requires a shared token (`PL_WS_TOKEN`, or auto-generated at `~/.projectionlab-mcp/ws-token` with owner-only permissions), so neither other local processes nor arbitrary web pages can drive your data. Native clients without an `Origin` header still need the token.
+- Snapshots scrub the literal Plugin API key while preserving restore data. Exports, plan reads, and the `plan-data` resource additionally redact secret-named fields before they are returned or written to disk.
+- Read-only mode (the default; any `PL_READ_ONLY` other than `false`) rejects mutation tools before they read, snapshot, or write plan data.
+- The published npm package ships only `dist/`, the agent skill, and docs (the `files` allowlist in `package.json`), so source and `.env` files are never distributed.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ted Lanham
+
+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,296 @@
-# Temporary Holding Version
+# ProjectionLab MCP Server
 
-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.
+**Talk to an AI assistant about your retirement plan, and let it read and update your numbers in [ProjectionLab](https://projectionlab.com) for you.**
+
+ProjectionLab is a retirement and financial-planning app. This project connects it to an AI assistant (like Claude, or any assistant that supports the "MCP" standard; more on that below) so you can ask questions in plain English and get real answers based on *your* actual plan:
+
+- *"Am I on track to retire at 60?"*
+- *"What happens to my plan if the market returns 2% less than I assumed?"*
+- *"Bump my planned travel spending to $12,000 a year and show me the effect."*
+
+The assistant can look at your plan, walk through the tradeoffs with you, and, only when you say so, make changes for you. Every change is previewed before it happens and can be undone.
+
+---
+
+## Is this for me?
+
+You'll get value from this if:
+
+- You already use (or want to use) **ProjectionLab** for retirement planning, and
+- You use an **AI assistant that supports MCP** (see below).
+
+You do **not** need to be a programmer. The recommended path is to let your assistant do the technical setup for you. You'll mostly be answering a few questions and clicking a couple of buttons in your browser.
+
+> **A note on trust and safety:** This tool can *change* your financial plan, so it's built to be careful. It starts in **read-only mode** (it can look but not touch). Nothing is changed without showing you a preview first, and every change is backed up so it can be reversed. Your ProjectionLab API key stays on your own computer and is never sent anywhere.
+
+### What's "MCP"? Which assistants work?
+
+**MCP** (Model Context Protocol) is an open standard that lets AI assistants safely connect to outside tools. This project is an MCP "server," so it works with **any** assistant or app that supports MCP, so you are not locked into one company. Popular options include **Claude Desktop** and **Claude Code**, and a growing list of other MCP-compatible assistants and editors. If your assistant can "add an MCP server," it can use this.
+
+*(The author uses Claude Code, but that's just a preference. Pick whatever you like.)*
+
+---
+
+## What you'll need
+
+1. A **ProjectionLab account** with **Plugins enabled**. In ProjectionLab, go to **Account Settings → Plugins**, turn plugins on, and copy your **Plugin API Key** (a long code; keep it handy, since you'll give it to your assistant).
+2. An **AI assistant that supports MCP** (see above).
+3. A **web browser** you already use: Chrome, Edge, Brave, or Firefox (version 128 or newer).
+4. **Node.js** installed on your computer (version 20 or newer). If you don't have it, your assistant can help you install it, or download it from [nodejs.org](https://nodejs.org).
+
+---
+
+## The easy way: let your assistant set it up
+
+Open your AI assistant and give it this instruction (copy-paste it as-is):
+
+> Please set up the ProjectionLab MCP server (the `projectionlab-mcp` npm
+> package) for me. Follow the "For your AI assistant" section of its README at
+> `https://github.com/Backroads4Me/projectionlab-mcp`. I'm not technical, so
+> walk me through anything you need from me (like my ProjectionLab Plugin API key
+> and loading the browser extension) one step at a time. Keep it in read-only
+> mode until I say otherwise.
+
+Your assistant will download the project, install it, and hand you a couple of short, click-by-click steps in your browser (loading a small helper extension and pasting in a code). When it's done, just start asking questions about your plan.
+
+If anything gets stuck, tell your assistant what you see on screen; it can troubleshoot from there.
+
+---
+
+## For your AI assistant
+
+*(This section is written for the AI agent doing the install. If you're a person reading this, you can skip it. Your assistant follows these steps.)*
+
+You are setting this up for a **non-technical user**. Explain each thing you need from them in plain language, one step at a time, and never ask them to do something you can do yourself.
+
+**1. Get the user's Plugin API key.** Ask them to open ProjectionLab → Account Settings → Plugins, enable plugins, and copy their **Plugin API Key**. Do **not** invent one, and never print, log, or commit it.
+
+**2. Store the key.** Write it to `~/.projectionlab-mcp/.env` as the line `PL_API_KEY=...` and make the file readable only by the user (`chmod 600`). Every MCP host on the machine reads this file, so the key lives in one place. Do not repeat the key back to the user. Writes stay disabled by default; do not set `PL_READ_ONLY=false` until the user has seen the tool working and explicitly asks.
+
+**3. Register the server with the user's MCP host.** The server runs with `npx`, which needs Node.js 20 or newer:
+```json
+{
+  "mcpServers": {
+    "projectionlab": {
+      "command": "npx",
+      "args": ["-y", "projectionlab-mcp"]
+    }
+  }
+}
+```
+The config location varies by host; see [Adding the server to your MCP host](#adding-the-server-to-your-mcp-host) for common ones. Have the user restart the host so it starts the server. On first start the server creates the browser connection token at `~/.projectionlab-mcp/ws-token`.
+
+**4. Connect the browser.** The server reaches ProjectionLab through the user's own browser. Pick the path that fits:
+
+- **Recommended: the browser extension** (persists across restarts). Download the zip for the user's browser from the [latest release](https://github.com/Backroads4Me/projectionlab-mcp/releases/latest) and unzip it. Then walk the user through loading it (this is a click-by-click browser task; describe exactly what they'll see):
+  - **Chrome / Edge / Brave:** open `chrome://extensions`, turn on "Developer mode" (top-right), click "Load unpacked", and choose the unzipped Chromium folder.
+  - **Firefox (128+):** open `about:debugging` → "This Firefox" → "Load Temporary Add-on", and choose `manifest.json` in the unzipped Firefox folder. Firefox removes temporary add-ons when it restarts.
+  Then have them open the extension's **options page** and enter the WebSocket **port** (default `8788`) and the **shared token** from `~/.projectionlab-mcp/ws-token`.
+
+- **Quick alternative: no install.** Call the `projectionlab_get_bootstrap` tool, then have the user paste the returned snippet into their ProjectionLab tab's developer console (F12 → Console). It works the same way but must be re-pasted if they reload the page. Good for a first test drive.
+
+**5. Verify.** Have the user open [ProjectionLab](https://app.projectionlab.com), log in, and confirm plugins are enabled. Then call `projectionlab_check_connection`; it should report all checks passing. Do this before any other tool call.
+
+**6. Enabling changes (writes).** Leave everything in dry-run/read-only until the user explicitly asks to make changes. When they do: set `PL_READ_ONLY=false` in `~/.projectionlab-mcp/.env` or the host's `env` block, restart the host, and remember that every write still previews first (`confirm: true` required) and auto-snapshots so it can be rolled back. Reassure the user of this before the first change.
+
+---
+
+## Technical reference
+
+The rest of this document is for developers or advanced users. Everyday use needs none of it.
+
+### How it works
+
+ProjectionLab has no REST API, so the server reaches its browser-side `window.projectionlabPluginAPI` over a localhost WebSocket that a browser-side executor connects out to: the **extension** for normal use, or a pasted **bootstrap snippet** for a zero-install test. See **[HOW-IT-WORKS.md](HOW-IT-WORKS.md)** for the full architecture: the bridge design, wire protocol, extension internals, and safety model.
+
+### Adding the server to your MCP host
+
+The server is a standard stdio MCP server started with `npx -y projectionlab-mcp`. Put the key in `~/.projectionlab-mcp/.env` (see [Configuration](#configuration)) so no host config holds a secret.
+
+**Claude Code:**
+```bash
+claude mcp add --scope user projectionlab -- npx -y projectionlab-mcp
+```
+
+**Claude Desktop** (`claude_desktop_config.json`) and other hosts that use the `mcpServers` JSON format:
+```json
+{
+  "mcpServers": {
+    "projectionlab": {
+      "command": "npx",
+      "args": ["-y", "projectionlab-mcp"]
+    }
+  }
+}
+```
+
+**Hermes Agent** (`config.yaml` of the profile):
+```yaml
+mcp_servers:
+  projectionlab:
+    command: npx
+    args: ["-y", "projectionlab-mcp"]
+    enabled: true
+```
+
+Only one server instance can hold the WebSocket port. When a second host starts the server while another instance holds it, the second retries every few seconds and takes over when the first exits; `projectionlab_check_connection` explains the state in the meantime. To run both at once, give one of them its own `PL_WS_PORT` in its `env` block.
+
+### Agent instructions
+
+The server carries its own instructions for the agents that use it, so no per-host prompt setup is needed:
+
+- **Server instructions**, sent in the MCP initialize result. Hosts that surface them give the model the core rules: check the connection first, the read-only/dry-run/confirm workflow, privacy.
+- **The `projectionlab://guide` resource**, the full agent guide: setup walkthrough for each failed connection check, which tool answers which question, the change workflow, and privacy rules. `projectionlab_check_connection` points agents to it.
+- **The `projectionlab` skill** at [`skills/projectionlab/SKILL.md`](skills/projectionlab/SKILL.md), the same guide in the Agent Skills format, for hosts that load skills (copy the folder into the host's skills directory).
+
+### Manual setup from source
+
+```bash
+npm install
+npm run build
+cd extension && npm install && npm run build   # build the extension
+```
+
+Register `node /absolute/path/to/projectionlab-mcp/dist/index.js` with your MCP host, load the built extension (`extension/dist/chromium` or `extension/dist/firefox`), configure its port + token on the options page, then run `projectionlab_check_connection`.
+
+### Configuration
+
+Each setting is read from the first of these that sets it:
+
+1. The `env` block of the server entry in the MCP host's config.
+2. `~/.projectionlab-mcp/.env`, shared by every MCP host on the machine.
+3. `.env` at the package root, for a development checkout (copy `.env.example`).
+
+The server starts without `PL_API_KEY` so it can tell the agent what is missing; tools that need the key return `API_KEY_MISSING` until it is set.
+
+### Environment variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `PL_API_KEY` | Yes | - | ProjectionLab Plugin API key; tools that reach the plan fail until it is set |
+| `PL_WS_PORT` | No | `8788` | Localhost WebSocket port |
+| `PL_WS_TOKEN` | No | auto-generated | Shared auth token; if unset, generated and saved to `~/.projectionlab-mcp/ws-token` |
+| `PL_APP_URL` | No | `https://app.projectionlab.com` | ProjectionLab app URL |
+| `PL_API_READY_TIMEOUT_MS` | No | `30000` | Timeout waiting for Plugin API to attach |
+| `PL_EXPORT_CACHE_MS` | No | `90000` | How long a full export may be served from cache (writes always invalidate) |
+| `PL_PRETTY_JSON` | No | `false` | Pretty-print JSON output (uses ~25–40% more tokens) |
+| `PL_READ_ONLY` | No | `true` | Write/mutation tools are disabled unless this is exactly `false` |
+| `PL_SNAPSHOT_DIR` | No | `~/.projectionlab-mcp/snapshots` | Directory for pre-mutation snapshots |
+| `LOG_LEVEL` | No | `info` | Log verbosity (`debug`, `info`, `warn`, `error`) |
+
+### Available tools
+
+| Tool | Description | Mutates |
+|---|---|---|
+| `projectionlab_check_connection` | Verify browser + API connectivity | No |
+| `projectionlab_get_bootstrap` | Return a console snippet to connect a ProjectionLab tab | No |
+| `projectionlab_describe_plugin_api` | Describe the available Plugin API surface | No |
+| `projectionlab_describe_schema` | Describe the data schema (plan names, account IDs) | No |
+| `projectionlab_export_data` | Export full plan state as JSON | No |
+| `projectionlab_get_summary` | Inventory Current Finances balances and current net worth (not projected outcomes) | No |
+| `projectionlab_get_plan` | Retrieve a single plan | No |
+| `projectionlab_get_plan_section` | Retrieve a plan section; supports event/path filters and typed field-path listing | No |
+| `projectionlab_get_plan_settings` | List discrete plan settings as path-addressable values | No |
+| `projectionlab_get_current_finances` | Get Current Finances or list typed paths for one account | No |
+| `projectionlab_update_account` | Patch one Current Finances account by top-level fields or nested dot paths | Yes |
+| `projectionlab_update_plan_event` | Patch one event by top-level fields or nested dot paths | Yes |
+| `projectionlab_update_plan_settings` | Patch existing assumptions, Monte Carlo, or withdrawal settings by path | Yes |
+| `projectionlab_update_plan_section` | Replace a whole section of a plan (dry-run by default) | Yes |
+| `projectionlab_clone_plan` | Copy a plan to a new, named plan for what-if scenarios | Yes |
+| `projectionlab_list_snapshots` | List saved pre-mutation snapshots | No |
+| `projectionlab_restore_current_finances` | Restore Current Finances from snapshot | Yes |
+| `projectionlab_restore_plans` | Restore Plans from snapshot | Yes |
+| `projectionlab_restore_progress` | Restore Progress from snapshot | Yes |
+| `projectionlab_restore_settings` | Restore Settings from snapshot | Yes |
+| `projectionlab_rollback` | Roll back to a previous snapshot | Yes |
+
+### Resources
+
+| URI | Description |
+|---|---|
+| `projectionlab://plan-data` | Full export of all plans/finances/progress/settings (refreshed per access) |
+| `projectionlab://summary` | High-level snapshot: net worth, account breakdown, plan count |
+| `projectionlab://knowledge` | Curated ProjectionLab data-model + FIRE/tax reference (static) |
+| `projectionlab://guide` | Agent guide: setup walkthrough, tool selection, change workflow, privacy rules (static) |
+
+### Prompts
+
+| Prompt | Purpose |
+|---|---|
+| `analyze-plan` | Structured analysis: cash flow, tax, risk, withdrawal, estate |
+| `compare-plans` | Side-by-side comparison of two plans |
+| `optimize-tax` | Roth conversion / bracket / IRMAA / gain-harvesting review |
+| `review-assumptions` | Stress-test returns, inflation, healthcare, longevity |
+
+### Safety model
+
+Write operations (`update_*`, `restore_*`, `clone_plan`) default to **dry-run mode**. Pass `confirm: true` to execute. Before any confirmed mutation, the server automatically snapshots the affected data section to disk so you can roll back with `projectionlab_rollback`. Writes are disabled entirely unless `PL_READ_ONLY=false`.
+
+Every write that replaces the plans array re-reads the plans just before writing and refuses with `PLAN_CONFLICT` if any plan was added, removed, or saved in ProjectionLab since the tool read them, so an edit made in the ProjectionLab UI is never silently overwritten. `projectionlab_update_plan_section` also returns a `planVersion` in its dry run; pass it back as `expectedPlanVersion` when confirming to refuse the write if the plan was saved after the preview.
+
+For a small assumptions or strategy change, first call
+`projectionlab_get_plan_settings` with the plan name. It returns the current
+`variables`, `montecarlo`, and `withdrawalStrategy` values as dot paths with
+their JSON types. Preview a path-level patch with
+`projectionlab_update_plan_settings`, for example:
+
+```json
+{
+  "planIdentifier": "Retire at 55",
+  "section": "variables",
+  "changes": {
+    "showFutureDollars": true
+  }
+}
+```
+
+The update tool preserves sibling settings, rejects unknown paths and JSON type
+changes, and still requires `"confirm": true` before it sends a mutation.
+Advanced inflation, stock-growth, dividend-yield, bond-growth, and bond-yield
+schedules expose both the complete ordered array and indexed control-point
+fields, so one existing year or rate can be adjusted without replacing the
+rest of the schedule.
+
+Event forms use the same path workflow. Fetch one event with
+`projectionlab_get_plan_section` using its `eventIdentifier` and
+`"listPaths": true`, then pass selected paths to
+`projectionlab_update_plan_event` as `pathChanges`. The older `patch` input
+remains available for shallow top-level changes.
+
+Current Finances accounts also support targeted discovery and nested patches.
+Call `projectionlab_get_current_finances` with an exact `accountId` and
+`"listPaths": true`, then pass selected paths to
+`projectionlab_update_account` as `pathChanges`. The legacy `data` input
+remains available for top-level fields. Dry runs validate the account and
+return before/after values as a safety diff; confirmed no-ops do not create a
+snapshot or send a mutation.
+
+### Evaluating plan impact
+
+Projected ending net worth and Chance of Success are the primary outcome
+metrics for comparing a plan before and after a change. Current Finances
+balances are inputs. Mutation before/after values verify that the requested
+input changed, but they do not measure the plan's financial impact.
+
+ProjectionLab's Plugin API currently exposes plan definitions and simulation
+settings, but not a supported method to recalculate and retrieve projected
+ending net worth or a completed Chance of Success result. After a confirmed
+mutation, re-read the targeted input through MCP for verification, then
+recalculate the plan and run Chance of Success in the ProjectionLab UI before
+drawing a conclusion.
+
+### Secret handling
+
+The Plugin API key stays on your computer: it is never logged, and the browser side never stores it. The WebSocket accepts only local connections that present a shared token. See [Security in HOW-IT-WORKS.md](HOW-IT-WORKS.md#4-security) for the details.
+
+### After code changes
+
+This server runs over stdio; the host process keeps compiled `dist/` in memory.
+
+```bash
+npm run build
+# Then restart your MCP host
+projectionlab_check_connection  # verify before other operations
+```
+
+With the extension the browser side reconnects on its own, so you only restart the MCP host. If you change extension source, rebuild it (`cd extension && npm run build`) and reload it in the browser.

package/dist/bootstrap.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tier 0 transport: a self-contained snippet the user pastes into the
+ * ProjectionLab tab's devtools console. It plays the same executor role as
+ * the browser extension - connects to the local WebSocket server, answers
+ * ping and request frames against window.projectionlabPluginAPI - but lives
+ * only until the tab reloads. Keep the executor logic in sync with
+ * extension/src/page-main.js.
+ */
+export declare function buildBootstrapSnippet(port: number, token: string): string;

package/dist/bootstrap.js

@@ -0,0 +1,90 @@
+import { PROTOCOL_VERSION } from "./types/wire.js";
+import { VERSION } from "./version.js";
+/**
+ * Tier 0 transport: a self-contained snippet the user pastes into the
+ * ProjectionLab tab's devtools console. It plays the same executor role as
+ * the browser extension - connects to the local WebSocket server, answers
+ * ping and request frames against window.projectionlabPluginAPI - but lives
+ * only until the tab reloads. Keep the executor logic in sync with
+ * extension/src/page-main.js.
+ */
+export function buildBootstrapSnippet(port, token) {
+    const cfg = JSON.stringify({
+        port,
+        token,
+        protocolVersion: PROTOCOL_VERSION,
+        executor: `bootstrap/${VERSION}`,
+    });
+    return `(() => {
+  const cfg = ${cfg};
+  if (window.__plmcpBootstrap) { console.log("[plmcp] bootstrap already running"); return; }
+  window.__plmcpBootstrap = true;
+  let stopped = false;
+  const log = (m) => console.log("[plmcp]", m);
+  function waitForApi(timeoutMs) {
+    return new Promise((resolve, reject) => {
+      const deadline = Date.now() + timeoutMs;
+      (function poll() {
+        if (window.projectionlabPluginAPI) return resolve(window.projectionlabPluginAPI);
+        if (Date.now() >= deadline) { const e = new Error("Plugin API did not appear within " + Math.round(timeoutMs / 1000) + "s - log in and enable plugins"); e.code = "API_NOT_AVAILABLE"; return reject(e); }
+        setTimeout(poll, 500);
+      })();
+    });
+  }
+  function describeApi(api) {
+    const out = {}; const seen = new Set(); let o = api;
+    while (o && o !== Object.prototype) {
+      for (const k of Object.getOwnPropertyNames(o)) {
+        if (k === "constructor" || seen.has(k)) continue;
+        seen.add(k);
+        const v = api[k];
+        out[k] = typeof v === "function" ? "function(" + v.length + " args)" : typeof v;
+      }
+      o = Object.getPrototypeOf(o);
+    }
+    return out;
+  }
+  async function handle(frame, ws) {
+    try {
+      const requested = frame.method === "waitForApi" ? Number((frame.params || [])[0]) : NaN;
+      const api = await waitForApi(Number.isFinite(requested) && requested > 0 ? requested : 15000);
+      let result;
+      if (frame.method === "waitForApi") result = true;
+      else if (frame.method === "describeApi") result = describeApi(api);
+      else {
+        const fn = api[frame.method];
+        if (typeof fn !== "function") throw new Error("Plugin API method unavailable: " + frame.method);
+        result = await fn.apply(api, frame.params);
+      }
+      ws.send(JSON.stringify({ type: "response", id: frame.id, ok: true, result }));
+    } catch (err) {
+      const msg = err && err.message ? err.message : String(err);
+      const code = err && err.code === "API_NOT_AVAILABLE" ? "API_NOT_AVAILABLE"
+        : /api.?key|invalid key|unauthori[sz]ed/i.test(msg) ? "API_KEY_INVALID" : "UNKNOWN";
+      ws.send(JSON.stringify({ type: "response", id: frame.id, ok: false, error: { code, message: msg } }));
+    }
+  }
+  function connect() {
+    if (stopped) return;
+    const ws = new WebSocket("ws://127.0.0.1:" + cfg.port);
+    ws.onopen = () => ws.send(JSON.stringify({ type: "hello", token: cfg.token, protocolVersion: cfg.protocolVersion, executor: cfg.executor }));
+    ws.onmessage = (ev) => {
+      let frame;
+      try { frame = JSON.parse(ev.data); } catch { return; }
+      if (frame.type === "helloAck") log("connected to projectionlab-mcp");
+      else if (frame.type === "ping") ws.send(JSON.stringify({ type: "pong" }));
+      else if (frame.type === "request") handle(frame, ws);
+    };
+    ws.onclose = (ev) => {
+      if (stopped) return;
+      if (ev.code === 4001 || ev.code === 4002) { stopped = true; window.__plmcpBootstrap = false; log("stopped: " + (ev.reason || ev.code)); return; }
+      if (ev.code === 4003) { stopped = true; window.__plmcpBootstrap = false; log("replaced by another executor (probably the extension) - bootstrap no longer needed"); return; }
+      log("disconnected; retrying in 3s");
+      setTimeout(connect, 3000);
+    };
+  }
+  connect();
+  log("bootstrap installed - keep this tab open; re-paste after a page reload");
+})();`;
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,KAAa;IAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC;QACzB,IAAI;QACJ,KAAK;QACL,eAAe,EAAE,gBAAgB;QACjC,QAAQ,EAAE,aAAa,OAAO,EAAE;KACjC,CAAC,CAAC;IACH,OAAO;gBACO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAqEb,CAAC;AACP,CAAC"}

package/dist/bridge.d.ts

@@ -0,0 +1,29 @@
+import type { ExportedData } from "./types/projectionlab.js";
+export interface ConnectionStatus {
+    browser: boolean;
+    pageLoaded: boolean;
+    apiAvailable: boolean;
+    apiKeyValid: boolean;
+    errors: string[];
+}
+/**
+ * Surface for reaching window.projectionlabPluginAPI in a live ProjectionLab
+ * page. Implemented by ExtensionBridge, which relays over a localhost
+ * WebSocket to a browser extension or bootstrap snippet. Tools, resources,
+ * prompts, and the snapshot manager depend only on this interface.
+ */
+export interface Bridge {
+    checkConnection(): Promise<ConnectionStatus>;
+    describePluginApi(): Promise<Record<string, string>>;
+    /** Full export, served from a short-lived cache unless `fresh` is true. */
+    exportData(opts?: {
+        fresh?: boolean;
+    }): Promise<ExportedData>;
+    updateAccount(accountId: string, data: Record<string, unknown>, force?: boolean): Promise<void>;
+    restoreCurrentFinances(state: unknown): Promise<void>;
+    restorePlans(plans: unknown[]): Promise<void>;
+    restoreProgress(progress: unknown): Promise<void>;
+    restoreSettings(settings: unknown): Promise<void>;
+    invalidateCache(): void;
+    close(): Promise<void>;
+}

package/dist/bridge.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bridge.js.map

package/dist/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":""}

package/dist/clonePlan.d.ts

@@ -0,0 +1,19 @@
+import { type PlanObj } from "./plans.js";
+/** True when another plan already uses `name` (case-insensitive, trimmed). */
+export declare function planNameTaken(plans: unknown[], name: string): boolean;
+/**
+ * Build a copy of `source` to append to `plans` as a new plan.
+ *
+ * Event ids are kept as they are. Event ids are scoped to their plan:
+ * ProjectionLab's own duplicated plans share every event id, built-in
+ * milestones use fixed ids such as "retirement", and events, Monte Carlo
+ * settings, the withdrawal strategy and bond account order all reference
+ * milestone and account ids within the same plan. Copying them unchanged keeps
+ * those references intact.
+ *
+ * The plan-level identity is replaced: a new id and name, a fresh lastUpdated,
+ * inactive, and simKey / meta.index / meta.runKey one past the highest among
+ * `plans` so the copy does not collide with an existing plan.
+ */
+export declare function buildPlanClone(source: PlanObj, plans: unknown[], newName: string, now?: number): PlanObj;
+export declare function verifyPlanClone(before: unknown[], after: unknown[], clone: PlanObj): string[];