mcpose 2.1.1 → 3.1.0

package/src/__tests__/core.toolCallTelemetry.test.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createProxyServer, type LocalTool } from '../core.js';
+import type { BackendClient } from '../backendClient.js';
+import type { TelemetryEvent } from '../telemetry.js';
+
+/** Invokes a registered handler directly via `_requestHandlers` — no transport needed. */
+async function invokeHandler(
+  server: ReturnType<typeof createProxyServer>,
+  method: string,
+  params: Record<string, unknown> = {},
+) {
+  const { _requestHandlers: handlers } = server as unknown as {
+    _requestHandlers: Map<
+      string,
+      (
+        req: { method: string; params: Record<string, unknown> },
+        extra: object,
+      ) => Promise<unknown>
+    >;
+  };
+  const handler = handlers.get(method);
+  if (!handler) throw new Error(`No handler registered for method: ${method}`);
+  return handler({ method, params }, {});
+}
+
+function makeBackend(): BackendClient {
+  return {
+    getServerCapabilities: vi.fn().mockReturnValue({ tools: {} }),
+    listTools: vi.fn().mockResolvedValue({ tools: [] }),
+    callTool: vi.fn(),
+    setNotificationHandler: vi.fn(),
+  } as unknown as BackendClient;
+}
+
+/**
+ * `hasToolContent` answers false for a value that is not a tool result instead
+ * of throwing on it. The `tools/call` telemetry decision reads that guard, so a
+ * pipeline that resolved to nothing must not be recorded as a clean call: the
+ * result never reached the client, and there is no `isError` to judge it by.
+ */
+describe('tools/call telemetry — a result that is not a tool result', () => {
+  it('reports error when a local tool handler resolves to nothing', async () => {
+    const events: TelemetryEvent[] = [];
+    const noReturn: LocalTool = {
+      tool: {
+        name: 'silent_tool',
+        description: 'returns undefined',
+        inputSchema: { type: 'object', properties: {} },
+      },
+      // A local tool with a missing `return`: the pipeline resolves to undefined.
+      handler: (async () => undefined) as unknown as LocalTool['handler'],
+    };
+
+    const server = createProxyServer(
+      { crm: makeBackend() },
+      {
+        name: 'test-server',
+        localTools: [noReturn],
+        onTelemetry: (e) => events.push(e),
+      },
+    );
+
+    // The SDK rejects the malformed result on the way out, which is correct and
+    // unchanged by this PR. What matters is what telemetry recorded first.
+    await expect(
+      invokeHandler(server, 'tools/call', {
+        name: 'silent_tool',
+        arguments: {},
+      }),
+    ).rejects.toBeDefined();
+
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      type: 'tool_call',
+      tool: 'silent_tool',
+      outcome: 'error',
+    });
+  });
+
+  it('still reports success for a real result and error for an isError one', async () => {
+    const events: TelemetryEvent[] = [];
+    const ok: LocalTool = {
+      tool: {
+        name: 'ok_tool',
+        description: 'ok',
+        inputSchema: { type: 'object', properties: {} },
+      },
+      handler: async () => ({ content: [{ type: 'text', text: 'fine' }] }),
+    };
+    const failing: LocalTool = {
+      tool: {
+        name: 'bad_tool',
+        description: 'bad',
+        inputSchema: { type: 'object', properties: {} },
+      },
+      handler: async () => ({
+        content: [{ type: 'text', text: 'nope' }],
+        isError: true,
+      }),
+    };
+
+    const server = createProxyServer(
+      { crm: makeBackend() },
+      {
+        name: 'test-server',
+        localTools: [ok, failing],
+        onTelemetry: (e) => events.push(e),
+      },
+    );
+
+    await invokeHandler(server, 'tools/call', {
+      name: 'ok_tool',
+      arguments: {},
+    });
+    await invokeHandler(server, 'tools/call', {
+      name: 'bad_tool',
+      arguments: {},
+    });
+
+    expect(events.map((e) => (e as { outcome?: string }).outcome)).toEqual([
+      'success',
+      'error',
+    ]);
+  });
+});
+
+/**
+ * The legacy `{ toolResult }` shape (protocol 2024-10-07) is a valid, documented
+ * result — `mapToolResult` returns it untouched and the guard answers `false` for
+ * it because it has no `.content`. It is not a failure, so it must not be
+ * telemetered as one.
+ */
+describe('tools/call telemetry — the legacy { toolResult } shape', () => {
+  it('reports success for a legacy-shape result', async () => {
+    const events: TelemetryEvent[] = [];
+    const backend = makeBackend();
+    backend.callTool = vi.fn().mockResolvedValue({
+      toolResult: { raw: true },
+    }) as BackendClient['callTool'];
+
+    const server = createProxyServer(
+      { crm: backend },
+      { name: 'test-server', onTelemetry: (e) => events.push(e) },
+    );
+
+    await invokeHandler(server, 'tools/call', {
+      name: 'crm__legacy_tool',
+      arguments: {},
+    });
+
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      type: 'tool_call',
+      outcome: 'success',
+    });
+  });
+});

package/src/__tests__/eventStore.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import { createInMemoryEventStore, scopeEventStore } from '../eventStore.js';
+
+function msg(id: number): JSONRPCMessage {
+  return { jsonrpc: '2.0', method: 'notifications/test', params: { id } };
+}
+
+describe('createInMemoryEventStore()', () => {
+  it('assigns monotonically increasing event ids', async () => {
+    const store = createInMemoryEventStore();
+    const a = await store.storeEvent('stream-a', msg(1));
+    const b = await store.storeEvent('stream-a', msg(2));
+    expect(parseInt(b, 10)).toBeGreaterThan(parseInt(a, 10));
+  });
+
+  it('resolves the stream id for a stored event', async () => {
+    const store = createInMemoryEventStore();
+    const id = await store.storeEvent('stream-a', msg(1));
+    expect(await store.getStreamIdForEventId?.(id)).toBe('stream-a');
+  });
+
+  describe('replayEventsAfter', () => {
+    it('replays only events belonging to the same stream', async () => {
+      const store = createInMemoryEventStore();
+      const a1 = await store.storeEvent('stream-a', msg(1));
+      await store.storeEvent('stream-b', msg(2));
+      const a2 = await store.storeEvent('stream-a', msg(3));
+      await store.storeEvent('stream-b', msg(4));
+
+      const send = vi.fn().mockResolvedValue(undefined);
+      const streamId = await store.replayEventsAfter(a1, { send });
+
+      expect(streamId).toBe('stream-a');
+      expect(send).toHaveBeenCalledTimes(1);
+      expect(send).toHaveBeenCalledWith(a2, msg(3));
+    });
+
+    it('replays nothing for an unknown Last-Event-ID', async () => {
+      const store = createInMemoryEventStore();
+      await store.storeEvent('stream-a', msg(1));
+      await store.storeEvent('stream-a', msg(2));
+
+      const send = vi.fn().mockResolvedValue(undefined);
+      const streamId = await store.replayEventsAfter('does-not-exist', {
+        send,
+      });
+
+      expect(streamId).toBe('');
+      expect(send).not.toHaveBeenCalled();
+    });
+
+    it('replays nothing for a malformed Last-Event-ID', async () => {
+      const store = createInMemoryEventStore();
+      await store.storeEvent('stream-a', msg(1));
+
+      const send = vi.fn().mockResolvedValue(undefined);
+      const streamId = await store.replayEventsAfter('not-a-number', { send });
+
+      expect(streamId).toBe('');
+      expect(send).not.toHaveBeenCalled();
+    });
+
+    it('replays nothing for an evicted Last-Event-ID', async () => {
+      const store = createInMemoryEventStore(2);
+      const first = await store.storeEvent('stream-a', msg(1));
+      await store.storeEvent('stream-a', msg(2));
+      await store.storeEvent('stream-a', msg(3)); // evicts `first`
+
+      const send = vi.fn().mockResolvedValue(undefined);
+      const streamId = await store.replayEventsAfter(first, { send });
+
+      expect(streamId).toBe('');
+      expect(send).not.toHaveBeenCalled();
+    });
+  });
+
+  it('evicts FIFO once maxEvents is reached', async () => {
+    const store = createInMemoryEventStore(2);
+    const first = await store.storeEvent('stream-a', msg(1));
+    const second = await store.storeEvent('stream-a', msg(2));
+    const third = await store.storeEvent('stream-a', msg(3));
+
+    expect(await store.getStreamIdForEventId?.(first)).toBeUndefined();
+    expect(await store.getStreamIdForEventId?.(second)).toBe('stream-a');
+    expect(await store.getStreamIdForEventId?.(third)).toBe('stream-a');
+  });
+});
+
+describe('scopeEventStore()', () => {
+  it('namespaces stream ids by session and strips the prefix on the way out', async () => {
+    const inner = createInMemoryEventStore();
+    const scoped = scopeEventStore(inner, 'session-a');
+    const id = await scoped.storeEvent('_GET_stream', msg(1));
+    const id2 = await scoped.storeEvent('_GET_stream', msg(2));
+
+    expect(await inner.getStreamIdForEventId?.(id)).toBe(
+      'session-a:_GET_stream',
+    );
+    expect(await scoped.getStreamIdForEventId?.(id)).toBe('_GET_stream');
+
+    const send = vi.fn().mockResolvedValue(undefined);
+    expect(await scoped.replayEventsAfter(id, { send })).toBe('_GET_stream');
+    expect(send).toHaveBeenCalledWith(id2, msg(2));
+  });
+
+  it("treats another session's cursor as unknown and replays nothing (#154)", async () => {
+    const inner = createInMemoryEventStore();
+    const a = scopeEventStore(inner, 'session-a');
+    const b = scopeEventStore(inner, 'session-b');
+    const cursor = await a.storeEvent('_GET_stream', msg(1));
+    await a.storeEvent('_GET_stream', msg(2));
+
+    expect(await b.getStreamIdForEventId?.(cursor)).toBeUndefined();
+    const send = vi.fn().mockResolvedValue(undefined);
+    expect(await b.replayEventsAfter(cursor, { send })).toBe('');
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it('learns the owner by a silent replay when the store has no getStreamIdForEventId', async () => {
+    const inner = createInMemoryEventStore();
+    const bare = {
+      storeEvent: inner.storeEvent,
+      replayEventsAfter: inner.replayEventsAfter,
+    };
+    const a = scopeEventStore(bare, 'session-a');
+    const b = scopeEventStore(bare, 'session-b');
+    const cursor = await a.storeEvent('_GET_stream', msg(1));
+    const next = await a.storeEvent('_GET_stream', msg(2));
+
+    expect(await a.getStreamIdForEventId?.(cursor)).toBe('_GET_stream');
+    expect(await b.getStreamIdForEventId?.(cursor)).toBeUndefined();
+    expect(await a.getStreamIdForEventId?.('unknown')).toBeUndefined();
+
+    const send = vi.fn().mockResolvedValue(undefined);
+    expect(await b.replayEventsAfter(cursor, { send })).toBe('');
+    expect(send).not.toHaveBeenCalled();
+    expect(await a.replayEventsAfter(cursor, { send })).toBe('_GET_stream');
+    expect(send).toHaveBeenCalledWith(next, msg(2));
+  });
+});

package/src/__tests__/hasToolContent.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { hasToolContent, mapToolResult } from '../core.js';
+import type {
+  CallToolResult,
+  CompatibilityCallToolResult,
+} from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * `hasToolContent` narrows by reading `.content`, and a value that is not a
+ * tool result has none: the legacy `{ toolResult }` shape, and a pipeline that
+ * resolved to nothing at all (a local tool handler with a missing `return`, or
+ * a middleware that dropped the result). It is a guard, so the answer to
+ * "is this a CallToolResult?" has to be `false`, not a thrown TypeError.
+ *
+ * Both in-repo call sites depend on that answer rather than on a throw:
+ * `mapToolResult` returns the value untouched when the guard says `false`, and
+ * the `tools/call` handler reads `result.isError` only behind it. A throw here
+ * instead replaces whatever the pipeline produced with
+ * `TypeError: Cannot read properties of undefined (reading 'content')`.
+ */
+
+/** Callers reach this through a pipeline result, which the types do not pin. */
+const untyped = (value: unknown): CompatibilityCallToolResult =>
+  value as CompatibilityCallToolResult;
+
+describe('hasToolContent()', () => {
+  it('is true for a CallToolResult, even an empty content array', () => {
+    const result: CallToolResult = { content: [] };
+    expect(hasToolContent(result)).toBe(true);
+  });
+
+  it('is false for the legacy { toolResult } shape, which has no content', () => {
+    const legacy: CompatibilityCallToolResult = {
+      toolResult: { raw: true },
+    };
+    expect(hasToolContent(legacy)).toBe(false);
+  });
+
+  it('is false for a non-object, rather than throwing', () => {
+    expect(hasToolContent(untyped('a string'))).toBe(false);
+    expect(hasToolContent(untyped(42))).toBe(false);
+  });
+
+  for (const [label, value] of [
+    ['undefined', undefined],
+    ['null', null],
+  ] as const) {
+    it(`is false for a ${label} result rather than throwing`, () => {
+      expect(hasToolContent(untyped(value))).toBe(false);
+    });
+
+    it(`mapToolResult returns a ${label} result untouched`, () => {
+      const result = untyped(value);
+      expect(
+        mapToolResult(result, {
+          onText: () => null,
+          onOther: () => null,
+          onStructured: () => undefined,
+        }),
+      ).toBe(result);
+    });
+  }
+});

package/src/__tests__/mapToolResult.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect, vi } from 'vitest';
+import { mapToolResult } from '../core.js';
+import type { ToolResultHandlers } from '../core.js';
+import type {
+  CallToolResult,
+  CompatibilityCallToolResult,
+} from '@modelcontextprotocol/sdk/types.js';
+
+/** Handlers that pass every channel through unchanged. */
+const identity: ToolResultHandlers = {
+  onText: (block) => block,
+  onOther: (block) => block,
+  onStructured: (structured) => structured,
+};
+
+describe('mapToolResult()', () => {
+  it('maps text blocks through onText', () => {
+    const result: CallToolResult = {
+      content: [{ type: 'text', text: 'ssn 123456789' }],
+    };
+
+    const mapped = mapToolResult(result, {
+      ...identity,
+      onText: (block) => ({ ...block, text: '[REDACTED]' }),
+    });
+
+    expect(mapped.content).toEqual([{ type: 'text', text: '[REDACTED]' }]);
+  });
+
+  it('routes non-text blocks through onOther, and null drops the block', () => {
+    const result: CallToolResult = {
+      content: [
+        { type: 'text', text: 'keep' },
+        { type: 'image', data: 'aGk=', mimeType: 'image/png' },
+      ],
+    };
+    const onOther = vi.fn().mockReturnValue(null);
+
+    const mapped = mapToolResult(result, { ...identity, onOther });
+
+    expect(onOther).toHaveBeenCalledWith(
+      expect.objectContaining({ type: 'image' }),
+    );
+    expect(mapped.content).toEqual([{ type: 'text', text: 'keep' }]);
+  });
+
+  it('null from onText drops the block too', () => {
+    const result: CallToolResult = {
+      content: [{ type: 'text', text: 'drop me' }],
+    };
+
+    const mapped = mapToolResult(result, { ...identity, onText: () => null });
+    expect(mapped.content).toEqual([]);
+  });
+
+  it('calls onStructured only when structuredContent is present', () => {
+    const onStructured = vi.fn().mockReturnValue({ ok: true });
+
+    mapToolResult({ content: [] }, { ...identity, onStructured });
+    expect(onStructured).not.toHaveBeenCalled();
+
+    const mapped = mapToolResult(
+      { content: [], structuredContent: { secret: 'x' } },
+      { ...identity, onStructured },
+    );
+    expect(onStructured).toHaveBeenCalledWith({ secret: 'x' });
+    expect(mapped.structuredContent).toEqual({ ok: true });
+  });
+
+  it('undefined from onStructured removes the field', () => {
+    const mapped = mapToolResult(
+      { content: [], structuredContent: { secret: 'x' } },
+      { ...identity, onStructured: () => undefined },
+    );
+    expect(mapped).not.toHaveProperty('structuredContent');
+  });
+
+  it('returns the legacy { toolResult } shape untouched', () => {
+    const legacy: CompatibilityCallToolResult = { toolResult: { raw: true } };
+    const onText = vi.fn();
+
+    expect(mapToolResult(legacy, { ...identity, onText })).toBe(legacy);
+    expect(onText).not.toHaveBeenCalled();
+  });
+
+  it('preserves isError, result _meta, and unknown extra keys', () => {
+    const result: CallToolResult = {
+      content: [],
+      isError: true,
+      _meta: { forwarded: 'deliberately' },
+      vendorKey: 'kept',
+    };
+
+    const mapped = mapToolResult(result, identity);
+    expect(mapped).toMatchObject({
+      isError: true,
+      _meta: { forwarded: 'deliberately' },
+      vendorKey: 'kept',
+    });
+  });
+});

package/src/__tests__/middleware.edge.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from 'vitest';
+import { compose, pipe, type Middleware } from '../middleware.js';
+import { createProxyContext, type ProxyContext } from '../proxyContext.js';
+
+type Req = { value: number };
+type Res = { result: number };
+
+const passthroughNext = async (r: Req): Promise<Res> => ({ result: r.value });
+
+describe('compose() — edge cases', () => {
+  it('rejects (not throws synchronously) when next() is called twice in the same middleware', async () => {
+    let secondCallReturn: unknown;
+    const dbl: Middleware<Req, Res> = async (req, next) => {
+      const first = next(req);
+      secondCallReturn = next(req);
+      await first;
+      return { result: 0 };
+    };
+
+    const pipeline = compose([dbl]);
+    const promise = pipeline({ value: 1 }, passthroughNext);
+
+    expect(secondCallReturn).toBeInstanceOf(Promise);
+    await expect(secondCallReturn as Promise<Res>).rejects.toThrow(
+      'next() called multiple times',
+    );
+    await expect(promise).resolves.toBeDefined();
+  });
+
+  it('rejects on a second next() call even after the first has settled', async () => {
+    let captured: Promise<Res> | undefined;
+    const mw: Middleware<Req, Res> = async (req, next) => {
+      const first = await next(req);
+      captured = next(req);
+      return first;
+    };
+
+    const pipeline = compose([mw]);
+    await pipeline({ value: 1 }, passthroughNext);
+
+    await expect(captured).rejects.toThrow('next() called multiple times');
+  });
+
+  it('does not mutate a frozen middleware array', async () => {
+    const mw: Middleware<Req, Res> = (req, next) =>
+      next({ value: req.value + 1 });
+    const arr = Object.freeze([mw]);
+
+    const pipeline = compose(arr);
+    const result = await pipeline({ value: 2 }, passthroughNext);
+
+    expect(result).toEqual({ result: 3 });
+    expect(arr).toHaveLength(1);
+  });
+
+  it('generates a fresh requestId for each invocation when no context is provided', async () => {
+    const seen: string[] = [];
+    const capture: Middleware<Req, Res> = async (req, next, context) => {
+      seen.push(context.requestId);
+      return next(req);
+    };
+
+    const pipeline = compose([capture]);
+    await pipeline({ value: 1 }, passthroughNext);
+    await pipeline({ value: 1 }, passthroughNext);
+
+    expect(seen).toHaveLength(2);
+    expect(seen[0]).not.toEqual(seen[1]);
+  });
+
+  it('propagates errors thrown from inner-most next through wrappers', async () => {
+    const wrap: Middleware<Req, Res> = async (req, next) => next(req);
+    const pipeline = compose([wrap, wrap, wrap]);
+
+    await expect(
+      pipeline({ value: 0 }, async () => {
+        throw new Error('inner boom');
+      }),
+    ).rejects.toThrow('inner boom');
+  });
+
+  it('passes the same context reference to every middleware', async () => {
+    const refs: ProxyContext[] = [];
+    const capture: Middleware<Req, Res> = async (req, next, context) => {
+      refs.push(context);
+      return next(req);
+    };
+    const ctx = createProxyContext({ requestId: 'fixed-id' });
+
+    await compose([capture, capture, capture])(
+      { value: 1 },
+      passthroughNext,
+      ctx,
+    );
+
+    expect(refs).toHaveLength(3);
+    expect(refs[0]).toBe(ctx);
+    expect(refs[1]).toBe(ctx);
+    expect(refs[2]).toBe(ctx);
+  });
+});
+
+describe('pipe() — edge cases', () => {
+  it('does not mutate the input array (reverse on a copy)', async () => {
+    const a: Middleware<Req, Res> = (req, next) =>
+      next({ value: req.value + 1 });
+    const b: Middleware<Req, Res> = (req, next) =>
+      next({ value: req.value * 2 });
+    const arr = [a, b];
+    const snapshot = [...arr];
+
+    await pipe(arr)({ value: 1 }, passthroughNext);
+
+    expect(arr).toEqual(snapshot);
+  });
+
+  it('accepts a frozen input array', async () => {
+    const a: Middleware<Req, Res> = (req, next) =>
+      next({ value: req.value + 1 });
+    const arr = Object.freeze([a]);
+
+    const result = await pipe(arr)({ value: 1 }, passthroughNext);
+
+    expect(result).toEqual({ result: 2 });
+  });
+});