@jaypie/mcp 0.3.2 → 0.4.0

package/skills/debugging.md

@@ -0,0 +1,148 @@
+---
+description: Debugging techniques and troubleshooting
+related: logs, datadog, errors
+---
+
+# Debugging Techniques
+
+Strategies for debugging Jaypie applications.
+
+## Log-Based Debugging
+
+### Enable Debug Logging
+
+```bash
+LOG_LEVEL=debug npm run dev
+LOG_LEVEL=trace npm run dev  # Most verbose
+```
+
+### Search Logs via MCP
+
+```
+# Find errors in last hour
+datadog_logs --query "status:error" --from "now-1h"
+
+# Find specific request
+datadog_logs --query "@requestId:abc-123"
+
+# Search CloudWatch directly
+aws_logs_filter_log_events --logGroupName "/aws/lambda/my-function" --filterPattern "ERROR"
+```
+
+## Common Issues
+
+### "undefined" in Stack Names
+
+If you see `undefined` in a CDK stack name, a required variable is missing:
+
+```typescript
+// BAD: undefined if PROJECT_NONCE not set
+const stackName = `api-${process.env.PROJECT_NONCE}`;
+
+// GOOD: Provide default
+const nonce = process.env.PROJECT_NONCE || "dev";
+const stackName = `api-${nonce}`;
+```
+
+### "unknown" in Logs
+
+`unknown` indicates a value was expected but fell back to a default:
+
+```typescript
+// This produces "unknown" if PROJECT_KEY not set
+log.info("Starting", { project: process.env.PROJECT_KEY || "unknown" });
+```
+
+### Lambda Cold Starts
+
+Check initialization time:
+
+```
+datadog_logs --query "@dd.cold_start:true" --from "now-1h"
+```
+
+### Connection Timeouts
+
+For database or external service timeouts:
+
+```typescript
+// Check Lambda timeout settings
+aws_lambda_get_function --functionName "my-function"
+
+// Look for timeout patterns in logs
+datadog_logs --query "timeout OR ETIMEDOUT" --from "now-1h"
+```
+
+Increase Lambda timeout or optimize slow operations.
+
+## Local Testing
+
+### Lambda Local Testing
+
+Use SAM CLI for local Lambda testing:
+
+```bash
+cd packages/express/docker
+sam local invoke -e event.json
+```
+
+### DynamoDB Local
+
+```bash
+# Start local DynamoDB
+docker run -p 8000:8000 amazon/dynamodb-local
+
+# Access with AWS CLI
+AWS_ACCESS_KEY_ID=local AWS_SECRET_ACCESS_KEY=local \
+  aws dynamodb list-tables --endpoint-url http://127.0.0.1:8000
+```
+
+## Stack Traces
+
+### Finding Root Cause
+
+Jaypie errors include context:
+
+```typescript
+try {
+  await riskyOperation();
+} catch (error) {
+  log.error("Operation failed", {
+    error: error.message,
+    stack: error.stack,
+    context: error.context,  // Jaypie errors include this
+  });
+  throw error;
+}
+```
+
+### Error Classification
+
+| Error Type | Cause |
+|------------|-------|
+| ConfigurationError | Missing or invalid config |
+| NotFoundError | Resource doesn't exist |
+| UnauthorizedError | Authentication failed |
+| ForbiddenError | Permission denied |
+| BadRequestError | Invalid input |
+
+## Step Function Debugging
+
+```
+# List running executions
+aws_stepfunctions_list_executions --stateMachineArn "arn:..." --statusFilter "RUNNING"
+
+# Stop stuck execution
+aws_stepfunctions_stop_execution --executionArn "arn:..." --cause "Manual stop for debugging"
+```
+
+## Queue Debugging
+
+```
+# Check queue depth
+aws_sqs_get_queue_attributes --queueUrl "https://..."
+
+# Peek at messages (does not delete)
+aws_sqs_receive_message --queueUrl "https://..." --maxNumberOfMessages 5
+```
+

package/skills/dns.md

@@ -0,0 +1,134 @@
+---
+description: DNS and domain configuration
+related: cdk, aws
+---
+
+# DNS Configuration
+
+Managing domains and DNS for Jaypie applications.
+
+## Route 53 Setup
+
+### Hosted Zone
+
+Create a hosted zone for your domain:
+
+```typescript
+import { HostedZone } from "aws-cdk-lib/aws-route53";
+
+const zone = HostedZone.fromLookup(this, "Zone", {
+  domainName: "example.com",
+});
+```
+
+### CloudFront Alias
+
+Point domain to CloudFront distribution:
+
+```typescript
+import { ARecord, RecordTarget } from "aws-cdk-lib/aws-route53";
+import { CloudFrontTarget } from "aws-cdk-lib/aws-route53-targets";
+
+new ARecord(this, "SiteAlias", {
+  zone,
+  recordName: "app",  // app.example.com
+  target: RecordTarget.fromAlias(new CloudFrontTarget(distribution)),
+});
+```
+
+### API Gateway Custom Domain
+
+```typescript
+import { DomainName } from "aws-cdk-lib/aws-apigatewayv2";
+
+const domainName = new DomainName(this, "ApiDomain", {
+  domainName: "api.example.com",
+  certificate: certificate,
+});
+
+new ARecord(this, "ApiAlias", {
+  zone,
+  recordName: "api",
+  target: RecordTarget.fromAlias(new ApiGatewayv2DomainProperties(
+    domainName.regionalDomainName,
+    domainName.regionalHostedZoneId,
+  )),
+});
+```
+
+## Certificate Management
+
+### ACM Certificate
+
+```typescript
+import { Certificate, CertificateValidation } from "aws-cdk-lib/aws-certificatemanager";
+
+const certificate = new Certificate(this, "Certificate", {
+  domainName: "example.com",
+  subjectAlternativeNames: ["*.example.com"],
+  validation: CertificateValidation.fromDns(zone),
+});
+```
+
+### Cross-Region Certificates
+
+CloudFront requires certificates in `us-east-1`:
+
+```typescript
+// In us-east-1 stack
+const cfCertificate = new Certificate(this, "CfCertificate", {
+  domainName: "app.example.com",
+  validation: CertificateValidation.fromDns(zone),
+});
+
+// Export ARN for use in other regions
+new CfnOutput(this, "CertificateArn", {
+  value: cfCertificate.certificateArn,
+  exportName: "CloudFrontCertificateArn",
+});
+```
+
+## Environment-Based Domains
+
+Map environments to subdomains:
+
+| Environment | Domain |
+|-------------|--------|
+| production | app.example.com |
+| sandbox | sandbox.example.com |
+| local | localhost:3000 |
+
+```typescript
+const subdomain = process.env.PROJECT_ENV === "production"
+  ? "app"
+  : process.env.PROJECT_ENV;
+
+new ARecord(this, "Alias", {
+  zone,
+  recordName: subdomain,
+  target: RecordTarget.fromAlias(new CloudFrontTarget(distribution)),
+});
+```
+
+## Debugging DNS
+
+### Check DNS Resolution
+
+```bash
+# Check A record
+dig app.example.com A
+
+# Check CNAME
+dig app.example.com CNAME
+
+# Check with specific nameserver
+dig @ns-123.awsdns-45.com app.example.com
+```
+
+### Verify Certificate
+
+```bash
+# Check certificate
+openssl s_client -connect app.example.com:443 -servername app.example.com
+```
+

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