# @lensmcp/nx-plugin

> Nx plugin that wires [LensMCP](https://github.com/kiwiapps-ltd/lensmcp) — the observability lens for coding agents — into your workspace.

LensMCP gives coding agents (Claude Code, Cursor, and other MCP clients) a live view into the app they are building: frontend events captured from a real Chrome session, backend traces from the running server, and deterministic build/verify reports. This plugin is the integration layer for Nx workspaces. Its **executors** run a host app or server under the lens, and its **generators** scaffold the wiring so you do not have to edit configs by hand.

In practice you run `init` once per workspace, run `setup-vite` / `setup-nest` once per project, then drive everything through the `agent-dev`, `agent-build`, and `agent-verify` targets the generators add for you.

## Install

```bash
yarn add -D @lensmcp/nx-plugin
```

Then register the plugin and scaffold the workspace wiring with the `init` generator:

```bash
nx g @lensmcp/nx-plugin:init
```

This is also run for you by `lensmcp install` (the [`lensmcp` CLI](https://github.com/kiwiapps-ltd/lensmcp)). `init` is idempotent — safe to re-run.

## Generators

| Generator | Purpose | Invocation |
| --- | --- | --- |
| `init` | Install LensMCP into the host Nx workspace: register the plugin in `nx.json`, add the workspace-wide `lensmcp` config block, patch `.gitignore`, and prepare the `.lensmcp` runtime directory. | `nx g @lensmcp/nx-plugin:init` |
| `setup-vite` | Wire LensMCP into a Vite project: add `@lensmcp/vite-plugin` to its `vite.config.ts` and add an `agent-dev` target. | `nx g @lensmcp/nx-plugin:setup-vite` |
| `setup-nest` | Wire LensMCP into a NestJS project: register `LensmcpModule.forRoot()` in the `AppModule` and add an `agent-dev` target. | `nx g @lensmcp/nx-plugin:setup-nest` |

### Options

**`init`**

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `registerHostConfig` | `"auto"` \| `"never"` \| `"always"` | `auto` | Whether to also append a `lensmcp` entry to the host agent's MCP client config (`~/.claude/mcp.json`, `~/.cursor/mcp.json`, `<workspace>/.mcp.json`). `auto` patches existing files only and never modifies anything outside the workspace by default. |
| `skipFormat` | `boolean` | `false` | Skip Prettier formatting of touched files. |

**`setup-vite`** / **`setup-nest`**

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `project` | `string` | _(required)_ | Target Nx project. For `setup-vite` it must already have a `vite.config.ts`; for `setup-nest` it must have an `app.module.ts` and `main.ts`. |
| `skipFormat` | `boolean` | `false` | Skip Prettier formatting of touched files. |

## Executors

| Executor | Purpose |
| --- | --- |
| `agent-dev` | Start a project under the LensMCP lens — runs the dev server alongside a Chrome capture sidecar and the MCP server so agents observe the live app. |
| `agent-build` | Run an instrumented production build that produces a bundle report and updates the baseline. |
| `agent-verify` | Deterministic verification loop — typecheck, lint, then build — with a per-run report under `.lensmcp/verifications/`. |

### `agent-dev`

Runs a host project (`vite-react`, `nestjs`, or `nextjs`) and attaches the lens. For Vite-React it starts the dev server and a Chrome sidecar pointed at the dev URL so frontend events are captured live.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `"vite-react"` \| `"nestjs"` \| `"nextjs"` | `vite-react` | Host project type. |
| `devTarget` | `string` | — | Nx target that starts the host's dev server (e.g. `web:serve`). If omitted, the executor runs `vite` on the current project. |
| `projectRoot` | `string` | — | Override the project root passed to Vite. Defaults to the running project's root. |
| `chrome` | `boolean` | `true` | Launch a Chrome sidecar attached to the dev URL. |
| `headless` | `boolean` | `true` | Run the Chrome sidecar headless. |
| `port` | `number` | — | Override the dev port. Defaults to the project's `vite.config.ts` setting or `5173`. |
| `openUrl` | `string` | — | Override the URL Chrome navigates to. |

### `agent-build`

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `"vite-react"` | `vite-react` | Host project type. |
| `projectRoot` | `string` | — | Override the project root passed to Vite. Defaults to the running project's root. |
| `updateBaseline` | `boolean` | `true` | On success, write the resulting bundle report to `.lensmcp/baseline/bundle.json`. |

### `agent-verify`

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `"vite-react"` | `vite-react` | Host project type. |
| `projectRoot` | `string` | — | Override the project root. Defaults to the running project's root. |
| `skipTypecheck` | `boolean` | `false` | Skip the typecheck phase. |
| `skipLint` | `boolean` | `false` | Skip the lint phase. |
| `skipBuild` | `boolean` | `false` | Skip the build phase. |

## Usage

The `setup-vite` / `setup-nest` generators add an `agent-dev` target for you. A Vite-React project's `project.json` ends up looking like this:

```jsonc
{
  "name": "web",
  "targets": {
    "agent-dev": {
      "executor": "@lensmcp/nx-plugin:agent-dev",
      "options": {
        "kind": "vite-react",
        "chrome": true,
        "port": 5173
      }
    }
  }
}
```

Then run the host under the lens:

```bash
# Serve the app + Chrome capture sidecar + MCP server
nx run web:agent-dev

# Non-headless Chrome on a custom port
nx run web:agent-dev --headless=false --port=4200

# Instrumented build that refreshes the bundle baseline
nx run web:agent-build

# Deterministic typecheck → lint → build, report under .lensmcp/verifications/
nx run web:agent-verify
```

For a NestJS host, set up the project and run its target the same way:

```bash
nx g @lensmcp/nx-plugin:setup-nest --project=api
nx run api:agent-dev --kind=nestjs
```

## How it fits

`@lensmcp/nx-plugin` is the wiring layer; the actual capture happens through framework-specific packages it installs:

- **Frontend** — `setup-vite` adds [`@lensmcp/vite-plugin`](https://github.com/kiwiapps-ltd/lensmcp) to your `vite.config.ts`. Combined with the Chrome sidecar that `agent-dev` launches, this streams real browser events into the lens.
- **Backend** — `setup-nest` registers `LensmcpModule.forRoot()` (from `@lensmcp/node-instrumentation`) in your NestJS `AppModule`, so server-side traces flow into the lens.

The plugin pairs with the rest of the LensMCP toolchain: the `lensmcp` CLI (which can run `init` for you via `lensmcp install`) and [`@lensmcp/cluster`](https://github.com/kiwiapps-ltd/lensmcp) for the gateway/registry that routes traffic between agents and instrumented apps.

---

Part of [LensMCP](https://github.com/kiwiapps-ltd/lensmcp). Apache-2.0.