mcpose 2.1.1 → 3.1.0

package/src/testing.ts

@@ -0,0 +1,174 @@
+/**
+ * Test helpers for mcpose middleware. No test framework imports — works in any env.
+ * @module mcpose/testing
+ */
+import type {
+  CallToolRequest,
+  CallToolResult,
+  ListToolsRequest,
+  ListToolsResult,
+  ListResourcesResult,
+  ListPromptsResult,
+  ReadResourceRequest,
+  ReadResourceResult,
+  Tool,
+  Resource,
+  Prompt,
+  CallToolRequestParams,
+  ReadResourceRequestParams,
+  GetPromptRequestParams,
+  GetPromptResult,
+  ServerCapabilities,
+} from '@modelcontextprotocol/sdk/types.js';
+import { hasToolContent } from './core.js';
+import type {
+  ListToolsMiddleware,
+  ResourceMiddleware,
+  ToolMiddleware,
+} from './core.js';
+import type { BackendClient } from './backendClient.js';
+import { createProxyContext, type ProxyContext } from './proxyContext.js';
+
+/**
+ * Runs a `ToolMiddleware` and narrows result to `CallToolResult`.
+ * Throws if upstream returns legacy `{ toolResult }` shape.
+ *
+ * @example
+ * const result = await runToolMiddleware(mw, req, async () => mockResult);
+ * expect(result.content[0]).toMatchObject({ type: 'text' });
+ */
+export async function runToolMiddleware(
+  mw: ToolMiddleware,
+  req: CallToolRequest,
+  next: (req: CallToolRequest) => Promise<CallToolResult>,
+  context: ProxyContext = createProxyContext(),
+): Promise<CallToolResult> {
+  const result = await mw(req, next, context);
+  if (!hasToolContent(result)) {
+    throw new Error(
+      'runToolMiddleware: middleware returned legacy toolResult shape — expected { content: [...] }',
+    );
+  }
+  return result;
+}
+
+/**
+ * Runs a `ListToolsMiddleware` with a defaulted `ProxyContext`, so tests
+ * do not pass `undefined as never` for the context argument.
+ *
+ * `ListToolsResult` has no legacy variant, so unlike `runToolMiddleware`
+ * there is nothing to narrow and this never throws on shape.
+ */
+export async function runListToolsMiddleware(
+  mw: ListToolsMiddleware,
+  req: ListToolsRequest,
+  next: (req: ListToolsRequest) => Promise<ListToolsResult>,
+  context: ProxyContext = createProxyContext(),
+): Promise<ListToolsResult> {
+  return mw(req, next, context);
+}
+
+/**
+ * Runs a `ResourceMiddleware` with a defaulted `ProxyContext`.
+ *
+ * `ReadResourceResult` has no legacy variant, so unlike
+ * `runToolMiddleware` there is nothing to narrow and this never throws on
+ * shape.
+ */
+export async function runResourceMiddleware(
+  mw: ResourceMiddleware,
+  req: ReadResourceRequest,
+  next: (req: ReadResourceRequest) => Promise<ReadResourceResult>,
+  context: ProxyContext = createProxyContext(),
+): Promise<ReadResourceResult> {
+  return mw(req, next, context);
+}
+
+/** Config for mock backend client. */
+export interface MockBackendClientOptions {
+  /** Default: tools/resources/prompts enabled */
+  capabilities?: ServerCapabilities;
+  /** Default: `[]` */
+  tools?: Tool[];
+  /**
+   * Static result or factory `(params) => result` for `callTool`.
+   * Default: `{ content: [{ type: 'text', text: 'mock response' }] }`
+   */
+  callToolResponse?:
+    CallToolResult | ((params: CallToolRequestParams) => CallToolResult);
+  /** Default: `[]` */
+  resources?: Resource[];
+  /** Default: `{ contents: [{ uri: '', text: 'mock resource' }] }` */
+  readResourceResponse?: ReadResourceResult;
+  /** Default: `[]` */
+  prompts?: Prompt[];
+  /** Default: `{ messages: [] }` */
+  getPromptResponse?: GetPromptResult;
+}
+
+/**
+ * Creates an in-memory `BackendClient` for unit tests. No process/network.
+ *
+ * @example
+ * const backend = createMockBackendClient({
+ *   callToolResponse: { content: [{ type: 'text', text: 'John Doe: 123-45-6789' }] },
+ * });
+ * const pipeline = compose([auditMW, piiToolMW]);
+ * const result = await pipeline(req, (r) => backend.callTool(r.params, undefined));
+ */
+export function createMockBackendClient(
+  options: MockBackendClientOptions = {},
+): BackendClient {
+  const capabilities = options.capabilities ?? {
+    tools: {},
+    resources: {},
+    prompts: {},
+  };
+
+  // Fixtures are cloned per call so a mutating middleware cannot corrupt
+  // them across calls.
+  return {
+    getServerCapabilities: (): ServerCapabilities =>
+      structuredClone(capabilities),
+
+    listTools: async (): Promise<ListToolsResult> => ({
+      tools: structuredClone(options.tools ?? []),
+    }),
+
+    callTool: async (
+      params: CallToolRequestParams,
+    ): Promise<CallToolResult> => {
+      const resp = options.callToolResponse;
+      if (typeof resp === 'function') return resp(params);
+      return structuredClone(
+        resp ?? { content: [{ type: 'text', text: 'mock response' }] },
+      );
+    },
+
+    listResources: async (): Promise<ListResourcesResult> => ({
+      resources: structuredClone(options.resources ?? []),
+    }),
+
+    readResource: async (
+      _params: ReadResourceRequestParams,
+    ): Promise<ReadResourceResult> =>
+      structuredClone(
+        options.readResourceResponse ?? {
+          contents: [{ uri: '', text: 'mock resource' }],
+        },
+      ),
+
+    listPrompts: async (): Promise<ListPromptsResult> => ({
+      prompts: structuredClone(options.prompts ?? []),
+    }),
+
+    getPrompt: async (
+      _params: GetPromptRequestParams,
+    ): Promise<GetPromptResult> =>
+      structuredClone(options.getPromptResponse ?? { messages: [] }),
+
+    setNotificationHandler: () => undefined,
+    removeNotificationHandler: () => undefined,
+    close: async () => undefined,
+  } as unknown as BackendClient;
+}

package/src/version.ts

@@ -0,0 +1,6 @@
+/**
+ * The mcpose library version, inlined so it survives bundling (a
+ * `createRequire('../package.json')` lookup breaks when consumers bundle
+ * the package). Kept in sync with package.json by `version.test.ts`.
+ */
+export const VERSION = '3.1.0';