Add recommended guards helper (#12)

## Summary

- add public `recommendedGuards()` helper for unpackaged + env-var MCP
opt-in checks
- export the helper and its options type from the root and types
entrypoints
- update README quickstart/security snippets to use the package helper

## Verification

- [x] `pnpm run lint`
- [x] `pnpm run typecheck`
- [x] `pnpm run test`
- [x] `pnpm run build`
- [ ] `pnpm test:electron` if Electron/CDP behavior changed

Closes #5

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added a public helper to opt into MCP when the app is unpackaged and a
specified environment variable equals "1".
* **Documentation**
* Quickstart and guidance updated with example usage and clearer
behavior and edge-case notes.
* **Tests**
* Unit tests added covering packaged vs unpackaged states, env-var
opt-in, and error conditions.
* **Chores**
  * Changeset added documenting a minor version bump.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: jnsdls

.changeset/recommended-guards.md

@@ -0,0 +1,5 @@
+---
+"@nebula-agents/electron-mcp": minor
+---
+
+Add a public `recommendedGuards()` helper for unpackaged app plus env-var MCP opt-in checks.

README.md

@@ -19,7 +19,10 @@ external model, this package is probably not the right fit.
 
 ```ts
 import { app, BrowserWindow } from "electron";
-import { createElectronMcpServer } from "@nebula-agents/electron-mcp";
+import {
+  createElectronMcpServer,
+  recommendedGuards,
+} from "@nebula-agents/electron-mcp";
 
 let mainWindow: BrowserWindow | null = null;
 
@@ -30,7 +33,7 @@ const mcp = createElectronMcpServer({
 app.whenReady().then(async () => {
   mainWindow = new BrowserWindow();
 
-  if (recommendedGuards()) {
+  if (recommendedGuards({ app, envVar: "MY_APP_MCP" })) {
     await mcp.start();
     console.log(`MCP listening at ${mcp.url}`);
   }
@@ -39,10 +42,6 @@ app.whenReady().then(async () => {
 app.on("before-quit", () => {
   void mcp.stop();
 });
-
-function recommendedGuards(): boolean {
-  return !app.isPackaged && process.env.MY_APP_MCP === "1";
-}
 ```
 
 Connect an MCP client to the logged HTTP URL. The default is
@@ -124,11 +123,17 @@ own gate or do not start it.
 Recommended production guard:
 
 ```ts
-function recommendedGuards(): boolean {
-  return !app.isPackaged && process.env.MY_APP_MCP === "1";
+import { recommendedGuards } from "@nebula-agents/electron-mcp";
+
+if (recommendedGuards({ app, envVar: "MY_APP_MCP" })) {
+  await mcp.start();
 }
 ```
 
+The helper returns `true` only when the app is not packaged and the selected
+environment variable is set to `"1"`. It throws if neither `app.isPackaged` nor
+`isPackaged` is provided.
+
 ## Maintenance
 
 This is open code with no support SLA. Agent Labs reviews issues and PRs on a

src/guards.ts

@@ -0,0 +1,23 @@
+export interface RecommendedGuardsOptions {
+  app?: { readonly isPackaged: boolean };
+  isPackaged?: boolean;
+  env?: Record<string, string | undefined>;
+  envVar?: string;
+}
+
+const DEFAULT_ENV_VAR = "ELECTRON_MCP";
+
+export function recommendedGuards({
+  app,
+  isPackaged,
+  env = process.env,
+  envVar = DEFAULT_ENV_VAR,
+}: RecommendedGuardsOptions = {}): boolean {
+  const packaged = isPackaged ?? app?.isPackaged;
+  if (packaged === undefined) {
+    throw new Error(
+      "[mcp] recommendedGuards requires app.isPackaged or isPackaged",
+    );
+  }
+  return !packaged && env[envVar] === "1";
+}

src/index.test.ts

@@ -5,7 +5,7 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { createElectronMcpServer } from "./index";
+import { createElectronMcpServer, recommendedGuards } from "./index";
 
 // Ephemeral-port helper — the harness picks a free port via `port: 0`
 // and the handle exposes the resolved URL.
@@ -120,3 +120,68 @@ describe("createElectronMcpServer", () => {
     expect(handle.isRunning).toBe(false);
   });
 });
+
+describe("recommendedGuards", () => {
+  it("throws a packaged-state error when called without options", () => {
+    expect(() => recommendedGuards()).toThrow(/isPackaged/i);
+  });
+
+  it("allows startup when the app is unpackaged and the opt-in env var is enabled", () => {
+    expect(
+      recommendedGuards({
+        isPackaged: false,
+        env: { MY_APP_MCP: "1" },
+        envVar: "MY_APP_MCP",
+      }),
+    ).toBe(true);
+  });
+
+  it("blocks startup when the opt-in env var is not enabled", () => {
+    expect(
+      recommendedGuards({
+        isPackaged: false,
+        env: {},
+        envVar: "MY_APP_MCP",
+      }),
+    ).toBe(false);
+  });
+
+  it("blocks startup in packaged builds even when the opt-in env var is enabled", () => {
+    expect(
+      recommendedGuards({
+        isPackaged: true,
+        env: { MY_APP_MCP: "1" },
+        envVar: "MY_APP_MCP",
+      }),
+    ).toBe(false);
+  });
+
+  it("accepts an Electron app-like object for the packaged-state check", () => {
+    expect(
+      recommendedGuards({
+        app: { isPackaged: false },
+        env: { MY_APP_MCP: "1" },
+        envVar: "MY_APP_MCP",
+      }),
+    ).toBe(true);
+  });
+
+  it("blocks startup when an Electron app-like object reports a packaged build", () => {
+    expect(
+      recommendedGuards({
+        app: { isPackaged: true },
+        env: { MY_APP_MCP: "1" },
+        envVar: "MY_APP_MCP",
+      }),
+    ).toBe(false);
+  });
+
+  it("throws when no packaged-state source is provided", () => {
+    expect(() =>
+      recommendedGuards({
+        env: { MY_APP_MCP: "1" },
+        envVar: "MY_APP_MCP",
+      }),
+    ).toThrow(/isPackaged/i);
+  });
+});

src/index.ts

@@ -7,6 +7,8 @@ import {
 import type { SurfaceGetter, SurfaceMap } from "./surfaces";
 import type { ToolDef } from "./tool-def";
 
+export { type RecommendedGuardsOptions, recommendedGuards } from "./guards";
+
 export interface ElectronMcpServerConfig {
   getSurfaces: SurfaceGetter;
   port?: number;

src/types.ts

@@ -2,6 +2,7 @@ export type {
   ElectronMcpServerConfig,
   ElectronMcpServerHandle,
   McpLogger,
+  RecommendedGuardsOptions,
   SurfaceGetter,
   SurfaceMap,
   ToolDef,