mcpose 2.0.1 → 2.0.2

package/README.md

@@ -0,0 +1,126 @@
+# mcpose
+
+[![npm](https://img.shields.io/npm/v/mcpose)](https://www.npmjs.com/package/mcpose)
+[![license](https://img.shields.io/npm/l/mcpose)](https://github.com/amir-gorji/mcpose/blob/main/LICENSE)
+
+**The composable middleware proxy for MCP.**
+
+mcpose sits between a **client** (an LLM or agent) and an **upstream** MCP server, forwarding every tool, resource, and `list_tools` call through a **pipeline** of composable middleware. It is a transparent proxy: the client talks to mcpose exactly as it would talk to the upstream, while you intercept, transform, hide, or govern calls in between — without touching the upstream server.
+
+## When to reach for it
+
+- Add cross-cutting behavior (logging, PII redaction, identity resolution, rate limiting) to an MCP server you don't own.
+- Hide or gate specific tools/resources per caller.
+- Resolve a caller **identity** once per session and stamp it on every request.
+- Lay the foundation for compliance-grade audit trails with [`@mcpose/audit`](https://www.npmjs.com/package/@mcpose/audit).
+
+If you only need the audit chain or the compliance test helpers, see the ecosystem packages below — they build on this core.
+
+## Install
+
+```bash
+npm install mcpose
+```
+
+Requires Node.js 18+. Ships ESM with TypeScript types.
+
+## Quick start
+
+Connect to an upstream over stdio, add one middleware, and serve the proxy:
+
+```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: (req, next, ctx) => Promise<result>
+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],
+});
+```
+
+To serve over HTTP instead — with identity resolution, mTLS, session limits, and SSE reconnect replay — use `startHttpProxy`:
+
+```ts
+import { createBackendClient, startHttpProxy } from 'mcpose';
+
+// Supplied by your application:
+//   extractJwt — a resolveIdentity function returning an Identity from the request
+const backend = await createBackendClient({ url: 'http://localhost:9000/mcp' });
+
+await startHttpProxy(
+  backend,
+  { toolMiddleware: [loggingMW] },
+  {
+    port: 3000,
+    resolveIdentity: extractJwt, // stamped on every ProxyContext in the session
+    onSessionClosed: (sessionId) => {/* flush audit manifest, etc. */},
+  },
+);
+```
+
+## Core concepts
+
+- **Middleware** — a single function `(req, next, ctx) => Promise<result>`. Call `next(req)` to delegate downstream; transform the request before, or the response after. Middlewares nest onion-style.
+- **Pipeline** — middlewares passed to `ProxyOptions` run in response-processing order (first = innermost). `[piiMW, auditMW]` redacts before it audits.
+- **ProxyContext** — per-request metadata threaded through the pipeline: `requestId`, `transport`, `sessionId`, resolved `identity`, and the agent `delegatedFrom` chain.
+
+## API surface
+
+| Export | Purpose |
+|---|---|
+| `createBackendClient(config)` | Connect to an upstream over stdio (`command`/`args`) or HTTP (`url`). |
+| `startProxy(backend, options?)` | Serve the proxy over **stdio**. |
+| `startHttpProxy(backend, proxyOptions?, httpOptions?)` | Serve over **HTTP/SSE** — identity, mTLS, sessions, reconnect replay. |
+| `createProxyServer(backend, options?)` | Build the underlying `Server` without binding a transport. |
+| `compose(middlewares)` | Compose middlewares into one (outermost-first). |
+| `createProxyContext(overrides?)` | Construct a `ProxyContext` (useful in tests). |
+| `createInMemoryEventStore()` | Default SSE reconnect event store; swap for a `PersistentEventStore`. |
+| `hasToolContent(result)` | Type guard for tool-call results. |
+
+**Key types:** `Middleware<Req, Res>`, `ToolMiddleware`, `ResourceMiddleware`, `ListToolsMiddleware`, `ProxyContext`, `Identity`, `BackendConfig`, `ProxyOptions`, `HttpProxyOptions`, `RejectionReason`, `TelemetryEvent`, `PersistentEventStore`.
+
+### Governance options (`ProxyOptions`)
+
+`hiddenTools` / `hiddenResources` reject calls with a structured [`RejectionReason`](https://github.com/amir-gorji/mcpose#rejectionreason) in the MCP error `data` field; `passThroughTools` skip the pipeline entirely; `onTelemetry` emits per-call timing and outcome.
+
+### Test helpers — `mcpose/testing`
+
+The core package exposes proxy/middleware test utilities under a subpath:
+
+```ts
+import { createMockBackendClient, runToolMiddleware } from 'mcpose/testing';
+```
+
+> **Not to be confused with** [`@mcpose/testing`](https://www.npmjs.com/package/@mcpose/testing), the separate package of compliance-chain assertions.
+
+## The mcpose ecosystem
+
+| Package | What it adds |
+|---|---|
+| **`mcpose`** (this package) | Proxy core — pipeline, transports, identity, governance. |
+| [`@mcpose/audit`](https://www.npmjs.com/package/@mcpose/audit) | Tamper-evident, HMAC-chained audit events + Merkle `ReplayManifest`. |
+| [`@mcpose/testing`](https://www.npmjs.com/package/@mcpose/testing) | Runner-agnostic compliance assertions for the audit chain. |
+
+## Documentation
+
+- [Full README & API reference](https://github.com/amir-gorji/mcpose#readme)
+- [CONTEXT.md](https://github.com/amir-gorji/mcpose/blob/main/CONTEXT.md) — canonical domain glossary
+- [Architecture decision records](https://github.com/amir-gorji/mcpose/tree/main/docs/adr)
+
+## License
+
+MIT © Amir Gorji

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpose",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "The audit and governance layer for MCP",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,10 +15,7 @@
       "default": "./dist/testing.js"
     }
   },
-  "files": [
-    "dist",
-    "README.md"
-  ],
+  "files": ["dist", "README.md"],
   "keywords": [
     "mcp",
     "middleware",
@@ -37,6 +34,12 @@
     "url": "git+https://github.com/amir-gorji/mcpose.git",
     "directory": "packages/core"
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "ts:ci": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "prepublishOnly": "pnpm run ts:ci && pnpm run test && pnpm run build"
+  },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": ">=1.0.0"
   },
@@ -45,10 +48,5 @@
     "@types/node": "^22.0.0",
     "typescript": "^5.0.0",
     "vitest": "^3.0.0"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "ts:ci": "tsc --noEmit",
-    "test": "vitest run --passWithNoTests"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-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.