@jaypie/mcp 0.4.0 → 0.4.1

package/skills/dynamodb.md

@@ -1,20 +1,15 @@
 ---
-description: DynamoDB patterns and queries
-related: aws, cdk, models
+description: DynamoDB code patterns, key design, and queries
+related: aws, cdk, models, tools-dynamodb
 ---
 
 # DynamoDB Patterns
 
 Best practices for DynamoDB with Jaypie applications.
 
-## MCP DynamoDB Tools
+## MCP Tools
 
-```
-aws_dynamodb_describe_table   - Get table schema and indexes
-aws_dynamodb_query            - Query by partition key (efficient)
-aws_dynamodb_scan             - Full table scan (use sparingly)
-aws_dynamodb_get_item         - Get single item by key
-```
+For interactive DynamoDB tools (query, scan, get-item, describe-table), see **tools-dynamodb**.
 
 ## Key Design
 
@@ -48,21 +43,7 @@ Use prefixed keys for multiple entity types:
 | List user orders | pk = USER#123, sk begins_with ORDER# |
 | Get specific order | pk = USER#123, sk = ORDER#2024-01-15#abc |
 
-## Query Examples
-
-### Query via MCP
-
-```
-# Get user profile
-aws_dynamodb_get_item --tableName "MyTable" --key '{"pk":{"S":"USER#123"},"sk":{"S":"PROFILE"}}'
-
-# List user orders
-aws_dynamodb_query --tableName "MyTable" \
-  --keyConditionExpression "pk = :pk AND begins_with(sk, :prefix)" \
-  --expressionAttributeValues '{":pk":{"S":"USER#123"},":prefix":{"S":"ORDER#"}}'
-```
-
-### Query in Code
+## Query in Code
 
 ```typescript
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
@@ -98,10 +79,15 @@ const result = await client.send(new QueryCommand({
 
 Query pending orders:
 
-```
-aws_dynamodb_query --tableName "MyTable" --indexName "gsi1" \
-  --keyConditionExpression "gsi1pk = :status" \
-  --expressionAttributeValues '{":status":{"S":"ORDER#pending"}}'
+```typescript
+const result = await client.send(new QueryCommand({
+  TableName: process.env.CDK_ENV_TABLE,
+  IndexName: "gsi1",
+  KeyConditionExpression: "gsi1pk = :status",
+  ExpressionAttributeValues: {
+    ":status": "ORDER#pending",
+  },
+}));
 ```
 
 ## CDK Table Definition
@@ -138,3 +124,26 @@ AWS_ACCESS_KEY_ID=local AWS_SECRET_ACCESS_KEY=local \
   --endpoint-url http://127.0.0.1:8000
 ```
 
+## Testing
+
+Mock DynamoDB in tests:
+
+```typescript
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { vi } from "vitest";
+
+vi.mock("@aws-sdk/client-dynamodb");
+
+describe("OrderService", () => {
+  it("queries user orders", async () => {
+    vi.mocked(DynamoDBClient.prototype.send).mockResolvedValue({
+      Items: [{ pk: "USER#123", sk: "ORDER#abc" }],
+    });
+
+    const orders = await getOrders("123");
+
+    expect(orders).toHaveLength(1);
+  });
+});
+```
+

package/skills/issues.md

@@ -0,0 +1,55 @@
+---
+description: Submitting issues to Jaypie repositories
+related: jaypie, agents
+---
+
+# Jaypie Issues
+
+## Repository
+
+Submit issues to: **github.com/finlaysonstudio/jaypie**
+
+## Agent Guidelines
+
+**CRITICAL: Never submit issues without explicit user approval.**
+
+Before creating an issue:
+1. Draft the issue title and body
+2. Present the draft to the user
+3. Wait for explicit approval ("yes", "submit it", etc.)
+4. Only then use `mcp__github__issue_write` to create the issue
+
+## Issue Format
+
+```markdown
+**Title**: [Brief, descriptive title]
+
+**Description**:
+[What is the issue or feature request]
+
+**Context**:
+- Package: [affected package, e.g., `jaypie`, `@jaypie/express`]
+- Version: [if known]
+- Environment: [if relevant]
+
+**Steps to Reproduce** (for bugs):
+1. ...
+2. ...
+
+**Expected Behavior**:
+[What should happen]
+
+**Actual Behavior**:
+[What actually happens]
+```
+
+## Labels
+
+Common labels: `bug`, `enhancement`, `documentation`, `question`
+
+## When to Suggest Issues
+
+- Bugs in Jaypie packages discovered during development
+- Missing features that would benefit multiple projects
+- Documentation gaps or errors
+- API inconsistencies

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