@mlightcad/cad-mcp-server 1.7.8-preview.1 → 1.7.8-preview.3

package/README.md

@@ -18,10 +18,10 @@ This server follows the design in
 - **Tools** for clear lifecycle steps (open / blank drawing)
 - **Scripts** for combining the CAD API into analysis, edits, and verification
 
-The model writes a `cad.*` function body; the headless viewer runs it. Same
-runtime as the in-app CAD Agent (`@mlightcad/cad-agent-core`), so external
-agents (Claude Code, Cursor, Codex, …) get flexibility without a ballooning
-tool list — and with lower token and round-trip cost for bulk work.
+The model writes a `cad.*` function body; the Chromium viewer runs it (headless
+or with a visible window). Same runtime as the in-app CAD Agent
+(`@mlightcad/cad-agent-core`), so external agents get flexibility without a
+ballooning tool list — and with lower token and round-trip cost for bulk work.
 
 ## Tools (intentionally small)
 
@@ -30,15 +30,26 @@ tool list — and with lower token and round-trip cost for bulk work.
 | `open_drawing` | Open a local/remote DXF/DWG, or omit `path` for a blank ISO template |
 | `execute_cad_script` | Run a `cad.*` JavaScript function body ([script API](https://mlightcad.github.io/cad-viewer/guide/script/overview.html)) |
 
+Both tools accept optional `visible`:
+
+| `visible` | Browser | Session lifecycle |
+| --- | --- | --- |
+| `false` / omit | Headless Chromium | Reused across tool calls; **auto-closes after idle** (default 30s) |
+| `true` | Visible Chromium window | Stays open so the user can watch the drawing |
+
+The agent chooses based on the user prompt (e.g. “open the browser so I can
+see the drawing” → `visible: true`; batch QA → headless). Changing `visible`
+after a session started rebuilds the browser and **resets drawing state**.
+
 There are **no** per-entity `draw_line` / `draw_circle` tools. All drawing,
 queries, edits, and context live inside one script call.
 
 ## Works with cad-simple-viewer and cad-viewer
 
 Both products share `AcApDocManager` from `@mlightcad/cad-simple-viewer`. This
-server’s headless runner boots that kernel (not the Vue UI package). Scripts
-you write for the Script panel or CAD Agent in either product are valid here,
-and the reverse is true.
+server’s runner boots that kernel (not the Vue UI package). Scripts you write
+for the Script panel or CAD Agent in either product are valid here, and the
+reverse is true.
 
 This package does **not** depend on `@mlightcad/cad-viewer`.
 
@@ -56,12 +67,19 @@ cad-mcp-server
 # or: node packages/cad-mcp-server/dist/cli.js
 ```
 
+### Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `CAD_MCP_VISIBLE=1` | Default headed when tools omit `visible` |
+| `CAD_MCP_IDLE_CLOSE_MS` | Headless idle auto-close delay in ms (default `30000`) |
+
 ## MCP client config
 
-### Cursor (`.cursor/mcp.json`)
+### Cursor (this monorepo)
 
-Prefer `${workspaceFolder}` over a hardcoded absolute path or a bare
-relative path (MCP cwd is not always the repo root):
+`npx` from the workspace root crashes npm (Arborist + workspace link). Use the
+launcher, which runs npx from the OS temp directory:
 
 ```json
 {
@@ -69,32 +87,71 @@ relative path (MCP cwd is not always the repo root):
     "cad": {
       "command": "node",
       "args": [
-        "${workspaceFolder}/packages/cad-mcp-server/dist/cli.js"
+        "${workspaceFolder}/packages/cad-mcp-server/scripts/run-published.mjs"
       ]
     }
   }
 }
 ```
 
-### Claude Code / Claude Desktop
+Override the pin with `CAD_MCP_SERVER_VERSION` (default `1.7.8-preview.1`).
+
+To force a visible browser by default (agent can still pass `visible: false`):
+
+```json
+{
+  "mcpServers": {
+    "cad": {
+      "command": "node",
+      "args": [
+        "${workspaceFolder}/packages/cad-mcp-server/dist/cli.js"
+      ],
+      "env": {
+        "CAD_MCP_VISIBLE": "1"
+      }
+    }
+  }
+}
+```
+
+### Claude Code / Claude Desktop (outside this repo)
 
 ```json
 {
   "mcpServers": {
     "cad": {
       "command": "npx",
-      "args": ["-y", "@mlightcad/cad-mcp-server"]
+      "args": [
+        "-y",
+        "--package=@mlightcad/cad-mcp-server@1.7.8-preview.1",
+        "cad-mcp-server"
+      ]
     }
   }
 }
 ```
 
-(After the package is published; for local monorepo use the `node …/dist/cli.js` form.)
+For local monorepo development against an unbuilt/unpublished tree, point at
+the built CLI instead:
+
+```json
+{
+  "mcpServers": {
+    "cad": {
+      "command": "node",
+      "args": [
+        "${workspaceFolder}/packages/cad-mcp-server/dist/cli.js"
+      ]
+    }
+  }
+}
+```
 
 ## Typical flow
 
 1. `open_drawing` with `{ "path": "./plan.dxf", "mode": "write" }`  
-   (local path or http(s) URL; omit `path` to start blank).
+   (local path or http(s) URL; omit `path` to start blank).  
+   Add `"visible": true` when the user should see the drawing.
 2. `execute_cad_script` with a function body:
 
 ```js
@@ -111,6 +168,17 @@ return cad.measure.report([
 `cad.view.capturePreview` is enabled; screenshots are returned as MCP image
 content.
 
+Save the drawing after edits:
+
+```js
+cad.file.saveDxf('./plan-out.dxf')
+```
+
+The MCP server writes that path (relative to the server process working
+directory). The DXF text is not sent back to the model; the tool result
+includes `savedFiles` with the absolute path. In the in-app CAD agent the same
+call downloads the file instead.
+
 ## Architecture
 
 ```
@@ -118,13 +186,13 @@ MCP client  --stdio-->  cad-mcp-server (Node)
                            |
                            | Playwright (lazy)
                            v
-                     headless Chromium
+                     Chromium (headless or headed)
                      cad-simple-viewer + cad-agent-core
                      createCadToolCatalog / execute_cad_script
 ```
 
-The browser session stays alive for the process lifetime so drawing state
-persists across tool calls.
+Headless sessions persist across tool calls until idle timeout. Headed sessions
+stay open until the MCP process exits.
 
 ## Library API
 
@@ -132,7 +200,8 @@ persists across tool calls.
 import {
   createCadMcpServer,
   registerCadMcpTools,
-  CadMcpSession
+  CadMcpSession,
+  resolveVisible
 } from '@mlightcad/cad-mcp-server'
 ```
 

package/dist/catalogTools.d.ts

@@ -9,6 +9,7 @@ import { z } from 'zod';
 export declare const executeCadScriptInputSchema: {
     code: z.ZodString;
     intent: z.ZodOptional<z.ZodString>;
+    visible: z.ZodOptional<z.ZodBoolean>;
 };
 /**
  * Input schema for MCP-only document lifecycle tool `open_drawing`.
@@ -16,6 +17,7 @@ export declare const executeCadScriptInputSchema: {
 export declare const openDrawingInputSchema: {
     path: z.ZodOptional<z.ZodString>;
     mode: z.ZodOptional<z.ZodEnum<["read", "write"]>>;
+    visible: z.ZodOptional<z.ZodBoolean>;
 };
 export interface RegisterCadMcpToolsOptions {
     /**
@@ -24,6 +26,7 @@ export interface RegisterCadMcpToolsOptions {
     openDrawing: (input: {
         path?: string;
         mode?: 'read' | 'write';
+        visible?: boolean;
     }) => Promise<{
         ok: true;
         title: string;
@@ -35,6 +38,7 @@ export interface RegisterCadMcpToolsOptions {
     executeCadScript: (input: {
         code: string;
         intent?: string;
+        visible?: boolean;
     }) => Promise<unknown>;
 }
 /**

package/dist/catalogTools.js

@@ -1,6 +1,10 @@
 import { CAD_SCRIPT_API_SUMMARY } from '@mlightcad/cad-agent-core/script-api';
 import { z } from 'zod';
 import { toolResultToMcpContent } from './toolResult.js';
+const visibleField = z
+    .boolean()
+    .optional()
+    .describe('Show a Chromium window so the user can watch the drawing. true = visible window (stays open). false/omit = headless (auto-closes after idle). Use true when the user asks to see the result; use headless for batch work. Changing this after a session started rebuilds the browser and resets drawing state.');
 /**
  * Input schema for `execute_cad_script`.
  *
@@ -16,7 +20,8 @@ export const executeCadScriptInputSchema = {
         .string()
         .max(200)
         .optional()
-        .describe('Optional short label for the tool result. Never send intent alone — code is required. Prefer emitting code before intent.')
+        .describe('Optional short label for the tool result. Never send intent alone — code is required. Prefer emitting code before intent.'),
+    visible: visibleField
 };
 /**
  * Input schema for MCP-only document lifecycle tool `open_drawing`.
@@ -29,7 +34,8 @@ export const openDrawingInputSchema = {
     mode: z
         .enum(['read', 'write'])
         .optional()
-        .describe('Open mode. Default: write when path is omitted, read when path is set. Use write to edit an existing file.')
+        .describe('Open mode. Default: write when path is omitted, read when path is set. Use write to edit an existing file.'),
+    visible: visibleField
 };
 /**
  * Registers the script-first CAD tool surface on an MCP server.
@@ -46,13 +52,14 @@ export function registerCadMcpTools(server, options) {
     // MCP SDK + zod generics often hit TS2589; register via a loose shim.
     const register = server.registerTool.bind(server);
     register('open_drawing', {
-        description: 'Open a DXF/DWG drawing (local path or http(s) URL), or omit path to create a blank ISO template. Call before editing an existing file. Drawing ops use execute_cad_script.',
+        description: 'Open a DXF/DWG drawing (local path or http(s) URL), or omit path to create a blank ISO template. Call before editing an existing file. Drawing ops use execute_cad_script. Pass visible=true when the user should see the browser/drawing; omit or false for headless (auto-closes after idle).',
         inputSchema: openDrawingInputSchema
     }, async (input) => {
         try {
             const result = await options.openDrawing({
                 path: input.path,
-                mode: input.mode
+                mode: input.mode,
+                visible: input.visible
             });
             return {
                 content: [{ type: 'text', text: JSON.stringify(result) }]
@@ -80,7 +87,8 @@ export function registerCadMcpTools(server, options) {
         try {
             const raw = await options.executeCadScript({
                 code: input.code,
-                intent: input.intent
+                intent: input.intent,
+                visible: input.visible
             });
             return toolResultToMcpContent(raw);
         }

package/dist/catalogTools.js.map

@@ -1 +1 @@
-{"version":3,"file":"catalogTools.js","sourceRoot":"","sources":["../src/catalogTools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAA;AAE7E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAExD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,iHAAiH,CAClH;IACH,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,GAAG,CAAC,GAAG,CAAC;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,2HAA2H,CAC5H;CACJ,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,mFAAmF,CACpF;IACH,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SACvB,QAAQ,EAAE;SACV,QAAQ,CACP,4GAA4G,CAC7G;CACJ,CAAA;AAmBD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAiB,EACjB,OAAmC;IAEnC,sEAAsE;IACtE,MAAM,QAAQ,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAavC,CAAA;IAET,QAAQ,CACN,cAAc,EACd;QACE,WAAW,EACT,4KAA4K;QAC9K,WAAW,EAAE,sBAAsB;KACpC,EACD,KAAK,EAAC,KAAK,EAAC,EAAE;QACZ,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC;gBACvC,IAAI,EAAE,KAAK,CAAC,IAA0B;gBACtC,IAAI,EAAE,KAAK,CAAC,IAAoC;aACjD,CAAC,CAAA;YACF,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;aACnE,CAAA;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;4BACnB,EAAE,EAAE,KAAK;4BACT,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;yBAC9D,CAAC;qBACH;iBACF;gBACD,OAAO,EAAE,IAAI;aACd,CAAA;QACH,CAAC;IACH,CAAC,CACF,CAAA;IAED,QAAQ,CACN,oBAAoB,EACpB;QACE,WAAW,EAAE,sBAAsB;QACnC,WAAW,EAAE,2BAA2B;KACzC,EACD,KAAK,EAAC,KAAK,EAAC,EAAE;QACZ,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,gBAAgB,CAAC;gBACzC,IAAI,EAAE,KAAK,CAAC,IAAc;gBAC1B,MAAM,EAAE,KAAK,CAAC,MAA4B;aAC3C,CAAC,CAAA;YACF,OAAO,sBAAsB,CAC3B,GAAqD,CACtD,CAAA;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;4BACnB,OAAO,EAAE,KAAK;4BACd,OAAO,EAAE,yBAAyB;4BAClC,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;yBAC9D,CAAC;qBACH;iBACF;gBACD,OAAO,EAAE,IAAI;aACd,CAAA;QACH,CAAC;IACH,CAAC,CACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"catalogTools.js","sourceRoot":"","sources":["../src/catalogTools.ts"],"names":[],"mappings":"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"}

package/dist/cli.js

@@ -5,12 +5,19 @@ import { createCadMcpServer } from './server.js';
  * stdio entry for `@mlightcad/cad-mcp-server`.
  *
  * stdout is reserved for MCP JSON-RPC — log only to stderr.
+ *
+ * Env (optional):
+ * - `CAD_MCP_VISIBLE=1` — default headed when tools omit `visible`
+ * - `CAD_MCP_IDLE_CLOSE_MS` — headless idle auto-close delay (default 30000)
  */
 async function main() {
     const server = createCadMcpServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error('[cad-mcp-server] listening on stdio');
+    const visibleDefault = process.env.CAD_MCP_VISIBLE?.trim().toLowerCase() === '1' ||
+        process.env.CAD_MCP_VISIBLE?.trim().toLowerCase() === 'true' ||
+        process.env.CAD_MCP_VISIBLE?.trim().toLowerCase() === 'yes';
+    console.error(`[cad-mcp-server] listening on stdio (default ${visibleDefault ? 'headed' : 'headless'})`);
 }
 main().catch(error => {
     console.error('[cad-mcp-server] fatal:', error instanceof Error ? error.message : error);

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AAEhF,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAEhD;;;;GAIG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAA;IACnC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAA;IAC5C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IAC/B,OAAO,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAA;AACtD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;IACnB,OAAO,CAAC,KAAK,CACX,yBAAyB,EACzB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAC/C,CAAA;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AAEhF,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAEhD;;;;;;;;GAQG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAA;IACnC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAA;IAC5C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IAC/B,MAAM,cAAc,GAClB,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,GAAG;QACzD,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM;QAC5D,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,KAAK,CAAA;IAC7D,OAAO,CAAC,KAAK,CACX,gDAAgD,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,GAAG,CAC1F,CAAA;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;IACnB,OAAO,CAAC,KAAK,CACX,yBAAyB,EACzB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAC/C,CAAA;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}

package/dist/headlessGpu.d.ts

@@ -1,6 +1,6 @@
 import { type Browser } from 'playwright';
 /**
- * ANGLE / GL backend tried for headless WebGL, in preference order.
+ * ANGLE / GL backend tried for WebGL, in preference order.
  * `swiftshader` is the software renderer used when no hardware backend works.
  */
 type GpuBackend = 'd3d11' | 'd3d9' | 'metal' | 'vulkan' | 'gl' | 'egl' | 'gles' | 'swiftshader';
@@ -24,9 +24,15 @@ export interface LaunchHeadlessChromiumOptions {
      * When hardware is unavailable, falls back to SwiftShader.
      */
     useGpu?: boolean;
+    /**
+     * Show a Chromium window. Default `false` (headless).
+     */
+    headed?: boolean;
 }
 /**
- * Launches headless Chromium for WebGL (same strategy as cad-simple-viewer-cli).
+ * Launches Chromium for WebGL (same GPU strategy as cad-simple-viewer-cli).
+ *
+ * Pass `headed: true` to show a visible browser window.
  */
 export declare function launchHeadlessChromium(options?: LaunchHeadlessChromiumOptions): Promise<HeadlessGpuLaunch>;
 export {};

package/dist/headlessGpu.js

@@ -62,14 +62,17 @@ async function launchSwiftShader(base) {
     return { browser, renderer, backend: 'swiftshader' };
 }
 /**
- * Launches headless Chromium for WebGL (same strategy as cad-simple-viewer-cli).
+ * Launches Chromium for WebGL (same GPU strategy as cad-simple-viewer-cli).
+ *
+ * Pass `headed: true` to show a visible browser window.
  */
 export async function launchHeadlessChromium(options = {}) {
     const channel = options.channel;
     const platform = options.platform ?? process.platform;
     const useGpu = options.useGpu !== false;
+    const headed = options.headed === true;
     const base = {
-        headless: true,
+        headless: !headed,
         ...(channel ? { channel } : {})
     };
     if (!useGpu) {

package/dist/headlessGpu.js.map

@@ -1 +1 @@
-{"version":3,"file":"headlessGpu.js","sourceRoot":"","sources":["../src/headlessGpu.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"headlessGpu.js","sourceRoot":"","sources":["../src/headlessGpu.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -6,6 +6,6 @@
  * @packageDocumentation
  */
 export { executeCadScriptInputSchema, openDrawingInputSchema, registerCadMcpTools, type RegisterCadMcpToolsOptions } from './catalogTools.js';
-export { createCadMcpServer } from './server.js';
+export { createCadMcpServer, resolveVisible } from './server.js';
 export { CadMcpSession, type CadMcpOpenMode, type CadMcpSessionCreateOptions } from './session.js';
 export { toolResultToMcpContent, type McpContentBlock } from './toolResult.js';

package/dist/index.js

@@ -6,7 +6,7 @@
  * @packageDocumentation
  */
 export { executeCadScriptInputSchema, openDrawingInputSchema, registerCadMcpTools } from './catalogTools.js';
-export { createCadMcpServer } from './server.js';
+export { createCadMcpServer, resolveVisible } from './server.js';
 export { CadMcpSession } from './session.js';
 export { toolResultToMcpContent } from './toolResult.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,EACtB,mBAAmB,EAEpB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EACL,aAAa,EAGd,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,sBAAsB,EAEvB,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,EACtB,mBAAmB,EAEpB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAChE,OAAO,EACL,aAAa,EAGd,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,sBAAsB,EAEvB,MAAM,iBAAiB,CAAA"}

package/dist/server.d.ts

@@ -1,7 +1,15 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Resolves whether the browser should be visible.
+ *
+ * Tool `visible` wins when set; otherwise `CAD_MCP_VISIBLE=1` / `true` / `yes`
+ * forces headed as the default for omitted `visible`.
+ */
+export declare function resolveVisible(toolVisible?: boolean): boolean;
 /**
  * Builds the stdio MCP server that exposes CAD script tools.
  *
- * The headless Chromium session is started lazily on the first tool call.
+ * The Chromium session is started lazily on the first tool call (headless or
+ * headed depending on `visible` / `CAD_MCP_VISIBLE`).
  */
 export declare function createCadMcpServer(): McpServer;

package/dist/server.js

@@ -4,10 +4,24 @@ import { registerCadMcpTools } from './catalogTools.js';
 import { CadMcpSession } from './session.js';
 const require = createRequire(import.meta.url);
 const { version: packageVersion } = require('../package.json');
+/**
+ * Resolves whether the browser should be visible.
+ *
+ * Tool `visible` wins when set; otherwise `CAD_MCP_VISIBLE=1` / `true` / `yes`
+ * forces headed as the default for omitted `visible`.
+ */
+export function resolveVisible(toolVisible) {
+    if (typeof toolVisible === 'boolean') {
+        return toolVisible;
+    }
+    const env = process.env.CAD_MCP_VISIBLE?.trim().toLowerCase();
+    return env === '1' || env === 'true' || env === 'yes';
+}
 /**
  * Builds the stdio MCP server that exposes CAD script tools.
  *
- * The headless Chromium session is started lazily on the first tool call.
+ * The Chromium session is started lazily on the first tool call (headless or
+ * headed depending on `visible` / `CAD_MCP_VISIBLE`).
  */
 export function createCadMcpServer() {
     const server = new McpServer({
@@ -16,11 +30,15 @@ export function createCadMcpServer() {
     });
     registerCadMcpTools(server, {
         openDrawing: async (input) => {
-            const session = await CadMcpSession.shared();
+            const session = await CadMcpSession.shared({
+                headed: resolveVisible(input.visible)
+            });
             return session.openDrawing(input);
         },
         executeCadScript: async (input) => {
-            const session = await CadMcpSession.shared();
+            const session = await CadMcpSession.shared({
+                headed: resolveVisible(input.visible)
+            });
             return session.executeCadScript(input);
         }
     });

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAEnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC9C,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAE5D,CAAA;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAA;IAEF,mBAAmB,CAAC,MAAM,EAAE;QAC1B,WAAW,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YACzB,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,CAAA;YAC5C,OAAO,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAA;QACnC,CAAC;QACD,gBAAgB,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YAC9B,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,CAAA;YAC5C,OAAO,OAAO,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAA;QACxC,CAAC;KACF,CAAC,CAAA;IAEF,OAAO,MAAM,CAAA;AACf,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAEnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC9C,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAE5D,CAAA;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,WAAqB;IAClD,IAAI,OAAO,WAAW,KAAK,SAAS,EAAE,CAAC;QACrC,OAAO,WAAW,CAAA;IACpB,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IAC7D,OAAO,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,KAAK,CAAA;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAA;IAEF,mBAAmB,CAAC,MAAM,EAAE;QAC1B,WAAW,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YACzB,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC;gBACzC,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC;aACtC,CAAC,CAAA;YACF,OAAO,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAA;QACnC,CAAC;QACD,gBAAgB,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YAC9B,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC;gBACzC,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC;aACtC,CAAC,CAAA;YACF,OAAO,OAAO,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAA;QACxC,CAAC;KACF,CAAC,CAAA;IAEF,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/session.d.ts

@@ -3,24 +3,45 @@ export type CadMcpOpenMode = 'read' | 'write';
 export interface CadMcpSessionCreateOptions {
     /** Prefer hardware GPU WebGL. Default `true`. */
     useGpu?: boolean;
+    /**
+     * Show a Chromium window so the user can watch the drawing.
+     * Default `false` (headless).
+     */
+    headed?: boolean;
+    /**
+     * Headless-only: close the browser after this many ms of idle time
+     * since the last tool call. Default `30000`. Ignored when headed.
+     */
+    idleCloseMs?: number;
 }
 /**
- * Long-lived headless Chromium session hosting cad-simple-viewer + agent-core.
+ * Long-lived Chromium session hosting cad-simple-viewer + agent-core.
  *
- * Started lazily on the first tool call and kept for the process lifetime so
- * drawing state persists across MCP tool invocations.
+ * Started lazily on the first tool call. Headless sessions auto-close after
+ * idle time; headed sessions stay open so the user can watch the drawing.
  */
 export declare class CadMcpSession {
     private readonly browser;
     private readonly page;
     private readonly server;
+    readonly headed: boolean;
+    private readonly idleCloseMs;
+    private idleTimer;
     private constructor();
     private static instance;
+    /** Resolved session used to detect headed mismatches before await. */
+    private static resolved;
     /**
      * Returns the shared session, creating it on first call.
+     *
+     * If an existing session has a different `headed` flag, it is closed and
+     * rebuilt (drawing state is lost).
      */
     static shared(options?: CadMcpSessionCreateOptions): Promise<CadMcpSession>;
     static create(options?: CadMcpSessionCreateOptions): Promise<CadMcpSession>;
+    private clearIdleClose;
+    private scheduleIdleClose;
+    private touchActivity;
     openDrawing(input: {
         path?: string;
         mode?: CadMcpOpenMode;