@jaypie/mcp 0.8.152 → 0.8.154

package/skills/express.md

@@ -60,6 +60,32 @@ expressHandler(handler, {
 });
 ```
 
+### Response Rules
+
+The return value becomes the response. Do not call `res.end()`, `res.json()`, or `res.send()` inside the handler; `expressHandler` logs a warning ("Illegal call to res.end()") and replays the call.
+
+| Return | Response |
+|--------|----------|
+| Object or JSON string | JSON body with the status (200 unless `res.status()` was called) |
+| Non-JSON string | Text body with the status |
+| `true` | 201, no body |
+| No body (`undefined`, `null`, other falsy) | 204, no body |
+| No body after `res.status(code)` | `code`, no body |
+
+Set an explicit status and return nothing to answer with a bodiless non-204 status, such as 202 for MCP notifications:
+
+```typescript
+app.post("/mcp", expressHandler(async (req, res) => {
+  if (isNotification(req.body)) {
+    res.status(202);
+    return; // 202 with no body, no warning
+  }
+  return answer(req.body);
+}));
+```
+
+`expressStreamHandler` flushes headers before the handler runs, so a status set inside a stream handler does not reach the client.
+
 ### Request Logging
 
 `expressHandler` logs a summary of every request. Two options control what that
@@ -131,6 +157,22 @@ import { createLambdaStreamHandler } from "@jaypie/express";
 export const handler = createLambdaStreamHandler(app);
 ```
 
+`createLambdaStreamHandler` wraps with `awslambda.streamifyResponse` only when the Lambda runtime global exists. Elsewhere (unit tests, local servers) it returns the unwrapped `(event, responseStream, context)` handler, so importing the streaming entry point never throws. Without `awslambda.HttpResponseStream`, the body writes straight to the provided stream with no status/headers prelude.
+
+### Options
+
+Both factories accept an optional second argument:
+
+| Option | Default | Effect |
+|--------|---------|--------|
+| `name` | `"createLambdaHandler"` / `"createLambdaStreamHandler"` | Label on unhandled adapter error output (`[name] Unhandled error:`) |
+
+```typescript
+export const handler = createLambdaStreamHandler(app, { name: "streamApi" });
+```
+
+Lifecycle options such as `format`, `secrets`, `setup`, and `validate` belong on each route's `expressHandler` / `expressStreamHandler`, not the adapter.
+
 ### Cookies
 
 Both adapters emit every `Set-Cookie` value separately, so cookie-session auth (multiple cookies per response, chunked session cookies) works unchanged:
@@ -158,6 +200,17 @@ app.get("/callback", (req, res) => {
 
 Libraries that defer header or cookie writes this way work unchanged: `express-openid-connect` (session cookie), `express-session`, `morgan`, `compression`. `res.flushHeaders()` and `res._implicitHeader()` both route through the same path.
 
+### Node request contract (`rawHeaders`)
+
+The adapter request exposes `rawHeaders` as Node's flat `[name, value, name, value]` list, built from the same lowercased event headers as `req.headers` (multi-value headers repeat the name once per value), plus `rawTrailers: []` and `trailers: {}`. When the event carries no `host` header, `host` falls back to `requestContext.domainName` (v1 and v2) in both `headers` and `rawHeaders`. Libraries that convert a Node request into a Web Standard `Request` read these directly, so `@hono/node-server` and the MCP SDK `StreamableHTTPServerTransport` work under both adapters:
+
+```typescript
+import { mcpExpressHandler } from "@jaypie/mcp";
+
+app.use("/mcp", await mcpExpressHandler({ enableSessions: false }));
+export const handler = createLambdaHandler(app);
+```
+
 ### LLM Observability auto-flush
 
 `createLambdaHandler` and `createLambdaStreamHandler` call `flushLlmObs()` from `@jaypie/datadog` in their `finally` block, so buffered Datadog LLM Obs spans flush before the Lambda freezes — even when the Express app errors. No-op unless `DD_LLMOBS_ENABLED` is truthy; never affects the response. No per-handler flush code is required.
@@ -246,8 +299,8 @@ Deploy with `@jaypie/constructs`:
 import { JaypieLambda } from "@jaypie/constructs";
 
 new JaypieLambda(this, "Api", {
-  entry: "src/lambda.ts",
-  handler: "handler",
+  code: "../api/dist",
+  handler: "index.handler",
   environment: {
     PROJECT_ENV: "production",
   },
@@ -326,3 +379,4 @@ new JaypieLambda(this, "Api", {
 ## See Also
 
 - **`skill("streaming")`** - Full guide to `expressStreamHandler` and `createLambdaStreamHandler`
+- **`skill("mcp")`** - `mcpHttpHandler` serves a `ServiceSuite` as MCP streamable HTTP from an Express route

package/skills/fabric.md

@@ -200,11 +200,24 @@ import { createMcpServerFromSuite } from "@jaypie/fabric/mcp";
 
 const server = createMcpServerFromSuite(suite, {
   name: "users-api",    // Optional override
+  services: ["greet"],  // Optional allowlist of service aliases
   version: "1.0.0",
 });
-// All suite services now available as MCP tools
+// Allowlisted suite services now available as MCP tools
 ```
 
+`services` narrows the tools; omit it to register every service. The same
+selection is available to any transport:
+
+```typescript
+import { selectServiceFunctions } from "@jaypie/fabric";
+
+const tools = selectServiceFunctions(suite, { services: ["greet"] });
+```
+
+To serve a suite as MCP streamable HTTP from Lambda without the MCP SDK, use
+`mcpHttpHandler` from `@jaypie/mcp/http` (see `skill("mcp")`).
+
 ## Input Validation
 
 Fabric validates inputs automatically:

package/skills/lambda.md

@@ -159,13 +159,13 @@ Deploy with `@jaypie/constructs`:
 import { JaypieLambda } from "@jaypie/constructs";
 
 new JaypieLambda(this, "Handler", {
-  entry: "src/handler.ts",
-  handler: "handler",
+  code: "../api/dist",
+  handler: "index.handler",
   secrets: ["MY_SECRET"],
 });
 ```
 
-**Build order**: When using `code: "../package/dist"` instead of `entry`, ensure the package has a `build` script and builds before CDK synth in CI/CD. New packages need to be added to `build:core-deps` in root `package.json` if they're build-time dependencies. See `skill("cicd")` for details.
+**Build order**: When using `code: "../package/dist"`, ensure the package has a `build` script and builds before CDK synth in CI/CD. New packages need to be added to `build:core-deps` in root `package.json` if they're build-time dependencies. See `skill("cicd")` for details.
 
 ## ESM Deployment
 

package/skills/mcp.md

@@ -1,6 +1,6 @@
 ---
 description: Jaypie MCP server tools reference
-related: mcp-datadog, debugging
+related: mcp-datadog, debugging, express, fabric, streaming
 ---
 
 # Jaypie MCP
@@ -53,6 +53,84 @@ datadog("monitors", { status: ["Alert", "Warn"] })
 | `metrics` | Query timeseries metrics |
 | `rum` | Search RUM events |
 
+## Serving MCP over HTTP
+
+### Streamable HTTP without the SDK (`@jaypie/mcp/http`)
+
+`mcpHttpHandler` serves a fabric `ServiceSuite` as MCP streamable HTTP from an Express route or a Jaypie Lambda. It implements stateless JSON-RPC 2.0 directly and never loads `@modelcontextprotocol/sdk`, whose Node transport fails against `LambdaRequest`.
+
+```typescript
+import express from "express";
+import { createLambdaStreamHandler } from "@jaypie/express";
+import { mcpHttpHandler } from "@jaypie/mcp/http";
+
+const app = express();
+app.use(express.json());
+app.all(
+  "/mcp",
+  mcpHttpHandler({
+    secrets: ["PROJECT_API_KEY"],
+    services: ["skill", "version", "release_notes"],
+    setup: requireApiKey,
+  }),
+);
+
+export const handler = createLambdaStreamHandler(app);
+```
+
+| Request | Response |
+|---------|----------|
+| POST, `Accept` absent or prefers `application/json` | 200 JSON (one response, or an array for a batch) |
+| POST, `Accept` prefers `text/event-stream` | 200 SSE via `expressStreamHandler({ format: "sse" })`, one `event: message` per response |
+| POST carrying only notifications | 202, no body |
+| GET, DELETE, any other method | 405 with `Allow: POST` |
+
+Methods: `initialize` (echoes a supported `protocolVersion`, else `2025-06-18`), `notifications/initialized`, `notifications/cancelled`, `ping`, `tools/list`, `tools/call`. Errors: `-32700` unparseable body, `-32600` invalid request or empty batch, `-32601` unknown method, `-32602` unknown tool or non-object arguments. A tool that throws answers `isError: true`; a Jaypie error surfaces its message, any other error answers "The tool call failed".
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `suite` | Jaypie MCP suite (loaded on first request) | `ServiceSuite` served as tools |
+| `services` | all | Allowlist of service aliases exposed as tools |
+| `name` | `suite.name` | `serverInfo.name` reported by `initialize` |
+| `version` | `suite.version` | `serverInfo.version` reported by `initialize` |
+| `chaos`, `locals`, `secrets`, `setup`, `teardown`, `unavailable`, `validate`, ... | | Passed to `expressHandler` and `expressStreamHandler` |
+
+`handleMcpRpcBody(body, options)` and `handleMcpRpc(request, options)` expose the JSON-RPC layer for other transports. `@jaypie/express` and `@jaypie/logger` are optional peer dependencies required by this entry point; `jaypie` provides both.
+
+#### Lambda Deployment
+
+- **Streaming**: `createLambdaStreamHandler(app)` behind a Function URL with `RESPONSE_STREAM` invoke mode (for example `JaypieDistribution` with `streaming: true`). Both JSON and SSE responses work.
+- **Buffered**: `createLambdaHandler(app)` behind API Gateway or a buffered Function URL. JSON responses work; SSE responses arrive when the request completes.
+- The endpoint is stateless: no sessions, no `Mcp-Session-Id`, no server-initiated GET stream. Every POST stands alone, which suits Lambda.
+- Put authentication in `setup` or `validate` so it runs for both JSON and SSE requests.
+
+### SDK Transport (`mcpExpressHandler`)
+
+`mcpExpressHandler` from `@jaypie/mcp` wraps the SDK's `StreamableHTTPServerTransport` with optional sessions. It suits a long-running Express server, not Lambda.
+
+```typescript
+import express from "express";
+import { mcpExpressHandler } from "@jaypie/mcp";
+
+const app = express();
+app.use(express.json());
+app.use("/mcp", await mcpExpressHandler({ services: ["skill"], version: "1.0.0" }));
+```
+
+## Filtering Tools
+
+Every server factory accepts `services`, an allowlist of service aliases. Omit it to expose every tool; an empty array exposes none; unknown aliases are ignored. All share `selectServiceFunctions` from `@jaypie/fabric`.
+
+```typescript
+import { createMcpServer } from "@jaypie/mcp";
+import { mcpHttpHandler } from "@jaypie/mcp/http";
+import { createMcpServerFromSuite } from "@jaypie/fabric/mcp";
+
+createMcpServer({ services: ["skill", "version"] });        // stdio / SDK
+createMcpServerFromSuite(suite, { services: ["greet"] });   // any suite, SDK
+mcpHttpHandler({ services: ["skill", "release_notes"] });   // no SDK
+```
+
 ## Environment Variables
 
 ### Datadog Tools

package/skills/streaming.md

@@ -14,6 +14,7 @@ Jaypie provides response streaming for real-time data delivery. Three handler pa
 | `lambdaStreamHandler` | `@jaypie/lambda` | Pure Lambda Function URL streaming |
 | `expressStreamHandler` | `@jaypie/express` | Express routes with SSE |
 | `createLambdaStreamHandler` | `@jaypie/express` | Express app on Lambda with streaming |
+| `mcpHttpHandler` | `@jaypie/mcp/http` | MCP streamable HTTP (JSON or SSE) over a `ServiceSuite`; see `skill("mcp")` |
 
 ## Stream Formats
 
@@ -82,7 +83,8 @@ export const handler = lambdaStreamHandler(async (event, context) => {
 import { JaypieLambda, JaypieDistribution } from "@jaypie/constructs";
 
 const streamingLambda = new JaypieLambda(this, "Stream", {
-  entry: "src/stream.ts",
+  code: "../api/dist",
+  handler: "index.handler",
 });
 
 new JaypieDistribution(this, "Api", {