@jaypie/mcp 0.8.152 → 0.8.153

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", {