@gtrabanco/pi-nan-provider 0.2.1 → 0.4.1

package/README.es.md

@@ -59,19 +59,29 @@ Consigue una clave en la [plataforma NaN](https://cloud.nan.builders/r/7GK06FX8)
 
 pi no incluye cliente MCP a propósito ("It intentionally does not include built-in MCP" — `docs/usage.md` de pi). Este paquete conecta servidores MCP dentro de pi como herramientas nativas personalizadas, de modo que el LLM las llama como cualquier herramienta integrada.
 
-### 1. Servidor MCP oficial de NaN (activo por defecto)
+Ambos puentes están **activados y perezosos por defecto**, y se configuran con el comando `/nan-mcp` que trae este paquete (pi no tiene comando `/mcp` propio — no tiene cliente MCP en absoluto — así que el comando se llama `/nan-mcp`):
+
+| Comando | Efecto |
+|---|---|
+| `/nan-mcp status` | Estado de ambos puentes y de dónde sale cada interruptor (env / persistido / por defecto) |
+| `/nan-mcp enable [target]` | Activa un puente — o ambos si no das target — y lo persiste en `<agentDir>/nan-provider.json` (p. ej. `~/.pi/agent/nan-provider.json`); las herramientas se registran al instante en la sesión actual |
+| `/nan-mcp disable [target]` | Desactiva persistentemente; pi no tiene `unregisterTool`, así que las herramientas ya registradas siguen hasta reiniciar; las sesiones futuras no las registran |
+
+Targets: `web-search` (puente oficial; alias `search`) y `nan-mcp-server` (puente de media de la comunidad; alias `media`). Ejemplo: `/nan-mcp enable nan-mcp-server`. Las variables de entorno explícitas tienen prioridad sobre los toggles persistidos (ver tabla inferior).
+
+### 1. Servidor MCP oficial de NaN (por defecto: activado, perezoso)
 
 El servidor MCP remoto oficial de NaN ([`https://api.nan.builders/mcp`](https://nan.builders/docs/api), JSON-RPC 2.0 sobre HTTP, misma clave `sk-`, mismo límite de tasa/cuota/concurrencia que la API REST) se conecta como:
 
-- **`nan_web_search(query, count?, freshness?, fetch_content?)`** — búsqueda web vía NaN. Registrado por defecto siempre que pi soporte `registerTool`; desactívalo con `NAN_MCP_TOOLS=0`.
+- **`nan_web_search(query, count?, freshness?, fetch_content?)`** — búsqueda web vía NaN. La llamada HTTP solo ocurre cuando se invoca la herramienta.
 
 El servidor es un registro en crecimiento (descubrible con `tools/list`); este paquete conecta por ahora la herramienta documentada `web_search` y mantiene un helper genérico `callNanMcpTool()` para herramientas futuras.
 
-### 2. Servidor MCP de media de la comunidad (opcional, perezoso)
+### 2. Servidor MCP de media de la comunidad (por defecto: activado, perezoso)
 
 [`nan-mcp-server`](https://github.com/luciferfran/nan-mcp-server) es un servidor MCP stdio que expone las herramientas de media de NaN: generación/edición de imágenes (flux-2-klein), TTS (kokoro) y STT (whisper). Como pi no tiene cliente MCP, este paquete lo conecta como herramientas de pi mediante un cliente MCP stdio mínimo:
 
-- **Desactivado por defecto** — actívalo con `NAN_MEDIA_MCP=1`.
+- **Activado por defecto**, conmutado persistentemente con `/nan-mcp enable|disable nan-mcp-server` (o `media`), o por sesión con `NAN_MEDIA_MCP` (cualquier valor explícito — p. ej. `NAN_MEDIA_MCP=0` — tiene prioridad sobre el toggle persistido).
 - **Perezoso (lazy)**: el proceso del servidor MCP se lanza *por cada llamada* y se termina justo después. No arranca ni conecta nada a menos que se invoque realmente generación de audio/imagen/transcripción.
 - **Configuración**: `NAN_API_KEY` se reenvía automáticamente (la misma clave del proveedor); los ficheros generados van a `~/nan-mcp-output/` (por defecto del servidor, configurable con `NAN_OUTPUT_DIR`).
 
@@ -87,11 +97,11 @@ Variables de entorno:
 
 | Variable | Por defecto | Significado |
 |---|---|---|
-| `NAN_MEDIA_MCP` | off | `1`/`true`/`on` activa las herramientas de media |
+| `NAN_MEDIA_MCP` | — | Override por sesión del puente de media: cualquier valor explícito (incl. `0`) gana al toggle persistido de `/nan-mcp`; sin definir → persistido/por defecto |
 | `NAN_MEDIA_MCP_VERSION` | `1.0.7` | Versión del servidor fijada para `npx -y nan-mcp-server@<v>` (recomendación de supply-chain del propio proyecto) |
 | `NAN_MEDIA_MCP_COMMAND` | — | Comando personalizado completo, p. ej. `bunx nan-mcp-server@1.0.7` |
 | `NAN_MEDIA_MCP_TIMEOUT_MS` | `120000` | Timeout por llamada; el proceso se mata al expirar |
-| `NAN_MCP_TOOLS` | — | `0`/`false`/`off` desactiva el puente `nan_web_search` oficial |
+| `NAN_MCP_TOOLS` | — | Override por sesión del puente oficial: `0`/`false`/`off` desactiva `nan_web_search`; sin definir → persistido/por defecto |
 
 ## Modelos
 

package/README.md

@@ -59,19 +59,29 @@ Get a key from the [NaN platform](https://cloud.nan.builders/r/7GK06FX8) (user s
 
 pi intentionally ships without an MCP client ("It intentionally does not include built-in MCP" — pi's `docs/usage.md`). This package bridges MCP servers into pi as native custom tools, so the LLM calls them like any built-in tool.
 
-### 1. Official NaN MCP server (on by default)
+Both bridges are **enabled and lazy by default** and are configured with the `/nan-mcp` slash command this package ships (pi has no `/mcp` command of its own — it has no MCP client at all — so the command is namespaced `/nan-mcp`):
+
+| Command | Effect |
+|---|---|
+| `/nan-mcp status` | State of both bridges and where each toggle comes from (env / persisted / default) |
+| `/nan-mcp enable [target]` | Enable a bridge — or both when no target is given — and persist it in `<agentDir>/nan-provider.json` (e.g. `~/.pi/agent/nan-provider.json`); tools register immediately for the current session |
+| `/nan-mcp disable [target]` | Disable persistently; pi has no `unregisterTool`, so already-registered tools remain until restart, future sessions skip them |
+
+Targets: `web-search` (official bridge) and `nan-mcp-server` (community media bridge; alias `media`). Example: `/nan-mcp enable nan-mcp-server`. Explicit env vars override the persisted toggles for the session (see the table below).
+
+### 1. Official NaN MCP server (default: enabled, lazy)
 
 NaN's official remote MCP server ([`https://api.nan.builders/mcp`](https://nan.builders/docs/api), JSON-RPC 2.0 over HTTP, same `sk-` key, same rate limit/quota/concurrency as the REST API) is bridged as:
 
-- **`nan_web_search(query, count?, freshness?, fetch_content?)`** — web search through NaN. Registered by default whenever pi supports `registerTool`; disable with `NAN_MCP_TOOLS=0`.
+- **`nan_web_search(query, count?, freshness?, fetch_content?)`** — web search through NaN. The HTTP call happens only when the tool is invoked.
 
 The server is a growing registry (discover with `tools/list`); this package currently bridges the documented `web_search` tool and keeps a generic `callNanMcpTool()` helper for future tools.
 
-### 2. Community media MCP server (opt-in, lazy)
+### 2. Community media MCP server (default: enabled, lazy)
 
 [`nan-mcp-server`](https://github.com/luciferfran/nan-mcp-server) is a stdio MCP server exposing NaN's media tools: image generation/editing (flux-2-klein), TTS (kokoro), and STT (whisper). Because pi has no MCP client, this package bridges it as pi tools via a minimal built-in MCP stdio client:
 
-- **Off by default** — enable with `NAN_MEDIA_MCP=1`.
+- **Enabled by default**, toggled persistently with `/nan-mcp enable|disable nan-mcp-server` (or `media`), or per-session with `NAN_MEDIA_MCP` (any explicit value — e.g. `NAN_MEDIA_MCP=0` — overrides the persisted toggle).
 - **Lazy**: the MCP server process is spawned *per tool call* and terminated immediately after. Nothing starts, connects, or costs anything unless audio/image/transcription is actually invoked.
 - **Config**: `NAN_API_KEY` is forwarded automatically (same key as the provider); generated files land in `~/nan-mcp-output/` (the server's default, override with `NAN_OUTPUT_DIR`).
 
@@ -87,11 +97,11 @@ Environment variables:
 
 | Variable | Default | Meaning |
 |---|---|---|
-| `NAN_MEDIA_MCP` | off | `1`/`true`/`on` enables the media tools |
+| `NAN_MEDIA_MCP` | — | Per-session override for the media bridge: any explicit value (incl. `0`) beats the `/nan-mcp` persisted toggle; unset → persisted/default |
 | `NAN_MEDIA_MCP_VERSION` | `1.0.7` | Pinned server version for `npx -y nan-mcp-server@<v>` (upstream's own supply-chain recommendation) |
 | `NAN_MEDIA_MCP_COMMAND` | — | Full custom command, e.g. `bunx nan-mcp-server@1.0.7` |
 | `NAN_MEDIA_MCP_TIMEOUT_MS` | `120000` | Per-call timeout; the process is killed after it |
-| `NAN_MCP_TOOLS` | — | `0`/`false`/`off` disables the official `nan_web_search` bridge |
+| `NAN_MCP_TOOLS` | — | Per-session override for the official bridge: `0`/`false`/`off` disables `nan_web_search`; unset → persisted/default |
 
 ## Models
 

package/package.json

@@ -1,18 +1,20 @@
 {
 	"name": "@gtrabanco/pi-nan-provider",
-	"version": "0.2.1",
+	"version": "0.4.1",
 	"description": "NaN Builders (api.nan.builders) model provider for pi - OpenAI-compatible registration with a models.dev-generated fallback, tier-aware live catalog, and MCP bridges (official web search + optional community media server)",
 	"keywords": [
 		"pi",
 		"pi-package",
 		"pi-extension",
-		"pi-coding-agent",
+		"provider",
 		"ai",
 		"ai-provider",
+		"llm",
 		"nan",
 		"nan-builders",
+		"api-nan-builders",
 		"openai-compatible",
-		"litellm"
+		"ai-model"
 	],
 	"type": "module",
 	"main": "./src/index.ts",
@@ -55,5 +57,13 @@
 	"bugs": {
 		"url": "https://github.com/gtrabanco/pi-nan-provider/issues"
 	},
-	"homepage": "https://github.com/gtrabanco/pi-nan-provider#readme"
+	"homepage": "https://github.com/gtrabanco/pi-nan-provider#readme",
+	"dependencies": {
+		"@gtrabanco/pi-agentic-workflow": "^0.4.0",
+		"@tintinweb/pi-subagents": "^0.19.0",
+		"pi-effort": "^0.0.8",
+		"pi-mcp-adapter": "^2.32.1",
+		"version": "^0.1.2",
+		"view": "^1.1.1"
+	}
 }

package/scripts/models.generated.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by scripts/generate-models.ts
 // Do not edit manually — run `bun run generate-models` to update.
 //
-// Source: https://models.dev/api.json (provider "nan"), fetched 2026-09-04T18:57:45.925Z
+// Source: https://models.dev/api.json (provider "nan"), fetched 2026-09-04T20:25:06.364Z
 // Provenance: every contextWindow/maxTokens/input/cost value traces to
 // models.dev or to the per-entry notes below. Nothing is invented; entries
 // models.dev documents incompletely are omitted and flagged instead.
@@ -430,7 +430,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 export const GENERATED_CATALOG_META = {
 	source: "https://models.dev/api.json",
 	modelsDevProvider: "nan",
-	fetchedAt: "2026-09-04T18:57:45.925Z",
+	fetchedAt: "2026-09-04T20:25:06.364Z",
 	modelCount: 7,
 	models: ["deepseek-v4-flash","gemma4","glm5.2","glm5.3-flash","mimo-v2.5","qwen3.6","qwen3.8-flash"],
 	notes: [

package/src/commands.ts

@@ -0,0 +1,165 @@
+/**
+ * `/nan-mcp` — slash command configuring BOTH MCP bridges this package
+ * registers as pi tools:
+ *
+ * - `web-search` — the official NaN remote MCP server (api.nan.builders/mcp),
+ *   exposing `nan_web_search`. Default: enabled.
+ * - `nan-mcp-server` — the community stdio media server (image generation /
+ *   editing, TTS, STT). Default: enabled, lazy (spawned per tool call).
+ *
+ * pi has no MCP client and therefore no `/mcp` command of its own, so this
+ * command owns the toggles:
+ *
+ * - `/nan-mcp` or `/nan-mcp status` — state of both bridges and their source.
+ * - `/nan-mcp enable [target]` — enable a bridge (or both, when no target is
+ *   given) and persist it in `<agentDir>/nan-provider.json`; enabled bridges
+ *   register their tools immediately for the current session.
+ * - `/nan-mcp disable [target]` — disable persistently. pi has no
+ *   unregisterTool, so already-registered tools remain until the next
+ *   session/restart; the persisted toggle governs future sessions.
+ *
+ * Targets accept aliases: `web-search` (`search`, `web_search`, `official`,
+ * `nan-web-search`) and `nan-mcp-server` (`media`, `media-mcp`, `nan-media`).
+ * Explicit env vars (NAN_MCP_TOOLS, NAN_MEDIA_MCP) override the persisted
+ * toggles for the session.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { mediaMcpCommand, mediaMcpEnabled, mediaMcpSource } from "./mcp/nan-media.ts";
+import { webSearchBridgeEnabled, webSearchBridgeSource } from "./mcp/nan-search.ts";
+import { NAN_STATE_FILE, readBridgeState, writeBridgeState, type BridgeKey } from "./mcp/state.ts";
+
+export interface NanMcpCommandOptions {
+	/** Register web-search bridge tools now; must skip already-registered tools. */
+	registerWebSearchTools: () => void;
+	/** Register media bridge tools now; must skip already-registered tools. */
+	registerMediaTools: () => void;
+}
+
+const USAGE =
+	"Usage: /nan-mcp [status] · /nan-mcp enable [web-search|nan-mcp-server] · /nan-mcp disable [web-search|nan-mcp-server]";
+
+/** Canonical bridge targets with aliases (e.g. `/mcp enable nan-mcp-server` muscle memory). */
+const TARGETS: Record<string, BridgeKey> = {
+	"web-search": "webSearch",
+	search: "webSearch",
+	web_search: "webSearch",
+	official: "webSearch",
+	"nan-web-search": "webSearch",
+	"nan-mcp-server": "mediaMcp",
+	media: "mediaMcp",
+	"media-mcp": "mediaMcp",
+	"nan-media": "mediaMcp",
+};
+
+function targetName(bridge: BridgeKey): string {
+	return bridge === "webSearch" ? "web-search" : "nan-mcp-server";
+}
+
+function envOverrideLabel(bridge: BridgeKey): string {
+	return bridge === "webSearch"
+		? `env NAN_MCP_TOOLS=${process.env.NAN_MCP_TOOLS ?? ""} (overrides persisted)`
+		: `env NAN_MEDIA_MCP=${process.env.NAN_MEDIA_MCP ?? ""} (overrides persisted)`;
+}
+
+function sourceLabel(bridge: BridgeKey, source: "env" | "persisted" | "default"): string {
+	if (source === "env") return envOverrideLabel(bridge);
+	if (source === "persisted") {
+		return `persisted in <agentDir>/${NAN_STATE_FILE} (${targetName(bridge)}: ${readBridgeState(bridge)})`;
+	}
+	return "default (both bridges are enabled and lazy by default)";
+}
+
+function statusMessage(): string {
+	return [
+		`web-search bridge (official NaN MCP → nan_web_search): ${webSearchBridgeEnabled() ? "enabled" : "disabled"} — ${sourceLabel("webSearch", webSearchBridgeSource())}.`,
+		`nan-mcp-server bridge (community media MCP → nan_generate_image/nan_edit_image/nan_text_to_speech/nan_list_voices/nan_speech_to_text): ${mediaMcpEnabled() ? "enabled" : "disabled"} — ${sourceLabel("mediaMcp", mediaMcpSource())}.`,
+		`Media spawn command: ${mediaMcpCommand().join(" ")} (per tool call, terminated after).`,
+		"Configure with /nan-mcp enable|disable [web-search|nan-mcp-server]; no target = both.",
+	].join("\n");
+}
+
+/** Parse an optional target argument; no target = both bridges. Returns undefined target name on unknown. */
+function parseTarget(token: string | undefined): { bridges: BridgeKey[]; target?: string } | undefined {
+	if (token === undefined) return { bridges: ["webSearch", "mediaMcp"] };
+	const key = TARGETS[token.toLowerCase()];
+	if (!key) return undefined;
+	return { bridges: [key], target: token.toLowerCase() };
+}
+
+function describeBridges(bridges: BridgeKey[]): string {
+	const names = bridges.map((bridge) => targetName(bridge));
+	return names.length === 2 ? "both bridges" : names.join(" and ");
+}
+
+export function registerNanMcpCommand(pi: ExtensionAPI, options: NanMcpCommandOptions): void {
+	pi.registerCommand("nan-mcp", {
+		description:
+			"NaN MCP configuration: enable/disable/status for both bridges (official web-search + community nan-mcp-server)",
+		getArgumentCompletions: (argumentPrefix: string) => {
+			const prefix = argumentPrefix.trim().toLowerCase();
+			const items = [
+				{ value: "enable", label: "enable", description: "Enable a bridge (or both) and persist it" },
+				{ value: "disable", label: "disable", description: "Disable a bridge (or both) persistently" },
+				{ value: "status", label: "status", description: "Show current bridge status" },
+				{ value: "enable web-search", label: "enable web-search", description: "Enable the official NaN web-search bridge" },
+				{ value: "enable nan-mcp-server", label: "enable nan-mcp-server", description: "Enable the community media bridge" },
+			];
+			const filtered = items.filter((item) => item.value.startsWith(prefix));
+			return filtered.length > 0 ? filtered : null;
+		},
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const tokens = args.trim().split(/\s+/).filter(Boolean);
+			const [rawSubcommand = "status", rawTarget, ...rest] = tokens;
+			const subcommand = rawSubcommand.toLowerCase();
+
+			if (subcommand === "status") {
+				ctx.ui.notify(statusMessage(), "info");
+				return;
+			}
+
+			if (subcommand === "enable" || subcommand === "disable") {
+				// Trailing tokens beyond the target (e.g. duplicate target names) are ignored.
+				const parsed = parseTarget(rawTarget);
+				if (parsed === undefined || rest.length > 0) {
+					ctx.ui.notify(
+						parsed === undefined
+							? `Unknown target "${[rawTarget, ...rest].filter(Boolean).join(" ")}". Targets: web-search, nan-mcp-server (or omit for both).`
+							: USAGE,
+						"warning",
+					);
+					return;
+				}
+				const { bridges, target } = parsed;
+				const enabled = subcommand === "enable";
+
+				for (const bridge of bridges) {
+					writeBridgeState(bridge, enabled);
+				}
+				if (enabled) {
+					if (bridges.includes("webSearch")) options.registerWebSearchTools();
+					if (bridges.includes("mediaMcp")) options.registerMediaTools();
+				}
+
+				const where = target ? `for "${target}"` : "for both bridges";
+				const persistence = `persisted in <agentDir>/${NAN_STATE_FILE}`;
+				if (enabled) {
+					ctx.ui.notify(
+						`Enabled ${describeBridges(bridges)} ${where}, ${persistence}. Tools are available now; both bridges are lazy (web-search calls the endpoint per request, nan-mcp-server spawns per call), so nothing runs until invoked.` +
+							" An explicit NAN_MCP_TOOLS / NAN_MEDIA_MCP env var would override this toggle.",
+						"info",
+					);
+				} else {
+					ctx.ui.notify(
+						`Disabled ${describeBridges(bridges)} ${where}, ${persistence}. pi has no unregisterTool, so tools already registered in this session remain until restart (or /reload); future sessions will not register them.` +
+							" An explicit NAN_MCP_TOOLS / NAN_MEDIA_MCP env var overrides this toggle.",
+						"warning",
+					);
+				}
+				return;
+			}
+
+			ctx.ui.notify(USAGE, "warning");
+		},
+	});
+}

package/src/index.ts

@@ -21,8 +21,9 @@
  */
 
 import type { ExtensionAPI, ProviderConfig } from "@earendil-works/pi-coding-agent";
+import { registerNanMcpCommand } from "./commands.ts";
 import { baselineModels } from "./fetch-models.ts";
-import { createNanWebSearchTool, mcpToolsDisabled, NAN_API_KEY_ENV } from "./mcp/nan-search.ts";
+import { createNanWebSearchTool, webSearchBridgeEnabled, NAN_API_KEY_ENV } from "./mcp/nan-search.ts";
 import { createNanMediaTools, mediaMcpEnabled } from "./mcp/nan-media.ts";
 import { createNanCompatibleProvider, type OpenAICompatibleProviderConfig } from "./provider-factory.ts";
 import { PROVIDERS } from "./providers.ts";
@@ -65,19 +66,35 @@ function registerProviderCompat(pi: ExtensionAPI, config: OpenAICompatibleProvid
 }
 
 /**
- * Register MCP-bridged tools when the runtime supports them. Old pi versions
- * without registerTool simply skip this block — provider registration is
- * unaffected.
+ * Register MCP-bridged tools when the runtime supports them. Both bridges
+ * are enabled by default and lazy (nothing runs until a tool is invoked);
+ * `/nan-mcp` (and the NAN_MCP_TOOLS / NAN_MEDIA_MCP env vars) toggle them.
+ * Old pi versions without registerTool/registerCommand skip gracefully.
+ *
+ * Registration is tracked in `registeredToolNames` so `/nan-mcp enable` can
+ * add tools mid-session without double-registering.
  */
 function registerMcpToolsCompat(pi: ExtensionAPI): void {
 	if (typeof pi.registerTool !== "function") return;
-	if (!mcpToolsDisabled()) {
-		pi.registerTool(createNanWebSearchTool());
-	}
-	if (mediaMcpEnabled()) {
+	const registeredToolNames = new Set<string>();
+	const registerSearchTool = () => {
+		const search = createNanWebSearchTool();
+		if (registeredToolNames.has(search.name)) return;
+		registeredToolNames.add(search.name);
+		pi.registerTool(search);
+	};
+	const registerMediaTools = () => {
 		for (const tool of createNanMediaTools()) {
+			if (registeredToolNames.has(tool.name)) continue;
+			registeredToolNames.add(tool.name);
 			pi.registerTool(tool);
 		}
+	};
+
+	if (webSearchBridgeEnabled()) registerSearchTool();
+	if (mediaMcpEnabled()) registerMediaTools();
+	if (typeof pi.registerCommand === "function") {
+		registerNanMcpCommand(pi, { registerWebSearchTools: registerSearchTool, registerMediaTools });
 	}
 }
 

package/src/mcp/nan-media.ts

@@ -20,6 +20,7 @@
 import { Type, type TSchema } from "@earendil-works/pi-ai";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { callStdioMcpTool } from "./stdio-client.ts";
+import { bridgeSource, resolveBridgeEnabled, type BridgeSource } from "./state.ts";
 import { NAN_API_KEY_ENV, resolveNanApiKey, type NapiKeyContext } from "./nan-search.ts";
 
 export const NAN_MEDIA_MCP_ENV = "NAN_MEDIA_MCP";
@@ -38,15 +39,34 @@ export const NAN_MEDIA_TOOLS = [
 	"nan_speech_to_text",
 ] as const;
 
-/** Truthy env parse: 1/true/on (case-insensitive). */
-function envEnabled(name: string): boolean {
-	const value = process.env[name]?.trim().toLowerCase();
-	return value === "1" || value === "true" || value === "on";
+/** Truthy env parse for the media bridge env var: 1/true/on (case-insensitive). */
+function envTruthy(): boolean {
+	return envValueIsTruthy(process.env[NAN_MEDIA_MCP_ENV]);
 }
 
-/** Whether the optional nan-mcp-server bridge is enabled (NAN_MEDIA_MCP=1). */
+/** Whether the env var is explicitly set (any value) — it overrides the persisted toggle. */
+function envExplicit(): boolean {
+	const value = process.env[NAN_MEDIA_MCP_ENV];
+	return value !== undefined && value.trim() !== "";
+}
+
+function envValueIsTruthy(value: string | undefined): boolean {
+	return value?.trim().toLowerCase() === "1" || value?.trim().toLowerCase() === "true" || value?.trim().toLowerCase() === "on";
+}
+
+/**
+ * Effective enablement of the community media MCP bridge: an explicit
+ * `NAN_MEDIA_MCP` env var (any value, e.g. `0` to force one session off)
+ * wins; then the toggle persisted by `/nan-mcp`; default: **enabled** (both
+ * bridges are on and lazy by default — the server spawns per tool call).
+ */
 export function mediaMcpEnabled(): boolean {
-	return envEnabled(NAN_MEDIA_MCP_ENV);
+	return resolveBridgeEnabled("mediaMcp", envExplicit(), envTruthy(), true);
+}
+
+/** Source of the effective media enablement (env / persisted / default). */
+export function mediaMcpSource(): BridgeSource {
+	return bridgeSource("mediaMcp", envExplicit());
 }
 
 /** Default spawn: `npx -y nan-mcp-server@<pinned version>` (npx caches after first use). */

package/src/mcp/nan-search.ts

@@ -15,12 +15,13 @@
 
 import { Type, type Static } from "@earendil-works/pi-ai";
 import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { bridgeSource, resolveBridgeEnabled, type BridgeSource } from "./state.ts";
 
 /** NaN's official remote MCP endpoint (host root, not /v1). */
 export const NAN_MCP_URL = "https://api.nan.builders/mcp";
 /** Web search can be slow; the endpoint shares the key's rate limits. */
 export const NAN_MCP_TIMEOUT_MS = 30_000;
-/** Env var that disables MCP tool registration: NAN_MCP_TOOLS=0|false|off. */
+/** Env var that overrides the official web_search bridge: NAN_MCP_TOOLS=0|false|off disables it. */
 export const NAN_MCP_TOOLS_ENV = "NAN_MCP_TOOLS";
 
 const NAN_PROVIDER_ID = "nan";
@@ -214,6 +215,26 @@ export function mcpToolsDisabled(): boolean {
 	return value === "0" || value === "false" || value === "off";
 }
 
+/** Whether NAN_MCP_TOOLS is explicitly set (any value) — it overrides the persisted toggle. */
+export function mcpToolsEnvExplicit(): boolean {
+	const value = process.env[NAN_MCP_TOOLS_ENV];
+	return value !== undefined && value.trim() !== "";
+}
+
+/**
+ * Effective enablement of the official web_search bridge: explicit
+ * NAN_MCP_TOOLS env var wins (any value, e.g. 0 to force one session off);
+ * then the toggle persisted by /nan-mcp; default: enabled.
+ */
+export function webSearchBridgeEnabled(): boolean {
+	return resolveBridgeEnabled("webSearch", mcpToolsEnvExplicit(), !mcpToolsDisabled(), true);
+}
+
+/** Source of the effective web_search enablement (env / persisted / default). */
+export function webSearchBridgeSource(): BridgeSource {
+	return bridgeSource("webSearch", mcpToolsEnvExplicit());
+}
+
 /** Extract an ExtensionContext-shaped key source for tests without full pi. */
 export function contextHasKeySource(ctx: ExtensionContext): NapiKeyContext {
 	return ctx as unknown as NapiKeyContext;

package/src/mcp/state.ts

@@ -0,0 +1,74 @@
+/**
+ * Persisted toggles for the MCP bridges this package registers, stored in
+ * pi's agent dir (e.g. ~/.pi/agent/nan-provider.json) so `/nan-mcp` changes
+ * survive across sessions.
+ *
+ * Resolution order for each bridge:
+ *   1. Explicit bridge env var (any value, including 0 — one-session override).
+ *   2. Persisted toggle written by /nan-mcp.
+ *   3. Default: enabled (both bridges are on and lazy by default).
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+/** Persisted-toggle state file inside pi's agent dir. */
+export const NAN_STATE_FILE = "nan-provider.json";
+
+export interface NanProviderState {
+	/** Persisted enablement of the official web_search MCP bridge. */
+	webSearch?: boolean;
+	/** Persisted enablement of the community nan-mcp-server media bridge. */
+	mediaMcp?: boolean;
+}
+
+export type BridgeKey = keyof NanProviderState;
+
+export type BridgeSource = "env" | "persisted" | "default";
+
+function stateFilePath(): string {
+	return join(getAgentDir(), NAN_STATE_FILE);
+}
+
+/**
+ * Read the persisted state. Never throws: a missing or corrupted file yields
+ * an empty state (defaults apply).
+ */
+export function readState(): NanProviderState {
+	try {
+		const parsed = JSON.parse(readFileSync(stateFilePath(), "utf8")) as NanProviderState;
+		return typeof parsed === "object" && parsed !== null ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+
+/** Persist a patch over the current state. Creates the agent dir if needed. */
+export function writeState(patch: Partial<NanProviderState>): void {
+	const path = stateFilePath();
+	mkdirSync(join(path, ".."), { recursive: true });
+	writeFileSync(path, `${JSON.stringify({ ...readState(), ...patch }, null, "\t")}\n`);
+}
+
+/** Persisted value for one bridge; `undefined` = not persisted (default applies). */
+export function readBridgeState(bridge: BridgeKey): boolean | undefined {
+	const value = readState()[bridge];
+	return typeof value === "boolean" ? value : undefined;
+}
+
+export function writeBridgeState(bridge: BridgeKey, enabled: boolean): void {
+	writeState({ [bridge]: enabled });
+}
+
+/** Where the effective value of a bridge comes from (for /nan-mcp status). */
+export function bridgeSource(bridge: BridgeKey, envExplicit: boolean): BridgeSource {
+	if (envExplicit) return "env";
+	return readBridgeState(bridge) !== undefined ? "persisted" : "default";
+}
+
+/** Effective value: explicit env → persisted → default. */
+export function resolveBridgeEnabled(bridge: BridgeKey, envExplicit: boolean, envTruthy: boolean, defaultValue: boolean): boolean {
+	if (envExplicit) return envTruthy;
+	return readBridgeState(bridge) ?? defaultValue;
+}