Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* Per-Step MCP Server Router.
*
* Manages MCP client connections for a single step execution.
* Stateless between steps — connections opened at step start, closed at step end.
*
* Security invariant: per-step isolation — no connection reuse across steps.
*
* Source of truth: STAGE-2-STEP-EXECUTION-ENGINE.md §4.3–§4.4
*/
import { logger } from '../logger'
import { VisualInputBudget } from '../visualInput/policy'
import { argumentValidator, checkToolArguments } from './argumentGate'
import { projectInternalToolResult } from './internalToolProjection'
import {
AllowedToolsConfig,
InternalToolDefinition,
StepMcpServerRef,
ToolCallRecord,
} from './types'
// ─── Tool Definition (simplified from MCP SDK) ─────────────────────────
export interface ToolDefinition {
name: string // prefixed: serverName__toolName
description?: string
inputSchema?: Record<string, unknown>
}
export interface ToolResult {
content: unknown
isError?: boolean
}
// ─── Errors ─────────────────────────────────────────────────────────────
export class StepRouterConnectionError extends Error {
failedServers: string[]
constructor(failedServers: string[]) {
super(`Failed to connect to MCP servers: ${failedServers.join(', ')}`)
this.name = 'StepRouterConnectionError'
this.failedServers = failedServers
}
}
export class ToolDispatchError extends Error {
toolName: string
constructor(toolName: string) {
super(`Unknown tool: '${toolName}' — no matching server prefix`)
this.name = 'ToolDispatchError'
this.toolName = toolName
}
}
export class ToolArgsValidationError extends Error {
toolName: string
validationErrors: string
constructor(toolName: string, validationErrors: string) {
super(`Invalid arguments for '${toolName}': ${validationErrors}`)
this.name = 'ToolArgsValidationError'
this.toolName = toolName
this.validationErrors = validationErrors
}
}
// ─── MCP Client Interface (for DI/mocking) ─────────────────────────────
export interface McpClientConnection {
connect(options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<void>
listTools(options?: {
timeoutMs?: number
signal?: AbortSignal
}): Promise<Array<{ name: string; description?: string; inputSchema?: Record<string, unknown> }>>
callTool(
toolName: string,
args: Record<string, unknown>,
options?: { timeoutMs?: number; signal?: AbortSignal }
): Promise<ToolResult>
disconnect(): Promise<void>
}
export type McpClientFactory = (server: StepMcpServerRef) => McpClientConnection
/**
* Error text the model receives when it calls a tool outside the step's
* allowedTools. Recoverable: the step continues and the model may retry with
* an offered tool (spec §3.1.2).
*/
function toolNotAllowedError(toolName: string): string {
return `Tool '${toolName}' is not allowed in this step and was not run. Use only the tools provided for this step.`
}
// ─── StepMcpRouter ──────────────────────────────────────────────────────
export class StepMcpRouter {
private readBudget = new VisualInputBudget()
private connections = new Map<string, McpClientConnection>()
private toolMap = new Map<string, { serverName: string; rawToolName: string }>()
private internalToolMap = new Map<string, InternalToolDefinition>()
private allTools: ToolDefinition[] = []
private readonly clientFactory: McpClientFactory
private outputDir = '/output'
// Names callTool() may dispatch when the step declares a non-empty
// allowedTools.include. null = no allowlist in effect (every registered tool
// is callable — the pre-§3.1.2 behaviour, kept for absent/empty include).
// Deliberately NOT cleared by disconnect(): a restriction must never lapse
// into "everything callable" on reuse; the caller re-applies it per step.
private callableToolNames: Set<string> | null = null
constructor(clientFactory: McpClientFactory) {
this.clientFactory = clientFactory
}
/**
* Register internal tools (clerum__*) that execute locally without MCP connection.
* Must be called before connect() so they appear in getFilteredTools().
*
* The tool's `parameters` JSON Schema is compiled here into the validator
* that runs before each dispatch (argumentGate.ts, shared with chat). Bad LLM
* output (wrong type, missing required, unknown enum value) is rejected
* before reaching `execute()`.
*/
registerInternalTools(tools: InternalToolDefinition[], outputDir: string): void {
this.outputDir = outputDir
for (const tool of tools) {
this.allTools.push({
name: tool.name,
description: tool.description,
inputSchema: tool.parameters,
})
this.internalToolMap.set(tool.name, tool)
// Compiled now so a schema that fails to compile is reported at
// registration; dispatch then falls through to the tool's own checks.
argumentValidator(tool)
// Also register in toolMap for consistent dispatch
this.toolMap.set(tool.name, {
serverName: 'clerum',
rawToolName: tool.name.replace('clerum__', ''),
})
}
}
/**
* Connect to all servers declared for this step.
* Throws StepRouterConnectionError if any server is unreachable.
*/
async connect(
servers: StepMcpServerRef[],
options: { timeoutMs?: number; signal?: AbortSignal } = {}
): Promise<void> {
if (this.readBudget.isClosed) this.readBudget = new VisualInputBudget()
if (servers.length === 0) return
const failed: string[] = []
for (const server of servers) {
const client = this.clientFactory(server)
try {
await client.connect(options)
this.connections.set(server.name, client)
} catch {
failed.push(server.name)
}
}
if (failed.length > 0) {
// Disconnect any that succeeded before throwing
await this.disconnect()
throw new StepRouterConnectionError(failed)
}
// Preserve internal tools registered before connect()
const savedInternalTools = [...this.allTools.filter(t => this.internalToolMap.has(t.name))]
const savedToolMapEntries = [...this.toolMap.entries()].filter(([k]) =>
this.internalToolMap.has(k)
)
// Build tool index from all connected servers
this.allTools = [...savedInternalTools]
this.toolMap.clear()
for (const [k, v] of savedToolMapEntries) this.toolMap.set(k, v)
const listFailed: string[] = []
for (const [serverName, client] of this.connections) {
try {
const tools = await client.listTools(options)
for (const tool of tools) {
const prefixed = `${serverName}__${tool.name}`
this.allTools.push({
name: prefixed,
description: tool.description,
inputSchema: tool.inputSchema,
})
this.toolMap.set(prefixed, { serverName, rawToolName: tool.name })
}
} catch {
listFailed.push(serverName)
}
}
if (listFailed.length > 0) {
await this.disconnect()
throw new StepRouterConnectionError(listFailed)
}
}
/**
* Return merged tool list from all connected servers.
* Filter to only tools in allowedTools.include (if non-empty).
*/
getFilteredTools(allowedTools?: AllowedToolsConfig): ToolDefinition[] {
const include = allowedTools?.include
if (!include || include.length === 0) {
return [...this.allTools]
}
const includeSet = new Set(include)
return this.allTools.filter(t => includeSet.has(t.name))
}
/**
* Enforce the step's allowlist at dispatch time (spec §3.1.2).
*
* - include absent or empty: no restriction. Every registered tool stays
* callable, matching getFilteredTools(), which offers every tool then.
* - include non-empty: callTool() dispatches only names that are both listed
* and registered, i.e. exactly what getFilteredTools() offers the model.
* Any other name gets a recoverable tool-error result and never runs.
*
* Membership is checked against the live registry on each call, so this may
* be applied before or after connect().
*/
setAllowedTools(allowedTools?: AllowedToolsConfig): void {
const include = allowedTools?.include
this.callableToolNames = include && include.length > 0 ? new Set(include) : null
}
private rejectNotAllowed(
toolName: string,
args: Record<string, unknown>
): { result: ToolResult; record: ToolCallRecord } {
const separator = toolName.indexOf('__')
const errorResult = { success: false, error: toolNotAllowedError(toolName) }
// Arguments are model output (and so attacker-shapeable); log the name only.
logger.warn(
{ toolName: toolName.slice(0, 200) },
'Workflow step tool call rejected: tool is not in allowedTools'
)
return {
result: { content: errorResult, isError: true },
record: {
serverName: separator > 0 ? toolName.slice(0, separator) : 'unknown',
toolName: separator > 0 ? toolName.slice(separator + 2) : toolName,
args,
result: errorResult,
durationMs: 0,
},
}
}
/**
* Dispatch a tool call to the correct server by tool name prefix.
* Internal tools (clerum__*) are dispatched locally without MCP connection.
* With a non-empty allowlist (setAllowedTools), names outside the offered set
* return a recoverable tool-error result instead of dispatching.
*/
async callTool(
toolName: string,
args: Record<string, unknown>,
options: { timeoutMs?: number; signal?: AbortSignal } = {}
): Promise<{ result: ToolResult; record: ToolCallRecord }> {
if (options.signal?.aborted) {
const reason =
typeof options.signal.reason === 'string' && options.signal.reason.trim()
? options.signal.reason
: 'step-timeout'
throw new Error(reason)
}
// Spec §3.1.2: with an allowlist in effect, anything outside the offered set
// (unlisted, or listed but never registered) is answered with a recoverable
// tool error and is never dispatched.
if (
this.callableToolNames &&
!(this.callableToolNames.has(toolName) && this.toolMap.has(toolName))
) {
return this.rejectNotAllowed(toolName, args)
}
// Check internal tools first
const internalTool = this.internalToolMap.get(toolName)
if (internalTool) {
// The same check as on the chat path: unset nulls dropped, then the
// schema. Failures come back as recoverable tool-error results (not
// thrown) so the LLM can read the error and retry within the same step.
// The record keeps what the model sent.
const checked = checkToolArguments(internalTool, args)
if (!checked.ok) {
const errorResult = {
success: false,
error: checked.error,
}
const record: ToolCallRecord = {
serverName: 'clerum',
toolName: toolName.replace('clerum__', ''),
args,
result: errorResult,
durationMs: 0,
}
return {
result: { content: errorResult, isError: true },
record,
}
}
const start = Date.now()
const internalResult = projectInternalToolResult(
await internalTool.execute(checked.input, this.outputDir, {
signal: options.signal,
timeoutMs: options.timeoutMs,
readBudget: this.readBudget,
})
)
const durationMs = Date.now() - start
const record: ToolCallRecord = {
serverName: 'clerum',
toolName: toolName.replace('clerum__', ''),
args,
result: internalResult,
durationMs,
}
return {
result: { content: internalResult, isError: !internalResult.success },
record,
}
}
const entry = this.toolMap.get(toolName)
if (!entry) throw new ToolDispatchError(toolName)
const client = this.connections.get(entry.serverName)
if (!client) throw new ToolDispatchError(toolName)
const start = Date.now()
const result = await client.callTool(entry.rawToolName, args, options)
const durationMs = Date.now() - start
const record: ToolCallRecord = {
serverName: entry.serverName,
toolName: entry.rawToolName,
args,
result: result.content,
durationMs,
}
return { result, record }
}
/**
* Disconnect all servers. Safe to call on unconnected router.
*/
async disconnect(): Promise<void> {
this.readBudget.close()
const disconnectPromises = [...this.connections.values()].map(client =>
client.disconnect().catch(() => {
/* swallow disconnect errors */
})
)
await Promise.all(disconnectPromises)
this.connections.clear()
this.toolMap.clear()
this.internalToolMap.clear()
this.allTools = []
}
}