mcpose 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amir Gorji
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# mcpose
+
+Composable middleware proxy for MCP servers.
+
+---
+
+## Background
+
+mcpose was extracted from [`financial-elastic-mcp-server`](https://github.com/amir-gorji/financial-elastic-mcp-server), an Elasticsearch MCP server built for financial institutions that needed PII redaction and audit logging on every tool call. Those cross-cutting concerns were originally hardcoded into a single server. mcpose lifts that pattern into a reusable, composable middleware layer that can wrap **any** upstream MCP server.
+
+---
+
+## Concept
+
+mcpose is a **transparent proxy**: it sits between an LLM client and an upstream MCP server, mirroring the upstream's tool, resource, and prompt lists while routing all calls through a configurable middleware pipeline. The client sees a normal MCP server; the upstream sees a normal MCP client. mcpose is the layer in between — controlling visibility and applying transformations without either side knowing.
+
+---
+
+## Install
+
+```bash
+npm install mcpose
+```
+
+**Peer dependency** — must be installed separately:
+
+```bash
+npm install @modelcontextprotocol/sdk@>=1.0.0
+```
+
+---
+
+## Quick Start
+
+```ts
+import { createBackendClient, startProxy } from 'mcpose';
+import type { ToolMiddleware } from 'mcpose';
+
+// 1. Connect to the upstream MCP server (stdio)
+const backend = await createBackendClient({
+  command: 'node',
+  args: ['/path/to/backend-server.mjs'],
+});
+
+// 2. Define middleware
+const loggingMW: ToolMiddleware = async (req, next) => {
+  console.error(`→ ${req.params.name}`);
+  const result = await next(req);
+  console.error(`← ${req.params.name} done`);
+  return result;
+};
+
+// 3. Start the proxy on stdio
+await startProxy(backend, {
+  toolMiddleware: [loggingMW],
+});
+```
+
+---
+
+## Proxy model
+
+```
+┌──────────────┐        ┌────────────────────────────────┐        ┌────────────────────┐
+│  LLM client  │ ◄────► │  mcpose                        │ ◄────► │  Upstream MCP      │
+│  (Claude,    │        │  · visibility filters          │        │  server            │
+│   Cursor…)   │        │  · middleware pipelines        │        │  (stdio or HTTP)   │
+└──────────────┘        └────────────────────────────────┘        └────────────────────┘
+```
+
+For each tool or resource, mcpose picks one of three routing paths:
+
+| Path | Option | Behavior |
+|---|---|---|
+| **Hidden** | `hiddenTools` / `hiddenResources` | Omitted from list responses; rejected with an error at call time |
+| **Pass-through** | `passThroughTools` / `passThroughResources` | Forwarded raw to upstream — all middleware skipped |
+| **Middleware** | everything else | Routed through the full `toolMiddleware` / `resourceMiddleware` pipeline |
+
+Prompts are always forwarded as-is — no filtering or middleware.
+
+---
+
+## Middleware model
+
+Middleware follows the **onion model**: outer layers run code before *and* after inner layers. Each middleware receives the request and a `next` function to invoke the rest of the pipeline.
+
+```
+  request ──►
+             ┌──────────────────────────────────────────┐
+             │  outerMW  (enter)                        │
+             │  ┌────────────────────────────────────┐  │
+             │  │  innerMW  (enter)                  │  │
+             │  │  ┌──────────────────────────────┐  │  │
+             │  │  │  upstream call               │  │  │
+             │  │  └──────────────────────────────┘  │  │
+             │  │  innerMW  (exit) ◄── response      │  │
+             │  └────────────────────────────────────┘  │
+             │  outerMW  (exit) ◄── response            │
+             └──────────────────────────────────────────┘
+  ◄── response
+```
+
+**Array order in `ProxyOptions`** uses **response-processing order**: the first element processes the response *first* (innermost layer). `ProxyOptions` calls `pipe()` internally — no need to wrap manually. To guarantee audit never sees raw PII:
+
+```ts
+toolMiddleware: [piiMW, auditMW]
+// Execution:
+// 1. auditMW enter  → capture startTime         (outermost)
+// 2. piiMW enter    → transform request
+// 3. upstream call
+// 4. piiMW exit     → redact PII from response  (processes response first)
+// 5. auditMW exit   → log already-clean data    (processes response last)
+```
+
+`compose([outerMW, innerMW])` uses the **opposite** (outermost-first) convention — `ProxyOptions` arrays are **not** interchangeable with `compose()` arguments.
+
+A middleware can **short-circuit** by returning without calling `next`, or **handle upstream errors** by wrapping `await next(req)` in a try/catch.
+
+---
+
+## API Reference
+
+### `Middleware<Req, Res>` · `ToolMiddleware` · `ResourceMiddleware` · `compose()`
+
+```ts
+type Middleware<Req, Res> = (
+  req: Req,
+  next: (req: Req) => Promise<Res>,
+) => Promise<Res>;
+
+// Convenience aliases for the two pipeline types:
+type ToolMiddleware     = Middleware<CallToolRequest, CompatibilityCallToolResult>;
+type ResourceMiddleware = Middleware<ReadResourceRequest, ReadResourceResult>;
+
+function compose<Req, Res>(
+  middlewares: ReadonlyArray<Middleware<Req, Res>>,
+): Middleware<Req, Res>;
+
+// Type guard — narrows CompatibilityCallToolResult to CallToolResult
+// (safe access to .content and .isError without casts):
+function hasToolContent(r: CompatibilityCallToolResult): r is CallToolResult;
+```
+
+`compose` takes an array in **outermost-first** order. Use `hasToolContent` in middleware implementations before accessing `.content` or `.isError`, since `CompatibilityCallToolResult` also covers the legacy `{ toolResult }` shape.
+
+---
+
+### `BackendConfig` · `createBackendClient()`
+
+```ts
+interface BackendConfig {
+  command?: string;   // Executable to spawn for stdio transport (e.g., "node")
+  args?:    string[]; // Arguments for the spawned process
+  url?:     string;   // HTTP endpoint of a running MCP server (takes precedence over stdio)
+}
+
+async function createBackendClient(config: BackendConfig): Promise<BackendClient>;
+```
+
+`BackendClient` is an alias for the SDK `Client`. Throws if neither `command` nor `url` is provided, or if the connection fails.
+
+---
+
+### `ProxyOptions` · `startProxy()` · `createProxyServer()`
+
+```ts
+interface ProxyOptions {
+  toolMiddleware?:       ReadonlyArray<ToolMiddleware>;
+  resourceMiddleware?:   ReadonlyArray<ResourceMiddleware>;
+  passThroughTools?:     ReadonlyArray<string>;
+  passThroughResources?: ReadonlyArray<string>;
+  hiddenTools?:          ReadonlyArray<string>;
+  hiddenResources?:      ReadonlyArray<string>;
+}
+
+async function startProxy(backend: BackendClient, options?: ProxyOptions): Promise<void>;
+function createProxyServer(backend: BackendClient, options?: ProxyOptions): Server;
+```
+
+| Option | Description |
+|---|---|
+| `toolMiddleware` | Middleware stack for tool calls, in response-processing order (first element processes response first). |
+| `resourceMiddleware` | Middleware stack for resource reads, in response-processing order. |
+| `passThroughTools` | Tool names forwarded raw to upstream — middleware skipped entirely. |
+| `passThroughResources` | Resource URIs forwarded raw to upstream — middleware skipped entirely. |
+| `hiddenTools` | Tool names removed from `list_tools` **and** rejected at call time with `MethodNotFound`. |
+| `hiddenResources` | Resource URIs removed from `list_resources` **and** rejected at call time with `InvalidRequest`. |
+
+`startProxy` connects the proxy to a `StdioServerTransport`. `createProxyServer` returns the configured `Server` without connecting — useful for testing request handlers without a live transport.
+
+---
+
+## Recipe: PII redaction
+
+The origin use case for mcpose: a financial-grade MCP server where every Elasticsearch tool response must be scrubbed of PII before it reaches the LLM or the audit log.
+
+Use a factory to keep middleware configurable and testable:
+
+```ts
+import { hasToolContent } from 'mcpose';
+import type { ToolMiddleware } from 'mcpose';
+
+function createPiiMiddleware(patterns: RegExp[]): ToolMiddleware {
+  return async (req, next) => {
+    const result = await next(req);
+    if (!hasToolContent(result)) return result;
+    return {
+      ...result,
+      content: result.content.map((item) =>
+        item.type === 'text'
+          ? { ...item, text: redactPii(item.text, patterns) }
+          : item,
+      ),
+    };
+  };
+}
+
+function redactPii(text: string, patterns: RegExp[]): string {
+  return patterns.reduce((t, re) => t.replace(re, '[REDACTED]'), text);
+}
+```
+
+Stack it with audit middleware — PII first in the array so audit always sees clean data:
+
+```ts
+await startProxy(backend, {
+  toolMiddleware: [
+    createPiiMiddleware([/\b\d{9}\b/g, /[A-Z]{2}\d{6}/g]), // SSNs, account numbers
+    createAuditMiddleware({ destination: auditLog }),
+  ],
+});
+```
+
+The array order guarantees: PII is redacted *before* the audit layer ever sees the response. No raw PII reaches a log, satisfying financial regulatory requirements.
+
+> **Reference implementation:** [`elastic-pii-proxy`](https://github.com/amir-gorji/elastic-pii-proxy) is a production example of this pattern — an Elasticsearch MCP proxy that uses mcpose with a PII redaction middleware and an audit middleware to serve financial data safely to LLM agents.
+
+---
+
+## Roadmap
+
+- [ ] **HTTP/SSE server transport** — currently the proxy emits only a stdio server; add a streamable HTTP/SSE server-side transport so mcpose can front HTTP-based clients without a subprocess wrapper
+- [ ] **ATXP protocol support** — enable MCP monetization by implementing the ATXP (Agent Transaction Protocol) standard, letting tool providers attach pricing and billing metadata to responses
+
+---
+
+## License
+
+MIT

package/dist/backendClient.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Factory for connecting to the backend MCP server.
+ *
+ * Supports two transport modes:
+ *  - **stdio** (default): spawns the backend server as a child process.
+ *  - **HTTP/SSE**: connects to an already-running HTTP MCP server.
+ *
+ * Returns a connected `@modelcontextprotocol/sdk` Client, which exposes the
+ * full MCP protocol surface (listTools, callTool, listResources, readResource,
+ * listPrompts, getPrompt) with exact MCP type fidelity — important for a
+ * transparent proxy that must not transform protocol shapes.
+ *
+ * @module
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+/** Connection options for the backend MCP server. */
+export interface BackendConfig {
+    /** Shell command to spawn the backend server (e.g., `"node"`). Required when not using `url`. */
+    command?: string;
+    /** Arguments passed to the command (e.g., `["/path/to/server.mjs"]`). */
+    args?: string[];
+    /** HTTP/SSE URL of an already-running backend server. Takes precedence over stdio when set. */
+    url?: string;
+}
+export type BackendClient = Client;
+/**
+ * Creates and connects an MCP client to the backend server.
+ *
+ * @param config - Backend connection details (stdio or HTTP).
+ * @returns A connected MCP SDK Client ready for tool/resource/prompt calls.
+ * @throws If neither `command` nor `url` is provided, or if the connection fails.
+ */
+export declare function createBackendClient(config: BackendConfig): Promise<BackendClient>;
+//# sourceMappingURL=backendClient.d.ts.map

package/dist/backendClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backendClient.d.ts","sourceRoot":"","sources":["../src/backendClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAInE,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,+FAA+F;IAC/F,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAEnC;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,aAAa,CAAC,CAqBxB"}

package/dist/backendClient.js

@@ -0,0 +1,39 @@
+/**
+ * Factory for connecting to the backend MCP server.
+ *
+ * Supports two transport modes:
+ *  - **stdio** (default): spawns the backend server as a child process.
+ *  - **HTTP/SSE**: connects to an already-running HTTP MCP server.
+ *
+ * Returns a connected `@modelcontextprotocol/sdk` Client, which exposes the
+ * full MCP protocol surface (listTools, callTool, listResources, readResource,
+ * listPrompts, getPrompt) with exact MCP type fidelity — important for a
+ * transparent proxy that must not transform protocol shapes.
+ *
+ * @module
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+/**
+ * Creates and connects an MCP client to the backend server.
+ *
+ * @param config - Backend connection details (stdio or HTTP).
+ * @returns A connected MCP SDK Client ready for tool/resource/prompt calls.
+ * @throws If neither `command` nor `url` is provided, or if the connection fails.
+ */
+export async function createBackendClient(config) {
+    if (!config.command && !config.url) {
+        throw new Error('mcpose: either command or url must be provided in BackendConfig');
+    }
+    const client = new Client({ name: 'mcpose-backend', version: '1.0.0' }, { capabilities: {} });
+    const transport = config.url
+        ? new StreamableHTTPClientTransport(new URL(config.url))
+        : new StdioClientTransport({
+            command: config.command,
+            args: config.args ?? [],
+        });
+    await client.connect(transport);
+    return client;
+}
+//# sourceMappingURL=backendClient.js.map

package/dist/backendClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backendClient.js","sourceRoot":"","sources":["../src/backendClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AAcnG;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAqB;IAErB,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,iEAAiE,CAClE,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,EAC5C,EAAE,YAAY,EAAE,EAAE,EAAE,CACrB,CAAC;IAEF,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG;QAC1B,CAAC,CAAC,IAAI,6BAA6B,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxD,CAAC,CAAC,IAAI,oBAAoB,CAAC;YACvB,OAAO,EAAE,MAAM,CAAC,OAAQ;YACxB,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,EAAE;SACxB,CAAC,CAAC;IAEP,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/core.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Generic MCP proxy core.
+ *
+ * Wires an MCP server (exposed to the LLM) to an upstream MCP client,
+ * applying composed middleware pipelines to tool calls and resource reads.
+ *
+ * @module
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { type CallToolRequest, type CallToolResult, type CompatibilityCallToolResult, type ReadResourceRequest, type ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
+import { type Middleware } from './middleware.js';
+import type { BackendClient } from './backendClient.js';
+/**
+ * Middleware for MCP tool calls.
+ *
+ * Uses `CompatibilityCallToolResult` because `Client.callTool()` returns a
+ * union that includes the legacy `{ toolResult }` shape (protocol 2024-10-07).
+ * Middleware implementations should narrow with `hasToolContent(result)` before
+ * accessing `.content` or `.isError`.
+ */
+export type ToolMiddleware = Middleware<CallToolRequest, CompatibilityCallToolResult>;
+/** Middleware for MCP resource reads. */
+export type ResourceMiddleware = Middleware<ReadResourceRequest, ReadResourceResult>;
+/**
+ * Type guard that narrows a {@link CompatibilityCallToolResult} to the modern
+ * {@link CallToolResult} shape (i.e. the result has a `content` array).
+ *
+ * Use this in middleware implementations to safely access `.content` and
+ * `.isError` without casts, since both union members carry an index signature
+ * (`[x: string]: unknown`) that would otherwise make property access `unknown`.
+ */
+export declare function hasToolContent(r: CompatibilityCallToolResult): r is CallToolResult;
+/** Options for the proxy server. */
+export interface ProxyOptions {
+    /**
+     * Ordered middleware stack for tool calls in response-processing order.
+     * The first element processes the response first (innermost layer).
+     * `pipe()` is called internally — no need to wrap manually.
+     *
+     * @example
+     * toolMiddleware: [piiMW, auditMW]  // pii redacts first, audit logs clean data
+     */
+    toolMiddleware?: ReadonlyArray<ToolMiddleware>;
+    /**
+     * Ordered middleware stack for resource reads in response-processing order.
+     * The first element processes the response first (innermost layer).
+     */
+    resourceMiddleware?: ReadonlyArray<ResourceMiddleware>;
+    /** Tool names that bypass all middleware — raw upstream response forwarded as-is. */
+    passThroughTools?: ReadonlyArray<string>;
+    /** Resource URIs that bypass all middleware — raw upstream response forwarded as-is. */
+    passThroughResources?: ReadonlyArray<string>;
+    /** Tool names hidden from list_tools AND rejected at runtime with MethodNotFound. */
+    hiddenTools?: ReadonlyArray<string>;
+    /** Resource URIs hidden from list_resources AND rejected at runtime with InvalidRequest. */
+    hiddenResources?: ReadonlyArray<string>;
+}
+/**
+ * Creates and wires a proxy MCP server without connecting it to a transport.
+ *
+ * Mirrors the upstream's tool/resource/prompt list and registers request
+ * handlers that route through the provided middleware pipelines. Prompts are
+ * forwarded as-is (no middleware applied).
+ *
+ * Separating creation from connection makes the server fully testable: tests
+ * can call `createProxyServer(mockUpstream, options)` and inspect or invoke
+ * the registered handlers without spawning a stdio transport.
+ *
+ * @param upstream - Connected (or mock) upstream MCP client.
+ * @param options  - Optional middleware stacks for tools and resources.
+ * @returns A configured {@link Server} that is ready to be connected.
+ */
+export declare function createProxyServer(backend: BackendClient, options?: ProxyOptions): Server;
+/**
+ * Starts the proxy MCP server on stdio.
+ *
+ * Convenience wrapper that calls {@link createProxyServer} then connects the
+ * result to a `StdioServerTransport`. Use `createProxyServer` directly when
+ * you need a testable handle to the configured server.
+ *
+ * @param upstream - Connected upstream MCP client.
+ * @param options  - Optional middleware stacks for tools and resources.
+ */
+export declare function startProxy(backend: BackendClient, options?: ProxyOptions): Promise<void>;
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAEnE,OAAO,EASL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,2BAA2B,EAChC,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,CACrC,eAAe,EACf,2BAA2B,CAC5B,CAAC;AAEF,yCAAyC;AACzC,MAAM,MAAM,kBAAkB,GAAG,UAAU,CACzC,mBAAmB,EACnB,kBAAkB,CACnB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,2BAA2B,GAC7B,CAAC,IAAI,cAAc,CAErB;AAED,oCAAoC;AACpC,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAE/C;;;OAGG;IACH,kBAAkB,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAEvD,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAEzC,wFAAwF;IACxF,oBAAoB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAE7C,qFAAqF;IACrF,WAAW,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAEpC,4FAA4F;IAC5F,eAAe,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACzC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,aAAa,EACtB,OAAO,GAAE,YAAiB,GACzB,MAAM,CAoER;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,aAAa,EACtB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/core.js

@@ -0,0 +1,105 @@
+/**
+ * Generic MCP proxy core.
+ *
+ * Wires an MCP server (exposed to the LLM) to an upstream MCP client,
+ * applying composed middleware pipelines to tool calls and resource reads.
+ *
+ * @module
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { pipe } from './middleware.js';
+/**
+ * Type guard that narrows a {@link CompatibilityCallToolResult} to the modern
+ * {@link CallToolResult} shape (i.e. the result has a `content` array).
+ *
+ * Use this in middleware implementations to safely access `.content` and
+ * `.isError` without casts, since both union members carry an index signature
+ * (`[x: string]: unknown`) that would otherwise make property access `unknown`.
+ */
+export function hasToolContent(r) {
+    return Array.isArray(r.content);
+}
+/**
+ * Creates and wires a proxy MCP server without connecting it to a transport.
+ *
+ * Mirrors the upstream's tool/resource/prompt list and registers request
+ * handlers that route through the provided middleware pipelines. Prompts are
+ * forwarded as-is (no middleware applied).
+ *
+ * Separating creation from connection makes the server fully testable: tests
+ * can call `createProxyServer(mockUpstream, options)` and inspect or invoke
+ * the registered handlers without spawning a stdio transport.
+ *
+ * @param upstream - Connected (or mock) upstream MCP client.
+ * @param options  - Optional middleware stacks for tools and resources.
+ * @returns A configured {@link Server} that is ready to be connected.
+ */
+export function createProxyServer(backend, options = {}) {
+    const toolPipeline = pipe(options.toolMiddleware ?? []);
+    const resourcePipeline = pipe(options.resourceMiddleware ?? []);
+    const hiddenToolSet = new Set(options.hiddenTools ?? []);
+    const passThroughToolSet = new Set(options.passThroughTools ?? []);
+    const hiddenResourceSet = new Set(options.hiddenResources ?? []);
+    const passThroughResourceSet = new Set(options.passThroughResources ?? []);
+    // NOTE: Using the low-level Server intentionally — a transparent proxy must
+    // intercept list_tools / list_resources generically without knowing tool names
+    // upfront. McpServer.tool() requires pre-registering each tool by name, which
+    // breaks dynamic forwarding. The SDK explicitly carves out this pattern:
+    // "Only use Server for advanced use cases."
+    const server = new Server({ name: 'mcpose', version: '1.0.0' }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+    // ── Tool handlers ──────────────────────────────────────────────────────────
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const result = await backend.listTools();
+        if (!hiddenToolSet.size)
+            return result;
+        return { ...result, tools: result.tools.filter((t) => !hiddenToolSet.has(t.name)) };
+    });
+    server.setRequestHandler(CallToolRequestSchema, (req) => {
+        const name = req.params.name;
+        if (hiddenToolSet.has(name)) {
+            throw new McpError(ErrorCode.MethodNotFound, `Tool not found: ${name}`);
+        }
+        if (passThroughToolSet.has(name)) {
+            return backend.callTool(req.params, undefined);
+        }
+        return toolPipeline(req, (r) => backend.callTool(r.params, undefined));
+    });
+    // ── Resource handlers ──────────────────────────────────────────────────────
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        const result = await backend.listResources();
+        if (!hiddenResourceSet.size)
+            return result;
+        return { ...result, resources: result.resources.filter((r) => !hiddenResourceSet.has(r.uri)) };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, (req) => {
+        const uri = req.params.uri;
+        if (hiddenResourceSet.has(uri)) {
+            throw new McpError(ErrorCode.InvalidRequest, `Resource not found: ${uri}`);
+        }
+        if (passThroughResourceSet.has(uri)) {
+            return backend.readResource(req.params);
+        }
+        return resourcePipeline(req, (r) => backend.readResource(r.params));
+    });
+    // ── Prompt handlers (pass-through) ────────────────────────────────────────
+    server.setRequestHandler(ListPromptsRequestSchema, () => backend.listPrompts());
+    server.setRequestHandler(GetPromptRequestSchema, (req) => backend.getPrompt(req.params));
+    return server;
+}
+/**
+ * Starts the proxy MCP server on stdio.
+ *
+ * Convenience wrapper that calls {@link createProxyServer} then connects the
+ * result to a `StdioServerTransport`. Use `createProxyServer` directly when
+ * you need a testable handle to the configured server.
+ *
+ * @param upstream - Connected upstream MCP client.
+ * @param options  - Optional middleware stacks for tools and resources.
+ */
+export async function startProxy(backend, options = {}) {
+    const server = createProxyServer(backend, options);
+    await server.connect(new StdioServerTransport());
+}
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { Middleware } from './middleware.js';
+export { compose } from './middleware.js';
+export type { BackendConfig, BackendClient } from './backendClient.js';
+export { createBackendClient } from './backendClient.js';
+export type { ProxyOptions, ToolMiddleware, ResourceMiddleware, } from './core.js';
+export { hasToolContent, createProxyServer, startProxy } from './core.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE1C,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,YAAY,EACV,YAAY,EACZ,cAAc,EACd,kBAAkB,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { compose } from './middleware.js';
+export { createBackendClient } from './backendClient.js';
+export { hasToolContent, createProxyServer, startProxy } from './core.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAG1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAOzD,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC"}

package/dist/middleware.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Generic Koa-style middleware composition for MCP request/response pipelines.
+ *
+ * A middleware is a pure function:
+ *   (req, next) => Promise<Res>
+ *
+ * Calling `next(req)` passes control to the next middleware in the chain.
+ * The innermost `next` is the actual upstream call. Middlewares wrap it like
+ * an onion: outer layers execute code before AND after inner layers.
+ *
+ * Execution order with `pipe([piiMW, auditMW])` (or equivalently `compose([auditMW, piiMW])`):
+ *   1. auditMW enter  → capture startTime
+ *   2. piiMW enter    → call next
+ *   3. upstream call  → raw response
+ *   4. piiMW exit     → redact PII
+ *   5. auditMW exit   → log clean result (never logs raw PII)
+ *
+ * @module
+ */
+/**
+ * A single middleware unit. Receives a request and a `next` function to
+ * call the remainder of the pipeline. May transform the request before
+ * calling `next` or transform the response after.
+ *
+ * @typeParam Req - Request type (e.g., `CallToolRequest`)
+ * @typeParam Res - Response type (e.g., `CallToolResult`)
+ */
+export type Middleware<Req, Res> = (req: Req, next: (req: Req) => Promise<Res>) => Promise<Res>;
+/**
+ * Composes an ordered array of middlewares into a single middleware using the
+ * onion (Koa-style) model. The first middleware is the outermost layer.
+ *
+ * The returned function accepts the initial request and an innermost `next`
+ * (typically the upstream I/O call).
+ *
+ * @param middlewares - Ordered list of middlewares, outermost first.
+ * @returns A single composed middleware.
+ *
+ * @example
+ * ```ts
+ * const pipeline = compose([auditMW, piiMW]);
+ * const result = await pipeline(req, (r) => upstream.callTool(r.params));
+ * ```
+ */
+export declare function compose<Req, Res>(middlewares: ReadonlyArray<Middleware<Req, Res>>): Middleware<Req, Res>;
+/**
+ * Composes middlewares in response-processing order (internal helper used by mcpose core).
+ *
+ * The first element processes the response first — it is the innermost layer.
+ * `pipe([piiMW, auditMW])` expresses "pii redacts first, then audit logs the clean result",
+ * which is equivalent to `compose([auditMW, piiMW])` (outermost-first).
+ *
+ * This is an internal utility. Consumers pass plain arrays to `ProxyOptions` which
+ * calls `pipe()` internally — there is no need to call `pipe()` directly.
+ *
+ * Equivalent to `compose([...middlewares].reverse())`.
+ *
+ * @param middlewares - Middlewares in response-processing order (first processes response first).
+ * @returns A single composed middleware.
+ */
+export declare function pipe<Req, Res>(middlewares: ReadonlyArray<Middleware<Req, Res>>): Middleware<Req, Res>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,CAAC,GAAG,EAAE,GAAG,IAAI,CACjC,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,KAC7B,OAAO,CAAC,GAAG,CAAC,CAAC;AAElB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAC9B,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,GAC/C,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAkBtB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,GAAG,EAC3B,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,GAC/C,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAEtB"}

package/dist/middleware.js

@@ -0,0 +1,68 @@
+/**
+ * Generic Koa-style middleware composition for MCP request/response pipelines.
+ *
+ * A middleware is a pure function:
+ *   (req, next) => Promise<Res>
+ *
+ * Calling `next(req)` passes control to the next middleware in the chain.
+ * The innermost `next` is the actual upstream call. Middlewares wrap it like
+ * an onion: outer layers execute code before AND after inner layers.
+ *
+ * Execution order with `pipe([piiMW, auditMW])` (or equivalently `compose([auditMW, piiMW])`):
+ *   1. auditMW enter  → capture startTime
+ *   2. piiMW enter    → call next
+ *   3. upstream call  → raw response
+ *   4. piiMW exit     → redact PII
+ *   5. auditMW exit   → log clean result (never logs raw PII)
+ *
+ * @module
+ */
+/**
+ * Composes an ordered array of middlewares into a single middleware using the
+ * onion (Koa-style) model. The first middleware is the outermost layer.
+ *
+ * The returned function accepts the initial request and an innermost `next`
+ * (typically the upstream I/O call).
+ *
+ * @param middlewares - Ordered list of middlewares, outermost first.
+ * @returns A single composed middleware.
+ *
+ * @example
+ * ```ts
+ * const pipeline = compose([auditMW, piiMW]);
+ * const result = await pipeline(req, (r) => upstream.callTool(r.params));
+ * ```
+ */
+export function compose(middlewares) {
+    return (req, next) => {
+        let index = -1;
+        const dispatch = (i, currentReq) => {
+            if (i <= index) {
+                return Promise.reject(new Error('next() called multiple times'));
+            }
+            index = i;
+            const fn = i < middlewares.length ? middlewares[i] : (_r, n) => next(_r);
+            return Promise.resolve(fn(currentReq, (r) => dispatch(i + 1, r)));
+        };
+        return dispatch(0, req);
+    };
+}
+/**
+ * Composes middlewares in response-processing order (internal helper used by mcpose core).
+ *
+ * The first element processes the response first — it is the innermost layer.
+ * `pipe([piiMW, auditMW])` expresses "pii redacts first, then audit logs the clean result",
+ * which is equivalent to `compose([auditMW, piiMW])` (outermost-first).
+ *
+ * This is an internal utility. Consumers pass plain arrays to `ProxyOptions` which
+ * calls `pipe()` internally — there is no need to call `pipe()` directly.
+ *
+ * Equivalent to `compose([...middlewares].reverse())`.
+ *
+ * @param middlewares - Middlewares in response-processing order (first processes response first).
+ * @returns A single composed middleware.
+ */
+export function pipe(middlewares) {
+    return compose([...middlewares].reverse());
+}
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAeH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,OAAO,CACrB,WAAgD;IAEhD,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;QACnB,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC;QAEf,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAE,UAAe,EAAgB,EAAE;YAC5D,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC;gBACf,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC,CAAC;YACnE,CAAC;YACD,KAAK,GAAG,CAAC,CAAC;YAEV,MAAM,EAAE,GACN,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAEjE,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACpE,CAAC,CAAC;QAEF,OAAO,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC1B,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,IAAI,CAClB,WAAgD;IAEhD,OAAO,OAAO,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AAC7C,CAAC"}

package/dist/testing.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Framework-agnostic test helpers for code that uses mcpose middleware.
+ *
+ * **No test framework imports** — this module has zero dependencies on
+ * vitest, jest, or mocha. Import it in any test environment.
+ *
+ * @module mcpose/testing
+ */
+import type { CallToolRequest, CallToolResult, ReadResourceResult, Tool, Resource, Prompt, CallToolRequestParams, GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolMiddleware } from './core.js';
+import type { BackendClient } from './backendClient.js';
+/**
+ * Calls a {@link ToolMiddleware} and narrows the result to {@link CallToolResult}.
+ *
+ * Eliminates the boilerplate `isCallToolResult` guard that every test of a
+ * `ToolMiddleware` must otherwise repeat. Throws a clear error if the upstream
+ * returns the legacy `{ toolResult }` protocol shape.
+ *
+ * @param mw   - The middleware under test.
+ * @param req  - The tool call request to pass in.
+ * @param next - The innermost handler (simulates the upstream or next middleware).
+ *
+ * @example
+ * ```ts
+ * const result = await runToolMiddleware(mw, req, async () => mockResult);
+ * expect(result.content[0]).toMatchObject({ type: 'text' });
+ * ```
+ */
+export declare function runToolMiddleware(mw: ToolMiddleware, req: CallToolRequest, next: (req: CallToolRequest) => Promise<CallToolResult>): Promise<CallToolResult>;
+/**
+ * Configuration for the mock backend client.
+ */
+export interface MockBackendClientOptions {
+    /** Tools advertised by the mock upstream. Default: `[]`. */
+    tools?: Tool[];
+    /**
+     * Response for `callTool`. Can be a static result or a factory function
+     * that receives the call params and returns a per-call result.
+     *
+     * Default: `{ content: [{ type: 'text', text: 'mock response' }] }`
+     */
+    callToolResponse?: CallToolResult | ((params: CallToolRequestParams) => CallToolResult);
+    /** Resources advertised by the mock upstream. Default: `[]`. */
+    resources?: Resource[];
+    /**
+     * Response for `readResource`.
+     *
+     * Default: `{ contents: [{ uri: '', text: 'mock resource' }] }`
+     */
+    readResourceResponse?: ReadResourceResult;
+    /** Prompts advertised by the mock upstream. Default: `[]`. */
+    prompts?: Prompt[];
+    /**
+     * Response for `getPrompt`.
+     *
+     * Default: `{ messages: [] }`
+     */
+    getPromptResponse?: GetPromptResult;
+}
+/**
+ * Creates a plain object implementing {@link BackendClient} for use in tests.
+ *
+ * No real process is spawned and no network connection is made. All methods
+ * return configurable in-memory responses, making it possible to test the full
+ * `compose([auditMW, piiMW])` pipeline in a unit test.
+ *
+ * @example
+ * ```ts
+ * const backend = createMockBackendClient({
+ *   callToolResponse: { content: [{ type: 'text', text: 'John Doe: 123-45-6789' }] },
+ * });
+ * // Now compose real middlewares against it:
+ * const pipeline = compose([auditMW, piiToolMW]);
+ * const result = await pipeline(req, (r) => backend.callTool(r.params, undefined));
+ * ```
+ */
+export declare function createMockBackendClient(options?: MockBackendClientOptions): BackendClient;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EAId,kBAAkB,EAClB,IAAI,EACJ,QAAQ,EACR,MAAM,EACN,qBAAqB,EAGrB,eAAe,EAChB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAMxD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,cAAc,EAClB,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,CAAC,GACtD,OAAO,CAAC,cAAc,CAAC,CAQzB;AAMD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,4DAA4D;IAC5D,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf;;;;;OAKG;IACH,gBAAgB,CAAC,EACb,cAAc,GACd,CAAC,CAAC,MAAM,EAAE,qBAAqB,KAAK,cAAc,CAAC,CAAC;IACxD,gEAAgE;IAChE,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;IAC1C,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,eAAe,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,wBAA6B,GACrC,aAAa,CAkCf"}

package/dist/testing.js

@@ -0,0 +1,69 @@
+import { hasToolContent } from './core.js';
+// ---------------------------------------------------------------------------
+// Pain Point 1: runToolMiddleware
+// ---------------------------------------------------------------------------
+/**
+ * Calls a {@link ToolMiddleware} and narrows the result to {@link CallToolResult}.
+ *
+ * Eliminates the boilerplate `isCallToolResult` guard that every test of a
+ * `ToolMiddleware` must otherwise repeat. Throws a clear error if the upstream
+ * returns the legacy `{ toolResult }` protocol shape.
+ *
+ * @param mw   - The middleware under test.
+ * @param req  - The tool call request to pass in.
+ * @param next - The innermost handler (simulates the upstream or next middleware).
+ *
+ * @example
+ * ```ts
+ * const result = await runToolMiddleware(mw, req, async () => mockResult);
+ * expect(result.content[0]).toMatchObject({ type: 'text' });
+ * ```
+ */
+export async function runToolMiddleware(mw, req, next) {
+    const result = await mw(req, next);
+    if (!hasToolContent(result)) {
+        throw new Error('runToolMiddleware: middleware returned legacy toolResult shape — expected { content: [...] }');
+    }
+    return result;
+}
+/**
+ * Creates a plain object implementing {@link BackendClient} for use in tests.
+ *
+ * No real process is spawned and no network connection is made. All methods
+ * return configurable in-memory responses, making it possible to test the full
+ * `compose([auditMW, piiMW])` pipeline in a unit test.
+ *
+ * @example
+ * ```ts
+ * const backend = createMockBackendClient({
+ *   callToolResponse: { content: [{ type: 'text', text: 'John Doe: 123-45-6789' }] },
+ * });
+ * // Now compose real middlewares against it:
+ * const pipeline = compose([auditMW, piiToolMW]);
+ * const result = await pipeline(req, (r) => backend.callTool(r.params, undefined));
+ * ```
+ */
+export function createMockBackendClient(options = {}) {
+    return {
+        listTools: async () => ({
+            tools: options.tools ?? [],
+        }),
+        callTool: async (params) => {
+            const resp = options.callToolResponse;
+            if (typeof resp === 'function')
+                return resp(params);
+            return resp ?? { content: [{ type: 'text', text: 'mock response' }] };
+        },
+        listResources: async () => ({
+            resources: options.resources ?? [],
+        }),
+        readResource: async (_params) => options.readResourceResponse ?? {
+            contents: [{ uri: '', text: 'mock resource' }],
+        },
+        listPrompts: async () => ({
+            prompts: options.prompts ?? [],
+        }),
+        getPrompt: async (_params) => options.getPromptResponse ?? { messages: [] },
+    };
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAI3C,8EAA8E;AAC9E,kCAAkC;AAClC,8EAA8E;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,EAAkB,EAClB,GAAoB,EACpB,IAAuD;IAEvD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,8FAA8F,CAC/F,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAuCD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,uBAAuB,CACrC,UAAoC,EAAE;IAEtC,OAAO;QACL,SAAS,EAAE,KAAK,IAA8B,EAAE,CAAC,CAAC;YAChD,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE;SAC3B,CAAC;QAEF,QAAQ,EAAE,KAAK,EACb,MAA6B,EACJ,EAAE;YAC3B,MAAM,IAAI,GAAG,OAAO,CAAC,gBAAgB,CAAC;YACtC,IAAI,OAAO,IAAI,KAAK,UAAU;gBAAE,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;YACpD,OAAO,IAAI,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC;QACxE,CAAC;QAED,aAAa,EAAE,KAAK,IAAkC,EAAE,CAAC,CAAC;YACxD,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,EAAE;SACnC,CAAC;QAEF,YAAY,EAAE,KAAK,EACjB,OAAkC,EACL,EAAE,CAC/B,OAAO,CAAC,oBAAoB,IAAI;YAC9B,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;SAC/C;QAEH,WAAW,EAAE,KAAK,IAAgC,EAAE,CAAC,CAAC;YACpD,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE;SAC/B,CAAC;QAEF,SAAS,EAAE,KAAK,EACd,OAA+B,EACL,EAAE,CAC5B,OAAO,CAAC,iBAAiB,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE;KACpB,CAAC;AAChC,CAAC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "mcpose",
+  "version": "1.0.0",
+  "description": "Composable FP (Koa-style) middleware proxy builder for any MCP server",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "keywords": ["mcp", "middleware","functional-programming", "proxy", "compose", "model-context-protocol"],
+  "author": "Amir Gorji",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "ts:ci": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run ts:ci && npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },"repository": {
+    "type": "git",
+    "url": "git+https://github.com/amir-gorji/mcpose.git"
+  }
+}