@jaypie/mcp 0.3.2 → 0.3.4

package/skills/dynamodb.md

@@ -0,0 +1,140 @@
+---
+description: DynamoDB patterns and queries
+related: aws, cdk, models
+---
+
+# DynamoDB Patterns
+
+Best practices for DynamoDB with Jaypie applications.
+
+## MCP DynamoDB 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
+```
+
+## Key Design
+
+### Single Table Design
+
+Use prefixed keys for multiple entity types:
+
+```typescript
+// User entity
+{
+  pk: "USER#123",
+  sk: "PROFILE",
+  name: "John Doe",
+  email: "john@example.com"
+}
+
+// User's orders
+{
+  pk: "USER#123",
+  sk: "ORDER#2024-01-15#abc",
+  total: 99.99,
+  status: "completed"
+}
+```
+
+### Access Patterns
+
+| Access Pattern | Key Condition |
+|---------------|---------------|
+| Get user profile | pk = USER#123, sk = PROFILE |
+| 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
+
+```typescript
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { QueryCommand } from "@aws-sdk/lib-dynamodb";
+
+const client = new DynamoDBClient({});
+
+const result = await client.send(new QueryCommand({
+  TableName: process.env.CDK_ENV_TABLE,
+  KeyConditionExpression: "pk = :pk AND begins_with(sk, :prefix)",
+  ExpressionAttributeValues: {
+    ":pk": "USER#123",
+    ":prefix": "ORDER#",
+  },
+  ScanIndexForward: false,  // Newest first
+  Limit: 10,
+}));
+```
+
+## GSI Patterns
+
+### By-Status Index
+
+```typescript
+// GSI for querying by status across all users
+{
+  pk: "USER#123",
+  sk: "ORDER#2024-01-15#abc",
+  gsi1pk: "ORDER#pending",
+  gsi1sk: "2024-01-15T10:00:00Z",
+}
+```
+
+Query pending orders:
+
+```
+aws_dynamodb_query --tableName "MyTable" --indexName "gsi1" \
+  --keyConditionExpression "gsi1pk = :status" \
+  --expressionAttributeValues '{":status":{"S":"ORDER#pending"}}'
+```
+
+## CDK Table Definition
+
+```typescript
+import { JaypieTable } from "@jaypie/constructs";
+
+const table = new JaypieTable(this, "DataTable", {
+  partitionKey: { name: "pk", type: AttributeType.STRING },
+  sortKey: { name: "sk", type: AttributeType.STRING },
+  globalSecondaryIndexes: [
+    {
+      indexName: "gsi1",
+      partitionKey: { name: "gsi1pk", type: AttributeType.STRING },
+      sortKey: { name: "gsi1sk", type: AttributeType.STRING },
+    },
+  ],
+});
+```
+
+## Local Development
+
+```bash
+# Start local DynamoDB
+docker run -p 8000:8000 amazon/dynamodb-local
+
+# Create table
+AWS_ACCESS_KEY_ID=local AWS_SECRET_ACCESS_KEY=local \
+  aws dynamodb create-table \
+  --table-name MyTable \
+  --attribute-definitions AttributeName=pk,AttributeType=S AttributeName=sk,AttributeType=S \
+  --key-schema AttributeName=pk,KeyType=HASH AttributeName=sk,KeyType=RANGE \
+  --billing-mode PAY_PER_REQUEST \
+  --endpoint-url http://127.0.0.1:8000
+```
+

package/skills/errors.md

@@ -0,0 +1,142 @@
+---
+description: Error handling with @jaypie/errors
+related: debugging, logs, tests
+---
+
+# Error Handling
+
+Jaypie provides structured error types for consistent error handling.
+
+## Core Principle
+
+**Never throw vanilla `Error`**. Use Jaypie error types:
+
+```typescript
+import { ConfigurationError, NotFoundError } from "jaypie";
+
+// BAD
+throw new Error("Missing API key");
+
+// GOOD
+throw new ConfigurationError("Missing API key");
+```
+
+## Error Types
+
+| Error | HTTP Status | Use When |
+|-------|-------------|----------|
+| BadRequestError | 400 | Invalid input from client |
+| UnauthorizedError | 401 | Authentication required |
+| ForbiddenError | 403 | Authenticated but not permitted |
+| NotFoundError | 404 | Resource doesn't exist |
+| ConfigurationError | 500 | Missing or invalid config |
+| InternalError | 500 | Unexpected server error |
+
+## Usage Examples
+
+### Bad Request
+
+```typescript
+import { BadRequestError } from "jaypie";
+
+if (!request.body.email) {
+  throw new BadRequestError("Email is required");
+}
+
+if (!isValidEmail(request.body.email)) {
+  throw new BadRequestError("Invalid email format");
+}
+```
+
+### Not Found
+
+```typescript
+import { NotFoundError } from "jaypie";
+
+const user = await User.findById(userId);
+if (!user) {
+  throw new NotFoundError(`User ${userId} not found`);
+}
+```
+
+### Configuration Error
+
+```typescript
+import { ConfigurationError } from "jaypie";
+
+if (!process.env.API_KEY) {
+  throw new ConfigurationError("API_KEY environment variable is required");
+}
+```
+
+### Unauthorized vs Forbidden
+
+```typescript
+import { UnauthorizedError, ForbiddenError } from "jaypie";
+
+// No credentials provided
+if (!token) {
+  throw new UnauthorizedError("Authentication required");
+}
+
+// Credentials provided but insufficient permission
+if (!user.hasRole("admin")) {
+  throw new ForbiddenError("Admin access required");
+}
+```
+
+## Error Context
+
+Add context to errors for debugging:
+
+```typescript
+import { NotFoundError } from "jaypie";
+
+throw new NotFoundError("User not found", {
+  context: {
+    userId,
+    requestId: req.id,
+    searchedTables: ["users", "legacy_users"],
+  },
+});
+```
+
+## Error Handling in Handlers
+
+Jaypie handlers automatically catch and format errors:
+
+```typescript
+import { lambdaHandler } from "@jaypie/lambda";
+import { NotFoundError } from "jaypie";
+
+export const handler = lambdaHandler(async (event) => {
+  const item = await getItem(event.id);
+  if (!item) {
+    throw new NotFoundError("Item not found");
+    // Returns: { statusCode: 404, body: { error: "Item not found" } }
+  }
+  return item;
+});
+```
+
+## Testing Errors
+
+```typescript
+import { expect, it } from "vitest";
+import { NotFoundError } from "jaypie";
+
+it("throws NotFoundError when user missing", async () => {
+  await expect(getUser("invalid-id"))
+    .rejects
+    .toThrow(NotFoundError);
+});
+
+it("includes context in error", async () => {
+  try {
+    await getUser("invalid-id");
+  } catch (error) {
+    expect(error.context.userId).toBe("invalid-id");
+  }
+});
+```
+

package/skills/fabric.md

@@ -0,0 +1,164 @@
+---
+description: Fabric service patterns and adapters
+related: services, errors, tools
+---
+
+# Fabric Services
+
+Fabric provides a unified service pattern that works across CLI, Lambda, LLM tools, and MCP.
+
+## Core Concept
+
+Define a service once, deploy it anywhere:
+
+```typescript
+import { fabricService } from "@jaypie/fabric";
+
+const greetService = fabricService({
+  alias: "greet",
+  description: "Greet a user by name",
+  input: {
+    name: {
+      type: String,
+      required: true,
+      description: "Name to greet",
+    },
+  },
+  service: async ({ name }) => {
+    return `Hello, ${name}!`;
+  },
+});
+```
+
+## Adapters
+
+### Lambda Handler
+
+```typescript
+import { fabricLambdaHandler } from "@jaypie/fabric";
+
+export const handler = fabricLambdaHandler(greetService);
+// Invoked via Lambda with { name: "World" }
+```
+
+### CLI Command
+
+```typescript
+import { fabricCommand } from "@jaypie/fabric";
+
+const program = new Command();
+program.addCommand(fabricCommand(greetService));
+// $ cli greet --name World
+```
+
+### MCP Tool
+
+```typescript
+import { fabricMcpTool } from "@jaypie/fabric";
+
+server.tool(...fabricMcpTool(greetService));
+// Available as MCP tool "greet"
+```
+
+### LLM Tool
+
+```typescript
+import { fabricLlmTool } from "@jaypie/fabric";
+
+const tools = [fabricLlmTool(greetService)];
+// Available to LLM as function call
+```
+
+## Service Suites
+
+Group related services:
+
+```typescript
+import { createServiceSuite, fabricService } from "@jaypie/fabric";
+
+const userService = fabricService({
+  alias: "user_get",
+  description: "Get user by ID",
+  input: { id: { type: String, required: true } },
+  service: async ({ id }) => User.findById(id),
+});
+
+const userListService = fabricService({
+  alias: "user_list",
+  description: "List all users",
+  input: {},
+  service: async () => User.find(),
+});
+
+const suite = createServiceSuite({
+  name: "users",
+  version: "1.0.0",
+});
+
+suite.register(userService, "users");
+suite.register(userListService, "users");
+```
+
+## Input Validation
+
+Fabric validates inputs automatically:
+
+```typescript
+const service = fabricService({
+  input: {
+    email: {
+      type: String,
+      required: true,
+      description: "User email address",
+    },
+    count: {
+      type: Number,
+      required: false,
+      description: "Number of results",
+    },
+    status: {
+      type: ["active", "inactive"] as const,
+      required: false,
+      description: "Filter by status",
+    },
+  },
+  service: async ({ email, count, status }) => {
+    // email: string (validated)
+    // count: number | undefined
+    // status: "active" | "inactive" | undefined
+  },
+});
+```
+
+## Error Handling
+
+Fabric services use Jaypie errors:
+
+```typescript
+import { fabricService } from "@jaypie/fabric";
+import { NotFoundError, BadRequestError } from "jaypie";
+
+const service = fabricService({
+  alias: "user_get",
+  input: { id: { type: String, required: true } },
+  service: async ({ id }) => {
+    if (!isValidId(id)) {
+      throw new BadRequestError("Invalid user ID format");
+    }
+    const user = await User.findById(id);
+    if (!user) {
+      throw new NotFoundError(`User ${id} not found`);
+    }
+    return user;
+  },
+});
+```
+
+## Best Practices
+
+1. **Single Responsibility**: Each service does one thing
+2. **Descriptive Aliases**: Use `noun_verb` format (`user_get`, `order_create`)
+3. **Clear Descriptions**: Write for AI tools that need context
+4. **Input Documentation**: Describe what each input expects
+5. **Return Types**: Return JSON-serializable data
+

package/skills/index.md

@@ -0,0 +1,7 @@
+---
+description: Skill directory listing
+---
+
+# Jaypie Skills
+
+Query the Jaypie MCP `skill` tool with one of the following alias keywords `mcp__jaypie__skill(alias: String)`:

package/skills/jaypie.md

@@ -0,0 +1,100 @@
+---
+description: Jaypie overview and core concepts
+---
+
+# Introduction to Jaypie
+
+Jaypie is a complete stack framework for building multi-environment cloud applications on AWS using TypeScript/Node.js.
+
+## Core Packages
+
+### Main Package: `jaypie`
+
+The main package provides:
+- **Secrets**: AWS Secrets Manager integration
+- **Errors**: Structured error types (ConfigurationError, etc.)
+- **Events**: Event parsing for Lambda handlers
+- **Lifecycle**: Handler lifecycle management
+- **Logging**: Structured logging with context
+- **Queues**: SQS messaging utilities
+
+```typescript
+import {
+  getSecret,
+  log,
+  ConfigurationError,
+  HTTP,
+  PROJECT
+} from "jaypie";
+```
+
+### Infrastructure: `@jaypie/constructs`
+
+CDK constructs for AWS infrastructure:
+- Lambda functions with best practices
+- SQS queues with DLQ
+- S3 buckets with encryption
+- CloudFront distributions
+- Secrets Manager secrets
+
+### Testing: `@jaypie/testkit`
+
+Testing utilities and mocks:
+- Mock implementations for all Jaypie functions
+- Vitest configuration helpers
+- Test data fabrication
+
+## Project Structure
+
+Jaypie projects use npm workspaces:
+
+```
+project/
+├── packages/           # npm packages
+│   ├── api/           # Express API
+│   └── lib/           # Shared library
+├── stacks/            # CDK infrastructure
+│   └── cdk/           # CDK app
+└── package.json       # Root workspace config
+```
+
+## Key Conventions
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `PROJECT_ENV` | Environment: local, sandbox, production |
+| `PROJECT_KEY` | Project identifier for logging |
+| `PROJECT_NONCE` | Unique resource identifier |
+| `LOG_LEVEL` | Log level: trace, debug, info, warn, error |
+
+### Error Handling
+
+Never throw vanilla `Error`. Use Jaypie errors:
+
+```typescript
+import { ConfigurationError, NotFoundError } from "jaypie";
+
+if (!config.required) {
+  throw new ConfigurationError("Missing required config");
+}
+```
+
+### Logging
+
+Use structured logging with context:
+
+```typescript
+import { log } from "jaypie";
+
+log.info("Processing request", { userId, action });
+log.error("Request failed", { error: error.message });
+```
+
+## Next Steps
+
+- `skill("style")` - Code style conventions
+- `skill("errors")` - Error handling patterns
+- `skill("tests")` - Testing with Vitest
+- `skill("cdk")` - Infrastructure with CDK

package/skills/legacy.md

@@ -0,0 +1,97 @@
+---
+description: Legacy libraries and deprecated patterns
+related: dynamodb, fabric, mocks
+---
+
+# Legacy Patterns
+
+Deprecated libraries and patterns that may exist in older Jaypie projects.
+
+## @jaypie/core (Deprecated)
+
+Migrated to `@jaypie/kit`. Update imports:
+
+```typescript
+// Old
+import { someUtil } from "@jaypie/core";
+
+// New
+import { someUtil } from "@jaypie/kit";
+```
+
+## @jaypie/mongoose (Legacy)
+
+MongoDB/Mongoose integration. Consider DynamoDB for new projects.
+
+### Connection
+
+```typescript
+import { connectMongoose } from "@jaypie/mongoose";
+
+export const handler = async (event) => {
+  await connectMongoose();
+  // Connection cached for Lambda warm starts
+};
+```
+
+### Models
+
+```typescript
+import mongoose, { Schema, Document } from "mongoose";
+
+interface IUser extends Document {
+  email: string;
+  name: string;
+}
+
+const userSchema = new Schema<IUser>({
+  email: { type: String, required: true },
+  name: { type: String, required: true },
+}, { timestamps: true });
+
+export const User = mongoose.model<IUser>("User", userSchema);
+```
+
+### Mocking
+
+```typescript
+vi.mock("@jaypie/mongoose", async () => {
+  const { mockMongoose } = await import("@jaypie/testkit");
+  return mockMongoose(vi);
+});
+```
+
+## Migration Guides
+
+### Mongoose to DynamoDB
+
+1. Define DynamoDB item types (see `skill("dynamodb")`)
+2. Update data access patterns for single-table design
+3. Replace Mongoose queries with DynamoDB operations
+4. Update tests to mock DynamoDB instead of Mongoose
+
+### Core to Kit
+
+Direct replacement - same exports, new package name:
+
+```bash
+npm uninstall @jaypie/core
+npm install @jaypie/kit
+```
+
+Update imports throughout codebase.
+
+## When to Keep Legacy
+
+Keep legacy patterns when:
+- Existing production system is stable
+- Migration cost outweighs benefits
+- Team expertise is in legacy stack
+- Database has significant existing data
+
+Migrate when:
+- Starting new features
+- Performance issues arise
+- Scaling requirements change
+- Simplifying architecture
+