mcpose 2.0.2 → 3.0.0

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

@@ -0,0 +1,314 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createProxyServer, type ToolMiddleware } from '../core.js';
+import type { BackendClient } from '../backendClient.js';
+import {
+  ErrorCode,
+  PromptListChangedNotificationSchema,
+  ResourceListChangedNotificationSchema,
+  ToolListChangedNotificationSchema,
+  type ServerCapabilities,
+} from '@modelcontextprotocol/sdk/types.js';
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function makeRichBackend(
+  capabilities: ServerCapabilities | undefined,
+): BackendClient & {
+  __notificationHandlers: Map<string, () => Promise<void>>;
+} {
+  const notificationHandlers = new Map<string, () => Promise<void>>();
+  return {
+    getServerCapabilities: vi.fn().mockReturnValue(capabilities),
+    listTools: vi.fn().mockResolvedValue({
+      tools: [
+        {
+          name: 'normal_tool',
+          description: 'n',
+          inputSchema: { type: 'object', properties: {} },
+        },
+      ],
+    }),
+    callTool: vi
+      .fn()
+      .mockResolvedValue({ content: [{ type: 'text', text: 'ok' }] }),
+    listResources: vi.fn().mockResolvedValue({
+      resources: [
+        { name: 'a', uri: 'res://a', mimeType: 'text/plain' },
+        { name: 'b', uri: 'res://b', mimeType: 'text/plain' },
+      ],
+    }),
+    readResource: vi.fn().mockResolvedValue({ contents: [] }),
+    listPrompts: vi.fn().mockResolvedValue({ prompts: [] }),
+    getPrompt: vi.fn().mockResolvedValue({ messages: [] }),
+    setNotificationHandler: vi.fn((schema, handler) => {
+      const method =
+        schema === ToolListChangedNotificationSchema
+          ? 'notifications/tools/list_changed'
+          : schema === PromptListChangedNotificationSchema
+            ? 'notifications/prompts/list_changed'
+            : schema === ResourceListChangedNotificationSchema
+              ? 'notifications/resources/list_changed'
+              : 'unknown';
+      notificationHandlers.set(method, handler as () => Promise<void>);
+    }),
+    removeNotificationHandler: vi.fn(),
+    close: vi.fn().mockResolvedValue(undefined),
+    __notificationHandlers: notificationHandlers,
+  } as unknown as BackendClient & {
+    __notificationHandlers: Map<string, () => Promise<void>>;
+  };
+}
+
+async function invoke(
+  server: ReturnType<typeof createProxyServer>,
+  method: string,
+  params: Record<string, unknown> = {},
+  extra: object = {},
+): Promise<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 }, extra);
+}
+
+// ── name validation ────────────────────────────────────────────────────────
+
+describe('createProxyServer() — name is required and non-blank', () => {
+  // The name is provenance on every audit event and manifest (ADR-0012), so a
+  // blank one is a trail that looks attributed and is not (#122). Rejected at
+  // construction, like a duplicate local tool name.
+  it.each([
+    ['empty', ''],
+    ['whitespace-only', '   '],
+    ['a tab and a newline', '\t\n'],
+  ])('throws on a %s name', (_label, name) => {
+    expect(() => createProxyServer(makeRichBackend({ tools: {} }), { name })) //
+      .toThrow(/name must be a non-empty string/);
+  });
+
+  it('throws when a JS caller omits the name the type requires', () => {
+    expect(() =>
+      createProxyServer(
+        makeRichBackend({ tools: {} }),
+        {} as unknown as { name: string },
+      ),
+    ).toThrow(/name must be a non-empty string/);
+  });
+
+  it('accepts a name that is non-blank once trimmed', () => {
+    expect(() =>
+      createProxyServer(makeRichBackend({ tools: {} }), { name: '  edge  ' }),
+    ).not.toThrow();
+  });
+});
+
+// ── capability mirroring ──────────────────────────────────────────────────
+
+describe('createProxyServer() — capability edge cases', () => {
+  it('throws when the backend is not connected (undefined capabilities)', () => {
+    const backend = makeRichBackend(undefined);
+
+    // A disconnected backend would otherwise produce a proxy that silently
+    // answers nothing — fail loudly instead.
+    expect(() => createProxyServer(backend, { name: 'test-server' })).toThrow(
+      /backend is not connected/,
+    );
+    expect(backend.setNotificationHandler).not.toHaveBeenCalled();
+  });
+
+  it('mirrors tools without listChanged as {} (not {listChanged:true})', async () => {
+    const backend = makeRichBackend({ tools: {} });
+    const server = createProxyServer(backend, { name: 'test-server' });
+
+    const result = (await invoke(server, 'initialize', {
+      protocolVersion: '2025-03-26',
+      capabilities: {},
+      clientInfo: { name: 't', version: '0' },
+    })) as { capabilities: ServerCapabilities };
+
+    expect(result.capabilities.tools).toEqual({});
+    expect(backend.setNotificationHandler).not.toHaveBeenCalled();
+  });
+
+  it('does not register list-changed handlers when upstream lacks listChanged', () => {
+    const backend = makeRichBackend({ tools: {}, resources: {}, prompts: {} });
+
+    createProxyServer(backend, { name: 'test-server' });
+
+    expect(backend.setNotificationHandler).not.toHaveBeenCalled();
+  });
+});
+
+// ── notification fanout multi-proxy ───────────────────────────────────────
+
+describe('createProxyServer() — shared notification bus', () => {
+  it('registers backend handler exactly once for two proxies sharing one backend', () => {
+    const backend = makeRichBackend({ tools: { listChanged: true } });
+
+    createProxyServer(backend, { name: 'test-server' });
+    createProxyServer(backend, { name: 'test-server' });
+
+    const calls = (
+      backend.setNotificationHandler as ReturnType<typeof vi.fn>
+    ).mock.calls.filter(
+      ([schema]) => schema === ToolListChangedNotificationSchema,
+    );
+    expect(calls).toHaveLength(1);
+  });
+
+  it('re-registers handler after all proxies close (bus is dropped)', async () => {
+    const backend = makeRichBackend({ tools: { listChanged: true } });
+
+    const a = createProxyServer(backend, { name: 'test-server' });
+    a.onclose?.();
+
+    // The bus should have been deleted; a fresh proxy registers a new handler.
+    createProxyServer(backend, { name: 'test-server' });
+
+    const calls = (
+      backend.setNotificationHandler as ReturnType<typeof vi.fn>
+    ).mock.calls.filter(
+      ([schema]) => schema === ToolListChangedNotificationSchema,
+    );
+    expect(calls.length).toBeGreaterThanOrEqual(2);
+  });
+});
+
+// ── hidden / passthrough overlap ──────────────────────────────────────────
+
+describe('createProxyServer() — hidden vs passthrough precedence', () => {
+  it('hides a tool that is also in passThroughTools (hidden wins)', async () => {
+    const backend = makeRichBackend({ tools: {} });
+    const server = createProxyServer(backend, {
+      hiddenTools: ['shared_name'],
+      passThroughTools: ['shared_name'],
+      name: 'test-server',
+    });
+
+    await expect(
+      invoke(server, 'tools/call', { name: 'shared_name', arguments: {} }),
+    ).rejects.toMatchObject({ code: ErrorCode.MethodNotFound });
+  });
+
+  it('returns the upstream list reference unchanged when hiddenTools is empty', async () => {
+    const backend = makeRichBackend({ tools: {} });
+    const upstream = {
+      tools: [
+        {
+          name: 't',
+          description: '',
+          inputSchema: { type: 'object', properties: {} },
+        },
+      ],
+    };
+    (backend.listTools as ReturnType<typeof vi.fn>).mockResolvedValue(upstream);
+
+    const server = createProxyServer(backend, {
+      name: 'test-server',
+      hiddenTools: [],
+    });
+    const result = await invoke(server, 'tools/list');
+
+    expect(result).toBe(upstream);
+  });
+});
+
+// ── createRequestOptions branches (asserted via backend args) ─────────────
+
+describe('createProxyServer() — request options shapes', () => {
+  it('passes undefined when neither signal nor progressToken is present', async () => {
+    const backend = makeRichBackend({ tools: {} });
+    const server = createProxyServer(backend, { name: 'test-server' });
+
+    await invoke(server, 'tools/list');
+
+    expect(backend.listTools).toHaveBeenCalledWith({}, undefined);
+  });
+
+  it('passes only { signal } when there is no progressToken', async () => {
+    const backend = makeRichBackend({ tools: {} });
+    const server = createProxyServer(backend, { name: 'test-server' });
+    const controller = new AbortController();
+
+    await invoke(
+      server,
+      'tools/list',
+      {},
+      { signal: controller.signal, requestId: 1 },
+    );
+
+    expect(backend.listTools).toHaveBeenCalledWith(
+      {},
+      { signal: controller.signal },
+    );
+  });
+
+  it('passes undefined when progressToken is present but sendNotification is missing', async () => {
+    const backend = makeRichBackend({ tools: {} });
+    const server = createProxyServer(backend, { name: 'test-server' });
+
+    await invoke(
+      server,
+      'tools/list',
+      {},
+      { _meta: { progressToken: 'p1' }, requestId: 1 },
+    );
+
+    expect(backend.listTools).toHaveBeenCalledWith({}, undefined);
+  });
+
+  it('omits total/message from progress notifications when undefined', async () => {
+    const backend = makeRichBackend({ tools: {} });
+    const sendNotification = vi.fn().mockResolvedValue(undefined);
+
+    vi.mocked(backend.callTool).mockImplementation(async (_p, _s, options) => {
+      options?.onprogress?.({ progress: 1 });
+      return { content: [] };
+    });
+
+    const server = createProxyServer(backend, { name: 'test-server' });
+    await invoke(
+      server,
+      'tools/call',
+      { name: 'normal_tool', arguments: {} },
+      { sendNotification, _meta: { progressToken: 'tok' }, requestId: 1 },
+    );
+
+    expect(sendNotification).toHaveBeenCalledWith({
+      method: 'notifications/progress',
+      params: { progressToken: 'tok', progress: 1 },
+    });
+    const call = sendNotification.mock.calls[0]?.[0] as {
+      params: Record<string, unknown>;
+    };
+    expect('total' in call.params).toBe(false);
+    expect('message' in call.params).toBe(false);
+  });
+});
+
+// ── tool middleware mutation safety ───────────────────────────────────────
+
+describe('createProxyServer() — middleware behavior', () => {
+  it('propagates errors from tool middleware to the caller', async () => {
+    const backend = makeRichBackend({ tools: {} });
+    const failing: ToolMiddleware = async () => {
+      throw new Error('mw failure');
+    };
+    const server = createProxyServer(backend, {
+      name: 'test-server',
+      toolMiddleware: [failing],
+    });
+
+    await expect(
+      invoke(server, 'tools/call', { name: 'normal_tool', arguments: {} }),
+    ).rejects.toThrow('mw failure');
+  });
+});

package/src/__tests__/core.hiddenTools.predicate.test.ts

@@ -0,0 +1,236 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createProxyServer } from '../core.js';
+import { dispatcherAwareBlock } from '../hiddenTools.js';
+import type { BackendClient } from '../backendClient.js';
+import { ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+
+// ── Test helpers ────────────────────────────────────────────────────────────
+
+const TOOLS = ['update_issue', 'search_issues', 'execute_sentry_tool'].map(
+  (name) => ({
+    name,
+    description: name,
+    inputSchema: { type: 'object', properties: {} },
+  }),
+);
+
+function makeMockBackend(): BackendClient {
+  return {
+    getServerCapabilities: vi.fn().mockReturnValue({ tools: {} }),
+    listTools: vi.fn().mockResolvedValue({ tools: TOOLS }),
+    callTool: vi.fn().mockResolvedValue({
+      content: [{ type: 'text', text: 'upstream response' }],
+    }),
+    setNotificationHandler: vi.fn(),
+    removeNotificationHandler: vi.fn(),
+    close: vi.fn().mockResolvedValue(undefined),
+  } as unknown as BackendClient;
+}
+
+/** 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 }, {});
+}
+
+const blockUpdateIssue = () =>
+  dispatcherAwareBlock({
+    tools: ['update_issue'],
+    dispatchers: ['execute_sentry_tool'],
+    argPath: 'name',
+  });
+
+// ── The predicate in the proxy ──────────────────────────────────────────────
+
+describe('createProxyServer() — hiddenTools accepts a predicate', () => {
+  it('filters tools the predicate hides out of tools/list, with undefined args', async () => {
+    const seen: Array<[string, unknown]> = [];
+    const server = createProxyServer(makeMockBackend(), {
+      name: 'test-server',
+      hiddenTools: (name, args) => {
+        seen.push([name, args]);
+        return name === 'update_issue';
+      },
+    });
+
+    const result = (await invokeHandler(server, 'tools/list')) as {
+      tools: { name: string }[];
+    };
+
+    expect(result.tools.map((t) => t.name)).toEqual([
+      'search_issues',
+      'execute_sentry_tool',
+    ]);
+    expect(seen.every(([, args]) => args === undefined)).toBe(true);
+  });
+
+  it('stays authoritative after listToolsMiddleware: a re-added hidden tool is filtered again', async () => {
+    const server = createProxyServer(makeMockBackend(), {
+      name: 'test-server',
+      hiddenTools: blockUpdateIssue(),
+      listToolsMiddleware: [
+        async (req, next) => {
+          const result = await next(req);
+          return {
+            ...result,
+            tools: [
+              ...result.tools,
+              {
+                name: 'update_issue',
+                description: 'Reintroduced',
+                inputSchema: { type: 'object', properties: {} },
+              },
+            ],
+          };
+        },
+      ],
+    });
+
+    const result = (await invokeHandler(server, 'tools/list')) as {
+      tools: { name: string }[];
+    };
+    expect(result.tools.map((t) => t.name)).not.toContain('update_issue');
+  });
+
+  it('rejects a call the predicate hides with TOOL_HIDDEN, upstream never called', async () => {
+    const backend = makeMockBackend();
+    const server = createProxyServer(backend, {
+      name: 'test-server',
+      hiddenTools: blockUpdateIssue(),
+    });
+
+    await expect(
+      invokeHandler(server, 'tools/call', {
+        name: 'update_issue',
+        arguments: {},
+      }),
+    ).rejects.toMatchObject({
+      code: ErrorCode.MethodNotFound,
+      data: { rejectionReason: 'TOOL_HIDDEN' },
+    });
+    expect(backend.callTool).not.toHaveBeenCalled();
+  });
+
+  it('passes an empty object, not undefined, when the client sent no arguments', async () => {
+    const seen: unknown[] = [];
+    const server = createProxyServer(makeMockBackend(), {
+      name: 'test-server',
+      hiddenTools: (_name, args) => {
+        seen.push(args);
+        return false;
+      },
+    });
+
+    await invokeHandler(server, 'tools/call', { name: 'search_issues' });
+    expect(seen).toEqual([{}]);
+  });
+});
+
+// ── dispatcherAwareBlock through the proxy ──────────────────────────────────
+
+describe('createProxyServer() — dispatcherAwareBlock closes the dispatcher bypass', () => {
+  it('blocks a dispatcher call targeting a hidden tool, upstream never called', async () => {
+    const backend = makeMockBackend();
+    const server = createProxyServer(backend, {
+      name: 'test-server',
+      hiddenTools: blockUpdateIssue(),
+    });
+
+    await expect(
+      invokeHandler(server, 'tools/call', {
+        name: 'execute_sentry_tool',
+        arguments: { name: 'update_issue', arguments: {} },
+      }),
+    ).rejects.toMatchObject({ data: { rejectionReason: 'TOOL_HIDDEN' } });
+    expect(backend.callTool).not.toHaveBeenCalled();
+  });
+
+  it('keeps the dispatcher listed and callable with a permitted target', async () => {
+    const backend = makeMockBackend();
+    const server = createProxyServer(backend, {
+      name: 'test-server',
+      hiddenTools: blockUpdateIssue(),
+    });
+
+    const listed = (await invokeHandler(server, 'tools/list')) as {
+      tools: { name: string }[];
+    };
+    expect(listed.tools.map((t) => t.name)).toContain('execute_sentry_tool');
+
+    const result = await invokeHandler(server, 'tools/call', {
+      name: 'execute_sentry_tool',
+      arguments: { name: 'search_issues', arguments: {} },
+    });
+    expect(result).toMatchObject({
+      content: [{ type: 'text', text: 'upstream response' }],
+    });
+  });
+});
+
+// ── dispatcherAwareBlock fail-closed cases ──────────────────────────────────
+
+describe('dispatcherAwareBlock() — fails closed on malformed dispatcher calls', () => {
+  const predicate = dispatcherAwareBlock({
+    tools: ['update_issue'],
+    dispatchers: ['dispatch'],
+    argPath: 'request.tool.name',
+  });
+
+  it.each([
+    ['missing target', {}],
+    ['null target', { request: { tool: { name: null } } }],
+    ['numeric target', { request: { tool: { name: 42 } } }],
+    ['object target', { request: { tool: { name: { nested: true } } } }],
+    ['array target', { request: { tool: { name: ['update_issue'] } } }],
+    ['path through a non-object', { request: 'not-an-object' }],
+    ['path through an array', { request: [{ tool: { name: 'x' } }] }],
+  ])('blocks a dispatcher call with %s', (_label, args) => {
+    expect(predicate('dispatch', args as Record<string, unknown>)).toBe(true);
+  });
+
+  it('blocks a dispatcher call with no arguments at all (call phase = empty object)', () => {
+    expect(predicate('dispatch', {})).toBe(true);
+  });
+
+  it('does not resolve prototype keys such as constructor', () => {
+    const proto = dispatcherAwareBlock({
+      tools: ['update_issue'],
+      dispatchers: ['dispatch'],
+      argPath: 'constructor',
+    });
+    expect(proto('dispatch', {})).toBe(true);
+  });
+
+  it('allows a dispatcher call with a permitted string target', () => {
+    expect(
+      predicate('dispatch', { request: { tool: { name: 'search_issues' } } }),
+    ).toBe(false);
+  });
+
+  it('blocks the hidden tool directly regardless of phase', () => {
+    expect(predicate('update_issue', undefined)).toBe(true);
+    expect(predicate('update_issue', {})).toBe(true);
+  });
+
+  it('keeps the dispatcher visible during the list phase', () => {
+    expect(predicate('dispatch', undefined)).toBe(false);
+  });
+
+  it('ignores non-dispatcher, non-hidden tools', () => {
+    expect(predicate('search_issues', { anything: 1 })).toBe(false);
+  });
+});