#Module: mcp-entry

#Interfaces

#GeneratedStdioMcpEntryModule

#Properties

#default?

readonly optional default?: unknown

---

#Heartbeat

#Properties

#log

readonly log: (reason) => void

#Parameters

#reason

string

#Returns

void

#noteActivity

readonly noteActivity: () => void

#Returns

void

#stop

readonly stop: () => void

#Returns

void

---

#HeartbeatOptions

#Properties

#activityThrottleMs?

readonly optional activityThrottleMs?: number

#intervalMs?

readonly optional intervalMs?: number

#name?

readonly optional name?: string

Log prefix — pass the MCP server name so multi-server logs stay attributable.

#writeLine

readonly writeLine: (line) => void

#Parameters

#line

string

#Returns

void

---

#LifecycleServer

#Methods

#close()

close(): void | Promise<void>

#Returns

void | Promise<void>

#connect()

connect(transport): Promise<void>

#Parameters

#transport

never

#Returns

Promise<void>

---

#LifecycleSignalSource

#Methods

#off()

off(signal, listener): unknown

#Parameters

#signal

"SIGINT" | "SIGTERM"

#listener

() => void

#Returns

unknown

#on()

on(signal, listener): unknown

#Parameters

#signal

"SIGINT" | "SIGTERM"

#listener

() => void

#Returns

unknown

---

#LifecycleStdin

#Methods

#off()?

optional off(event, listener): unknown

#Parameters

#event

"end"

#listener

() => void

#Returns

unknown

#once()?

optional once(event, listener): unknown

#Parameters

#event

"end"

#listener

() => void

#Returns

unknown

---

#LifecycleTransport

#Properties

#onclose?

optional onclose?: () => void

#Returns

void

#onmessage?

optional onmessage?: (message, extra?) => void

#Parameters

#message

never

#extra?

undefined

#Returns

void

#Methods

#close()

close(): void | Promise<void>

#Returns

void | Promise<void>

---

#RunGeneratedStdioMcpEntryOptions

#Properties

#lifecycle?

readonly optional lifecycle?: Omit<RunStdioServerOptions, "server" | "serverName" | "transport">

Test seam mirroring RunStdioServerOptions.

#loadEntry

readonly loadEntry: () => Promise<GeneratedStdioMcpEntryModule>

Loads the consumer entry module. The generated shell imports the module statically, after its stdio prelude — the console guard plus the operator .env layer (#469) — and resolves it here: under bundling every module of the single-chunk entry evaluates before the shell body whichever way it is imported, so import order, not this call, is what puts the guard and the layer ahead of the module's own top level.

#Returns

Promise<GeneratedStdioMcpEntryModule>

#serverName

readonly serverName: string

---

#RunStdioServerOptions

#Properties

#activityThrottleMs?

readonly optional activityThrottleMs?: number

#exit?

readonly optional exit?: (code) => void

#Parameters

#code

number

#Returns

void

#heartbeat?

readonly optional heartbeat?: boolean

Disables interval/activity heartbeat logging; shutdown behavior is unaffected.

#heartbeatIntervalMs?

readonly optional heartbeatIntervalMs?: number

#server

readonly server: LifecycleServer

#serverName?

readonly optional serverName?: string

Heartbeat log prefix — pass the MCP server name.

#shutdownTimeoutMs?

readonly optional shutdownTimeoutMs?: number

#signals?

readonly optional signals?: LifecycleSignalSource

#stdin?

readonly optional stdin?: LifecycleStdin

#transport

readonly transport: LifecycleTransport

#writeLine?

readonly optional writeLine?: (line) => void

#Parameters

#line

string

#Returns

void

---

#StdioServerHandle

#Properties

#heartbeat

readonly heartbeat: Heartbeat

#shutdown

readonly shutdown: (exitCode?) => Promise<void>

#Parameters

#exitCode?

number

#Returns

Promise<void>

---

#StdoutProtocolGuard

The framework-owned stdio MCP entry shell: console-to-stderr protection, signal handling (SIGINT exits 130, SIGTERM exits 143), stdin-EOF detection (exit 0 so the client can respawn), a bounded shutdown race against wedged transports, and heartbeat/activity logging. agent-bundle build wraps every factory-exporting MCP server entry in this lifecycle, and consumers can import it directly for hand-rolled entries.

Every value in this module is injectable through structural option types so the lifecycle is testable with plain-object harnesses; the real StdioServerTransport and MCP server instances satisfy these shapes.

#Properties

#restoreProtocolStdout

readonly restoreProtocolStdout: () => void

Hands stdout back to the protocol transport; console.* keeps writing to stderr. Once only: later calls are no-ops.

#Returns

void

#Type Aliases

#StdioMcpServerFactory

StdioMcpServerFactory = () => LifecycleServer | Promise<LifecycleServer>

The factory shape a generated stdio entry module default-exports.

#Returns

LifecycleServer | Promise<LifecycleServer>

#Variables

#createHeartbeat

const createHeartbeat: ({ activityThrottleMs, intervalMs, name, writeLine, }) => Heartbeat

Lightweight liveness logging, stderr only — stdout is the protocol channel. Logs on a slow interval plus on request activity (throttled), so a silently stalled server is visible in the client's logs without spamming them.

#Parameters

#{ activityThrottleMs, intervalMs, name, writeLine, }

HeartbeatOptions

#Returns

Heartbeat

---

#redirectConsoleToStderr

const redirectConsoleToStderr: () => StdoutProtocolGuard

stdout carries JSON-RPC framing on a stdio server: a stray console.log (or direct process.stdout.write) from any imported module would corrupt the protocol stream. Install this guard before evaluating server modules, then call restoreProtocolStdout() right before serving. Console methods stay on stderr forever; only the raw process.stdout.write is restored for protocol frames.

While a guard is installed, calling this returns it — whatever process.stdout.write has become since. A consumer module that wraps process.stdout.write at module scope wraps the redirect, not the protocol stream; stdout is the protocol channel, so such a wrapper is unsupported, and restoreProtocolStdout() discards it in favour of the real stdout, saying so once on stderr.

#Returns

StdoutProtocolGuard

---

#runGeneratedStdioMcpEntry

const runGeneratedStdioMcpEntry: (options) => Promise<StdioServerHandle>

The body of every generated stdio MCP entry: adopt the stdout guard the shell's prelude installed as its first import (installing it here only for a hand-rolled caller that has none), take the consumer module, build the server from its default-exported factory, hand raw stdout back for protocol frames, and serve under the managed lifecycle.

#Parameters

#options

RunGeneratedStdioMcpEntryOptions

#Returns

Promise<StdioServerHandle>

---

#runStdioServer

const runStdioServer: ({ activityThrottleMs, exit, heartbeat: heartbeatEnabled, heartbeatIntervalMs, server, serverName, shutdownTimeoutMs, signals, stdin, transport, writeLine, }) => Promise<StdioServerHandle>

Owns the stdio server lifecycle: SIGINT exits 130, SIGTERM exits 143, stdin EOF and transport close exit 0 promptly (so the client can respawn), and a wedged transport/server close never hangs shutdown — the closes race a bounded timer and the process exits unconditionally once it fires.

#Parameters

#{ activityThrottleMs, exit, heartbeat: heartbeatEnabled, heartbeatIntervalMs, server, serverName, shutdownTimeoutMs, signals, stdin, transport, writeLine, }

RunStdioServerOptions

#Returns

Promise<StdioServerHandle>