@jaypie/mcp 0.2.3 → 0.2.4

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

package/prompts/Jaypie_Vocabulary_Commander.md

@@ -0,0 +1,411 @@
+---
+description: Commander.js CLI integration with serviceHandler callbacks (onMessage, onComplete, onError, onFatal)
+include: "**/cli/**"
+---
+
+# Jaypie Vocabulary Commander Adapter
+
+The Commander adapter (`@jaypie/vocabulary/commander`) integrates Jaypie service handlers with Commander.js CLI applications, providing automatic option generation, type coercion, and callback hooks for progress reporting.
+
+**See also:** [Jaypie_Vocabulary_Package.md](Jaypie_Vocabulary_Package.md) for core serviceHandler documentation.
+
+## Installation
+
+```bash
+npm install @jaypie/vocabulary commander
+```
+
+## Quick Start
+
+```typescript
+import { Command } from "commander";
+import { serviceHandler } from "@jaypie/vocabulary";
+import { registerServiceCommand } from "@jaypie/vocabulary/commander";
+
+const handler = serviceHandler({
+  alias: "greet",
+  description: "Greet a user",
+  input: {
+    userName: { type: String, flag: "user", letter: "u" },
+    loud: { type: Boolean, letter: "l", default: false },
+  },
+  service: ({ loud, userName }) => {
+    const greeting = `Hello, ${userName}!`;
+    console.log(loud ? greeting.toUpperCase() : greeting);
+  },
+});
+
+const program = new Command();
+registerServiceCommand({ handler, program });
+program.parse();
+// Usage: greet --user Alice -l
+```
+
+## registerServiceCommand
+
+The primary function for registering a service handler as a Commander command.
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `handler` | `ServiceHandlerFunction` | Required. The service handler to register |
+| `program` | `Command` | Required. Commander program or command |
+| `name` | `string` | Override command name (default: handler.alias) |
+| `description` | `string` | Override description (default: handler.description) |
+| `exclude` | `string[]` | Field names to exclude from CLI options |
+| `onComplete` | `OnCompleteCallback` | Called with handler's return value on success |
+| `onError` | `OnErrorCallback` | Receives errors reported via `context.onError()` |
+| `onFatal` | `OnFatalCallback` | Receives fatal errors (thrown or via `context.onFatal()`) |
+| `onMessage` | `OnMessageCallback` | Receives messages from `context.sendMessage` |
+| `overrides` | `Record<string, override>` | Per-field option overrides |
+
+## Callback Hooks
+
+### onMessage
+
+Receives progress messages sent by the service via `context.sendMessage`:
+
+```typescript
+import { Command } from "commander";
+import { serviceHandler } from "@jaypie/vocabulary";
+import { registerServiceCommand } from "@jaypie/vocabulary/commander";
+
+const handler = serviceHandler({
+  alias: "process",
+  input: { jobId: { type: String, letter: "j" } },
+  service: async ({ jobId }, context) => {
+    // Send progress messages during execution
+    context?.sendMessage?.({ content: `Starting job ${jobId}` });
+
+    // Simulate work
+    await doStep1();
+    context?.sendMessage?.({ content: "Step 1 complete", level: "debug" });
+
+    await doStep2();
+    context?.sendMessage?.({ content: "Step 2 complete", level: "debug" });
+
+    context?.sendMessage?.({ content: "Job finished!", level: "info" });
+    return { jobId, status: "complete" };
+  },
+});
+
+const program = new Command();
+registerServiceCommand({
+  handler,
+  program,
+  onMessage: (msg) => {
+    // msg: { content: string, level?: "trace"|"debug"|"info"|"warn"|"error" }
+    const level = msg.level || "info";
+    console[level](msg.content);
+  },
+});
+program.parse();
+```
+
+**Important:** Errors in `onMessage` are swallowed to ensure messaging failures never halt service execution.
+
+### onComplete
+
+Called with the handler's return value on successful completion:
+
+```typescript
+registerServiceCommand({
+  handler,
+  program,
+  onComplete: (response) => {
+    // Called after service completes successfully
+    console.log("Result:", JSON.stringify(response, null, 2));
+
+    // Common patterns:
+    // - Save results to file
+    // - Display formatted output
+    // - Trigger follow-up actions
+  },
+});
+```
+
+### onError
+
+Receives errors that the service explicitly reports via `context.onError()`. Use this for recoverable errors that don't halt execution:
+
+```typescript
+registerServiceCommand({
+  handler,
+  program,
+  onError: (error) => {
+    // Log recoverable errors
+    console.warn("Warning:", error.message);
+  },
+});
+```
+
+### onFatal
+
+Receives fatal errors - either thrown errors or errors reported via `context.onFatal()`. Any error that escapes the service (is thrown) is treated as fatal:
+
+```typescript
+registerServiceCommand({
+  handler,
+  program,
+  onFatal: (error) => {
+    console.error("Fatal error:", error.message);
+    process.exit(1);
+  },
+});
+```
+
+**Error handling priority:**
+1. If `onFatal` is provided, thrown errors go to `onFatal`
+2. If only `onError` is provided, thrown errors fall back to `onError`
+3. If neither is provided, errors are re-thrown
+
+## Complete Example with All Callbacks
+
+```typescript
+import { Command } from "commander";
+import { serviceHandler } from "@jaypie/vocabulary";
+import { registerServiceCommand } from "@jaypie/vocabulary/commander";
+
+const evaluateHandler = serviceHandler({
+  alias: "evaluate",
+  description: "Run an evaluation job",
+  input: {
+    jobId: {
+      type: String,
+      flag: "job",
+      letter: "j",
+      description: "Job identifier",
+    },
+    priority: {
+      type: [1, 2, 3, 4, 5],
+      default: 3,
+      letter: "p",
+      description: "Job priority (1-5)",
+    },
+    tags: {
+      type: [String],
+      letter: "t",
+      required: false,
+      description: "Tags to apply",
+    },
+    dryRun: {
+      type: Boolean,
+      letter: "d",
+      default: false,
+      description: "Run without executing",
+    },
+  },
+  service: async ({ dryRun, jobId, priority, tags }, context) => {
+    context?.sendMessage?.({ content: `Initializing job ${jobId}...` });
+
+    if (dryRun) {
+      context?.sendMessage?.({ content: "Dry run mode - skipping execution", level: "warn" });
+      return { jobId, status: "dry-run", skipped: true };
+    }
+
+    // Handle recoverable errors without throwing
+    try {
+      await riskyOperation();
+    } catch (err) {
+      context?.onError?.(err);  // Reports error but continues
+    }
+
+    context?.sendMessage?.({ content: `Running with priority ${priority}` });
+
+    if (tags?.length) {
+      context?.sendMessage?.({ content: `Applying tags: ${tags.join(", ")}`, level: "debug" });
+    }
+
+    // Simulate processing
+    for (let i = 1; i <= 5; i++) {
+      await new Promise(resolve => setTimeout(resolve, 100));
+      context?.sendMessage?.({ content: `Progress: ${i * 20}%`, level: "debug" });
+    }
+
+    context?.sendMessage?.({ content: "Evaluation complete!" });
+    return { jobId, status: "complete", results: 42 };
+  },
+});
+
+const program = new Command();
+program.version("1.0.0").description("Evaluation CLI");
+
+registerServiceCommand({
+  handler: evaluateHandler,
+  program,
+  onMessage: (msg) => {
+    const prefix = msg.level === "warn" ? "WARNING: " :
+                   msg.level === "error" ? "ERROR: " : "";
+    console.log(`${prefix}${msg.content}`);
+  },
+  onComplete: (response) => {
+    console.log("\n--- Results ---");
+    console.log(JSON.stringify(response, null, 2));
+  },
+  onError: (error) => {
+    // Recoverable errors reported via context.onError()
+    console.warn("Warning:", error.message);
+  },
+  onFatal: (error) => {
+    // Fatal errors (thrown or via context.onFatal())
+    console.error("\nFatal:", error.message);
+    process.exit(1);
+  },
+});
+
+program.parse();
+```
+
+Usage:
+```bash
+# Basic execution
+cli evaluate --job abc123
+
+# With all options
+cli evaluate -j abc123 -p 1 -t urgent -t critical --dry-run
+
+# Help
+cli evaluate --help
+```
+
+## Input Flag and Letter Properties
+
+Define CLI flags directly in input definitions:
+
+```typescript
+input: {
+  userName: {
+    type: String,
+    flag: "user",     // Long flag: --user (instead of --user-name)
+    letter: "u",      // Short flag: -u
+    description: "User name to greet",
+  },
+  verbose: {
+    type: Boolean,
+    letter: "v",      // -v
+  },
+}
+// Generates: --user <userName>, -u and --verbose, -v
+```
+
+### Naming Convention
+
+| Property | CLI Flag | Example |
+|----------|----------|---------|
+| `userName` (camelCase) | `--user-name` | Default behavior |
+| `flag: "user"` | `--user` | Override long flag |
+| `letter: "u"` | `-u` | Short flag |
+
+## Boolean Flag Behavior
+
+Commander.js automatically handles boolean flags:
+- `--verbose` sets to `true`
+- `--no-verbose` sets to `false` (for flags with `default: true`)
+
+## Manual Integration
+
+For more control, use `createCommanderOptions` and `parseCommanderOptions`:
+
+```typescript
+import { Command } from "commander";
+import { serviceHandler } from "@jaypie/vocabulary";
+import {
+  createCommanderOptions,
+  parseCommanderOptions,
+} from "@jaypie/vocabulary/commander";
+
+const handler = serviceHandler({
+  input: {
+    userName: { type: String, description: "User name" },
+    maxRetries: { type: Number, default: 3 },
+    verbose: { type: Boolean },
+  },
+  service: (input) => console.log(input),
+});
+
+const program = new Command();
+
+// Create options from handler input
+const { options } = createCommanderOptions(handler.input, {
+  exclude: ["internalField"],
+  overrides: {
+    userName: { short: "u", description: "Override description" },
+  },
+});
+options.forEach((opt) => program.addOption(opt));
+
+// Wire up action
+program.action(async (opts) => {
+  const input = parseCommanderOptions(opts, { input: handler.input });
+  await handler(input);
+});
+
+program.parse();
+```
+
+## TypeScript Types
+
+```typescript
+import type {
+  CommanderOptionOverride,
+  CreateCommanderOptionsConfig,
+  CreateCommanderOptionsResult,
+  OnCompleteCallback,
+  OnErrorCallback,
+  OnFatalCallback,
+  OnMessageCallback,
+  ParseCommanderOptionsConfig,
+  RegisterServiceCommandConfig,
+  RegisterServiceCommandResult,
+} from "@jaypie/vocabulary/commander";
+```
+
+### Callback Type Definitions
+
+```typescript
+// Message received from context.sendMessage
+interface Message {
+  content: string;
+  level?: "trace" | "debug" | "info" | "warn" | "error";
+}
+
+// onMessage callback
+type OnMessageCallback = (message: Message) => void | Promise<void>;
+
+// onComplete callback - receives handler return value
+type OnCompleteCallback<T = unknown> = (response: T) => void | Promise<void>;
+
+// onError callback - receives errors from context.onError()
+type OnErrorCallback = (error: unknown) => void | Promise<void>;
+
+// onFatal callback - receives fatal errors (thrown or context.onFatal())
+type OnFatalCallback = (error: unknown) => void | Promise<void>;
+```
+
+## Exports
+
+```typescript
+// @jaypie/vocabulary/commander
+export { createCommanderOptions } from "./createCommanderOptions.js";
+export { parseCommanderOptions } from "./parseCommanderOptions.js";
+export { registerServiceCommand } from "./registerServiceCommand.js";
+
+export type {
+  CommanderOptionOverride,
+  CreateCommanderOptionsConfig,
+  CreateCommanderOptionsResult,
+  OnCompleteCallback,
+  OnErrorCallback,
+  OnFatalCallback,
+  OnMessageCallback,
+  ParseCommanderOptionsConfig,
+  RegisterServiceCommandConfig,
+  RegisterServiceCommandResult,
+} from "./types.js";
+```
+
+## Related
+
+- [Jaypie_Commander_CLI_Package.md](Jaypie_Commander_CLI_Package.md) - Setting up a Commander CLI project from scratch
+- [Jaypie_Vocabulary_Package.md](Jaypie_Vocabulary_Package.md) - Core serviceHandler and type coercion