lensmcp 1.8.0 → 1.9.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "lensmcp-marketplace",
+  "owner": {
+    "name": "David Antoon",
+    "email": "davidmantoon@gmail.com"
+  },
+  "metadata": {
+    "description": "The LensMCP observability lens, packaged as a Claude Code plugin."
+  },
+  "plugins": [
+    {
+      "name": "lensmcp",
+      "source": "./plugin",
+      "description": "Run the LensMCP dev cluster gateway + per-project dashboard + MCP server from inside Claude Code."
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lensmcp",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "lensmcp",
+  "displayName": "LensMCP",
+  "description": "The observability lens for coding agents. One command brings up the dev cluster gateway (every project.json `cluster` decl → its host on :443), the per-project lens dashboard at https://lensmcp.local/<project>/, and the MCP server your agent connects to — scoped automatically to whatever project you opened Claude Code in.",
+  "version": "1.9.0",
+  "author": {
+    "name": "David Antoon",
+    "email": "davidmantoon@gmail.com"
+  },
+  "homepage": "https://github.com/kiwiapps-ltd/lensmcp",
+  "repository": "https://github.com/kiwiapps-ltd/lensmcp",
+  "license": "Apache-2.0",
+  "keywords": [
+    "mcp",
+    "lens",
+    "observability",
+    "nx",
+    "vite",
+    "nestjs",
+    "gateway"
+  ],
+  "mcpServers": "./.mcp.json"
+}

package/plugin/.mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "lensmcp": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PROJECT_DIR}/node_modules/lensmcp/bin.js",
+        "mcp",
+        "--cwd",
+        "${CLAUDE_PROJECT_DIR}"
+      ]
+    }
+  }
+}

package/plugin/README.md

@@ -0,0 +1,49 @@
+# LensMCP — Claude Code plugin
+
+Run the LensMCP observability lens for **any** project, from inside Claude Code: the dev
+cluster **gateway**, the per-project **dashboard**, and the **MCP server** your agent
+connects to — all scoped automatically to the project you opened Claude Code in.
+
+## What it bundles
+
+- **MCP server** (`.mcp.json`) — launched as `lensmcp mcp --cwd ${CLAUDE_PROJECT_DIR}`, so it
+  always reads *that project's* `.lensmcp/events.jsonl`. Open Claude Code in `tetros` → you
+  get tetros's flows; open it elsewhere → that project's flows. No cross-talk.
+- **Commands** (skills):
+  - `/lensmcp:start` — start the gateway (every `project.json` `cluster` decl → its host on
+    :443) + the lens dashboard at `https://lensmcp.local/<key>/`.
+  - `/lensmcp:stop` — stop the gateway.
+  - `/lensmcp:status` — gateway liveness + `lensmcp doctor`.
+  - `/lensmcp:dashboard` — open the per-project dashboard in the browser.
+  - `/lensmcp:using-lensmcp` — how to drive the lens (which tool answers which question).
+
+## Requirements
+
+The target project must have **`lensmcp` installed** as a dev dependency
+(`yarn add -D lensmcp`) — the plugin shells out to its project-local CLI so versions stay in
+lock-step with the project. `lensmcp` is a **dev-only** tool; never a prod/CI dependency.
+
+Binding **:443** needs privilege — run `nx run gateway:trust` once per machine (sets up the
+`*.local` hosts + a TLS CA), and start the gateway with the elevation your OS requires.
+
+## Install
+
+**Dev (fastest, what we use while iterating):**
+
+```bash
+claude --plugin-dir /Users/davidantoon/git/lensmcp/plugin
+```
+
+**Via marketplace (once published):**
+
+```bash
+/plugin marketplace add kiwiapps-ltd/lensmcp
+/plugin install lensmcp@lensmcp-marketplace
+```
+
+## Multi-project
+
+Each project derives its own `key`, ports, and dashboard mount path
+(`.lensmcp/config.json`), so the lens runs cleanly across projects — switch projects and the
+dashboard moves to `lensmcp.local/<that-project>/` with its own ports. One gateway owns :443
+at a time.

package/plugin/scripts/dashboard-open.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Open the per-project LensMCP dashboard (history-routed) in the default browser.
+# The mount path comes from .lensmcp/config.json (e.g. /tetros), served by the gateway
+# at https://lensmcp.local/<key>/.
+set -uo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+CFG="$PROJECT_DIR/.lensmcp/config.json"
+
+BASE=""
+if [ -f "$CFG" ]; then
+  BASE="$(node -e "try{process.stdout.write(require('$CFG').dashboardBasePath||'')}catch(e){}" 2>/dev/null || echo '')"
+fi
+
+URL="https://lensmcp.local${BASE}/"
+echo "LensMCP dashboard → $URL"
+echo "(needs the gateway running: /lensmcp:start)"
+
+case "$(uname -s)" in
+  Darwin) open "$URL" 2>/dev/null || true ;;
+  Linux)  xdg-open "$URL" 2>/dev/null || true ;;
+  *)      echo "Open it manually: $URL" ;;
+esac

package/plugin/scripts/gateway-start.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Start the LensMCP dev cluster gateway for the project Claude Code is open in.
+# The gateway reads every project.json `cluster` decl, launches each app/service under
+# its host on :443, and serves the per-project lens dashboard at lensmcp.local/<key>/.
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+BIN="$PROJECT_DIR/node_modules/lensmcp/bin.js"
+
+if [ ! -f "$BIN" ]; then
+  echo "✗ lensmcp is not installed in $PROJECT_DIR (no node_modules/lensmcp/bin.js)." >&2
+  echo "  Install it as a dev dependency:  yarn add -D lensmcp" >&2
+  echo "  (the gateway is a dev-only tool — never a prod/CI dependency)." >&2
+  exit 1
+fi
+
+exec node "$BIN" gateway start --cwd "$PROJECT_DIR"

package/plugin/scripts/gateway-status.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Report LensMCP gateway status for the current project, then run the install doctor.
+set -uo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+BIN="$PROJECT_DIR/node_modules/lensmcp/bin.js"
+
+if [ ! -f "$BIN" ]; then
+  echo "✗ lensmcp is not installed in $PROJECT_DIR." >&2
+  exit 1
+fi
+
+node "$BIN" gateway status --cwd "$PROJECT_DIR" || true
+echo
+node "$BIN" doctor --cwd "$PROJECT_DIR" || true

package/plugin/scripts/gateway-stop.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Stop the LensMCP dev cluster gateway for the current project.
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+BIN="$PROJECT_DIR/node_modules/lensmcp/bin.js"
+
+if [ ! -f "$BIN" ]; then
+  echo "✗ lensmcp is not installed in $PROJECT_DIR." >&2
+  exit 1
+fi
+
+exec node "$BIN" gateway stop --cwd "$PROJECT_DIR"

package/plugin/skills/dashboard/SKILL.md

@@ -0,0 +1,19 @@
+---
+description: Open the per-project LensMCP dashboard (Flows / Cluster / Logs / Resources) in the browser at https://lensmcp.local/<key>/. Use when the user asks to open the lens dashboard, see the flows/cluster UI, or watch the app live.
+---
+
+# Open the LensMCP dashboard
+
+Run the open script with the Bash tool:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/dashboard-open.sh"
+```
+
+It reads the project's mount path from `.lensmcp/config.json` and opens
+`https://lensmcp.local/<key>/` — the human view of the lens (the same event stream the
+MCP server reads): **Flows**, **Cluster**, **Logs**, **Resources**, history-routed so deep
+links + refresh work.
+
+The dashboard is served by the gateway, so it needs the gateway running first
+(`/lensmcp:start`). If the page doesn't load, check `/lensmcp:status`.

package/plugin/skills/start/SKILL.md

@@ -0,0 +1,33 @@
+---
+description: Start the LensMCP dev cluster gateway for the current project — brings up every app/service/site under its host on :443 and the per-project lens dashboard at https://lensmcp.local/<key>/. Use when the user asks to start the gateway/cluster, "start lensmcp", bring the dev cluster up, or start listening.
+---
+
+# Start the LensMCP gateway
+
+Run the startup script with the Bash tool:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/gateway-start.sh"
+```
+
+The script calls `lensmcp gateway start` for the project Claude Code is open in
+(`${CLAUDE_PROJECT_DIR}`). That single command:
+
+- reads every `project.json` `cluster` declaration and launches each app / service /
+  website under its own host (e.g. `app.tetros.ai.local`, `auth.tetros.ai.local`,
+  `api.tetros.ai.local/crm`), each on its own port/socket via the one HTTPS front door
+  on **:443**;
+- serves the project-scoped lens **dashboard** at `https://lensmcp.local/<key>/`;
+- writes a pid + log under `.lensmcp/` so it can be stopped later.
+
+After running it:
+
+1. Report the dashboard URL the script printed.
+2. **Binding :443 needs privilege.** If the log shows `EACCES`/permission denied, tell
+   the user to either run the gateway target with `sudo`, or that ports <1024 require
+   elevation on macOS — and that `nx run gateway:trust` must be run once (sudo) to set up
+   the `*.local` hosts + TLS CA. Check `.lensmcp/gateway.log` for the real error.
+3. If the user has not run `gateway:trust` yet, mention it (one-time per machine).
+
+Do **not** run a service's `serve`/`serve-hmr` manually — the gateway owns each service's
+lifecycle. This one command is the entry point.

package/plugin/skills/status/SKILL.md

@@ -0,0 +1,18 @@
+---
+description: Report LensMCP status for the current project — gateway liveness, the dashboard URL, and the install doctor (Node, plugin wiring, MCP bundle, per-project vite/nest wiring). Use when the user asks if lensmcp is running, to check the gateway, or to diagnose the lens setup.
+---
+
+# LensMCP status + doctor
+
+Run the status script with the Bash tool:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/gateway-status.sh"
+```
+
+It runs `lensmcp gateway status` (is the gateway up? the project key + dashboard URL) and
+then `lensmcp doctor` (Node version, plugin registration, `.mcp.json`, the MCP server
+bundle, per-project Vite/Nest wiring, agent-dev targets, Chrome for browser capture).
+
+Summarize the result for the user: whether the gateway is running, the dashboard URL, and
+any `✗`/`!` items doctor flagged with their suggested fix.

package/plugin/skills/stop/SKILL.md

@@ -0,0 +1,17 @@
+---
+description: Stop the LensMCP dev cluster gateway for the current project. Use when the user asks to stop the gateway/cluster, "stop lensmcp", or shut the dev cluster down.
+---
+
+# Stop the LensMCP gateway
+
+Run the stop script with the Bash tool:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/gateway-stop.sh"
+```
+
+It calls `lensmcp gateway stop` for `${CLAUDE_PROJECT_DIR}`, which reads the pid recorded
+in `.lensmcp/gateway.pid` and terminates the gateway process group (the gateway plus the
+app/service pods + the lens dashboard it spawned).
+
+Report whether it stopped, or that it was already not running.

package/plugin/skills/using-lensmcp/SKILL.md

@@ -0,0 +1,42 @@
+---
+description: How to drive the LensMCP lens to observe a running app — the start→interact→read loop, and which MCP tool answers which question (what happened on a click, why a component re-rendered, what's slow, memory leaks). Use when the user asks how to use lensmcp, what it can do, or to explain/trace something the running app just did.
+---
+
+# Using LensMCP
+
+LensMCP gives you (and the user) eyes on a running application. Producers (the gateway,
+agent-dev, instrumented apps) write events to `<project>/.lensmcp/events.jsonl`; the MCP
+server and the dashboard both read that file. **Project isolation is automatic** — the MCP
+server is launched with `--cwd ${CLAUDE_PROJECT_DIR}`, so it always reads the flows of the
+project Claude Code is open in. Different project → different event file → different flows.
+
+## The loop
+
+1. **Start** the cluster + lens: `/lensmcp:start` (gateway up, all hosts routed, dashboard
+   at `https://lensmcp.local/<key>/`). For a single app instead of the whole cluster, the
+   workspace's `nx run <project>:agent-dev` also produces events.
+2. **Interact** with the running app (click around in the browser, or let an e2e drive it).
+3. **Read** the lens — ask in plain language and call the right MCP tool:
+
+| The user asks… | Tool |
+|---|---|
+| "what's the current state / is the lens live?" | `observe_current_status` |
+| "show me recent flows" / "what just happened?" | `flow_list_recent`, then `flow_get` |
+| "what happened when I clicked X?" | `graph_find_backend_work_caused_by_click`, `graph_trace_from_origin` |
+| "why did this component re-render?" | `graph_explain_rerender` |
+| "what's slow?" / "is there a DB call in a loop?" | `graph_find_slow_path`, `graph_find_db_in_loop` |
+| "what state updates did this cause?" | `graph_find_state_updates_caused_by` |
+| "did anything leak memory?" | `memory_explain_leak`, `memory_find_growth_by_flow` |
+| "tell the story of this flow" | `story_compile`, `story_get` |
+| visual / render checks | `visual_capture_frame`, `visual_inspect_node`, `visual_compare_frames` |
+
+4. Watch it as a human anytime with `/lensmcp:dashboard`.
+
+## Tips
+
+- If a tool returns nothing, no events have been produced yet — start the gateway (or an
+  `agent-dev`) and interact with the app first.
+- `/lensmcp:status` runs the doctor if something seems off (Node, plugin wiring, MCP bundle,
+  per-project Vite/Nest instrumentation, Chrome for browser capture).
+- Don't run a service's `serve`/`serve-hmr` by hand — the gateway owns each service's
+  lifecycle; `/lensmcp:start` is the one entry point.