@interactive-inc/claude-funnel 0.52.0 → 0.55.0

package/dist/claude.js

@@ -1,14 +1,405 @@
-import { d as settingsSchema, o as resolveFunnelPort } from "./settings-store-D2XSXTyt.js";
-import { a as FileProcessGuard, i as FunnelMcp, n as FUNNEL_MCP_COMMAND, o as FunnelClaude, r as FUNNEL_MCP_NAME, t as FUNNEL_MCP_ARGS } from "./mcp-Dr-nIBwN.js";
-import { a as FunnelLocalConfig, c as connectorSpecSchema, i as FunnelTokenPrompter, l as localConfigSchema, n as NodeFunnelTokenPrompter, o as LOCAL_CONFIG_FILENAME, r as FunnelLocalConfigSync, s as channelSpecSchema, t as funnelJsonSchema, u as profileSpecSchema } from "./local-config-json-schema-8IHjS4Q7.js";
-import { t as FunnelProfiles } from "./profiles-wMRnjSid.js";
-import { n as FunnelLocalConfigWriter, t as MemoryFunnelTokenPrompter } from "./memory-token-prompter-CLerGsgM.js";
+import { f as settingsSchema, s as resolveFunnelPort, t as gatewayLoopbackUrl } from "./gateway-base-url-6foMXfFf.js";
+import { a as FunnelMcp, i as FUNNEL_MCP_NAME, n as FUNNEL_MCP_ARGS, o as FileProcessGuard, r as FUNNEL_MCP_COMMAND, s as FunnelClaude, t as renderYaml } from "./yaml-render-OhUN-qkS.js";
+import { t as FunnelDocs } from "./funnel-docs-ng5K8w4j.js";
+import { a as FunnelLocalConfig, c as connectorSpecSchema, i as FunnelTokenPrompter, l as localConfigSchema, n as NodeFunnelTokenPrompter, o as LOCAL_CONFIG_FILENAME, r as FunnelLocalConfigSync, s as channelSpecSchema, t as funnelJsonSchema, u as profileSpecSchema } from "./local-config-json-schema-DE1zkMcb.js";
+import { t as FunnelProfiles } from "./profiles-MnXvYfZF.js";
+import { n as FunnelLocalConfigWriter, t as MemoryFunnelTokenPrompter } from "./memory-token-prompter-vBXxY20-.js";
 import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+//#region lib/engine/mcp/channel-server-http.ts
+const GATEWAY_OFFLINE_HINT = "Run `fnl gateway start` in a shell (MCP cannot start the daemon)";
+/**
+* Pass a value through `renderYaml` into the shape the MCP transport expects.
+* Used for offline fallbacks where we synthesise a response locally instead
+* of forwarding gateway JSON.
+*/
+const yamlResult = (value) => ({ content: [{
+	type: "text",
+	text: renderYaml(value)
+}] });
+/**
+* MCP error result with `isError: true` and a structured `{ error, nextAction }`
+* body. Keeping the shape uniform lets Claude pattern-match on `nextAction`
+* without re-parsing free-form text.
+*/
+const errorResult = (message, nextAction) => ({
+	content: [{
+		type: "text",
+		text: renderYaml({
+			error: message,
+			nextAction
+		})
+	}],
+	isError: true
+});
+/**
+* Convert a gateway HTTP response (JSON wire format) into the YAML text the
+* MCP transport hands back to Claude. YAML is what every fnl_* tool returns,
+* matching the CLI's output and keeping the parsing surface Claude has to
+* learn down to one.
+*/
+const toYamlResult = async (res) => {
+	const text = await res.text();
+	try {
+		return { content: [{
+			type: "text",
+			text: renderYaml(JSON.parse(text))
+		}] };
+	} catch {
+		return { content: [{
+			type: "text",
+			text
+		}] };
+	}
+};
+const getJson = async (url, headers, options = {}) => {
+	const res = await fetch(url, { headers }).catch(() => null);
+	if (!res) {
+		if (options.offlineFallback !== void 0) return yamlResult(options.offlineFallback);
+		return errorResult("gateway unreachable", GATEWAY_OFFLINE_HINT);
+	}
+	return toYamlResult(res);
+};
+const postJson = async (url, headers, body, options = {}) => {
+	const res = await fetch(url, {
+		method: "POST",
+		headers: {
+			...headers,
+			"content-type": "application/json"
+		},
+		body: JSON.stringify(body)
+	}).catch(() => null);
+	if (!res) {
+		if (options.offlineFallback !== void 0) return yamlResult(options.offlineFallback);
+		return errorResult("gateway unreachable", GATEWAY_OFFLINE_HINT);
+	}
+	return toYamlResult(res);
+};
+//#endregion
+//#region lib/engine/mcp/channel-server-builtin-handler.ts
+const docs = new FunnelDocs();
+/**
+* Dispatch a built-in fnl_* tool call to the right gateway endpoint (over
+* loopback HTTP) and return the response as a YAML-text MCP result. The few
+* read-only tools that can run without the gateway (docs lookup) bypass HTTP
+* entirely.
+*/
+const handleBuiltinTool = async (deps) => {
+	const headers = {};
+	if (deps.token) headers.authorization = `Bearer ${deps.token}`;
+	const args = deps.args;
+	const channelArg = typeof args?.channel === "string" ? args.channel : null;
+	const limitArg = typeof args?.limit === "number" ? args.limit : void 0;
+	const seqArg = typeof args?.seq === "number" ? args.seq : void 0;
+	const modeArg = args?.mode === "safe" || args?.mode === "aggressive" || args?.mode === "off" ? args.mode : "off";
+	const topicArg = typeof args?.topic === "string" ? args.topic : null;
+	const base = deps.gatewayBaseUrl;
+	if (deps.name === "fnl_doctor") return postJson(`${base}/doctor`, headers, { mode: modeArg }, { offlineFallback: doctorOfflineFallback(deps.allChannels) });
+	if (deps.name === "fnl_status") return getJson(`${base}/status`, headers, { offlineFallback: {
+		running: false,
+		error: "gateway unreachable",
+		nextAction: "run `fnl gateway start` in a shell (cannot be started from MCP)",
+		knownChannels: deps.allChannels.map((ch) => ch.name)
+	} });
+	if (deps.name === "fnl_debug") return getJson(channelArg ? `${base}/diagnostics?channel=${encodeURIComponent(channelArg)}` : `${base}/diagnostics?all=true`, headers, { offlineFallback: {
+		gateway: { running: false },
+		diagnosis: {
+			status: "error",
+			message: "gateway is not running",
+			nextActions: ["fnl gateway start"],
+			rootCause: null
+		},
+		knownChannels: deps.allChannels.map((ch) => ch.name)
+	} });
+	if (deps.name === "fnl_recent_events") return getJson(`${base}/diagnostics/events?${eventListQuery(channelArg, limitArg)}`, headers);
+	if (deps.name === "fnl_dropped_events") return getJson(`${base}/diagnostics/dropped?${eventListQuery(channelArg, limitArg)}`, headers);
+	if (deps.name === "fnl_connection_errors") return getJson(`${base}/diagnostics/errors?${eventListQuery(channelArg, limitArg)}`, headers);
+	if (deps.name === "fnl_replay_event") {
+		if (!channelArg) return errorResult("channel is required", "Provide the channel name (see fnl_status)");
+		return postJson(`${base}/diagnostics/replay`, headers, {
+			channel: channelArg,
+			seq: seqArg
+		});
+	}
+	if (deps.name === "fnl_docs") {
+		if (!topicArg) return yamlResult({ topics: docs.list() });
+		const text = docs.get(topicArg);
+		if (text === null) return yamlResult({
+			error: `unknown topic: ${topicArg}`,
+			availableTopics: docs.topics()
+		});
+		return yamlResult({
+			topic: topicArg,
+			text
+		});
+	}
+	return errorResult(`unknown built-in tool: ${deps.name}`, null);
+};
+const eventListQuery = (channel, limit) => {
+	const params = new URLSearchParams();
+	if (channel) params.set("channel", channel);
+	if (limit !== void 0) params.set("limit", String(limit));
+	return params.toString();
+};
+const doctorOfflineFallback = (allChannels) => ({
+	status: "error",
+	message: "gateway is not running and cannot be started over HTTP from the MCP side. Run `fnl gateway start` in a shell, or relaunch Claude with `fnl claude` which auto-starts the gateway.",
+	appliedActions: [],
+	remainingIssues: allChannels.map((ch) => ({
+		channel: ch.name,
+		diagnosis: {
+			status: "error",
+			message: "gateway is not running",
+			nextActions: ["fnl gateway start"],
+			rootCause: null
+		}
+	})),
+	before: null,
+	after: null
+});
+//#endregion
+//#region lib/engine/mcp/channel-server-instructions.ts
+/**
+* Build the MCP server's `instructions` text. Claude reads this once at session
+* start to learn the event format and the autonomous troubleshooting loop.
+* Pure function — kept in its own file so updating prompt content does not
+* touch the server bootstrap.
+*/
+const buildChannelServerInstructions = (allChannels, currentChannelName) => {
+	return [
+		`Events arrive as notifications (method: notifications/claude/channel) with two fields:`,
+		`  content — the event payload as a JSON string (parse it to read the message)`,
+		`  meta    — key/value strings describing the event`,
+		"",
+		"meta fields by event_type:",
+		"  slack:    event_type=slack  channel_id=C…  thread_ts=1234.5678  user_id=U…  mentioned=true|false",
+		"  gh:       event_type=gh     repository=owner/repo  subject_type=Issue|PullRequest  subject_url=…  reason=…",
+		"  discord:  event_type=discord  channel_id=…  user_id=…  guild_id=…  mentioned=true|false",
+		"  schedule: event_type=schedule  entry_id=…",
+		"",
+		"To reply to a Slack message in the same thread, call the connector tool with:",
+		`  method: POST`,
+		`  path:   chat.postMessage`,
+		`  body:   { channel: meta.channel_id, text: "your reply", thread_ts: meta.thread_ts }`,
+		"",
+		"To comment on a GitHub issue/PR (extract from subject_url in meta):",
+		`  method: POST`,
+		`  path:   repos/<meta.repository>/issues/<number>/comments`,
+		`  body:   { body: "your reply" }`,
+		"",
+		"When anything seems off (events stopped, a tool failed), call fnl_doctor first:",
+		"  fnl_doctor                  → diagnose all channels (read-only)",
+		"  fnl_doctor { mode: \"safe\" } → diagnose + safely fix what can be fixed",
+		"  fnl_doctor { mode: \"aggressive\" } → also restart the gateway if needed",
+		"",
+		"fnl_doctor returns { status, message, appliedActions, remainingIssues } —",
+		"if status is 'ok' you are done; otherwise read remainingIssues for what is left.",
+		"",
+		"Other diagnostic tools you can call freely:",
+		"  fnl_status                          gateway running state, listener health snapshot",
+		"  fnl_debug                           per-channel diagnosis (subset of fnl_doctor)",
+		"  fnl_recent_events                   last N processed events with outcome",
+		"  fnl_dropped_events                  events filtered out (skip:*) with reason",
+		"  fnl_connection_errors               listener auth-failed / error events",
+		"  fnl_replay_event                    replay a past event to test a fix",
+		"  fnl_docs                            embedded docs (architecture / debugging / recipes / …)",
+		"",
+		"Always prefer the built-in fnl_* tools over invoking the shell — they go directly to the",
+		"gateway over loopback HTTP and return structured JSON.",
+		allChannels.length > 0 ? [
+			"",
+			"Configured channels (use as the `channel` argument to diagnostic tools):",
+			...allChannels.map((ch) => `  ${ch.name}${ch.name === currentChannelName ? " ← this session" : ""}`)
+		].join("\n") : ""
+	].join("\n");
+};
+//#endregion
+//#region lib/engine/mcp/usage-hint-for-type.ts
+const usageHintForType = (type) => {
+	if (type === "slack") return [
+		"Slack Web API.",
+		"To reply in the same thread: method=POST path=chat.postMessage body={ channel: meta.channel_id, text: \"...\", thread_ts: meta.thread_ts }",
+		"To react: method=POST path=reactions.add body={ channel: meta.channel_id, timestamp: meta.thread_ts, name: \"thumbsup\" }",
+		"Use meta fields from the incoming event: channel_id (Slack channel), thread_ts (thread anchor), user_id (sender)."
+	].join(" ");
+	if (type === "discord") return [
+		"Discord REST API.",
+		"To reply: method=POST path=/channels/<meta.channel_id>/messages body={ content: \"...\" }",
+		"Use meta fields: channel_id (Discord channel), user_id (sender), guild_id."
+	].join(" ");
+	if (type === "gh") return [
+		"GitHub REST via gh CLI.",
+		"To comment: method=POST path=repos/<meta.repository>/issues/<number>/comments body={ body: \"...\" }",
+		"Parse <number> from meta.subject_url. meta fields: repository (owner/repo), subject_type, subject_url, reason."
+	].join(" ");
+	return "Generic adapter call.";
+};
+//#endregion
+//#region lib/engine/mcp/channel-server-tools.ts
+const BUILTIN_TOOL_NAMES = [
+	"fnl_doctor",
+	"fnl_status",
+	"fnl_debug",
+	"fnl_recent_events",
+	"fnl_dropped_events",
+	"fnl_connection_errors",
+	"fnl_replay_event",
+	"fnl_docs"
+];
+const isBuiltinTool = (name) => BUILTIN_TOOL_NAMES.includes(name);
+/**
+* Build the per-connector outbound tools. One tool per connector; the channel
+* MCP server exposes them so Claude can dispatch HTTP / API calls without
+* shelling out.
+*/
+const buildConnectorTools = (connectors) => connectors.map((connector) => ({
+	name: connector.name,
+	description: `Call the "${connector.name}" (${connector.type}) connector. ${usageHintForType(connector.type)}`,
+	inputSchema: {
+		type: "object",
+		properties: {
+			method: {
+				type: "string",
+				description: "HTTP verb or API method (e.g. POST, chat.postMessage)"
+			},
+			path: {
+				type: "string",
+				description: "API path or method name (adapter-specific)"
+			},
+			body: {
+				type: "object",
+				description: "Request body / params (adapter-specific)"
+			}
+		},
+		required: ["method", "path"]
+	}
+}));
+/**
+* Build the built-in fnl_* tools that drive diagnosis, recovery, and docs.
+* The list mirrors BUILTIN_TOOL_NAMES; descriptions are tuned for Claude to
+* pick the right tool from the name + summary alone.
+*/
+const buildBuiltinTools = (allChannels) => {
+	const channelEnum = allChannels.length > 0 ? allChannels.map((ch) => ch.name) : void 0;
+	const channelArgSchema = channelEnum ? {
+		type: "string",
+		description: `Channel name to inspect. One of: ${channelEnum.join(", ")}. Omit to use the first available.`,
+		enum: channelEnum
+	} : {
+		type: "string",
+		description: "Channel name. Omit to use the first available."
+	};
+	return [
+		{
+			name: "fnl_doctor",
+			description: "Diagnose every channel and optionally apply safe self-healing fixes. Returns { status (ok|warn|error), message, appliedActions[], remainingIssues[], before, after }. When status is 'ok' you are done. Use this as the FIRST tool when anything seems off — it replaces the older diagnose → recover → verify loop with one call.",
+			inputSchema: {
+				type: "object",
+				properties: { mode: {
+					type: "string",
+					enum: [
+						"off",
+						"safe",
+						"aggressive"
+					],
+					description: "off (default): read-only diagnosis. safe: also start gateway if down and restart dead listeners. aggressive: also restart the gateway when safe fixes are not enough."
+				} }
+			}
+		},
+		{
+			name: "fnl_status",
+			description: "Return the gateway status as JSON — gateway running state, every listener's alive/dead per channel, and connected Claude WS clients. Lightweight snapshot; use fnl_doctor when you want diagnosis with next actions.",
+			inputSchema: {
+				type: "object",
+				properties: {}
+			}
+		},
+		{
+			name: "fnl_debug",
+			description: "Return a full channel diagnosis as JSON — gateway health, listeners, Claude WS connection, last 5 inbound events, connection errors (when listener is dead), and `diagnosis` with `status` (ok|warn|error), `message`, `nextActions`, and `rootCause`. Call this whenever events seem missing or to verify a fix worked. Omit `channel` to diagnose all channels.",
+			inputSchema: {
+				type: "object",
+				properties: { channel: {
+					...channelArgSchema,
+					description: `${channelArgSchema.description} Omit to diagnose all channels.`
+				} }
+			}
+		},
+		{
+			name: "fnl_recent_events",
+			description: "Return the last N processed events for a channel as JSON, with `outcome` (emitted | skip:type | skip:dedup | skip:subtype | skip:self-user | …), payload preview, and seq. Use this when you need to confirm whether a specific event reached the broadcaster.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					channel: channelArgSchema,
+					limit: {
+						type: "number",
+						description: "Max rows (default 20)"
+					}
+				}
+			}
+		},
+		{
+			name: "fnl_dropped_events",
+			description: "Return events that were filtered out (outcome starts with `skip:`) for a channel. Use when fnl_debug says listeners look healthy but a particular message never reached Claude — the skip reason tells you why.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					channel: channelArgSchema,
+					limit: {
+						type: "number",
+						description: "Max rows (default 20)"
+					}
+				}
+			}
+		},
+		{
+			name: "fnl_connection_errors",
+			description: "Return listener connection lifecycle errors (auth-failed / error). Use when a listener never connects or keeps disconnecting — the detail field carries the upstream error message.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					channel: channelArgSchema,
+					limit: {
+						type: "number",
+						description: "Max rows (default 20)"
+					}
+				}
+			}
+		},
+		{
+			name: "fnl_replay_event",
+			description: "Re-publish a past event back into a channel so subscribers receive it again. Call after applying a fix to verify Claude handles the previously-failed event correctly. Without `seq`, replays the most recent emitted event for that channel.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					channel: channelArgSchema,
+					seq: {
+						type: "number",
+						description: "Processed-table seq to replay (optional)"
+					}
+				},
+				required: ["channel"]
+			}
+		},
+		{
+			name: "fnl_docs",
+			description: "Return embedded funnel documentation. Without `topic`, returns the list of topics. With `topic`, returns the full text. Topics: architecture, channels, connectors, profiles, claude, mcp, gateway, local-config, debugging, recipes, glossary.",
+			inputSchema: {
+				type: "object",
+				properties: { topic: {
+					type: "string",
+					description: "Topic name (omit to list available topics)"
+				} }
+			}
+		}
+	];
+};
+//#endregion
 //#region lib/engine/mcp/channel-subscriber.ts
 const RECONNECT_DELAY = 1e3;
 const MAX_RECONNECT_DELAY = 1e4;
@@ -98,31 +489,8 @@ const readGatewayToken = (dir) => {
 	return value.length > 0 ? value : null;
 };
 //#endregion
-//#region lib/engine/mcp/usage-hint-for-type.ts
-const usageHintForType = (type) => {
-	if (type === "slack") return [
-		"Slack Web API.",
-		"To reply in the same thread: method=POST path=chat.postMessage body={ channel: meta.channel_id, text: \"...\", thread_ts: meta.thread_ts }",
-		"To react: method=POST path=reactions.add body={ channel: meta.channel_id, timestamp: meta.thread_ts, name: \"thumbsup\" }",
-		"Use meta fields from the incoming event: channel_id (Slack channel), thread_ts (thread anchor), user_id (sender)."
-	].join(" ");
-	if (type === "discord") return [
-		"Discord REST API.",
-		"To reply: method=POST path=/channels/<meta.channel_id>/messages body={ content: \"...\" }",
-		"Use meta fields: channel_id (Discord channel), user_id (sender), guild_id."
-	].join(" ");
-	if (type === "gh") return [
-		"GitHub REST via gh CLI.",
-		"To comment: method=POST path=repos/<meta.repository>/issues/<number>/comments body={ body: \"...\" }",
-		"Parse <number> from meta.subject_url. meta fields: repository (owner/repo), subject_type, subject_url, reason."
-	].join(" ");
-	return "Generic adapter call.";
-};
-//#endregion
 //#region lib/engine/mcp/channel-server.ts
 const DEFAULT_FUNNEL_DIR = join(homedir(), ".funnel");
-const BUILTIN_TOOL_NAMES = ["fnl_status", "fnl_debug"];
-const isBuiltinTool = (name) => BUILTIN_TOOL_NAMES.includes(name);
 const readAllChannels = (dir) => {
 	const settingsPath = join(dir, "settings.json");
 	if (!existsSync(settingsPath)) return [];
@@ -138,20 +506,26 @@ const readAllChannels = (dir) => {
 		return [];
 	}
 };
+/**
+* Start the funnel MCP server over stdio. Wires:
+*
+*  - inbound channel subscription (gateway WebSocket → notifications/claude/channel)
+*  - outbound per-connector tools (one tool per connector, dispatched via gateway HTTP)
+*  - built-in fnl_* diagnostic + recovery tools (delegated to handleBuiltinTool)
+*
+* Tool definitions live in channel-server-tools.ts; the instructions string in
+* channel-server-instructions.ts; HTTP helpers in channel-server-http.ts. This
+* file is the orchestrator — wiring only, no business logic.
+*/
 const startChannelServer = async (options = {}) => {
 	const dir = options.dir ?? DEFAULT_FUNNEL_DIR;
-	const gatewayBaseUrl = options.gatewayUrl ?? process.env.FUNNEL_GATEWAY_URL ?? `http://127.0.0.1:${resolveFunnelPort()}`;
+	const gatewayBaseUrl = options.gatewayUrl ?? process.env.FUNNEL_GATEWAY_URL ?? gatewayLoopbackUrl(resolveFunnelPort());
 	const gatewayWsUrl = `${gatewayBaseUrl.replace(/^http/, "ws")}/ws`;
 	const channelId = options.channelId ?? process.env.FUNNEL_CHANNEL_ID;
 	const channel = channelId ? readChannelConnectors(dir, channelId) : null;
 	const token = options.token ?? readGatewayToken(dir);
 	const allChannels = readAllChannels(dir);
 	const currentChannelName = channel?.channelName ?? null;
-	const channelContext = allChannels.length > 0 ? [
-		"",
-		"Configured channels (use as the `channel` argument to fnl_debug):",
-		...allChannels.map((ch) => `  ${ch.name}${ch.name === currentChannelName ? " ← this session" : ""}`)
-	].join("\n") : "";
 	const server = new Server({
 		name: FUNNEL_MCP_NAME,
 		version: "1.0.0"
@@ -160,112 +534,30 @@ const startChannelServer = async (options = {}) => {
 			experimental: { "claude/channel": {} },
 			tools: {}
 		},
-		instructions: [
-			`Events arrive as notifications (method: notifications/claude/channel) with two fields:`,
-			`  content — the event payload as a JSON string (parse it to read the message)`,
-			`  meta    — key/value strings describing the event`,
-			"",
-			"meta fields by event_type:",
-			"  slack:    event_type=slack  channel_id=C…  thread_ts=1234.5678  user_id=U…  mentioned=true|false",
-			"  gh:       event_type=gh     repository=owner/repo  subject_type=Issue|PullRequest  subject_url=…  reason=…",
-			"  discord:  event_type=discord  channel_id=…  user_id=…  guild_id=…  mentioned=true|false",
-			"  schedule: event_type=schedule  entry_id=…",
-			"",
-			"To reply to a Slack message in the same thread, call the connector tool with:",
-			`  method: POST`,
-			`  path:   chat.postMessage`,
-			`  body:   { channel: meta.channel_id, text: "your reply", thread_ts: meta.thread_ts }`,
-			"",
-			"To comment on a GitHub issue/PR (extract from subject_url in meta):",
-			`  method: POST`,
-			`  path:   repos/<meta.repository>/issues/<number>/comments   (parse number from meta.subject_url)`,
-			`  body:   { body: "your reply" }`,
-			"",
-			"Built-in diagnostic tools — call proactively when events seem missing or delayed:",
-			"  fnl_status — gateway running state, all listeners alive/dead, Claude WS clients",
-			"  fnl_debug  — per-channel diagnosis with last 10 events, rootCause, suggestedActions",
-			"               omit channel arg to diagnose all channels; check summary.suggestedActions first",
-			channelContext
-		].join("\n")
-	});
-	server.setRequestHandler(ListToolsRequestSchema, async () => {
-		const connectorTools = (channel?.connectors ?? []).map((c) => ({
-			name: c.name,
-			description: `Call the "${c.name}" (${c.type}) connector. ${usageHintForType(c.type)}`,
-			inputSchema: {
-				type: "object",
-				properties: {
-					method: {
-						type: "string",
-						description: "HTTP verb or API method (e.g. POST, chat.postMessage)"
-					},
-					path: {
-						type: "string",
-						description: "API path or method name (adapter-specific)"
-					},
-					body: {
-						type: "object",
-						description: "Request body / params (adapter-specific)"
-					}
-				},
-				required: ["method", "path"]
-			}
-		}));
-		const channelEnum = allChannels.length > 0 ? allChannels.map((ch) => ch.name) : void 0;
-		const builtinTools = [{
-			name: "fnl_status",
-			description: "Return the current funnel gateway status as JSON — gateway running state, listener alive/dead per channel, and connected Claude WS clients. Call this when you need to check whether the gateway is up or why events stopped arriving.",
-			inputSchema: {
-				type: "object",
-				properties: {}
-			}
-		}, {
-			name: "fnl_debug",
-			description: "Return a full channel diagnosis as JSON — gateway health, listener state, Claude WS connection, last 10 inbound events with outcome, connectionErrors (when listener is dead), and diagnosis.rootCause. Call this first when debugging missing events. Omit `channel` to diagnose all channels at once.",
-			inputSchema: {
-				type: "object",
-				properties: { channel: channelEnum ? {
-					type: "string",
-					description: `Channel name to inspect. One of: ${channelEnum.join(", ")}. Omit to get all channels.`,
-					enum: channelEnum
-				} : {
-					type: "string",
-					description: "Channel name to inspect. Omit to get all channels."
-				} }
-			}
-		}];
-		return { tools: [...connectorTools, ...builtinTools] };
+		instructions: buildChannelServerInstructions(allChannels, currentChannelName)
 	});
+	server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [...buildConnectorTools(channel?.connectors ?? []), ...buildBuiltinTools(allChannels)] }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
 		const toolName = request.params.name;
-		if (isBuiltinTool(toolName)) return handleBuiltinTool(toolName, request.params.arguments, gatewayBaseUrl, token, allChannels);
+		if (isBuiltinTool(toolName)) return handleBuiltinTool({
+			name: toolName,
+			args: request.params.arguments,
+			gatewayBaseUrl,
+			token,
+			allChannels
+		});
 		if (!channel) throw new Error("FUNNEL_CHANNEL_ID is not set or channel not found in settings.json");
-		const args = request.params.arguments ?? {};
-		const method = typeof args.method === "string" ? args.method : "";
-		const path = typeof args.path === "string" ? args.path : "";
-		const body = args.body ?? {};
-		if (!method || !path) throw new Error("`method` and `path` are required");
-		const url = `${gatewayBaseUrl}/channels/${encodeURIComponent(channel.channelName)}/connectors/${encodeURIComponent(toolName)}/call`;
-		const headers = { "content-type": "application/json" };
-		if (token) headers.authorization = `Bearer ${token}`;
-		const res = await fetch(url, {
-			method: "POST",
-			headers,
-			body: JSON.stringify({
-				method,
-				path,
-				body
-			})
+		return await dispatchConnectorTool({
+			channelName: channel.channelName,
+			toolName,
+			args: request.params.arguments ?? {},
+			gatewayBaseUrl,
+			token
 		});
-		const text = await res.text();
-		if (!res.ok) throw new Error(`gateway call failed (${res.status}): ${text}`);
-		return { content: [{
-			type: "text",
-			text
-		}] };
 	});
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
+	process.stderr.write(`funnel MCP ready (channel=${currentChannelName ?? "?"}); if events stop, call fnl_doctor.\n`);
 	if (!channelId) return;
 	new FunnelChannelSubscriber({
 		server,
@@ -273,50 +565,45 @@ const startChannelServer = async (options = {}) => {
 		protocols: token ? [`funnel.token.${token}`] : void 0
 	}).start();
 };
-const handleBuiltinTool = async (name, args, gatewayBaseUrl, token, allChannels) => {
-	const headers = {};
-	if (token) headers.authorization = `Bearer ${token}`;
-	if (name === "fnl_status") {
-		const res = await fetch(`${gatewayBaseUrl}/status`, { headers }).catch(() => null);
-		if (!res) return { content: [{
+const dispatchConnectorTool = async (input) => {
+	const method = typeof input.args.method === "string" ? input.args.method : "";
+	const path = typeof input.args.path === "string" ? input.args.path : "";
+	const body = input.args.body;
+	if (!method || !path) throw new Error("`method` and `path` are required");
+	const url = `${input.gatewayBaseUrl}/channels/${encodeURIComponent(input.channelName)}/connectors/${encodeURIComponent(input.toolName)}/call`;
+	const headers = { "content-type": "application/json" };
+	if (input.token) headers.authorization = `Bearer ${input.token}`;
+	const res = await fetch(url, {
+		method: "POST",
+		headers,
+		body: JSON.stringify({
+			method,
+			path,
+			body
+		})
+	});
+	const text = await res.text();
+	if (!res.ok) return {
+		content: [{
 			type: "text",
-			text: JSON.stringify({
-				running: false,
-				error: "gateway unreachable",
-				hint: "run: fnl gateway start",
-				knownChannels: allChannels.map((ch) => ch.name)
+			text: renderYaml({
+				error: `gateway call failed (${res.status}): ${text}`,
+				nextAction: "Call fnl_doctor to diagnose the failure"
 			})
+		}],
+		isError: true
+	};
+	try {
+		return { content: [{
+			type: "text",
+			text: renderYaml(JSON.parse(text))
 		}] };
-		const body = await res.json();
+	} catch {
 		return { content: [{
 			type: "text",
-			text: JSON.stringify(body)
+			text
 		}] };
 	}
-	const channelArg = typeof args?.channel === "string" ? args.channel : null;
-	const url = channelArg ? `${gatewayBaseUrl}/debug?channel=${encodeURIComponent(channelArg)}` : `${gatewayBaseUrl}/debug`;
-	const res = await fetch(url, { headers }).catch(() => null);
-	if (!res) return { content: [{
-		type: "text",
-		text: JSON.stringify({
-			gateway: { running: false },
-			channels: allChannels.map((ch) => ({
-				id: ch.id,
-				name: ch.name,
-				diagnosis: {
-					status: "error",
-					message: "gateway is not running",
-					nextAction: "fnl gateway start",
-					rootCause: null
-				}
-			}))
-		})
-	}] };
-	const body = await res.json();
-	return { content: [{
-		type: "text",
-		text: JSON.stringify(body)
-	}] };
 };
 //#endregion
 export { FUNNEL_MCP_ARGS, FUNNEL_MCP_COMMAND, FUNNEL_MCP_NAME, FileProcessGuard, FunnelClaude, FunnelLocalConfig, FunnelLocalConfigSync, FunnelLocalConfigWriter, FunnelMcp, FunnelProfiles, FunnelTokenPrompter, LOCAL_CONFIG_FILENAME, MemoryFunnelTokenPrompter, NodeFunnelTokenPrompter, channelSpecSchema, connectorSpecSchema, funnelJsonSchema, localConfigSchema, profileSpecSchema, startChannelServer };