Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
14.9 KB
Raw Blame
import { describe, expect, it, vi } from 'vitest'
import {
  type McpClientConnection,
  type McpClientFactory,
  StepMcpRouter,
  StepRouterConnectionError,
  ToolDispatchError,
} from '../stepRouter'
import type { AllowedToolsConfig, StepMcpServerRef } from '../types'

describe('internal tool execution context', () => {
  it('forwards cancellation and deadline while projecting both recorded destinations', async () => {
    const execute = vi.fn(async () => ({
      success: true,
      content: 'text',
      unexpected: Buffer.from('raw'),
    }))
    const router = new StepMcpRouter(() => mockClient())
    router.registerInternalTools(
      [
        {
          name: 'clerum__read',
          description: 'read',
          parameters: { type: 'object' },
          execute,
        },
      ],
      '/output'
    )
    const signal = new AbortController().signal
    const result = await router.callTool('clerum__read', {}, { timeoutMs: 1234, signal })
    expect(execute).toHaveBeenCalledWith(
      {},
      '/output',
      expect.objectContaining({ timeoutMs: 1234, signal })
    )
    expect(result.result.content).toEqual({ success: true, content: 'text' })
    expect(result.record.result).toEqual({ success: true, content: 'text' })
  })

  it('never starts an internal tool for an already cancelled caller', async () => {
    const execute = vi.fn(async () => ({ success: true, content: 'text' }))
    const router = new StepMcpRouter(() => mockClient())
    router.registerInternalTools(
      [
        {
          name: 'clerum__read',
          description: 'read',
          parameters: { type: 'object' },
          execute,
        },
      ],
      '/output'
    )
    await expect(
      router.callTool('clerum__read', {}, { signal: AbortSignal.abort() })
    ).rejects.toThrow()
    expect(execute).not.toHaveBeenCalled()
  })
})

// ─── Mock Factory ───────────────────────────────────────────────────────

function mockClient(
  tools: Array<{ name: string; description?: string }> = []
): McpClientConnection {
  return {
    connect: vi.fn().mockResolvedValue(undefined),
    listTools: vi.fn().mockResolvedValue(tools),
    callTool: vi.fn().mockResolvedValue({ content: 'result', isError: false }),
    disconnect: vi.fn().mockResolvedValue(undefined),
  }
}

function mockFactory(clients: Map<string, McpClientConnection>): McpClientFactory {
  return (server: StepMcpServerRef) => {
    const client = clients.get(server.name)
    if (!client) throw new Error(`No mock for ${server.name}`)
    return client
  }
}

describe('StepMcpRouter.connect', () => {
  it('connects to all declared servers successfully', async () => {
    const clientA = mockClient([{ name: 'tool1' }])
    const clientB = mockClient([{ name: 'tool2' }])
    const factory = mockFactory(
      new Map([
        ['serverA', clientA],
        ['serverB', clientB],
      ])
    )

    const router = new StepMcpRouter(factory)
    await router.connect([
      { name: 'serverA', url: 'http://a:3000' },
      { name: 'serverB', url: 'http://b:3000' },
    ])

    expect(clientA.connect).toHaveBeenCalled()
    expect(clientB.connect).toHaveBeenCalled()
  })

  it('throws StepRouterConnectionError when one server is unreachable', async () => {
    const clientA = mockClient()
    const clientB = mockClient()
    ;(clientB.connect as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('unreachable'))
    const factory = mockFactory(
      new Map([
        ['serverA', clientA],
        ['serverB', clientB],
      ])
    )

    const router = new StepMcpRouter(factory)
    await expect(
      router.connect([
        { name: 'serverA', url: 'http://a:3000' },
        { name: 'serverB', url: 'http://b:3000' },
      ])
    ).rejects.toThrow(StepRouterConnectionError)
  })

  it('includes failed server name in StepRouterConnectionError', async () => {
    const clientA = mockClient()
    ;(clientA.connect as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('timeout'))
    const factory = mockFactory(new Map([['badServer', clientA]]))

    const router = new StepMcpRouter(factory)
    try {
      await router.connect([{ name: 'badServer', url: 'http://bad:3000' }])
      expect.fail('Should have thrown')
    } catch (err) {
      expect((err as StepRouterConnectionError).failedServers).toContain('badServer')
    }
  })

  it('connects to zero servers without error (step with no MCP tools)', async () => {
    const router = new StepMcpRouter(() => mockClient())
    await expect(router.connect([])).resolves.toBeUndefined()
  })

  it('forwards caller timeout options to connect and tool discovery', async () => {
    const clientA = mockClient([{ name: 'tool1' }])
    const factory = mockFactory(new Map([['serverA', clientA]]))
    const router = new StepMcpRouter(factory)
    const controller = new AbortController()
    const options = { timeoutMs: 1_234, signal: controller.signal }

    await router.connect([{ name: 'serverA', url: 'http://a:3000' }], options)

    expect(clientA.connect).toHaveBeenCalledWith(options)
    expect(clientA.listTools).toHaveBeenCalledWith(options)
  })
})

describe('StepMcpRouter.getFilteredTools', () => {
  async function routerWithTools() {
    const clientA = mockClient([{ name: 'read' }, { name: 'write' }])
    const clientB = mockClient([{ name: 'query' }])
    const factory = mockFactory(
      new Map([
        ['db', clientA],
        ['api', clientB],
      ])
    )
    const router = new StepMcpRouter(factory)
    await router.connect([
      { name: 'db', url: 'http://db:3000' },
      { name: 'api', url: 'http://api:3000' },
    ])
    return router
  }

  it('returns all tools when allowedTools is absent', async () => {
    const router = await routerWithTools()
    const tools = router.getFilteredTools()
    expect(tools).toHaveLength(3)
  })

  it('returns all tools when allowedTools.include is empty array', async () => {
    const router = await routerWithTools()
    const tools = router.getFilteredTools({ include: [] })
    expect(tools).toHaveLength(3)
  })

  it('returns only tools matching allowedTools.include', async () => {
    const router = await routerWithTools()
    const tools = router.getFilteredTools({ include: ['db__read'] })
    expect(tools).toHaveLength(1)
    expect(tools[0].name).toBe('db__read')
  })

  it('prefixes tool names with serverName__toolName', async () => {
    const router = await routerWithTools()
    const tools = router.getFilteredTools()
    const names = tools.map(t => t.name)
    expect(names).toContain('db__read')
    expect(names).toContain('db__write')
    expect(names).toContain('api__query')
  })

  it('does not include tools from unrelated server when allowedTools.include is set', async () => {
    const router = await routerWithTools()
    const tools = router.getFilteredTools({ include: ['db__read'] })
    expect(tools.some(t => t.name.startsWith('api__'))).toBe(false)
  })

  it('returns tools from multiple servers merged into single list', async () => {
    const router = await routerWithTools()
    const tools = router.getFilteredTools()
    const servers = new Set(tools.map(t => t.name.split('__')[0]))
    expect(servers.size).toBe(2)
  })

  it('returns empty list when allowedTools.include has no matching tools', async () => {
    const router = await routerWithTools()
    const tools = router.getFilteredTools({ include: ['nonexistent__tool'] })
    expect(tools).toHaveLength(0)
  })
})

describe('StepMcpRouter.callTool', () => {
  it('dispatches call to correct server by prefix', async () => {
    const clientA = mockClient([{ name: 'read' }])
    const factory = mockFactory(new Map([['db', clientA]]))
    const router = new StepMcpRouter(factory)
    await router.connect([{ name: 'db', url: 'http://db:3000' }])

    await router.callTool('db__read', { table: 'users' })
    expect(clientA.callTool).toHaveBeenCalledWith('read', { table: 'users' }, {})
  })

  it('returns tool result from server', async () => {
    const client = mockClient([{ name: 'query' }])
    ;(client.callTool as ReturnType<typeof vi.fn>).mockResolvedValue({
      content: { rows: 5 },
      isError: false,
    })
    const factory = mockFactory(new Map([['db', client]]))
    const router = new StepMcpRouter(factory)
    await router.connect([{ name: 'db', url: 'http://db:3000' }])

    const { result, record } = await router.callTool('db__query', {})
    expect(result.content).toEqual({ rows: 5 })
    expect(record.serverName).toBe('db')
    expect(record.toolName).toBe('query')
    expect(record.durationMs).toBeGreaterThanOrEqual(0)
  })

  it('throws ToolDispatchError for unknown tool name', async () => {
    const router = new StepMcpRouter(() => mockClient())
    await router.connect([])
    await expect(router.callTool('unknown__tool', {})).rejects.toThrow(ToolDispatchError)
  })
})

describe('StepMcpRouter call-time allowlist (spec §3.1.2)', () => {
  const notAllowed = (toolName: string) =>
    `Tool '${toolName}' is not allowed in this step and was not run. Use only the tools provided for this step.`

  async function routerWithAllowlist(allowedTools?: AllowedToolsConfig) {
    const client = mockClient([{ name: 'read' }, { name: 'write' }])
    const execute = vi.fn(async () => ({ success: true, content: 'internal ran' }))
    const router = new StepMcpRouter(mockFactory(new Map([['srv', client]])))
    router.registerInternalTools(
      [
        {
          name: 'clerum__read_workflow',
          description: 'read',
          parameters: { type: 'object' },
          execute,
        },
        {
          name: 'clerum__list_workflows',
          description: 'list',
          parameters: { type: 'object' },
          execute,
        },
      ],
      '/output'
    )
    await router.connect([{ name: 'srv', url: 'http://srv:3000' }])
    router.setAllowedTools(allowedTools)
    return { client, execute, router }
  }

  it('returns a recoverable tool error for an MCP tool outside include and never calls the server', async () => {
    const { client, router } = await routerWithAllowlist({ include: ['srv__read'] })

    const { result, record } = await router.callTool('srv__write', { path: 'README.md' })

    const errorResult = { success: false, error: notAllowed('srv__write') }
    expect(result).toEqual({ content: errorResult, isError: true })
    expect(record).toEqual({
      serverName: 'srv',
      toolName: 'write',
      args: { path: 'README.md' },
      result: errorResult,
      durationMs: 0,
    })
    expect(client.callTool).not.toHaveBeenCalled()
  })

  it('returns a recoverable tool error for a registered internal tool outside include and never executes it', async () => {
    const { execute, router } = await routerWithAllowlist({ include: ['srv__read'] })

    const { result, record } = await router.callTool('clerum__read_workflow', {
      namespace: 'sandbox-recipes',
      name: 'other-recipe',
    })

    expect(result).toEqual({
      content: { success: false, error: notAllowed('clerum__read_workflow') },
      isError: true,
    })
    expect(record.serverName).toBe('clerum')
    expect(record.toolName).toBe('read_workflow')
    expect(execute).not.toHaveBeenCalled()
  })

  it('answers a listed name that no server registered with a tool error instead of throwing', async () => {
    const { client, router } = await routerWithAllowlist({
      include: ['srv__read', 'srv__delete', 'shell_exec'],
    })

    await expect(router.callTool('srv__delete', {})).resolves.toMatchObject({
      result: { content: { success: false, error: notAllowed('srv__delete') }, isError: true },
      record: { serverName: 'srv', toolName: 'delete' },
    })
    await expect(router.callTool('shell_exec', {})).resolves.toMatchObject({
      result: { isError: true },
      record: { serverName: 'unknown', toolName: 'shell_exec' },
    })
    expect(client.callTool).not.toHaveBeenCalled()
  })

  it('dispatches listed MCP and internal tools normally', async () => {
    const { client, execute, router } = await routerWithAllowlist({
      include: ['srv__read', 'clerum__list_workflows'],
    })

    const mcp = await router.callTool('srv__read', { q: 1 })
    const internal = await router.callTool('clerum__list_workflows', {})

    expect(client.callTool).toHaveBeenCalledWith('read', { q: 1 }, {})
    expect(mcp.result).toEqual({ content: 'result', isError: false })
    expect(execute).toHaveBeenCalledTimes(1)
    expect(internal.result).toEqual({
      content: { success: true, content: 'internal ran' },
      isError: false,
    })
  })

  it.each<[string, AllowedToolsConfig | undefined]>([
    ['absent', undefined],
    ['empty', { include: [] }],
  ])('keeps unrestricted dispatch when include is %s', async (_label, allowedTools) => {
    const { client, execute, router } = await routerWithAllowlist(allowedTools)

    await router.callTool('srv__write', { path: 'notes.md' })
    await router.callTool('clerum__read_workflow', {})

    expect(client.callTool).toHaveBeenCalledWith('write', { path: 'notes.md' }, {})
    expect(execute).toHaveBeenCalledTimes(1)
    await expect(router.callTool('unknown__tool', {})).rejects.toThrow(ToolDispatchError)
  })

  it('still throws for an already cancelled caller before the allowlist check', async () => {
    const { client, router } = await routerWithAllowlist({ include: ['srv__read'] })

    await expect(
      router.callTool('srv__write', {}, { signal: AbortSignal.abort('step-timeout') })
    ).rejects.toThrow('step-timeout')
    expect(client.callTool).not.toHaveBeenCalled()
  })
})

describe('StepMcpRouter.disconnect', () => {
  it('disconnects all connected servers', async () => {
    const clientA = mockClient([{ name: 't1' }])
    const clientB = mockClient([{ name: 't2' }])
    const factory = mockFactory(
      new Map([
        ['a', clientA],
        ['b', clientB],
      ])
    )
    const router = new StepMcpRouter(factory)
    await router.connect([
      { name: 'a', url: 'http://a:3000' },
      { name: 'b', url: 'http://b:3000' },
    ])

    await router.disconnect()
    expect(clientA.disconnect).toHaveBeenCalled()
    expect(clientB.disconnect).toHaveBeenCalled()
  })

  it('does not throw if called on unconnected router', async () => {
    const router = new StepMcpRouter(() => mockClient())
    await expect(router.disconnect()).resolves.toBeUndefined()
  })

  it('disconnects even when one server disconnect throws', async () => {
    const clientA = mockClient([{ name: 't1' }])
    const clientB = mockClient([{ name: 't2' }])
    ;(clientA.disconnect as ReturnType<typeof vi.fn>).mockRejectedValue(
      new Error('disconnect fail')
    )
    const factory = mockFactory(
      new Map([
        ['a', clientA],
        ['b', clientB],
      ])
    )
    const router = new StepMcpRouter(factory)
    await router.connect([
      { name: 'a', url: 'http://a:3000' },
      { name: 'b', url: 'http://b:3000' },
    ])

    await expect(router.disconnect()).resolves.toBeUndefined()
    expect(clientB.disconnect).toHaveBeenCalled()
  })
})