@jaypie/mcp 0.3.4 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/mcp",
-  "version": "0.3.4",
+  "version": "0.4.1",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",
@@ -26,7 +26,6 @@
   },
   "files": [
     "dist",
-    "prompts",
     "release-notes",
     "skills"
   ],

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/fabric/0.1.3.md

@@ -0,0 +1,25 @@
+---
+version: 0.1.3
+date: 2025-01-20
+summary: Added FabricMcpServer for multi-service MCP tool registration
+---
+
+## Changes
+
+- Added `FabricMcpServer` function for creating MCP servers with multiple services registered as tools
+- Added `isFabricMcpServer` type guard for runtime type checking
+- Added `isService` export from main package for checking if a value is a fabricated service
+- New types: `FabricMcpServerConfig`, `FabricMcpServerServiceEntry`, `FabricMcpServerToolConfig`, `RegisteredTool`
+
+## Usage
+
+```typescript
+import { fabricService } from "@jaypie/fabric";
+import { FabricMcpServer } from "@jaypie/fabric/mcp";
+
+const server = FabricMcpServer({
+  name: "my-server",
+  version: "1.0.0",
+  services: [greetService, echoService],
+});
+```

package/release-notes/fabric/0.1.4.md

@@ -0,0 +1,42 @@
+---
+version: 0.1.4
+date: 2025-01-20
+summary: Added ServiceSuite bridge for MCP servers
+---
+
+## Changes
+
+- Added `getServiceFunctions()` method to `ServiceSuite` - returns all registered service functions for transport adapters
+- Added `getServiceFunction(name)` method to `ServiceSuite` - returns a specific service function by name
+- Added `createMcpServerFromSuite()` function in `@jaypie/fabric/mcp` - creates FabricMcpServer from a ServiceSuite
+- New type: `CreateMcpServerFromSuiteConfig`
+
+## Usage
+
+ServiceSuites now connect directly to MCP servers:
+
+```typescript
+import { createServiceSuite, fabricService } from "@jaypie/fabric";
+import { createMcpServerFromSuite } from "@jaypie/fabric/mcp";
+
+const suite = createServiceSuite({ name: "my-suite", version: "1.0.0" });
+suite.register(myService, "category");
+
+// Create MCP server from suite
+const server = createMcpServerFromSuite(suite);
+// All suite services are now registered as MCP tools
+
+// Access service functions directly
+const functions = suite.getServiceFunctions();
+const specific = suite.getServiceFunction("my-service");
+```
+
+## Architecture
+
+This enables a pattern where services are defined once and deployed to multiple transports:
+
+```
+fabricService() → ServiceSuite → createMcpServerFromSuite() → MCP Server
+                              → FabricHttpServer → HTTP/Lambda
+                              → FabricRouter → Express
+```

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/release-notes/mcp/0.4.0.md

@@ -0,0 +1,27 @@
+---
+version: 0.4.0
+date: 2025-01-20
+summary: Remove deprecated list_prompts and read_prompt tools
+---
+
+## Changes
+
+### Breaking Changes
+
+- **Removed `list_prompts` tool**: Use `skill("index")` instead
+- **Removed `read_prompt` tool**: Use `skill(alias)` instead
+- **Removed `prompts/` directory from package**: All documentation now lives in `skills/`
+
+### Migration
+
+If you were using `list_prompts`, replace with:
+```
+skill("index")
+```
+
+If you were using `read_prompt("Jaypie_Express_Package.md")`, find the equivalent skill alias and use:
+```
+skill("express")  // or appropriate alias
+```
+
+Use `skill("index")` to see all available skills with descriptions.

package/release-notes/testkit/1.2.15.md

@@ -0,0 +1,23 @@
+---
+version: 1.2.15
+date: 2025-01-20
+summary: Removed vocabulary mocks, updated to fabric types
+---
+
+## Changes
+
+- Removed `vocabulary` mock module (vocabulary package deprecated)
+- Updated `IndexableEntity` type import to `IndexableModel` from `@jaypie/fabric`
+- Removed `mock.vocabulary` exports from mock index
+
+## Migration
+
+If you were using vocabulary mocks, they are no longer needed as the functionality has moved to `@jaypie/fabric`:
+
+```typescript
+// Before
+import { IndexableEntity } from "@jaypie/testkit/mock";
+
+// After
+import { IndexableModel } from "@jaypie/fabric";
+```

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");
+  });
+});
+```