@jaypie/mcp 0.3.4 → 0.4.1

package/skills/llm.md

@@ -0,0 +1,381 @@
+---
+description: Using @jaypie/llm for unified LLM access
+related: fabric, tools, tests
+---
+
+# @jaypie/llm
+
+Unified interface for calling LLM providers with multi-turn conversations, tool calling, streaming, and structured output.
+
+## Quick Start
+
+```typescript
+import Llm from "@jaypie/llm";
+
+// Auto-detect provider from model name
+const response = await Llm.operate("What is 2+2?", { model: "claude-sonnet-4" });
+console.log(response.content); // "4"
+```
+
+## Providers and Models
+
+| Provider | Match Keywords | Default Model |
+|----------|----------------|---------------|
+| OpenAI | "openai", "gpt", /^o\d/ | gpt-5.1 |
+| Anthropic | "anthropic", "claude", "haiku", "opus", "sonnet" | claude-sonnet-4-5 |
+| Gemini | "gemini", "google" | gemini-3-pro-preview |
+| OpenRouter | "openrouter" | z-ai/glm-4.7 |
+
+```typescript
+// Provider auto-detected from model
+await Llm.operate(input, { model: "gpt-5.1" });      // OpenAI
+await Llm.operate(input, { model: "claude-opus-4" }); // Anthropic
+await Llm.operate(input, { model: "gemini-3" });     // Gemini
+```
+
+## Core Methods
+
+### operate() - Multi-turn with Tools
+
+The primary method for complex interactions:
+
+```typescript
+const response = await Llm.operate(input, {
+  model: "gpt-5.1",
+  system: "You are a helpful assistant",
+  tools: toolkit,
+  turns: 5, // Allow up to 5 conversation turns
+});
+
+// Response structure
+response.content;    // string | object (structured output)
+response.history;    // LlmHistory - for follow-up calls
+response.usage;      // Token usage per turn
+response.reasoning;  // Extended thinking (if available)
+response.status;     // "completed" | "incomplete" | "in_progress"
+```
+
+### send() - Simple Completions
+
+For single-shot text completions:
+
+```typescript
+const response = await Llm.send("Explain REST APIs", {
+  model: "claude-sonnet-4",
+  system: "You are a technical writer",
+});
+```
+
+### stream() - Streaming Responses
+
+For real-time output:
+
+```typescript
+for await (const chunk of Llm.stream("Tell me a story", { model: "gpt-5.1" })) {
+  switch (chunk.type) {
+    case "text":
+      process.stdout.write(chunk.content);
+      break;
+    case "tool_call":
+      console.log(`Tool: ${chunk.toolCall.name}`);
+      break;
+    case "done":
+      console.log("Usage:", chunk.usage);
+      break;
+  }
+}
+```
+
+## Tool Calling
+
+### Define Tools with Toolkit
+
+```typescript
+import Llm, { Toolkit } from "@jaypie/llm";
+
+const toolkit = new Toolkit([
+  {
+    name: "get_weather",
+    description: "Get current weather for a city",
+    type: "function",
+    parameters: {
+      type: "object",
+      properties: {
+        city: { type: "string", description: "City name" },
+      },
+      required: ["city"],
+    },
+    call: async ({ city }) => {
+      // Actual implementation
+      return { temp: 72, conditions: "sunny" };
+    },
+  },
+]);
+
+const response = await Llm.operate("What's the weather in NYC?", {
+  model: "gpt-5.1",
+  tools: toolkit,
+});
+```
+
+### Built-in Tools
+
+```typescript
+import Llm, { tools, JaypieToolkit } from "@jaypie/llm";
+
+// Use individual tools
+const response = await Llm.operate("Roll 2d6", {
+  model: "gpt-5.1",
+  tools,  // Includes: random, roll, time, weather
+});
+
+// Or use the pre-configured toolkit
+const toolkit = new JaypieToolkit();
+```
+
+### Fabric Services as Tools
+
+```typescript
+import { fabricLlmTool } from "@jaypie/fabric";
+
+const greetTool = fabricLlmTool(greetService);
+const toolkit = new Toolkit([greetTool]);
+```
+
+## Structured Output
+
+### Natural Schema
+
+```typescript
+const result = await Llm.operate("Extract contact info from: John Doe, john@example.com, 555-1234", {
+  model: "gpt-5.1",
+  format: {
+    name: String,
+    email: String,
+    phone: String,
+  },
+});
+// result.content = { name: "John Doe", email: "john@example.com", phone: "555-1234" }
+```
+
+### Zod Schema
+
+```typescript
+import { z } from "zod";
+
+const PersonSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+  hobbies: z.array(z.string()),
+});
+
+const result = await Llm.operate("Parse: Alice is 30 and likes hiking and reading", {
+  model: "gpt-5.1",
+  format: PersonSchema,
+});
+```
+
+## Conversation History
+
+Continue conversations across calls:
+
+```typescript
+const first = await Llm.operate("My name is Alice", { model: "gpt-5.1" });
+
+const second = await Llm.operate("What's my name?", {
+  model: "gpt-5.1",
+  history: first.history,
+});
+// second.content = "Your name is Alice"
+```
+
+## Input with Files and Images
+
+```typescript
+const response = await Llm.operate([
+  "Analyze these documents",
+  { file: "report.pdf", bucket: "my-bucket" },
+  { image: "chart.png" },
+], {
+  model: "claude-sonnet-4",
+});
+```
+
+## Placeholders and Data
+
+Substitute data into prompts:
+
+```typescript
+const response = await Llm.operate("Summarize the article about {{topic}}", {
+  model: "gpt-5.1",
+  data: { topic: "climate change" },
+  placeholders: { input: true },
+});
+```
+
+## Lifecycle Hooks
+
+Monitor and react to LLM operations:
+
+```typescript
+const response = await Llm.operate(input, {
+  model: "gpt-5.1",
+  hooks: {
+    beforeEachModelRequest: ({ providerRequest }) => {
+      console.log("Sending request...");
+    },
+    afterEachModelResponse: ({ content, usage }) => {
+      console.log(`Tokens: ${usage.total}`);
+    },
+    beforeEachTool: ({ toolName, args }) => {
+      console.log(`Calling ${toolName} with`, args);
+    },
+    afterEachTool: ({ result, toolName }) => {
+      console.log(`${toolName} returned:`, result);
+    },
+    onToolError: ({ error, toolName }) => {
+      console.error(`${toolName} failed:`, error);
+    },
+  },
+});
+```
+
+## Fallback Providers
+
+Configure a chain of fallback providers that automatically retry failed calls when the primary provider fails:
+
+```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" }],
+});
+```
+
+### Fallback Response Metadata
+
+```typescript
+response.provider;        // Which provider handled the request
+response.fallbackUsed;    // true if a fallback was used
+response.fallbackAttempts; // Number of providers tried (1 = primary only)
+```
+
+## Instance Usage
+
+For repeated calls with same configuration:
+
+```typescript
+const llm = new Llm("anthropic", {
+  model: "claude-sonnet-4",
+  system: "You are a code reviewer",
+});
+
+const review1 = await llm.operate(code1);
+const review2 = await llm.operate(code2);
+```
+
+## Environment Variables
+
+```bash
+OPENAI_API_KEY      # Required for OpenAI
+ANTHROPIC_API_KEY   # Required for Anthropic
+GOOGLE_API_KEY      # Required for Gemini
+OPENROUTER_API_KEY  # Required for OpenRouter
+```
+
+Keys are resolved via `getEnvSecret()` which supports AWS Secrets Manager.
+
+## Error Handling
+
+The package auto-retries rate limits and transient errors:
+
+```typescript
+try {
+  const response = await Llm.operate(input, { model: "gpt-5.1" });
+  if (response.status !== "completed") {
+    console.log("Incomplete:", response.error);
+  }
+} catch (error) {
+  // Unrecoverable errors (auth, validation) throw
+}
+```
+
+## Testing Pattern
+
+```typescript
+import { describe, expect, it, vi } from "vitest";
+import Llm, { Toolkit } from "@jaypie/llm";
+
+describe("LLM Integration", () => {
+  it("calls tool and returns response", async () => {
+    const mockTool = {
+      name: "calculate",
+      description: "Perform calculation",
+      type: "function",
+      parameters: { type: "object", properties: { expr: { type: "string" } } },
+      call: vi.fn().mockResolvedValue("42"),
+    };
+
+    const toolkit = new Toolkit([mockTool]);
+    const response = await Llm.operate("Calculate 6*7", {
+      model: "gpt-5.1",
+      tools: toolkit,
+    });
+
+    expect(mockTool.call).toHaveBeenCalled();
+    expect(response.status).toBe("completed");
+  });
+});
+```
+
+## Best Practices
+
+1. **Use operate() over send()** - More flexible, handles tools and structure
+2. **Set turns appropriately** - Default is 1; increase for tool-heavy workflows
+3. **Provide clear tool descriptions** - LLMs use these to decide which tool to call
+4. **Use structured output** - More reliable than parsing free text
+5. **Track usage** - Monitor `response.usage` for cost management
+6. **Handle incomplete status** - Check `response.status` for tool errors or limits
+7. **Configure fallbacks** - Set up fallback providers for resilience against outages
+
+## Common Options
+
+```typescript
+interface LlmOperateOptions {
+  data?: Record<string, any>;           // Placeholder substitution data
+  fallback?: LlmFallbackConfig[] | false; // Fallback provider chain
+  format?: JsonObject | ZodType;        // Structured output schema
+  history?: LlmHistory;                 // Previous conversation
+  hooks?: LlmHooks;                     // Lifecycle callbacks
+  instructions?: string;                // Additional instructions
+  model?: string;                       // Model override
+  system?: string;                      // System prompt
+  tools?: LlmTool[] | Toolkit;         // Available tools
+  turns?: boolean | number;             // Max conversation turns
+  user?: string;                        // User ID for logging
+}
+
+interface LlmFallbackConfig {
+  provider: string;   // Provider name (e.g., "openai", "anthropic", "gemini")
+  model?: string;     // Model to use (optional, uses provider default)
+  apiKey?: string;    // API key (optional, uses environment variable)
+}
+```
+

package/skills/secrets.md

@@ -5,26 +5,52 @@ related: aws, cdk, variables
 
 # Secret Management
 
-Jaypie uses AWS Secrets Manager for secure credential storage.
+Jaypie uses AWS Secrets Manager for secure credential storage, with environment-aware resolution that works seamlessly in both local development and Lambda.
 
 ## Basic Usage
 
+Use `getEnvSecret` for environment-aware secret resolution:
+
 ```typescript
-import { getSecret } from "jaypie";
+import { getEnvSecret } from "jaypie";
 
-const apiKey = await getSecret("my-api-key");
-const dbUri = await getSecret("mongodb-connection-string");
+const apiKey = await getEnvSecret("ANTHROPIC_API_KEY");
+const dbUri = await getEnvSecret("MONGODB_URI");
 ```
 
-## Environment Variables
+### How getEnvSecret Works
+
+`getEnvSecret` checks environment variables in order:
+
+1. `SECRET_{name}` - If found, fetches from AWS Secrets Manager
+2. `{name}_SECRET` - If found, fetches from AWS Secrets Manager
+3. `{name}` - Returns direct value without AWS call
+
+This allows the same code to work locally (with direct env values) and in Lambda (with secret references).
+
+## Loading Multiple Secrets
+
+Use `loadEnvSecrets` during handler initialization:
+
+```typescript
+import { loadEnvSecrets } from "jaypie";
+
+// Load secrets and set in process.env
+await loadEnvSecrets("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "MONGODB_URI");
+
+// Now available as process.env.ANTHROPIC_API_KEY, etc.
+```
+
+## CDK Configuration
 
 Reference secrets via environment variables in CDK:
 
 ```typescript
 const handler = new JaypieLambda(this, "Handler", {
   environment: {
-    SECRET_MONGODB_URI: "mongodb-connection-string",
-    SECRET_API_KEY: "third-party-api-key",
+    // SECRET_ prefix triggers AWS Secrets Manager fetch
+    SECRET_MONGODB_URI: "my-project/mongodb-uri",
+    SECRET_API_KEY: "my-project/third-party-api-key",
   },
 });
 ```
@@ -32,10 +58,23 @@ const handler = new JaypieLambda(this, "Handler", {
 In code:
 
 ```typescript
-const secretName = process.env.SECRET_MONGODB_URI;
-const mongoUri = await getSecret(secretName);
+// getEnvSecret sees SECRET_MONGODB_URI and fetches from Secrets Manager
+const mongoUri = await getEnvSecret("MONGODB_URI");
 ```
 
+## Direct Secret Access
+
+Use `getSecret` when you need to fetch by exact AWS secret name:
+
+```typescript
+import { getSecret } from "jaypie";
+
+// Fetch by exact AWS secret name
+const secret = await getSecret("my-project/production/api-key");
+```
+
+Note: `getSecret` requires `AWS_SESSION_TOKEN` and always calls Secrets Manager. Prefer `getEnvSecret` for typical use cases.
+
 ## Creating Secrets
 
 ### Via CDK
@@ -86,7 +125,7 @@ aws secretsmanager create-secret \
 Retrieve in code:
 
 ```typescript
-const credentialsJson = await getSecret("my-project/db-credentials");
+const credentialsJson = await getEnvSecret("DB_CREDENTIALS");
 const credentials = JSON.parse(credentialsJson);
 ```
 
@@ -96,10 +135,10 @@ Secrets are cached by default to reduce API calls:
 
 ```typescript
 // First call: fetches from Secrets Manager
-const key1 = await getSecret("api-key");
+const key1 = await getEnvSecret("API_KEY");
 
 // Second call: returns cached value
-const key2 = await getSecret("api-key");
+const key2 = await getEnvSecret("API_KEY");
 ```
 
 Cache is scoped to Lambda execution context (warm starts reuse cache).
@@ -125,19 +164,16 @@ secret.addRotationSchedule("Rotation", {
 
 ## Local Development
 
-For local development, use environment variables:
+For local development, set environment variables directly:
 
 ```bash
 # .env.local (not committed)
+ANTHROPIC_API_KEY=sk-ant-test123
 MONGODB_URI=mongodb://localhost:27017/dev
 API_KEY=test_key_123
 ```
 
-In code, check for direct value first:
-
-```typescript
-const mongoUri = process.env.MONGODB_URI || await getSecret(process.env.SECRET_MONGODB_URI);
-```
+`getEnvSecret` automatically returns these values without AWS calls since there's no `SECRET_` prefix.
 
 ## IAM Permissions
 
@@ -153,3 +189,23 @@ lambdaFunction.addToRolePolicy(new PolicyStatement({
 }));
 ```
 
+## Testing
+
+Mock secret functions in tests:
+
+```typescript
+import { getEnvSecret } from "@jaypie/testkit/mock";
+import { vi } from "vitest";
+
+vi.mock("@jaypie/aws");
+
+describe("Handler", () => {
+  it("uses API key from secrets", async () => {
+    vi.mocked(getEnvSecret).mockResolvedValue("test-api-key");
+
+    const result = await handler();
+
+    expect(getEnvSecret).toHaveBeenCalledWith("API_KEY");
+  });
+});
+```

package/skills/skills.md

@@ -0,0 +1,23 @@
+---
+description:
+related:
+  agents: Prompts to improve agent adoption in AGENTS.md, CLAUDE.md, etc.
+  index: All available skills
+---
+
+# Jaypie Skills
+
+- Instruct Jaypie styles, techniques, and traditions
+- Written for agents
+- Balance brevity and rigor
+
+Look up skills by their "alias:"
+`mcp__jaypie__skills(index)`
+
+## Essentials
+
+Contents: index, releasenotes
+Development: documentation, errors, logs, mocks, style, tests
+Infrastructure: aws, cdk, cicd, datadog, dns, dynamodb, secrets, variables
+Patterns: fabric, models, services, vocabulary
+Meta: issues, jaypie, skills, tools

package/skills/tools-aws.md

@@ -0,0 +1,148 @@
+---
+description: AWS MCP tools for Lambda, S3, SQS, CloudWatch, Step Functions, CloudFormation
+related: aws, tools, tools-dynamodb
+---
+
+# AWS MCP Tools
+
+Tools for interacting with AWS services via the Jaypie MCP. Uses your local AWS credentials.
+
+## Lambda Functions
+
+| Tool | Description |
+|------|-------------|
+| `aws_lambda_list_functions` | List functions with optional prefix filter |
+| `aws_lambda_get_function` | Get function configuration and details |
+
+```
+# List all functions
+aws_lambda_list_functions
+
+# Filter by prefix
+aws_lambda_list_functions --prefix "my-api"
+
+# Get function details
+aws_lambda_get_function --functionName "my-api-handler"
+```
+
+## Step Functions
+
+| Tool | Description |
+|------|-------------|
+| `aws_stepfunctions_list_executions` | List executions for a state machine |
+| `aws_stepfunctions_stop_execution` | Stop a running execution |
+
+```
+# List recent executions
+aws_stepfunctions_list_executions --stateMachineArn "arn:aws:states:..."
+
+# Stop a running execution
+aws_stepfunctions_stop_execution --executionArn "arn:aws:states:..."
+```
+
+## CloudWatch Logs
+
+| Tool | Description |
+|------|-------------|
+| `aws_logs_filter_log_events` | Search logs with patterns and time ranges |
+
+```
+# Search for errors in Lambda logs
+aws_logs_filter_log_events --logGroupName "/aws/lambda/my-function" --filterPattern "ERROR"
+
+# Search with time range
+aws_logs_filter_log_events --logGroupName "/aws/lambda/my-function" --startTime "2024-01-15T10:00:00Z"
+```
+
+## S3
+
+| Tool | Description |
+|------|-------------|
+| `aws_s3_list_objects` | List bucket objects with prefix filtering |
+
+```
+# List all objects
+aws_s3_list_objects --bucket "my-bucket"
+
+# Filter by prefix
+aws_s3_list_objects --bucket "my-bucket" --prefix "uploads/"
+```
+
+## SQS
+
+| Tool | Description |
+|------|-------------|
+| `aws_sqs_list_queues` | List queues with prefix filter |
+| `aws_sqs_get_queue_attributes` | Get queue attributes including message counts |
+| `aws_sqs_receive_message` | Peek at queue messages (does not delete) |
+| `aws_sqs_purge_queue` | Delete all messages (irreversible) |
+
+```
+# List queues
+aws_sqs_list_queues --prefix "my-app"
+
+# Check queue depth
+aws_sqs_get_queue_attributes --queueUrl "https://sqs..."
+
+# Peek at messages
+aws_sqs_receive_message --queueUrl "https://sqs..." --maxNumberOfMessages 5
+
+# Purge queue (careful!)
+aws_sqs_purge_queue --queueUrl "https://sqs..."
+```
+
+## CloudFormation
+
+| Tool | Description |
+|------|-------------|
+| `aws_cloudformation_describe_stack` | Get stack details, outputs, and status |
+
+```
+# Get stack details
+aws_cloudformation_describe_stack --stackName "MyStack"
+```
+
+## Credential Management
+
+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`
+
+```
+# List available profiles
+aws_list_profiles
+
+# Use a specific profile (supported on all tools)
+aws_lambda_list_functions --profile production --region us-west-2
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AWS_PROFILE` | Default profile |
+| `AWS_REGION` | Default region |
+
+## Common Patterns
+
+### Debug Lambda Issues
+
+```
+# Check function config
+aws_lambda_get_function --functionName "my-function"
+
+# Search recent logs
+aws_logs_filter_log_events --logGroupName "/aws/lambda/my-function" --filterPattern "ERROR"
+```
+
+### Check Queue Health
+
+```
+# Get queue depth
+aws_sqs_get_queue_attributes --queueUrl "https://..."
+
+# Peek at messages
+aws_sqs_receive_message --queueUrl "https://..." --maxNumberOfMessages 5
+```
+