@jaypie/mcp 0.2.3 → 0.2.5

package/prompts/Jaypie_Vocabulary_Lambda.md

@@ -0,0 +1,310 @@
+---
+description: AWS Lambda integration with serviceHandler for event processing and callbacks
+include: "**/lambda/**"
+---
+
+# Jaypie Vocabulary Lambda Adapter
+
+The Lambda adapter (`@jaypie/vocabulary/lambda`) wraps Jaypie service handlers for use as AWS Lambda handlers, providing automatic event parsing, secrets management, and lifecycle hooks.
+
+**See also:** [Jaypie_Vocabulary_Package.md](Jaypie_Vocabulary_Package.md) for core serviceHandler documentation.
+
+## Installation
+
+```bash
+npm install @jaypie/vocabulary
+```
+
+## Quick Start
+
+```typescript
+import { serviceHandler } from "@jaypie/vocabulary";
+import { lambdaServiceHandler } from "@jaypie/vocabulary/lambda";
+
+const handler = serviceHandler({
+  alias: "processOrder",
+  input: { orderId: { type: String } },
+  service: async ({ orderId }) => {
+    return { orderId, status: "processed" };
+  },
+});
+
+export const lambdaHandler = lambdaServiceHandler({ handler });
+```
+
+## lambdaServiceHandler
+
+Wraps a serviceHandler for use as an AWS Lambda handler.
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `handler` | `ServiceHandlerFunction` | Required. The service handler to wrap |
+| `chaos` | `string` | Chaos testing mode |
+| `name` | `string` | Override handler name for logging (default: handler.alias) |
+| `onComplete` | `OnCompleteCallback` | Called with handler's return value on success |
+| `onError` | `OnErrorCallback` | Receives errors reported via `context.onError()` in service |
+| `onFatal` | `OnFatalCallback` | Receives fatal errors (thrown or via `context.onFatal()`) |
+| `onMessage` | `OnMessageCallback` | Receives messages from `context.sendMessage` |
+| `secrets` | `string[]` | AWS secrets to load into process.env |
+| `setup` | `LifecycleFunction[]` | Functions to run before handler |
+| `teardown` | `LifecycleFunction[]` | Functions to run after handler (always runs) |
+| `throw` | `boolean` | Re-throw errors instead of returning error response |
+| `unavailable` | `boolean` | Return 503 Unavailable immediately |
+| `validate` | `ValidatorFunction[]` | Validation functions to run before handler |
+
+## Lifecycle Callbacks
+
+Services can use context callbacks to report progress, errors, and completion:
+
+```typescript
+import { serviceHandler } from "@jaypie/vocabulary";
+import { lambdaServiceHandler } from "@jaypie/vocabulary/lambda";
+
+const handler = serviceHandler({
+  alias: "evaluate",
+  input: { jobId: { type: String } },
+  service: async ({ jobId }, context) => {
+    context?.sendMessage?.({ content: `Starting job ${jobId}` });
+
+    // Handle recoverable errors without throwing
+    try {
+      await riskyOperation();
+    } catch (err) {
+      context?.onError?.(err); // Reports error but continues
+    }
+
+    // For fatal errors, either throw or call context.onFatal()
+    if (criticalFailure) {
+      context?.onFatal?.(new Error("Cannot continue"));
+    }
+
+    return { jobId, status: "complete" };
+  },
+});
+
+export const lambdaHandler = lambdaServiceHandler({
+  handler,
+  onComplete: (response) => {
+    console.log("Done:", JSON.stringify(response, null, 2));
+  },
+  onError: (error) => {
+    // Recoverable errors reported via context.onError()
+    console.error("Warning:", error);
+  },
+  onFatal: (error) => {
+    // Fatal errors (thrown or via context.onFatal())
+    console.error("Fatal:", error);
+  },
+  onMessage: (msg) => {
+    console.log(`[${msg.level || "info"}] ${msg.content}`);
+  },
+});
+```
+
+**Error handling**: Services receive `context.onError()` and `context.onFatal()` callbacks to report errors without throwing. Any error that escapes the service (is thrown) is treated as fatal and routes to `onFatal`. If `onFatal` is not provided, thrown errors fall back to `onError`. Callback errors are swallowed to ensure failures never halt service execution.
+
+## Secrets Management
+
+Automatically loads AWS Secrets Manager values into `process.env`:
+
+```typescript
+export const lambdaHandler = lambdaServiceHandler({
+  handler,
+  secrets: ["ANTHROPIC_API_KEY", "DATABASE_URL"],
+});
+// Before handler runs, secrets are fetched and available as:
+// process.env.ANTHROPIC_API_KEY
+// process.env.DATABASE_URL
+```
+
+## Lifecycle Hooks
+
+### setup
+
+Functions to run before the handler:
+
+```typescript
+export const lambdaHandler = lambdaServiceHandler({
+  handler,
+  setup: [
+    async () => {
+      await initializeDatabase();
+    },
+    async () => {
+      await warmCache();
+    },
+  ],
+});
+```
+
+### teardown
+
+Functions to run after the handler (always runs, even on error):
+
+```typescript
+export const lambdaHandler = lambdaServiceHandler({
+  handler,
+  teardown: [
+    async () => {
+      await closeConnections();
+    },
+  ],
+});
+```
+
+### validate
+
+Validation functions to run before handler. If any returns falsy or throws, handler is skipped:
+
+```typescript
+export const lambdaHandler = lambdaServiceHandler({
+  handler,
+  validate: [
+    (event) => event.headers?.authorization !== undefined,
+    async (event) => {
+      const token = event.headers?.authorization;
+      return await verifyToken(token);
+    },
+  ],
+});
+```
+
+## Event Handling
+
+The adapter uses `getMessages()` from `@jaypie/aws` to extract messages from various event types:
+
+- **SQS Events**: Extracts message body from each record
+- **SNS Events**: Extracts message from SNS notification
+- **Direct Invocation**: Uses event body directly
+
+### Single vs Multiple Messages
+
+```typescript
+// Single message returns single response
+const result = await lambdaHandler(singleMessageEvent);
+// result: { orderId: "123", status: "processed" }
+
+// Multiple messages return array of responses
+const results = await lambdaHandler(sqsBatchEvent);
+// results: [
+//   { orderId: "123", status: "processed" },
+//   { orderId: "456", status: "processed" },
+// ]
+```
+
+## Complete Example
+
+```typescript
+import { serviceHandler } from "@jaypie/vocabulary";
+import { lambdaServiceHandler } from "@jaypie/vocabulary/lambda";
+import log from "@jaypie/logger";
+
+const processOrderHandler = serviceHandler({
+  alias: "processOrder",
+  description: "Process an incoming order",
+  input: {
+    orderId: { type: String, description: "Order ID to process" },
+    priority: { type: [1, 2, 3], default: 2 },
+    rush: { type: Boolean, default: false },
+  },
+  service: async ({ orderId, priority, rush }, context) => {
+    context?.sendMessage?.({ content: `Processing order ${orderId}` });
+
+    if (rush) {
+      context?.sendMessage?.({ content: "Rush order - expediting", level: "warn" });
+    }
+
+    // Process the order...
+    await processOrder(orderId, { priority, rush });
+
+    context?.sendMessage?.({ content: "Order processed successfully" });
+    return { orderId, status: "complete", priority, rush };
+  },
+});
+
+export const handler = lambdaServiceHandler({
+  handler: processOrderHandler,
+  name: "order-processor",
+  secrets: ["DATABASE_URL", "STRIPE_API_KEY"],
+  setup: [
+    async () => {
+      await connectToDatabase();
+    },
+  ],
+  teardown: [
+    async () => {
+      await flushMetrics();
+    },
+  ],
+  onMessage: (msg) => {
+    log[msg.level || "info"](msg.content);
+  },
+});
+```
+
+## Error Handling
+
+### Default Behavior
+
+Errors are caught and returned as structured error responses:
+
+```typescript
+// On error, returns:
+{
+  error: true,
+  message: "Error message",
+  statusCode: 500,
+  // ... additional error details
+}
+```
+
+### Re-throwing Errors
+
+Set `throw: true` to re-throw errors (useful for SQS retry behavior):
+
+```typescript
+export const lambdaHandler = lambdaServiceHandler({
+  handler,
+  throw: true, // Errors will propagate, triggering SQS retry
+});
+```
+
+## TypeScript Types
+
+```typescript
+import type {
+  LambdaContext,
+  LambdaServiceHandlerConfig,
+  LambdaServiceHandlerOptions,
+  LambdaServiceHandlerResult,
+  OnCompleteCallback,
+  OnErrorCallback,
+  OnFatalCallback,
+  OnMessageCallback,
+} from "@jaypie/vocabulary/lambda";
+```
+
+## Exports
+
+```typescript
+// @jaypie/vocabulary/lambda
+export { lambdaServiceHandler } from "./lambdaServiceHandler.js";
+
+export type {
+  LambdaContext,
+  LambdaServiceHandlerConfig,
+  LambdaServiceHandlerOptions,
+  LambdaServiceHandlerResult,
+  OnCompleteCallback,
+  OnErrorCallback,
+  OnFatalCallback,
+  OnMessageCallback,
+} from "./types.js";
+```
+
+## Related
+
+- [Jaypie_Vocabulary_Package.md](Jaypie_Vocabulary_Package.md) - Core serviceHandler and type coercion
+- [Jaypie_Init_Lambda_Package.md](Jaypie_Init_Lambda_Package.md) - Setting up Lambda projects

package/prompts/Jaypie_Vocabulary_MCP.md

@@ -0,0 +1,296 @@
+---
+description: MCP server tool registration from serviceHandler
+---
+
+# Jaypie Vocabulary MCP Adapter
+
+The MCP adapter (`@jaypie/vocabulary/mcp`) registers Jaypie service handlers as MCP (Model Context Protocol) tools for use with MCP servers.
+
+**See also:** [Jaypie_Vocabulary_Package.md](Jaypie_Vocabulary_Package.md) for core serviceHandler documentation.
+
+## Installation
+
+```bash
+npm install @jaypie/vocabulary @modelcontextprotocol/sdk
+```
+
+## Quick Start
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { serviceHandler } from "@jaypie/vocabulary";
+import { registerMcpTool } from "@jaypie/vocabulary/mcp";
+
+const handler = serviceHandler({
+  alias: "greet",
+  description: "Greet a user by name",
+  input: {
+    userName: { type: String, description: "The user's name" },
+    loud: { type: Boolean, default: false, description: "Shout the greeting" },
+  },
+  service: ({ userName, loud }) => {
+    const greeting = `Hello, ${userName}!`;
+    return loud ? greeting.toUpperCase() : greeting;
+  },
+});
+
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
+registerMcpTool({ handler, server });
+```
+
+## registerMcpTool
+
+Registers a serviceHandler as an MCP tool.
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `handler` | `ServiceHandlerFunction` | Required. The service handler to adapt |
+| `server` | `McpServer` | Required. The MCP server to register with |
+| `name` | `string` | Override tool name (defaults to handler.alias) |
+| `description` | `string` | Override tool description (defaults to handler.description) |
+| `onComplete` | `OnCompleteCallback` | Called with tool's return value on success |
+| `onError` | `OnErrorCallback` | Receives errors reported via `context.onError()` in service |
+| `onFatal` | `OnFatalCallback` | Receives fatal errors (thrown or via `context.onFatal()`) |
+| `onMessage` | `OnMessageCallback` | Receives messages from `context.sendMessage` in service |
+
+### Basic Usage
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { serviceHandler } from "@jaypie/vocabulary";
+import { registerMcpTool } from "@jaypie/vocabulary/mcp";
+
+const calculateHandler = serviceHandler({
+  alias: "calculate",
+  description: "Perform a mathematical calculation",
+  input: {
+    operation: { type: ["add", "subtract", "multiply", "divide"] },
+    a: { type: Number, description: "First operand" },
+    b: { type: Number, description: "Second operand" },
+  },
+  service: ({ operation, a, b }) => {
+    switch (operation) {
+      case "add": return a + b;
+      case "subtract": return a - b;
+      case "multiply": return a * b;
+      case "divide": return a / b;
+    }
+  },
+});
+
+const server = new McpServer({ name: "calculator", version: "1.0.0" });
+registerMcpTool({ handler: calculateHandler, server });
+```
+
+### Overriding Name and Description
+
+```typescript
+registerMcpTool({
+  handler,
+  server,
+  name: "math_calculate",
+  description: "A tool for performing basic math operations",
+});
+```
+
+### Lifecycle Callbacks
+
+Services can use context callbacks to report progress, errors, and completion:
+
+```typescript
+const handler = serviceHandler({
+  alias: "evaluate",
+  input: { jobId: { type: String } },
+  service: async ({ jobId }, context) => {
+    context?.sendMessage?.({ content: `Processing ${jobId}` });
+
+    try {
+      await riskyOperation();
+    } catch (err) {
+      context?.onError?.(err); // Reports error but continues
+    }
+
+    return { jobId, status: "complete" };
+  },
+});
+
+registerMcpTool({
+  handler,
+  server,
+  onComplete: (result) => console.log("Tool completed:", result),
+  onError: (error) => console.warn("Recoverable error:", error),
+  onFatal: (error) => console.error("Fatal error:", error),
+  onMessage: (msg) => console.log(`[${msg.level || "info"}] ${msg.content}`),
+});
+```
+
+**Error handling**: Services receive `context.onError()` and `context.onFatal()` callbacks to report errors without throwing. Any error that escapes the service (is thrown) is treated as fatal and routes to `onFatal`. If `onFatal` is not provided, thrown errors fall back to `onError`. Callback errors are swallowed to ensure failures never halt service execution.
+
+## Response Format
+
+The adapter formats handler responses as MCP text content:
+
+```typescript
+// Handler returns:
+{ result: 42, status: "complete" }
+
+// MCP response:
+{
+  content: [{
+    type: "text",
+    text: '{"result":42,"status":"complete"}'
+  }]
+}
+```
+
+For string responses:
+
+```typescript
+// Handler returns:
+"Hello, World!"
+
+// MCP response:
+{
+  content: [{
+    type: "text",
+    text: "Hello, World!"
+  }]
+}
+```
+
+## Complete Example
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { serviceHandler } from "@jaypie/vocabulary";
+import { registerMcpTool } from "@jaypie/vocabulary/mcp";
+
+// Define handlers
+const weatherHandler = serviceHandler({
+  alias: "get_weather",
+  description: "Get current weather for a location",
+  input: {
+    location: { type: String, description: "City name" },
+    units: { type: ["celsius", "fahrenheit"], default: "celsius" },
+  },
+  service: async ({ location, units }) => {
+    const weather = await fetchWeather(location);
+    return {
+      location,
+      temperature: units === "celsius" ? weather.tempC : weather.tempF,
+      units,
+      conditions: weather.conditions,
+    };
+  },
+});
+
+const searchHandler = serviceHandler({
+  alias: "search",
+  description: "Search for information",
+  input: {
+    query: { type: String, description: "Search query" },
+    limit: { type: Number, default: 10 },
+  },
+  service: async ({ query, limit }) => {
+    return await performSearch(query, { limit });
+  },
+});
+
+// Create server and register tools
+const server = new McpServer({
+  name: "my-mcp-server",
+  version: "1.0.0",
+});
+
+registerMcpTool({ handler: weatherHandler, server });
+registerMcpTool({ handler: searchHandler, server });
+
+// Start server
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+## Input Validation
+
+The adapter delegates input validation to the service handler. Invalid inputs result in errors:
+
+```typescript
+// If handler expects:
+input: {
+  priority: { type: [1, 2, 3, 4, 5] },
+  email: { type: /^[^@]+@[^@]+\.[^@]+$/ },
+}
+
+// Invalid calls throw BadRequestError:
+// { priority: 10 }     → Validation fails
+// { email: "invalid" } → Pattern mismatch
+```
+
+## TypeScript Types
+
+```typescript
+import type {
+  McpToolContentItem,
+  McpToolResponse,
+  OnCompleteCallback,
+  OnErrorCallback,
+  OnFatalCallback,
+  OnMessageCallback,
+  RegisterMcpToolConfig,
+  RegisterMcpToolResult,
+} from "@jaypie/vocabulary/mcp";
+```
+
+### Type Definitions
+
+```typescript
+interface McpToolContentItem {
+  type: "text";
+  text: string;
+}
+
+interface McpToolResponse {
+  content: McpToolContentItem[];
+}
+
+interface RegisterMcpToolConfig {
+  handler: ServiceHandlerFunction;
+  server: McpServer;
+  name?: string;
+  description?: string;
+  onComplete?: OnCompleteCallback;
+  onError?: OnErrorCallback;
+  onFatal?: OnFatalCallback;
+  onMessage?: OnMessageCallback;
+}
+
+interface RegisterMcpToolResult {
+  name: string;
+}
+```
+
+## Exports
+
+```typescript
+// @jaypie/vocabulary/mcp
+export { registerMcpTool } from "./registerMcpTool.js";
+
+export type {
+  McpToolContentItem,
+  McpToolResponse,
+  OnCompleteCallback,
+  OnErrorCallback,
+  OnFatalCallback,
+  OnMessageCallback,
+  RegisterMcpToolConfig,
+  RegisterMcpToolResult,
+} from "./types.js";
+```
+
+## Related
+
+- [Jaypie_Vocabulary_Package.md](Jaypie_Vocabulary_Package.md) - Core serviceHandler and type coercion
+- [Jaypie_Vocabulary_LLM.md](Jaypie_Vocabulary_LLM.md) - LLM tool creation (similar pattern)