@jaypie/mcp 0.4.0 → 0.4.1

package/dist/suite.js

@@ -1202,7 +1202,7 @@ async function purgeSQSQueue(options, logger = nullLogger) {
 
 // ServiceSuite for @jaypie/mcp
 // Provides metadata and direct execution for Jaypie MCP services
-const BUILD_VERSION_STRING = "@jaypie/mcp@0.4.0#988a2bd8"
+const BUILD_VERSION_STRING = "@jaypie/mcp@0.4.1#c7b5feb2"
     ;
 const __filename$1 = fileURLToPath(import.meta.url);
 const __dirname$1 = path.dirname(__filename$1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/mcp",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",

package/release-notes/constructs/1.2.18.md

@@ -0,0 +1,12 @@
+---
+version: 1.2.18
+date: 2025-01-21
+summary: JaypieNextJs supports domain-less CloudFront-only deployment
+---
+
+## Changes
+
+- Added `domainProps: false` option to `JaypieNextJs` to deploy without a custom domain
+- When `domainProps: false`, the application is accessible only via CloudFront URL
+- `NEXT_PUBLIC_SITE_URL` is automatically set to the CloudFront distribution URL when no domain is configured
+- Cache policy names use construct ID instead of domain name for domain-less deployments

package/release-notes/llm/1.2.5.md

@@ -0,0 +1,25 @@
+---
+version: 1.2.5
+date: 2025-01-21
+summary: Preserve original error details in BadGatewayError thrown by RetryExecutor
+---
+
+## Changes
+
+### Bug Fixes
+
+- **Preserve original error message in BadGatewayError**: When `RetryExecutor` encounters a non-retryable error or exhausts retries, it now preserves the original error message in the thrown `BadGatewayError`. Previously, the original error details (e.g., "Quota exceeded for metric X, limit: 0") were lost, making debugging difficult.
+
+### Before
+
+```
+JaypieError: An unexpected error occurred on an upstream resource
+```
+
+### After
+
+```
+JaypieError: You exceeded your current quota... limit: 0
+```
+
+This fix improves debugging by preserving context from LLM provider errors (like Gemini's 429 quota exceeded responses).

package/release-notes/llm/1.2.6.md

@@ -0,0 +1,55 @@
+---
+version: 1.2.6
+date: 2025-01-21
+summary: Add configurable fallback provider chain for automatic retry with alternative providers
+---
+
+## Changes
+
+### New Features
+
+- **Fallback Provider Support**: Configure a chain of fallback providers that automatically retry failed `operate()` calls when the primary provider fails with an unrecoverable error.
+
+### Usage
+
+```typescript
+// Instance-level configuration
+const llm = new Llm("anthropic", {
+  model: "claude-sonnet-4",
+  fallback: [
+    { provider: "openai", model: "gpt-4o" },
+    { provider: "gemini", model: "gemini-2.0-flash" },
+  ],
+});
+
+// Per-call override
+const response = await llm.operate(input, {
+  fallback: [{ provider: "openai", model: "gpt-4o" }],
+});
+
+// Disable fallback for specific call
+const response = await llm.operate(input, { fallback: false });
+
+// Static method with fallback
+const response = await Llm.operate(input, {
+  model: "claude-sonnet-4",
+  fallback: [{ provider: "openai", model: "gpt-4o" }],
+});
+```
+
+### Response Metadata
+
+The `LlmOperateResponse` now includes:
+- `provider`: Which provider actually handled the request
+- `fallbackUsed`: `true` if a fallback provider was used
+- `fallbackAttempts`: Number of providers tried (1 = primary only)
+
+### New Type
+
+```typescript
+interface LlmFallbackConfig {
+  provider: string;
+  model?: string;
+  apiKey?: string;
+}
+```

package/skills/agents.md

@@ -1,25 +1,35 @@
 ---
-description: Minimal agent instructions
+description: Recommended prompts to help agents use Jaypie; to put in AGENTS.md, CLAUDE.md, etc.
+related: jaypie
 ---
 
 # Agent Instructions
 
-Add to CLAUDE.md or AGENTS.md:
+The goal is concise introduction to Jaypie capabilities that invite agent exploration.
+
+Add one of the following to AGENTS.md, CLAUDE.md, or similar files.
+
+## Complete Version
+
+The complete version references as many daily tasks as possible without listing everything.
+Some tasks should not be listed to avoid suboptimal pathing.
 
 ```markdown
 ## Jaypie
 
 Query `mcp__jaypie__skill(alias: String)` for development guidance:
 
-Contents: index, releasenotes, topics
-Development: debugging, errors, logs, mocks, style, tests, writing
+Contents: index, releasenotes
+Development: documentation, errors, logs, mocks, style, tests
 Infrastructure: aws, cdk, cicd, datadog, dns, dynamodb, secrets, variables
-Patterns: fabric, models, services, tools
-Meta: agents, jaypie, legacy
+Patterns: fabric, models, services, vocabulary
+Meta: issues, jaypie, skills, tools
 ```
 
-Or, for one line,
+## Short Version
+
+The one-line version tells the agent how to find out more about Jaypie skills.
 
 ```markdown
-`mcp__jaypie__skill(index)` describes Jaypie development skills for this repository.
+`mcp__jaypie__skill(skills)`: Discover Jaypie development skills and tools available in this repository.
 ```

package/skills/aws.md

@@ -1,107 +1,279 @@
 ---
-description: AWS integration, CLI tools, and cloud services
-related: cdk, dynamodb, secrets, logs
+description: AWS integration and cloud services code patterns
+related: cdk, dynamodb, secrets, logs, tools-aws
 ---
 
 # AWS Integration
 
-Jaypie integrates with AWS services through SDK utilities and CLI tools available via the MCP.
+Jaypie integrates with AWS services through the `@jaypie/aws` package and CDK constructs.
+Access `@jaypie/aws` through the main `jaypie` package.
 
-## MCP AWS Tools
+## MCP Tools
 
-The Jaypie MCP provides AWS tools that use your local AWS credentials:
+For interactive AWS tools (Lambda, S3, SQS, CloudWatch, Step Functions, CloudFormation), see **tools-aws**.
 
-### Lambda Functions
-```
-aws_lambda_list_functions     - List functions with optional prefix filter
-aws_lambda_get_function       - Get function configuration and details
-```
+## @jaypie/aws Package
 
-### Step Functions
-```
-aws_stepfunctions_list_executions  - List executions for a state machine
-aws_stepfunctions_stop_execution   - Stop a running execution
-```
+The `@jaypie/aws` package provides SDK utilities for Secrets Manager, SQS, S3, Textract, and streaming.
 
-### CloudWatch Logs
-```
-aws_logs_filter_log_events    - Search logs with patterns and time ranges
+```typescript
+import {
+  getEnvSecret,
+  getMessages,
+  getS3FileBuffer,
+  loadEnvSecrets,
+  sendBatchMessages,
+  sendMessage,
+} from "@jaypie/aws";
 ```
 
-### S3
-```
-aws_s3_list_objects           - List bucket objects with prefix filtering
-```
+### Available Functions
+
+| Function | Description |
+|----------|-------------|
+| **Secrets** | |
+| `getEnvSecret(name, { env? })` | Preferred: Fetch secret using env var patterns |
+| `loadEnvSecrets(...names)` | Load multiple secrets into `process.env` |
+| `getSecret(name)` | Internal: Direct fetch by AWS secret name |
+| **SQS Messaging** | |
+| `sendMessage(body, { queueUrl?, ... })` | Send single message to SQS |
+| `sendBatchMessages({ messages, queueUrl?, ... })` | Send multiple messages (batched in groups of 10) |
+| `getMessages(event)` | Parse SQS/SNS event into array of message bodies |
+| `getSingletonMessage(event)` | Get exactly one message or throw `BadGatewayError` |
+| **S3** | |
+| `getS3FileBuffer({ bucket, key })` | Fetch S3 file as Buffer |
+| **Textract** | |
+| `sendTextractJob({ bucket, key, ... })` | Start async Textract job |
+| `getTextractJob(jobId)` | Get results of completed Textract job |
+| **Streaming** | |
+| `JaypieStream` | Class wrapping async iterable with streaming methods |
+| `createJaypieStream(source)` | Factory for JaypieStream |
+| `createLambdaStream(stream, writer)` | Stream to Lambda response writer |
+| `createExpressStream(stream, res)` | Stream to Express response |
+
+## Secrets Management
 
-### DynamoDB
+### getEnvSecret (Preferred)
+
+Use `getEnvSecret` for environment-aware secret resolution. It checks environment variables in order:
+
+1. `SECRET_{name}` - Explicit secret reference (fetches from Secrets Manager)
+2. `{name}_SECRET` - Alternative secret reference (fetches from Secrets Manager)
+3. `{name}` - Returns direct value without AWS call
+
+```typescript
+import { getEnvSecret } from "@jaypie/aws";
+
+// If SECRET_ANTHROPIC_API_KEY="arn:aws:secretsmanager:..." exists, fetches from AWS
+// Otherwise returns process.env.ANTHROPIC_API_KEY directly
+const apiKey = await getEnvSecret("ANTHROPIC_API_KEY");
 ```
-aws_dynamodb_describe_table   - Get table metadata and indexes
-aws_dynamodb_scan             - Scan table (use sparingly)
-aws_dynamodb_query            - Query by partition key
-aws_dynamodb_get_item         - Get single item by key
+
+This pattern allows the same code to work locally (with direct env values) and in Lambda (with secret references).
+
+### loadEnvSecrets
+
+Load multiple secrets at once during handler initialization:
+
+```typescript
+import { loadEnvSecrets } from "@jaypie/aws";
+
+// Load secrets and set in process.env
+await loadEnvSecrets("ANTHROPIC_API_KEY", "OPENAI_API_KEY");
+
+// Now available as process.env.ANTHROPIC_API_KEY, etc.
 ```
 
-### SQS
+### getSecret (Internal Use)
+
+Direct fetch by AWS secret name. Requires `AWS_SESSION_TOKEN`. Prefer `getEnvSecret` unless you need to fetch a secret by its exact AWS name:
+
+```typescript
+import { getSecret } from "@jaypie/aws";
+
+// Fetch by exact AWS secret name
+const secret = await getSecret("my-project/production/api-key");
 ```
-aws_sqs_list_queues           - List queues with prefix filter
-aws_sqs_get_queue_attributes  - Get queue attributes
-aws_sqs_receive_message       - Peek at queue messages
-aws_sqs_purge_queue           - Delete all messages (irreversible)
+
+## SQS Messaging
+
+### sendMessage
+
+Send a single message to SQS. Uses `CDK_ENV_QUEUE_URL` by default:
+
+```typescript
+import { sendMessage } from "@jaypie/aws";
+
+// Simple usage with default queue
+await sendMessage({ action: "process", documentId: "doc-123" });
+
+// With explicit queue URL
+await sendMessage({ action: "process" }, { queueUrl: "https://sqs..." });
+
+// With options
+await sendMessage(
+  { action: "process" },
+  {
+    delaySeconds: 30,
+    messageAttributes: { Priority: { DataType: "String", StringValue: "high" } },
+    queueUrl: process.env.CDK_ENV_QUEUE_URL,
+  }
+);
 ```
 
-### CloudFormation
+### sendBatchMessages
+
+Send multiple messages, automatically batched in groups of 10:
+
+```typescript
+import { sendBatchMessages } from "@jaypie/aws";
+
+const messages = items.map((item) => ({ action: "process", id: item.id }));
+await sendBatchMessages({ messages });
 ```
-aws_cloudformation_describe_stack  - Get stack details and outputs
+
+### getMessages and getSingletonMessage
+
+Parse incoming SQS/SNS events:
+
+```typescript
+import { getMessages, getSingletonMessage } from "@jaypie/aws";
+
+// Get all messages from event
+const messages = getMessages(event); // Returns array
+
+// Get exactly one message or throw BadGatewayError
+const message = getSingletonMessage(event);
 ```
 
-## Credential Management
+## S3 Operations
 
-Tools use the host's AWS credential chain:
-1. Environment variables (`AWS_ACCESS_KEY_ID`, etc.)
-2. `~/.aws/credentials` and `~/.aws/config`
-3. SSO sessions via `aws sso login`
+### getS3FileBuffer
 
-```bash
-# List available profiles
-aws_list_profiles
+Fetch a file from S3 as a Buffer:
+
+```typescript
+import { getS3FileBuffer } from "@jaypie/aws";
 
-# Use a specific profile
-aws_lambda_list_functions --profile production
+const buffer = await getS3FileBuffer({
+  bucket: process.env.CDK_ENV_BUCKET,
+  key: "documents/report.pdf",
+});
 ```
 
-## Jaypie AWS Package
+## Textract
 
-The `@jaypie/aws` package provides SDK utilities:
+### Document Processing
 
 ```typescript
-import { getSecret, sendMessage } from "@jaypie/aws";
+import { sendTextractJob, getTextractJob } from "@jaypie/aws";
 
-// Get secret from Secrets Manager
-const apiKey = await getSecret("my-api-key");
+// Start async job
+const { JobId } = await sendTextractJob({
+  bucket: process.env.CDK_ENV_BUCKET,
+  key: "documents/scan.pdf",
+});
 
-// Send SQS message
-await sendMessage(queueUrl, { action: "process", id: "123" });
+// Later, retrieve results
+const results = await getTextractJob(JobId);
 ```
 
-## Environment-Based Configuration
-
-Use CDK environment variables in Lambda:
+## Environment Variables
 
 | Variable | Description |
 |----------|-------------|
-| `CDK_ENV_BUCKET` | S3 bucket name |
-| `CDK_ENV_QUEUE_URL` | SQS queue URL |
+| `AWS_SESSION_TOKEN` | Required for secrets access in Lambda |
+| `CDK_ENV_BUCKET` | Default S3 bucket name |
+| `CDK_ENV_QUEUE_URL` | Default SQS queue URL |
 | `CDK_ENV_SNS_TOPIC_ARN` | SNS topic ARN |
+| `CDK_ENV_SNS_ROLE_ARN` | SNS role ARN |
+| `PROJECT_KEY` | Used for FIFO queue message group ID |
 
-## Profile Selection
+## Credential Management
 
-When working with multiple AWS accounts:
+### Local Development
+
+Configure credentials via environment or files:
 
 ```bash
 # Set default profile
 export AWS_PROFILE=development
 
-# Or specify per-command via MCP tools
-aws_lambda_list_functions --profile production --region us-west-2
+# Or use named profiles
+export AWS_PROFILE=production
+```
+
+Credential chain priority:
+1. Environment variables (`AWS_ACCESS_KEY_ID`, etc.)
+2. `~/.aws/credentials` and `~/.aws/config`
+3. SSO sessions via `aws sso login`
+
+### Lambda Runtime
+
+Lambda functions automatically receive credentials via IAM role. Use CDK to grant permissions:
+
+```typescript
+import { JaypieLambda } from "@jaypie/constructs";
+
+const handler = new JaypieLambda(this, "Handler", {
+  entry: "src/handler.ts",
+});
+
+// Grant S3 access
+bucket.grantReadWrite(handler);
+
+// Grant SQS access
+queue.grantSendMessages(handler);
+
+// Grant Secrets Manager access
+secret.grantRead(handler);
 ```
 
+## Error Handling
+
+Handle AWS errors with Jaypie patterns:
+
+```typescript
+import { getEnvSecret } from "@jaypie/aws";
+import { ConfigurationError, log } from "jaypie";
+
+async function getApiKey() {
+  try {
+    return await getEnvSecret("API_KEY");
+  } catch (error) {
+    log.error("Failed to retrieve API key", { error });
+    throw new ConfigurationError("API key not configured");
+  }
+}
+```
+
+## Testing
+
+Mock AWS functions in tests:
+
+```typescript
+import { getEnvSecret, sendMessage } from "@jaypie/testkit/mock";
+import { vi } from "vitest";
+
+vi.mock("@jaypie/aws");
+
+describe("Handler", () => {
+  it("sends message to queue", async () => {
+    vi.mocked(sendMessage).mockResolvedValue({ MessageId: "123" });
+
+    await handler({ documentId: "doc-123" });
+
+    expect(sendMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ documentId: "doc-123" })
+    );
+  });
+
+  it("fetches secret from environment", async () => {
+    vi.mocked(getEnvSecret).mockResolvedValue("test-api-key");
+
+    const key = await getApiKey();
+
+    expect(key).toBe("test-api-key");
+  });
+});
+```

package/skills/datadog.md

@@ -1,61 +1,15 @@
 ---
-description: Datadog integration and observability
-related: logs, debugging, aws
+description: Datadog integration, logging, and observability code patterns
+related: logs, debugging, aws, tools-datadog
 ---
 
 # Datadog Integration
 
 Jaypie integrates with Datadog for logging, monitoring, and APM.
 
-## MCP Datadog Tools
+## MCP Tools
 
-The Jaypie MCP provides tools for querying Datadog:
-
-### Log Search
-```
-datadog_logs          - Search individual log entries
-datadog_log_analytics - Aggregate logs with groupBy
-```
-
-### Monitoring
-```
-datadog_monitors      - List and check monitor status
-datadog_synthetics    - List synthetic tests and results
-datadog_metrics       - Query timeseries metrics
-datadog_rum           - Search Real User Monitoring events
-```
-
-## Environment Variables
-
-Configure Datadog tools via environment:
-
-| Variable | Description |
-|----------|-------------|
-| `DATADOG_API_KEY` or `DD_API_KEY` | API key |
-| `DATADOG_APP_KEY` or `DD_APP_KEY` | Application key |
-| `DD_ENV` | Default environment filter |
-| `DD_SERVICE` | Default service filter |
-| `DD_SOURCE` | Default log source (default: lambda) |
-
-## Common Queries
-
-### Search Error Logs
-
-```
-datadog_logs --query "status:error" --from "now-1h"
-```
-
-### Count Errors by Service
-
-```
-datadog_log_analytics --groupBy '["service"]' --query "status:error"
-```
-
-### Check Alerting Monitors
-
-```
-datadog_monitors --status '["Alert", "Warn"]'
-```
+For interactive Datadog tools (logs, monitors, metrics, synthetics, RUM), see **tools-datadog**.
 
 ## Lambda Integration
 
@@ -65,6 +19,7 @@ Enable Datadog tracing in CDK:
 import { JaypieLambda } from "@jaypie/constructs";
 
 const handler = new JaypieLambda(this, "Handler", {
+  entry: "src/handler.ts",
   datadogApiKeyArn: process.env.CDK_ENV_DATADOG_API_KEY_ARN,
   environment: {
     DD_ENV: "production",
@@ -87,26 +42,32 @@ log.info("Request processed", {
   action: "checkout",
   duration: 150,
 });
+
+// Error logs include stack traces
+log.error("Payment failed", {
+  error,
+  orderId: "order-456",
+});
 ```
 
-## Query Syntax
+## @jaypie/datadog Package
 
-### Log Search Syntax
+The `@jaypie/datadog` package provides utilities:
 
-```
-status:error                    # By status
-@http.status_code:500          # By attribute
-service:my-api                  # By service
-*timeout*                       # Wildcard
-```
+```typescript
+import { datadogMetric, datadogEvent } from "@jaypie/datadog";
 
-### Time Ranges
+// Send custom metric
+await datadogMetric("checkout.completed", 1, {
+  tags: ["env:production", "service:checkout"],
+});
 
-```
-now-15m                         # Last 15 minutes
-now-1h                          # Last hour
-now-1d                          # Last day
-2024-01-15T10:00:00Z           # Specific time (ISO 8601)
+// Send event
+await datadogEvent({
+  title: "Deployment completed",
+  text: "Version 1.2.3 deployed to production",
+  tags: ["env:production"],
+});
 ```
 
 ## Unified Service Tagging
@@ -127,3 +88,76 @@ environment: {
 }
 ```
 
+## Environment Variables
+
+### CDK Configuration
+
+| Variable | Description |
+|----------|-------------|
+| `CDK_ENV_DATADOG_API_KEY_ARN` | Datadog API key ARN in Secrets Manager |
+
+### Lambda Environment
+
+| Variable | Description |
+|----------|-------------|
+| `DD_ENV` | Environment tag |
+| `DD_SERVICE` | Service tag |
+| `DD_VERSION` | Version tag |
+| `DD_TRACE_ENABLED` | Enable APM tracing |
+| `DD_LOGS_INJECTION` | Inject trace IDs in logs |
+
+## Trace Correlation
+
+Correlate logs with traces:
+
+```typescript
+import { log, getTraceContext } from "jaypie";
+
+function processRequest() {
+  const traceContext = getTraceContext();
+
+  log.info("Processing request", {
+    ...traceContext,
+    requestId: "req-123",
+  });
+}
+```
+
+## Custom Metrics
+
+Send custom metrics from Lambda:
+
+```typescript
+import { log } from "jaypie";
+
+// Use log for metrics that Datadog indexes
+log.info("MONITORING", {
+  metric: "orders.processed",
+  value: 1,
+  tags: { env: "production", region: "us-east-1" },
+});
+```
+
+## Testing
+
+Mock Datadog in tests:
+
+```typescript
+import { datadogMetric } from "@jaypie/datadog";
+import { vi } from "vitest";
+
+vi.mock("@jaypie/datadog");
+
+describe("CheckoutService", () => {
+  it("sends metric on completion", async () => {
+    await processCheckout();
+
+    expect(datadogMetric).toHaveBeenCalledWith(
+      "checkout.completed",
+      1,
+      expect.objectContaining({ tags: expect.any(Array) })
+    );
+  });
+});
+```
+