@jaypie/mcp 0.3.1 → 0.3.4

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

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