@jaypie/mcp 0.3.1 → 0.3.4

package/skills/aws.md

@@ -0,0 +1,107 @@
+---
+description: AWS integration, CLI tools, and cloud services
+related: cdk, dynamodb, secrets, logs
+---
+
+# AWS Integration
+
+Jaypie integrates with AWS services through SDK utilities and CLI tools available via the MCP.
+
+## MCP AWS Tools
+
+The Jaypie MCP provides AWS tools that use your local AWS credentials:
+
+### Lambda Functions
+```
+aws_lambda_list_functions     - List functions with optional prefix filter
+aws_lambda_get_function       - Get function configuration and details
+```
+
+### Step Functions
+```
+aws_stepfunctions_list_executions  - List executions for a state machine
+aws_stepfunctions_stop_execution   - Stop a running execution
+```
+
+### CloudWatch Logs
+```
+aws_logs_filter_log_events    - Search logs with patterns and time ranges
+```
+
+### S3
+```
+aws_s3_list_objects           - List bucket objects with prefix filtering
+```
+
+### DynamoDB
+```
+aws_dynamodb_describe_table   - Get table metadata and indexes
+aws_dynamodb_scan             - Scan table (use sparingly)
+aws_dynamodb_query            - Query by partition key
+aws_dynamodb_get_item         - Get single item by key
+```
+
+### SQS
+```
+aws_sqs_list_queues           - List queues with prefix filter
+aws_sqs_get_queue_attributes  - Get queue attributes
+aws_sqs_receive_message       - Peek at queue messages
+aws_sqs_purge_queue           - Delete all messages (irreversible)
+```
+
+### CloudFormation
+```
+aws_cloudformation_describe_stack  - Get stack details and outputs
+```
+
+## 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`
+
+```bash
+# List available profiles
+aws_list_profiles
+
+# Use a specific profile
+aws_lambda_list_functions --profile production
+```
+
+## Jaypie AWS Package
+
+The `@jaypie/aws` package provides SDK utilities:
+
+```typescript
+import { getSecret, sendMessage } from "@jaypie/aws";
+
+// Get secret from Secrets Manager
+const apiKey = await getSecret("my-api-key");
+
+// Send SQS message
+await sendMessage(queueUrl, { action: "process", id: "123" });
+```
+
+## Environment-Based Configuration
+
+Use CDK environment variables in Lambda:
+
+| Variable | Description |
+|----------|-------------|
+| `CDK_ENV_BUCKET` | S3 bucket name |
+| `CDK_ENV_QUEUE_URL` | SQS queue URL |
+| `CDK_ENV_SNS_TOPIC_ARN` | SNS topic ARN |
+
+## Profile Selection
+
+When working with multiple AWS accounts:
+
+```bash
+# Set default profile
+export AWS_PROFILE=development
+
+# Or specify per-command via MCP tools
+aws_lambda_list_functions --profile production --region us-west-2
+```
+

package/skills/cdk.md

@@ -0,0 +1,141 @@
+---
+description: CDK constructs and deployment patterns
+related: aws, dynamodb, cicd
+---
+
+# CDK Constructs
+
+Jaypie provides CDK constructs through `@jaypie/constructs` for deploying AWS infrastructure with best practices built-in.
+
+## Installation
+
+```bash
+npm install @jaypie/constructs
+```
+
+## Core Constructs
+
+### JaypieLambda
+
+Lambda function with Datadog tracing, logging, and error handling:
+
+```typescript
+import { JaypieLambda } from "@jaypie/constructs";
+
+const handler = new JaypieLambda(this, "ApiHandler", {
+  entry: "src/handler.ts",
+  handler: "handler",
+  environment: {
+    PROJECT_ENV: "production",
+    PROJECT_KEY: "my-api",
+  },
+  timeout: Duration.seconds(30),
+  memorySize: 512,
+});
+```
+
+### JaypieQueue
+
+SQS queue with DLQ and Lambda trigger:
+
+```typescript
+import { JaypieQueue } from "@jaypie/constructs";
+
+const queue = new JaypieQueue(this, "ProcessQueue", {
+  visibilityTimeout: Duration.seconds(60),
+  retentionPeriod: Duration.days(7),
+});
+
+// Connect to Lambda
+queue.addEventSource(handler);
+```
+
+### JaypieBucket
+
+S3 bucket with encryption and lifecycle rules:
+
+```typescript
+import { JaypieBucket } from "@jaypie/constructs";
+
+const bucket = new JaypieBucket(this, "AssetsBucket", {
+  encryption: BucketEncryption.S3_MANAGED,
+  lifecycleRules: [
+    { expiration: Duration.days(90), prefix: "temp/" }
+  ],
+});
+```
+
+## Stack Structure
+
+Organize stacks in the `stacks/` directory:
+
+```
+stacks/
+├── cdk/
+│   ├── src/
+│   │   ├── app.ts        # CDK app entry
+│   │   └── stacks/
+│   │       ├── api.ts    # API stack
+│   │       └── data.ts   # Data stack
+│   ├── cdk.json
+│   └── package.json
+```
+
+## Environment Configuration
+
+Use environment-specific configuration:
+
+```typescript
+const env = process.env.PROJECT_ENV || "sandbox";
+const nonce = process.env.PROJECT_NONCE || "dev";
+
+const stack = new ApiStack(app, `api-${env}-${nonce}`, {
+  env: {
+    account: process.env.CDK_DEFAULT_ACCOUNT,
+    region: process.env.CDK_DEFAULT_REGION,
+  },
+});
+```
+
+## Deployment
+
+```bash
+# Deploy to sandbox
+PROJECT_ENV=sandbox PROJECT_NONCE=dev cdk deploy
+
+# Deploy to production
+PROJECT_ENV=production PROJECT_NONCE=prod cdk deploy
+```
+
+## Environment Variables
+
+Pass configuration to Lambda via environment variables:
+
+```typescript
+const handler = new JaypieLambda(this, "Handler", {
+  environment: {
+    CDK_ENV_BUCKET: bucket.bucketName,
+    CDK_ENV_QUEUE_URL: queue.queueUrl,
+    SECRET_MONGODB_URI: "mongodb-connection-string",
+  },
+});
+
+// Grant permissions
+bucket.grantReadWrite(handler);
+queue.grantSendMessages(handler);
+```
+
+## Datadog Integration
+
+Enable Datadog tracing:
+
+```typescript
+const handler = new JaypieLambda(this, "Handler", {
+  datadogApiKeyArn: "arn:aws:secretsmanager:...",
+  environment: {
+    DD_ENV: "production",
+    DD_SERVICE: "my-api",
+  },
+});
+```
+

package/skills/cicd.md

@@ -0,0 +1,152 @@
+---
+description: GitHub Actions CI/CD workflows
+related: tests, cdk
+---
+
+# CI/CD with GitHub Actions
+
+Jaypie projects use GitHub Actions for continuous integration and deployment.
+
+## Standard Workflows
+
+### npm-check.yml
+
+Runs on feature branches (`feat/*`, `fix/*`, `devin/*`):
+
+```yaml
+name: npm-check
+
+on:
+  push:
+    branches:
+      - 'feat/*'
+      - 'fix/*'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: npm ci
+      - run: npm run lint
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: npm ci
+      - run: npm run typecheck
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [22, 24, 25]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+```
+
+### npm-deploy.yml
+
+Runs on `main` branch and release tags:
+
+```yaml
+name: npm-deploy
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - 'deploy-*'
+      - 'rc-*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+## Branch Strategy
+
+| Branch Pattern | Purpose | Triggers |
+|---------------|---------|----------|
+| `main` | Production releases | npm-deploy |
+| `feat/*` | Feature development | npm-check |
+| `fix/*` | Bug fixes | npm-check |
+| `rc-*` tags | Release candidates | npm-deploy (--tag rc) |
+
+## Testing Matrix
+
+Test across multiple Node.js versions:
+
+```yaml
+strategy:
+  matrix:
+    node-version: [22, 24, 25]
+```
+
+## Secrets Configuration
+
+Required repository secrets:
+
+| Secret | Purpose |
+|--------|---------|
+| `NPM_TOKEN` | npm publish authentication |
+| `DATADOG_API_KEY` | Optional: Test tracing |
+
+## Workflow Tips
+
+### Skip Already-Published Versions
+
+```yaml
+- run: |
+    CURRENT=$(npm view ${{ github.repository }} version 2>/dev/null || echo "0.0.0")
+    LOCAL=$(node -p "require('./package.json').version")
+    if [ "$CURRENT" = "$LOCAL" ]; then
+      echo "Version already published, skipping"
+      exit 0
+    fi
+    npm publish --provenance
+```
+
+### Conditional Job Execution
+
+Run jobs only when specific files change:
+
+```yaml
+- uses: dorny/paths-filter@v2
+  id: changes
+  with:
+    filters: |
+      src:
+        - 'packages/llm/**'
+
+- run: npm test -w packages/llm
+  if: steps.changes.outputs.src == 'true'
+```
+

package/skills/datadog.md

@@ -0,0 +1,129 @@
+---
+description: Datadog integration and observability
+related: logs, debugging, aws
+---
+
+# Datadog Integration
+
+Jaypie integrates with Datadog for logging, monitoring, and APM.
+
+## MCP Datadog Tools
+
+The Jaypie MCP provides tools for querying Datadog:
+
+### Log Search
+```
+datadog_logs          - Search individual log entries
+datadog_log_analytics - Aggregate logs with groupBy
+```
+
+### Monitoring
+```
+datadog_monitors      - List and check monitor status
+datadog_synthetics    - List synthetic tests and results
+datadog_metrics       - Query timeseries metrics
+datadog_rum           - Search Real User Monitoring events
+```
+
+## Environment Variables
+
+Configure Datadog tools via environment:
+
+| Variable | Description |
+|----------|-------------|
+| `DATADOG_API_KEY` or `DD_API_KEY` | API key |
+| `DATADOG_APP_KEY` or `DD_APP_KEY` | Application key |
+| `DD_ENV` | Default environment filter |
+| `DD_SERVICE` | Default service filter |
+| `DD_SOURCE` | Default log source (default: lambda) |
+
+## Common Queries
+
+### Search Error Logs
+
+```
+datadog_logs --query "status:error" --from "now-1h"
+```
+
+### Count Errors by Service
+
+```
+datadog_log_analytics --groupBy '["service"]' --query "status:error"
+```
+
+### Check Alerting Monitors
+
+```
+datadog_monitors --status '["Alert", "Warn"]'
+```
+
+## Lambda Integration
+
+Enable Datadog tracing in CDK:
+
+```typescript
+import { JaypieLambda } from "@jaypie/constructs";
+
+const handler = new JaypieLambda(this, "Handler", {
+  datadogApiKeyArn: process.env.CDK_ENV_DATADOG_API_KEY_ARN,
+  environment: {
+    DD_ENV: "production",
+    DD_SERVICE: "my-api",
+    DD_VERSION: "1.0.0",
+  },
+});
+```
+
+## Logging Integration
+
+Jaypie logging automatically formats for Datadog:
+
+```typescript
+import { log } from "jaypie";
+
+// Structured logs are indexed by Datadog
+log.info("Request processed", {
+  userId: "user-123",
+  action: "checkout",
+  duration: 150,
+});
+```
+
+## Query Syntax
+
+### Log Search Syntax
+
+```
+status:error                    # By status
+@http.status_code:500          # By attribute
+service:my-api                  # By service
+*timeout*                       # Wildcard
+```
+
+### Time Ranges
+
+```
+now-15m                         # Last 15 minutes
+now-1h                          # Last hour
+now-1d                          # Last day
+2024-01-15T10:00:00Z           # Specific time (ISO 8601)
+```
+
+## Unified Service Tagging
+
+Use consistent tags across services:
+
+| Tag | Purpose |
+|-----|---------|
+| `env` | Environment (sandbox, production) |
+| `service` | Service name |
+| `version` | Deployment version |
+
+```typescript
+environment: {
+  DD_ENV: process.env.PROJECT_ENV,
+  DD_SERVICE: process.env.PROJECT_KEY,
+  DD_VERSION: process.env.npm_package_version,
+}
+```
+

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
+```
+