@nimrobo/mcporter-remote 0.1.0

package/tests/result-utils.test.ts

@@ -0,0 +1,254 @@
+import { describe, expect, it } from 'vitest';
+import { createCallResult, describeConnectionIssue } from '../src/result-utils.js';
+
+describe('result-utils connection helpers', () => {
+  it('describes connection issues for offline errors', () => {
+    const issue = describeConnectionIssue(new Error('fetch failed: connect ECONNREFUSED 127.0.0.1:9999'));
+    expect(issue.kind).toBe('offline');
+  });
+});
+
+describe('createCallResult text extraction', () => {
+  it('extracts text from content array at top level', () => {
+    const response = {
+      content: [
+        {
+          type: 'text',
+          text: 'Hello World',
+        },
+      ],
+    };
+    const result = createCallResult(response);
+    expect(result.text()).toBe('Hello World');
+  });
+
+  it('extracts text from content array nested inside raw wrapper', () => {
+    const response = {
+      raw: {
+        content: [
+          {
+            type: 'text',
+            text: 'Available pages for stanfordnlp/dspy:\n\n- 1 Overview',
+          },
+        ],
+      },
+    };
+    const result = createCallResult(response);
+    expect(result.text()).toBe('Available pages for stanfordnlp/dspy:\n\n- 1 Overview');
+  });
+
+  it('extracts multiple text entries and joins them', () => {
+    const response = {
+      content: [
+        {
+          type: 'text',
+          text: 'First part',
+        },
+        {
+          type: 'text',
+          text: 'Second part',
+        },
+      ],
+    };
+    const result = createCallResult(response);
+    expect(result.text()).toBe('First part\nSecond part');
+  });
+
+  it('returns null when no text content is available', () => {
+    const response = {
+      content: [
+        {
+          type: 'image',
+          data: 'base64...',
+        },
+      ],
+    };
+    const result = createCallResult(response);
+    expect(result.text()).toBe(null);
+  });
+
+  it('returns string when raw is already a string', () => {
+    const response = 'Simple string response';
+    const result = createCallResult(response);
+    expect(result.text()).toBe('Simple string response');
+  });
+});
+
+describe('createCallResult image extraction', () => {
+  it('extracts image blocks from content', () => {
+    const response = {
+      content: [
+        { type: 'image', mimeType: 'image/png', data: 'aGVsbG8=' },
+        { type: 'image', mimeType: 'image/jpeg', data: 'd29ybGQ=' },
+      ],
+    };
+    const result = createCallResult(response);
+    expect(result.images()).toEqual([
+      { mimeType: 'image/png', data: 'aGVsbG8=' },
+      { mimeType: 'image/jpeg', data: 'd29ybGQ=' },
+    ]);
+  });
+
+  it('extracts image blocks nested under raw.content', () => {
+    const response = {
+      raw: {
+        content: [{ type: 'image', data: 'aGVsbG8=' }],
+      },
+    };
+    const result = createCallResult(response);
+    expect(result.images()).toEqual([{ mimeType: 'image/png', data: 'aGVsbG8=' }]);
+  });
+
+  it('returns null when no images exist', () => {
+    const response = {
+      content: [{ type: 'text', text: 'no image here' }],
+    };
+    const result = createCallResult(response);
+    expect(result.images()).toBeNull();
+  });
+});
+
+describe('createCallResult markdown extraction', () => {
+  it('extracts markdown from content array', () => {
+    const response = {
+      content: [
+        {
+          type: 'markdown',
+          text: '# Header\n\nContent',
+        },
+      ],
+    };
+    const result = createCallResult(response);
+    expect(result.markdown()).toBe('# Header\n\nContent');
+  });
+
+  it('extracts markdown from content array nested inside raw wrapper', () => {
+    const response = {
+      raw: {
+        content: [
+          {
+            type: 'markdown',
+            text: '## Subtitle',
+          },
+        ],
+      },
+    };
+    const result = createCallResult(response);
+    expect(result.markdown()).toBe('## Subtitle');
+  });
+
+  it('extracts markdown from structuredContent nested inside raw wrapper', () => {
+    const response = {
+      raw: {
+        structuredContent: {
+          markdown: '_italic_',
+        },
+      },
+    };
+    const result = createCallResult(response);
+    expect(result.markdown()).toBe('_italic_');
+  });
+});
+
+describe('createCallResult json extraction', () => {
+  it('returns null for text-only content', () => {
+    const response = {
+      content: [
+        {
+          type: 'text',
+          text: 'Plain text',
+        },
+      ],
+    };
+    const result = createCallResult(response);
+    expect(result.json()).toBe(null);
+  });
+
+  it('extracts json from content array with json type', () => {
+    const response = {
+      content: [
+        {
+          type: 'json',
+          json: { foo: 'bar' },
+        },
+      ],
+    };
+    const result = createCallResult(response);
+    expect(result.json()).toEqual({ foo: 'bar' });
+  });
+
+  it('returns all items when content array has multiple json entries', () => {
+    const response = {
+      content: [
+        { type: 'json', json: { id: 1, name: 'first' } },
+        { type: 'json', json: { id: 2, name: 'second' } },
+        { type: 'json', json: { id: 3, name: 'third' } },
+      ],
+    };
+    const result = createCallResult(response);
+    expect(result.json()).toEqual([
+      { id: 1, name: 'first' },
+      { id: 2, name: 'second' },
+      { id: 3, name: 'third' },
+    ]);
+  });
+
+  it('returns all items when content has mixed json and text-parseable-as-json entries', () => {
+    const response = {
+      content: [
+        { type: 'json', json: { source: 'json-type' } },
+        { type: 'text', text: '{"source":"text-type"}' },
+      ],
+    };
+    const result = createCallResult(response);
+    expect(result.json()).toEqual([{ source: 'json-type' }, { source: 'text-type' }]);
+  });
+
+  it('extracts json from structuredContent nested inside raw wrapper', () => {
+    const response = {
+      raw: {
+        structuredContent: {
+          json: { nested: true },
+        },
+      },
+    };
+    const result = createCallResult(response);
+    expect(result.json()).toEqual({ nested: true });
+  });
+});
+
+describe('createCallResult structured accessors', () => {
+  it('content() returns nested raw content array', () => {
+    const nested = [{ type: 'text', text: 'Hello' }];
+    const response = {
+      raw: {
+        content: nested,
+      },
+    };
+    const result = createCallResult(response);
+    expect(result.content()).toBe(nested);
+  });
+
+  it('structuredContent() returns nested raw structuredContent', () => {
+    const structured = { text: 'Inner text' };
+    const response = {
+      raw: {
+        structuredContent: structured,
+      },
+    };
+    const result = createCallResult(response);
+    expect(result.structuredContent()).toBe(structured);
+  });
+
+  it('text() falls back to structuredContent.text when no content exists', () => {
+    const response = {
+      raw: {
+        structuredContent: {
+          text: 'Structured fallback',
+        },
+      },
+    };
+    const result = createCallResult(response);
+    expect(result.text()).toBe('Structured fallback');
+  });
+});

package/tests/runtime-call-timeout.test.ts

@@ -0,0 +1,75 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createRuntime } from '../src/runtime.js';
+
+describe('runtime callTool timeouts', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('forwards timeout into MCP client request options', async () => {
+    const runtime = await createRuntime({ servers: [] });
+
+    const callTool = vi.fn(
+      async (
+        _params,
+        _schema,
+        options?: { timeout?: number; resetTimeoutOnProgress?: boolean; maxTotalTimeout?: number }
+      ) => {
+        // Simulate a successful response without timing out.
+        expect(options?.timeout).toBe(456);
+        expect(options?.resetTimeoutOnProgress).toBe(true);
+        expect(options?.maxTotalTimeout).toBe(456);
+        return { ok: true };
+      }
+    );
+
+    type ClientContext = Awaited<ReturnType<typeof runtime.connect>>;
+    const fakeContext = {
+      client: { callTool },
+      transport: { close: vi.fn().mockResolvedValue(undefined) },
+      definition: {
+        name: 'temp',
+        description: 'test',
+        command: { kind: 'stdio', command: 'node', args: [], cwd: process.cwd() },
+        source: { kind: 'local', path: '<test>' },
+      },
+      oauthSession: undefined,
+    } as unknown as ClientContext;
+    vi.spyOn(runtime, 'connect').mockResolvedValue(fakeContext);
+
+    const result = await runtime.callTool('temp', 'ping', { timeoutMs: 456 });
+    expect(result).toEqual({ ok: true });
+    expect(callTool).toHaveBeenCalledOnce();
+  });
+
+  it('rejects when a call exceeds the timeout and closes the server', async () => {
+    vi.useFakeTimers();
+    const runtime = await createRuntime({ servers: [] });
+    const callTool = vi.fn(() => new Promise(() => {}));
+    type ClientContext = Awaited<ReturnType<typeof runtime.connect>>;
+    const fakeContext = {
+      client: { callTool },
+      transport: { close: vi.fn().mockResolvedValue(undefined) },
+      definition: {
+        name: 'temp',
+        description: 'test',
+        command: { kind: 'stdio', command: 'node', args: [], cwd: process.cwd() },
+        source: { kind: 'local', path: '<test>' },
+      },
+      oauthSession: undefined,
+    } as unknown as ClientContext;
+    vi.spyOn(runtime, 'connect').mockResolvedValue(fakeContext);
+    (runtime as unknown as { clients: Map<string, Promise<ClientContext>> }).clients.set(
+      'temp',
+      Promise.resolve(fakeContext)
+    );
+    const closeSpy = vi.spyOn(runtime, 'close').mockResolvedValue();
+
+    const promise = runtime.callTool('temp', 'ping', { timeoutMs: 123 });
+    const expectation = expect(promise).rejects.toThrow('Timeout');
+    await vi.advanceTimersByTimeAsync(200);
+    await expectation;
+    expect(closeSpy).toHaveBeenCalledWith('temp');
+  });
+});

package/tests/runtime-compose.test.ts

@@ -0,0 +1,298 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => {
+  const connectMock = vi.fn();
+  const listToolsMock = vi.fn();
+  const callToolMock = vi.fn();
+  const listResourcesMock = vi.fn();
+  const clientInstances: unknown[] = [];
+  const streamableInstances: unknown[] = [];
+  const stdioInstances: unknown[] = [];
+
+  class MockClient {
+    constructor() {
+      clientInstances.push(this);
+    }
+
+    async connect(transport: { start?: () => Promise<void> }) {
+      connectMock(transport);
+      if (typeof transport.start === 'function') {
+        await transport.start();
+      }
+    }
+
+    async close() {}
+
+    async listTools(params: unknown) {
+      return listToolsMock(params);
+    }
+
+    async callTool(params: unknown) {
+      return callToolMock(params);
+    }
+
+    async listResources(params: unknown) {
+      return listResourcesMock(params);
+    }
+  }
+
+  class MockStreamableHTTPClientTransport {
+    public start = vi.fn(async () => {});
+    public close = vi.fn(async () => {});
+    constructor(
+      public url: URL,
+      public options?: unknown
+    ) {
+      streamableInstances.push(this);
+    }
+  }
+
+  class MockSSEClientTransport {
+    public start = vi.fn(async () => {});
+    public close = vi.fn(async () => {});
+    constructor(
+      public url: URL,
+      public options?: unknown
+    ) {}
+  }
+
+  class MockStdioClientTransport {
+    public start = vi.fn(async () => {});
+    public close = vi.fn(async () => {});
+    constructor(public options: unknown) {
+      stdioInstances.push(this);
+    }
+  }
+
+  class MockUnauthorizedError extends Error {}
+
+  return {
+    connectMock,
+    listToolsMock,
+    callToolMock,
+    listResourcesMock,
+    clientInstances,
+    streamableInstances,
+    stdioInstances,
+    MockClient,
+    MockStreamableHTTPClientTransport,
+    MockSSEClientTransport,
+    MockStdioClientTransport,
+    MockUnauthorizedError,
+  };
+});
+
+vi.mock('@modelcontextprotocol/sdk/client/index.js', () => ({
+  Client: mocks.MockClient,
+}));
+
+vi.mock('@modelcontextprotocol/sdk/client/streamableHttp.js', () => ({
+  StreamableHTTPClientTransport: mocks.MockStreamableHTTPClientTransport,
+}));
+
+vi.mock('@modelcontextprotocol/sdk/client/sse.js', () => ({
+  SSEClientTransport: mocks.MockSSEClientTransport,
+}));
+
+vi.mock('@modelcontextprotocol/sdk/client/stdio.js', () => ({
+  StdioClientTransport: mocks.MockStdioClientTransport,
+}));
+
+vi.mock('@modelcontextprotocol/sdk/client/auth.js', () => ({
+  UnauthorizedError: mocks.MockUnauthorizedError,
+}));
+
+import { createRuntime } from '../src/runtime.js';
+
+describe('mcporter composability', () => {
+  beforeEach(() => {
+    mocks.connectMock.mockClear();
+    mocks.listToolsMock.mockReset();
+    mocks.callToolMock.mockReset();
+    mocks.listResourcesMock.mockReset();
+    mocks.clientInstances.length = 0;
+    mocks.streamableInstances.length = 0;
+    mocks.stdioInstances.length = 0;
+
+    mocks.listToolsMock.mockResolvedValue({ tools: [] });
+    mocks.callToolMock.mockResolvedValue({ ok: true });
+    mocks.listResourcesMock.mockResolvedValue({ resources: [] });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+    vi.unstubAllEnvs();
+  });
+
+  it('reuses a single client connection for sequential calls', async () => {
+    mocks.listToolsMock.mockResolvedValueOnce({
+      tools: [{ name: 'echo', description: 'Echo tool' }],
+    });
+    mocks.callToolMock.mockResolvedValueOnce({ ok: 'first' }).mockResolvedValueOnce({ ok: 'second' });
+
+    const previousToken = process.env.INLINE_TOKEN;
+    process.env.INLINE_TOKEN = 'inline-test';
+
+    const runtime = await createRuntime({
+      servers: [
+        {
+          name: 'fake',
+          description: 'Inline fake server',
+          command: {
+            kind: 'http' as const,
+            url: new URL('https://example.com'),
+            headers: { Authorization: `Bearer \${INLINE_TOKEN}` },
+          },
+        },
+      ],
+    });
+
+    try {
+      const tools = await runtime.listTools('fake');
+      expect(tools).toEqual([
+        {
+          name: 'echo',
+          description: 'Echo tool',
+          inputSchema: undefined,
+          outputSchema: undefined,
+        },
+      ]);
+      expect(mocks.connectMock).toHaveBeenCalledTimes(1);
+      expect(mocks.clientInstances).toHaveLength(1);
+      const streamableTransport = mocks.streamableInstances[0] as {
+        options?: {
+          requestInit?: { headers?: Record<string, string> };
+          authProvider?: unknown;
+        };
+        close: ReturnType<typeof vi.fn>;
+      };
+      expect(streamableTransport.options?.requestInit?.headers).toEqual({
+        Authorization: 'Bearer inline-test',
+      });
+
+      const first = await runtime.callTool('fake', 'echo', {
+        args: { text: 'hi' },
+      });
+      const second = await runtime.callTool('fake', 'echoSecond', {
+        args: { count: 2 },
+      });
+
+      expect(first).toEqual({ ok: 'first' });
+      expect(second).toEqual({ ok: 'second' });
+      expect(mocks.callToolMock).toHaveBeenNthCalledWith(1, {
+        name: 'echo',
+        arguments: { text: 'hi' },
+      });
+      expect(mocks.callToolMock).toHaveBeenNthCalledWith(2, {
+        name: 'echoSecond',
+        arguments: { count: 2 },
+      });
+      expect(mocks.connectMock).toHaveBeenCalledTimes(1);
+      expect(mocks.clientInstances).toHaveLength(1);
+    } finally {
+      await runtime.close();
+      const streamableTransport = mocks.streamableInstances[0] as {
+        close: ReturnType<typeof vi.fn>;
+      };
+      expect(mocks.streamableInstances).toHaveLength(1);
+      expect(streamableTransport.close).toHaveBeenCalledTimes(1);
+      if (previousToken === undefined) {
+        delete process.env.INLINE_TOKEN;
+      } else {
+        process.env.INLINE_TOKEN = previousToken;
+      }
+    }
+  });
+
+  it('passes the current process env to stdio transports', async () => {
+    vi.stubEnv('MCPORTER_STDIO_TEST', 'from-parent');
+    const runtime = await createRuntime({
+      servers: [
+        {
+          name: 'local',
+          command: { kind: 'stdio', command: 'node', args: ['-v'], cwd: process.cwd() },
+          source: { kind: 'local', path: '<test>' },
+        },
+      ],
+    });
+    await runtime.callTool('local', 'echo', {});
+    const instance = mocks.stdioInstances.at(-1) as { options?: { env?: Record<string, string> } };
+    expect(instance?.options?.env?.MCPORTER_STDIO_TEST).toBe('from-parent');
+  });
+
+  it('overrides inherited env vars with server-specific values', async () => {
+    vi.stubEnv('MCPORTER_STDIO_TEST', 'parent');
+    const runtime = await createRuntime({
+      servers: [
+        {
+          name: 'local',
+          command: { kind: 'stdio', command: 'node', args: ['-v'], cwd: process.cwd() },
+          env: { MCPORTER_STDIO_TEST: 'from-config', EXTRA: '42' },
+          source: { kind: 'local', path: '<test>' },
+        },
+      ],
+    });
+    await runtime.callTool('local', 'echo', {});
+    const instance = mocks.stdioInstances.at(-1) as { options?: { env?: Record<string, string> } };
+    expect(instance?.options?.env?.MCPORTER_STDIO_TEST).toBe('from-config');
+    expect(instance?.options?.env?.EXTRA).toBe('42');
+  });
+});
+
+describe('stdio transport environment', () => {
+  const previousEnv = { ...process.env };
+
+  beforeEach(() => {
+    process.env = { ...previousEnv };
+    mocks.listToolsMock.mockReset();
+    mocks.listToolsMock.mockResolvedValue({ tools: [] });
+    mocks.clientInstances.length = 0;
+    mocks.stdioInstances.length = 0;
+  });
+
+  afterEach(() => {
+    process.env = { ...previousEnv };
+    vi.clearAllMocks();
+  });
+
+  it('resolves env overrides before spawning stdio transport', async () => {
+    process.env.OBSIDIAN_API_KEY = 'secret';
+    delete process.env.OBSIDIAN_BASE_URL;
+
+    const runtime = await createRuntime({
+      servers: [
+        {
+          name: 'obsidian',
+          description: 'Local Obsidian bridge',
+          command: {
+            kind: 'stdio' as const,
+            command: 'node',
+            args: ['--version'],
+            cwd: '/repo',
+          },
+          env: {
+            // biome-ignore lint/suspicious/noTemplateCurlyInString: placeholders resolve against process env at runtime
+            OBSIDIAN_API_KEY: '${OBSIDIAN_API_KEY}',
+            // biome-ignore lint/suspicious/noTemplateCurlyInString: placeholders resolve against process env at runtime
+            OBSIDIAN_BASE_URL: '${OBSIDIAN_BASE_URL:-https://127.0.0.1:27124}',
+            EMPTY_VAR: '',
+          },
+        },
+      ],
+    });
+
+    try {
+      await runtime.listTools('obsidian');
+      expect(mocks.stdioInstances).toHaveLength(1);
+      const transport = mocks.stdioInstances[0] as { options: { env?: Record<string, string> } };
+      expect(transport.options.env).toEqual(
+        expect.objectContaining({
+          OBSIDIAN_API_KEY: 'secret',
+          OBSIDIAN_BASE_URL: 'https://127.0.0.1:27124',
+        })
+      );
+    } finally {
+      await runtime.close().catch(() => {});
+    }
+  });
+});

package/tests/runtime-error-reset.test.ts

@@ -0,0 +1,65 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createRuntime } from '../src/runtime.js';
+
+describe('runtime connection resets', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('closes cached connections after fatal MCP errors', async () => {
+    const runtime = await createRuntime({ servers: [] });
+    type ClientContext = Awaited<ReturnType<typeof runtime.connect>>;
+    const rejected = new McpError(ErrorCode.ConnectionClosed, 'Connection closed');
+    const context = {
+      client: {
+        callTool: vi.fn().mockRejectedValue(rejected),
+      },
+      transport: { close: vi.fn().mockResolvedValue(undefined) },
+      definition: {
+        name: 'temp',
+        description: 'test',
+        command: { kind: 'stdio', command: 'node', args: [], cwd: process.cwd() },
+        source: { kind: 'local', path: '<test>' },
+      },
+      oauthSession: undefined,
+    } as unknown as ClientContext;
+    vi.spyOn(runtime, 'connect').mockResolvedValue(context);
+    (runtime as unknown as { clients: Map<string, Promise<ClientContext>> }).clients.set(
+      'temp',
+      Promise.resolve(context)
+    );
+    const closeSpy = vi.spyOn(runtime, 'close').mockResolvedValue();
+
+    await expect(runtime.callTool('temp', 'list_pages')).rejects.toThrow('Connection closed');
+    expect(closeSpy).toHaveBeenCalledWith('temp');
+  });
+
+  it('keeps the connection open for user-facing InvalidParams errors', async () => {
+    const runtime = await createRuntime({ servers: [] });
+    type ClientContext = Awaited<ReturnType<typeof runtime.connect>>;
+    const rejected = new McpError(ErrorCode.InvalidParams, 'Tool help not found');
+    const context = {
+      client: {
+        callTool: vi.fn().mockRejectedValue(rejected),
+      },
+      transport: { close: vi.fn().mockResolvedValue(undefined) },
+      definition: {
+        name: 'temp',
+        description: 'test',
+        command: { kind: 'stdio', command: 'node', args: [], cwd: process.cwd() },
+        source: { kind: 'local', path: '<test>' },
+      },
+      oauthSession: undefined,
+    } as unknown as ClientContext;
+    vi.spyOn(runtime, 'connect').mockResolvedValue(context);
+    (runtime as unknown as { clients: Map<string, Promise<ClientContext>> }).clients.set(
+      'temp',
+      Promise.resolve(context)
+    );
+    const closeSpy = vi.spyOn(runtime, 'close').mockResolvedValue();
+
+    await expect(runtime.callTool('temp', 'help')).rejects.toThrow('Tool help not found');
+    expect(closeSpy).not.toHaveBeenCalled();
+  });
+});