@jaypie/mcp 0.3.2 → 0.4.0

package/release-notes/mcp/0.3.4.md

@@ -0,0 +1,36 @@
+---
+version: 0.3.4
+date: 2025-01-20
+summary: Add skill tool for cleaner documentation access
+---
+
+## Changes
+
+### New Features
+
+- **skill tool**: New `skill(alias)` function for accessing Jaypie documentation
+  - Call `skill("index")` to list all available skills with descriptions
+  - Call `skill("aws")`, `skill("tests")`, etc. to get specific documentation
+  - Path traversal protection for security
+  - Case insensitive alias matching
+
+### New Skills
+
+Added 25 skill files covering all aspects of Jaypie development:
+- **Infrastructure**: aws, cdk, cicd, datadog, dns, dynamodb, secrets, variables
+- **Development**: debugging, errors, logs, mocks, style, tests, writing
+- **Patterns**: fabric, models, services, tools
+- **Reference**: agents, index, jaypie, legacy, releasenotes, topics
+
+### Skill Frontmatter
+
+Skills use YAML frontmatter with:
+- `description` - Brief description shown in index listing
+- `related` - Comma-separated list of related skill aliases
+
+### Deprecations
+
+- `list_prompts` - Use `skill("index")` instead
+- `read_prompt` - Use `skill(alias)` instead
+
+Both deprecated tools remain functional for backwards compatibility.

package/release-notes/mcp/0.4.0.md

@@ -0,0 +1,27 @@
+---
+version: 0.4.0
+date: 2025-01-20
+summary: Remove deprecated list_prompts and read_prompt tools
+---
+
+## Changes
+
+### Breaking Changes
+
+- **Removed `list_prompts` tool**: Use `skill("index")` instead
+- **Removed `read_prompt` tool**: Use `skill(alias)` instead
+- **Removed `prompts/` directory from package**: All documentation now lives in `skills/`
+
+### Migration
+
+If you were using `list_prompts`, replace with:
+```
+skill("index")
+```
+
+If you were using `read_prompt("Jaypie_Express_Package.md")`, find the equivalent skill alias and use:
+```
+skill("express")  // or appropriate alias
+```
+
+Use `skill("index")` to see all available skills with descriptions.

package/release-notes/testkit/1.2.15.md

@@ -0,0 +1,23 @@
+---
+version: 1.2.15
+date: 2025-01-20
+summary: Removed vocabulary mocks, updated to fabric types
+---
+
+## Changes
+
+- Removed `vocabulary` mock module (vocabulary package deprecated)
+- Updated `IndexableEntity` type import to `IndexableModel` from `@jaypie/fabric`
+- Removed `mock.vocabulary` exports from mock index
+
+## Migration
+
+If you were using vocabulary mocks, they are no longer needed as the functionality has moved to `@jaypie/fabric`:
+
+```typescript
+// Before
+import { IndexableEntity } from "@jaypie/testkit/mock";
+
+// After
+import { IndexableModel } from "@jaypie/fabric";
+```

package/skills/agents.md

@@ -0,0 +1,25 @@
+---
+description: Minimal agent instructions
+---
+
+# Agent Instructions
+
+Add to CLAUDE.md or AGENTS.md:
+
+```markdown
+## Jaypie
+
+Query `mcp__jaypie__skill(alias: String)` for development guidance:
+
+Contents: index, releasenotes, topics
+Development: debugging, errors, logs, mocks, style, tests, writing
+Infrastructure: aws, cdk, cicd, datadog, dns, dynamodb, secrets, variables
+Patterns: fabric, models, services, tools
+Meta: agents, jaypie, legacy
+```
+
+Or, for one line,
+
+```markdown
+`mcp__jaypie__skill(index)` describes Jaypie development skills for this repository.
+```

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