@jaypie/mcp 0.2.3 → 0.2.5

package/prompts/Jaypie_Express_Package.md

@@ -406,3 +406,94 @@ expressHandler automatically sets these headers:
 ## Datadog Integration
 
 When Datadog environment variables are configured, expressHandler automatically submits metrics for each request including status code and path.
+
+## Streaming Responses
+
+Use `expressStreamHandler` for Server-Sent Events (SSE) streaming responses. Ideal for real-time updates, LLM streaming, and long-running operations.
+
+### Basic Streaming Usage
+
+```typescript
+import { expressStreamHandler } from "jaypie";
+import type { Request, Response } from "express";
+
+const streamRoute = expressStreamHandler(async (req: Request, res: Response) => {
+  // Write SSE events directly to response
+  res.write("event: message\ndata: {\"text\": \"Hello\"}\n\n");
+  res.write("event: message\ndata: {\"text\": \"World\"}\n\n");
+  // Handler automatically ends the stream
+});
+
+app.get("/stream", streamRoute);
+```
+
+### Streaming with LLM
+
+```typescript
+import { expressStreamHandler, Llm, createExpressStream } from "jaypie";
+
+const llmStreamRoute = expressStreamHandler(async (req: Request, res: Response) => {
+  const llm = new Llm("anthropic");
+  const stream = llm.stream(req.body.prompt);
+
+  // createExpressStream pipes LLM chunks as SSE events
+  await createExpressStream(stream, res);
+});
+
+app.post("/chat", llmStreamRoute);
+```
+
+### Stream Handler Options
+
+`expressStreamHandler` supports the same lifecycle options as `expressHandler`:
+
+```typescript
+import { expressStreamHandler } from "jaypie";
+import type { ExpressStreamHandlerOptions } from "jaypie";
+
+const options: ExpressStreamHandlerOptions = {
+  name: "myStreamHandler",      // Handler name for logging
+  contentType: "text/event-stream", // Default SSE content type
+  chaos: "low",                 // Chaos testing level
+  secrets: ["API_KEY"],         // Secrets to load
+  setup: [],                    // Setup function(s)
+  teardown: [],                 // Teardown function(s)
+  validate: [],                 // Validation function(s)
+  locals: {},                   // Values to set on req.locals
+  unavailable: false,           // Return 503 if true
+};
+
+const handler = expressStreamHandler(async (req, res) => {
+  // Streaming logic
+}, options);
+```
+
+### SSE Headers
+
+`expressStreamHandler` automatically sets SSE headers:
+- `Content-Type: text/event-stream`
+- `Cache-Control: no-cache`
+- `Connection: keep-alive`
+- `X-Accel-Buffering: no` (disables nginx buffering)
+
+### Error Handling in Streams
+
+Errors are formatted as SSE error events:
+
+```typescript
+// Jaypie errors and unhandled errors are written as:
+// event: error
+// data: {"errors":[{"status":500,"title":"Internal Error"}]}
+```
+
+### TypeScript Types
+
+```typescript
+import type {
+  ExpressStreamHandlerOptions,
+  ExpressStreamHandlerLocals,
+  JaypieStreamHandlerSetup,
+  JaypieStreamHandlerTeardown,
+  JaypieStreamHandlerValidate,
+} from "jaypie";
+```

package/prompts/Jaypie_Init_Lambda_Package.md

@@ -361,4 +361,137 @@ Deploy using AWS CDK or other deployment tool. The Lambda handler will be refere
 - Use double quotes, trailing commas, semicolons
 - Alphabetize imports and properties
 - Define constants for hard-coded values at file top
-- Never throw vanilla Error; use errors from `@jaypie/errors`
+- Never throw vanilla Error; use errors from `@jaypie/errors`
+
+## Streaming Lambda Functions
+
+Use `lambdaStreamHandler` for AWS Lambda Response Streaming. This enables real-time streaming responses for LLM interactions, large file processing, and SSE endpoints.
+
+### Lambda Streaming Setup
+
+Create a streaming Lambda handler with `awslambda.streamifyResponse`:
+
+```typescript
+// src/streamWorker.ts
+import { log } from "@jaypie/core";
+import { lambdaStreamHandler, createLambdaStream, Llm } from "jaypie";
+import type { StreamHandlerContext } from "@jaypie/lambda";
+
+export interface StreamWorkerEvent {
+  prompt?: string;
+}
+
+const streamWorker = lambdaStreamHandler(
+  async (event: StreamWorkerEvent, context: StreamHandlerContext) => {
+    log.trace("streamWorker: start");
+
+    const llm = new Llm("anthropic");
+    const stream = llm.stream(event.prompt || "Hello");
+
+    // createLambdaStream pipes LLM chunks as SSE events
+    await createLambdaStream(stream, context.responseStream);
+
+    log.trace("streamWorker: complete");
+  },
+  {
+    name: "streamWorker",
+    contentType: "text/event-stream",
+  }
+);
+
+// Wrap with AWS streamifyResponse
+declare const awslambda: { streamifyResponse: <T>(handler: T) => T };
+export const handler = awslambda.streamifyResponse(streamWorker);
+```
+
+### Manual Stream Writing
+
+Write directly to the response stream for custom SSE events:
+
+```typescript
+import { lambdaStreamHandler } from "jaypie";
+import type { StreamHandlerContext } from "@jaypie/lambda";
+
+const manualStreamHandler = lambdaStreamHandler(
+  async (event: unknown, context: StreamHandlerContext) => {
+    const { responseStream } = context;
+
+    // Write SSE events directly
+    responseStream.write("event: start\ndata: {\"status\": \"processing\"}\n\n");
+
+    // Process data in chunks
+    for (const item of items) {
+      const result = await process(item);
+      responseStream.write(`event: data\ndata: ${JSON.stringify(result)}\n\n`);
+    }
+
+    responseStream.write("event: done\ndata: {\"status\": \"complete\"}\n\n");
+    // Handler automatically calls responseStream.end()
+  },
+  {
+    name: "manualStream",
+  }
+);
+```
+
+### Stream Handler Options
+
+```typescript
+import type { LambdaStreamHandlerOptions } from "@jaypie/lambda";
+
+const options: LambdaStreamHandlerOptions = {
+  name: "myStreamHandler",          // Handler name for logging
+  contentType: "text/event-stream", // Response content type (default)
+  chaos: "low",                     // Chaos testing level
+  secrets: ["API_KEY"],             // AWS secrets to load into process.env
+  setup: [],                        // Setup function(s)
+  teardown: [],                     // Teardown function(s)
+  validate: [],                     // Validation function(s)
+  throw: false,                     // Re-throw errors instead of SSE error
+  unavailable: false,               // Return 503 if true
+};
+```
+
+### Stream Handler Types
+
+```typescript
+import type {
+  LambdaStreamHandlerOptions,
+  StreamHandlerContext,
+  ResponseStream,
+  AwsStreamingHandler,
+} from "@jaypie/lambda";
+```
+
+### CDK Configuration for Streaming
+
+Enable Lambda Response Streaming via Function URL in CDK:
+
+```typescript
+import { JaypieLambda } from "@jaypie/constructs";
+import { FunctionUrlAuthType, InvokeMode } from "aws-cdk-lib/aws-lambda";
+
+const streamingLambda = new JaypieLambda(this, "StreamingFunction", {
+  code: "dist",
+  handler: "streamWorker.handler",
+  timeout: Duration.minutes(5),
+});
+
+// Add Function URL with streaming enabled
+streamingLambda.addFunctionUrl({
+  authType: FunctionUrlAuthType.NONE, // or AWS_IAM for auth
+  invokeMode: InvokeMode.RESPONSE_STREAM,
+});
+```
+
+### Error Handling in Streams
+
+Errors are formatted as SSE error events:
+
+```typescript
+// Jaypie errors written as:
+// event: error
+// data: {"errors":[{"status":500,"title":"Internal Error"}]}
+```
+
+Set `throw: true` to re-throw errors instead of writing to stream.

package/prompts/Jaypie_Llm_Calls.md

@@ -312,6 +312,60 @@ type LlmStreamChunk =
   | LlmStreamChunkError;    // { type: "error", error: { status, title, detail? } }
 ```
 
+### Streaming to Express
+
+Use `createExpressStream` to pipe LLM streams to Express responses:
+
+```javascript
+import { expressStreamHandler, Llm, createExpressStream } from "jaypie";
+
+const chatRoute = expressStreamHandler(async (req, res) => {
+  const llm = new Llm("anthropic");
+  const stream = llm.stream(req.body.prompt);
+  await createExpressStream(stream, res);
+});
+
+app.post("/chat", chatRoute);
+```
+
+### Streaming to Lambda
+
+Use `createLambdaStream` with Lambda Response Streaming:
+
+```javascript
+import { lambdaStreamHandler, Llm, createLambdaStream } from "jaypie";
+
+const handler = awslambda.streamifyResponse(
+  lambdaStreamHandler(async (event, context) => {
+    const llm = new Llm("openai");
+    const stream = llm.stream(event.prompt);
+    await createLambdaStream(stream, context.responseStream);
+  })
+);
+```
+
+### JaypieStream Wrapper
+
+Use `JaypieStream` or `createJaypieStream` for fluent piping:
+
+```javascript
+import { createJaypieStream, Llm } from "jaypie";
+
+const llm = new Llm("gemini");
+const stream = createJaypieStream(llm.stream("Hello"));
+
+// Pipe to Express
+await stream.toExpress(res);
+
+// Or pipe to Lambda
+await stream.toLambda(responseStream);
+
+// Or iterate manually
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
 ## Hooks
 
 Use hooks to intercept and observe the LLM lifecycle:
@@ -365,6 +419,29 @@ const result = await llm.operate("Roll dice and check weather", {
 });
 ```
 
+### Zod Schema Support
+
+Tool parameters can be defined using Zod schemas instead of JSON Schema:
+
+```javascript
+import { z } from "zod/v4";
+import { Llm, Toolkit } from "jaypie";
+
+const weatherTool = {
+  name: "get_weather",
+  description: "Get weather for a city",
+  parameters: z.object({
+    city: z.string().describe("City name"),
+    unit: z.enum(["celsius", "fahrenheit"]),
+  }),
+  type: "function",
+  call: async ({ city, unit }) => ({ city, temp: 72, unit }),
+};
+
+const toolkit = new Toolkit([weatherTool]);
+// Zod schemas are automatically converted to JSON Schema
+```
+
 ## Footnotes
 
 Llm.operate(input, options)

package/prompts/Jaypie_Llm_Tools.md

@@ -16,10 +16,12 @@ Create and integrate tools that enable LLMs to perform specific functions beyond
 Implement the `LlmTool` interface:
 
 ```typescript
+import { z } from "zod/v4";
+
 interface LlmTool {
   description: string;
   name: string;
-  parameters: JsonObject;
+  parameters: JsonObject | z.ZodType;  // JSON Schema or Zod schema
   type: "function" | string;
   call: (args?: JsonObject) => Promise<AnyValue> | AnyValue;
 }
@@ -28,11 +30,11 @@ interface LlmTool {
 Properties:
 - `description`: Clear explanation of tool functionality
 - `name`: Unique identifier
-- `parameters`: JSON Schema defining input parameters
+- `parameters`: JSON Schema or Zod schema defining input parameters
 - `type`: Usually "function" (OpenAI convention)
 - `call`: Implementation function executed on invocation
 
-## Example: Dice Roller
+## Example: Dice Roller (JSON Schema)
 
 ```typescript
 import { LlmTool } from "../types/LlmTool.interface.js";
@@ -84,6 +86,27 @@ export const roll: LlmTool = {
 };
 ```
 
+## Example: Weather Tool (Zod Schema)
+
+```typescript
+import { z } from "zod/v4";
+import { LlmTool } from "jaypie";
+
+export const getWeather: LlmTool = {
+  description: "Get current weather for a city",
+  name: "get_weather",
+  parameters: z.object({
+    city: z.string().describe("City name"),
+    unit: z.enum(["celsius", "fahrenheit"]).describe("Temperature unit"),
+  }),
+  type: "function",
+  call: async ({ city, unit }) => {
+    // Implementation here
+    return { city, temperature: 72, unit };
+  },
+};
+```
+
 ## Best Practices
 
 ### Input Validation