@jaypie/mcp 0.3.2 → 0.3.4

package/skills/tools.md

@@ -0,0 +1,127 @@
+---
+description: Available MCP tools reference
+related: aws, datadog, debugging
+---
+
+# MCP Tools Reference
+
+Tools available through the Jaypie MCP server.
+
+## Documentation Tools
+
+| Tool | Description |
+|------|-------------|
+| `skill` | Access Jaypie skill documentation |
+| `list_prompts` | List prompt files (deprecated, use skill) |
+| `read_prompt` | Read prompt file (deprecated, use skill) |
+| `version` | Get MCP server version |
+| `list_release_notes` | List package release notes |
+| `read_release_note` | Read specific release note |
+
+### Using Skills
+
+```
+skill("index")          # List all skills
+skill("jaypie")         # Jaypie overview
+skill("tests")          # Testing patterns
+```
+
+## AWS Tools
+
+| Tool | Description |
+|------|-------------|
+| `aws_list_profiles` | List AWS profiles from ~/.aws |
+| `aws_lambda_list_functions` | List Lambda functions |
+| `aws_lambda_get_function` | Get Lambda function details |
+| `aws_logs_filter_log_events` | Search CloudWatch Logs |
+| `aws_s3_list_objects` | List S3 bucket objects |
+| `aws_cloudformation_describe_stack` | Get CloudFormation stack details |
+
+### DynamoDB
+
+| Tool | Description |
+|------|-------------|
+| `aws_dynamodb_describe_table` | Get table metadata |
+| `aws_dynamodb_query` | Query by partition key |
+| `aws_dynamodb_scan` | Full table scan |
+| `aws_dynamodb_get_item` | Get single item |
+
+### SQS
+
+| Tool | Description |
+|------|-------------|
+| `aws_sqs_list_queues` | List SQS queues |
+| `aws_sqs_get_queue_attributes` | Get queue attributes |
+| `aws_sqs_receive_message` | Peek at messages |
+| `aws_sqs_purge_queue` | Delete all messages |
+
+### Step Functions
+
+| Tool | Description |
+|------|-------------|
+| `aws_stepfunctions_list_executions` | List state machine executions |
+| `aws_stepfunctions_stop_execution` | Stop running execution |
+
+## Datadog Tools
+
+| Tool | Description |
+|------|-------------|
+| `datadog_logs` | Search log entries |
+| `datadog_log_analytics` | Aggregate logs with groupBy |
+| `datadog_monitors` | List and check monitors |
+| `datadog_synthetics` | List synthetic tests |
+| `datadog_metrics` | Query timeseries metrics |
+| `datadog_rum` | Search RUM events |
+
+## LLM Tools
+
+| Tool | Description |
+|------|-------------|
+| `llm_debug_call` | Debug LLM API call |
+| `llm_list_providers` | List available LLM providers |
+
+## Environment Variables
+
+### AWS Tools
+- `AWS_PROFILE` - Default profile
+- `AWS_REGION` - Default region
+
+### Datadog Tools
+- `DATADOG_API_KEY` or `DD_API_KEY` - API key
+- `DATADOG_APP_KEY` or `DD_APP_KEY` - App key
+- `DD_ENV` - Default environment filter
+- `DD_SERVICE` - Default service filter
+- `DD_SOURCE` - Default log source
+
+## Common Patterns
+
+### Debug Lambda Issues
+
+```
+# Check function config
+aws_lambda_get_function --functionName "my-function"
+
+# Search recent logs
+aws_logs_filter_log_events --logGroupName "/aws/lambda/my-function" --filterPattern "ERROR"
+
+# Or via Datadog
+datadog_logs --query "service:my-function status:error" --from "now-1h"
+```
+
+### Check Queue Health
+
+```
+# Get queue depth
+aws_sqs_get_queue_attributes --queueUrl "https://..."
+
+# Peek at messages
+aws_sqs_receive_message --queueUrl "https://..." --maxNumberOfMessages 5
+```
+
+### Monitor Status
+
+```
+# Check alerting monitors
+datadog_monitors --status '["Alert", "Warn"]'
+```
+

package/skills/topics.md

@@ -0,0 +1,116 @@
+---
+description: Topic index and cross-reference
+---
+
+# Topic Index
+
+Quick reference for finding the right skill for your task.
+
+## By Task
+
+### Starting a New Project
+- `skill("jaypie")` - Jaypie overview
+- `skill("style")` - Code conventions
+- `skill("cdk")` - Infrastructure setup
+
+### Writing Code
+- `skill("style")` - Code style
+- `skill("errors")` - Error handling
+- `skill("services")` - Service patterns
+- `skill("models")` - Data models
+
+### Testing
+- `skill("tests")` - Vitest patterns
+- `skill("mocks")` - @jaypie/testkit mocks
+
+### Deploying
+- `skill("cdk")` - CDK constructs
+- `skill("cicd")` - GitHub Actions
+- `skill("variables")` - Environment config
+
+### Debugging
+- `skill("debugging")` - Debug techniques
+- `skill("logs")` - Log searching
+- `skill("datadog")` - Observability tools
+
+### AWS Integration
+- `skill("aws")` - AWS tools overview
+- `skill("dynamodb")` - DynamoDB patterns
+- `skill("secrets")` - Secret management
+
+## By Package
+
+### jaypie (main package)
+- `skill("jaypie")` - Overview
+- `skill("errors")` - Error types
+- `skill("logs")` - Logging
+- `skill("secrets")` - Secret access
+
+### @jaypie/constructs
+- `skill("cdk")` - CDK constructs
+
+### @jaypie/testkit
+- `skill("mocks")` - Mock patterns
+- `skill("tests")` - Test patterns
+
+### @jaypie/fabric
+- `skill("fabric")` - Service patterns
+- `skill("services")` - Service layer
+
+### Legacy Packages
+- `skill("legacy")` - Deprecated patterns
+
+## By Concept
+
+### Error Handling
+- `skill("errors")` - Error types and usage
+
+### Environment Configuration
+- `skill("variables")` - Environment variables
+- `skill("secrets")` - Secret management
+
+### Infrastructure
+- `skill("cdk")` - CDK constructs
+- `skill("aws")` - AWS integration
+- `skill("dns")` - Domain configuration
+
+### Observability
+- `skill("logs")` - Logging patterns
+- `skill("datadog")` - Datadog integration
+- `skill("debugging")` - Debug techniques
+
+### Data
+- `skill("models")` - Data models and types
+- `skill("dynamodb")` - DynamoDB patterns
+
+## Quick Answers
+
+### "How do I throw an error?"
+```typescript
+import { NotFoundError } from "jaypie";
+throw new NotFoundError("Item not found");
+```
+See: `skill("errors")`
+
+### "How do I mock Jaypie in tests?"
+```typescript
+vi.mock("jaypie", async () => {
+  const { mockJaypie } = await import("@jaypie/testkit");
+  return mockJaypie(vi);
+});
+```
+See: `skill("mocks")`
+
+### "How do I get a secret?"
+```typescript
+import { getSecret } from "jaypie";
+const apiKey = await getSecret("my-api-key");
+```
+See: `skill("secrets")`
+
+### "How do I log with context?"
+```typescript
+import { log } from "jaypie";
+log.info("Operation completed", { userId, duration });
+```
+See: `skill("logs")`

package/skills/variables.md

@@ -0,0 +1,146 @@
+---
+description: Environment variables reference
+related: secrets, cdk, datadog
+---
+
+# Environment Variables
+
+Configuration variables used in Jaypie applications.
+
+## Project Variables
+
+| Variable | Description | Values |
+|----------|-------------|--------|
+| `PROJECT_ENV` | Environment identifier | local, sandbox, kitchen, lab, studio, production |
+| `PROJECT_KEY` | Project name for logging | e.g., my-api |
+| `PROJECT_NONCE` | Unique resource suffix | e.g., dev, staging, prod |
+| `PROJECT_CHAOS` | Chaos engineering mode | none, partial, full |
+
+### Usage
+
+```typescript
+const env = process.env.PROJECT_ENV || "local";
+const key = process.env.PROJECT_KEY || "unknown";
+
+log.info("Starting", { env, project: key });
+```
+
+## Node Environment
+
+| Variable | Description | Values |
+|----------|-------------|--------|
+| `NODE_ENV` | Node.js environment | development, production, test |
+| `LOG_LEVEL` | Logging verbosity | trace, debug, info, warn, error |
+
+### Log Level in Development
+
+```bash
+# Very verbose
+LOG_LEVEL=trace npm run dev
+
+# Normal debugging
+LOG_LEVEL=debug npm run dev
+```
+
+## CDK Infrastructure Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CDK_ENV_BUCKET` | S3 bucket name |
+| `CDK_ENV_QUEUE_URL` | SQS queue URL |
+| `CDK_ENV_SNS_ROLE_ARN` | SNS role ARN |
+| `CDK_ENV_SNS_TOPIC_ARN` | SNS topic ARN |
+| `CDK_ENV_DATADOG_API_KEY_ARN` | Datadog API key ARN |
+| `CDK_ENV_TABLE` | DynamoDB table name |
+
+### Passing to Lambda
+
+```typescript
+const handler = new JaypieLambda(this, "Handler", {
+  environment: {
+    PROJECT_ENV: "production",
+    PROJECT_KEY: "my-api",
+    CDK_ENV_BUCKET: bucket.bucketName,
+    CDK_ENV_QUEUE_URL: queue.queueUrl,
+  },
+});
+```
+
+## Secret Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SECRET_MONGODB_URI` | MongoDB connection secret name |
+| `SECRET_API_KEY` | Third-party API key secret name |
+
+### Usage Pattern
+
+```typescript
+// Secret name from env, value from Secrets Manager
+const secretName = process.env.SECRET_MONGODB_URI;
+const mongoUri = await getSecret(secretName);
+```
+
+## AWS Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AWS_PROFILE` | Default AWS profile |
+| `AWS_REGION` | Default AWS region |
+| `AWS_DEFAULT_REGION` | Fallback region |
+| `AWS_SESSION_TOKEN` | Session token (Lambda runtime) |
+| `AWS_ACCESS_KEY_ID` | Access key (if not using profile) |
+| `AWS_SECRET_ACCESS_KEY` | Secret key (if not using profile) |
+
+## Datadog Variables
+
+| Variable | Description |
+|----------|-------------|
+| `DATADOG_API_KEY` or `DD_API_KEY` | API key |
+| `DATADOG_APP_KEY` or `DD_APP_KEY` | Application key |
+| `DD_ENV` | Environment tag |
+| `DD_SERVICE` | Service name tag |
+| `DD_VERSION` | Version tag |
+| `DD_SOURCE` | Log source (default: lambda) |
+
+### Unified Service Tagging
+
+```typescript
+environment: {
+  DD_ENV: process.env.PROJECT_ENV,
+  DD_SERVICE: process.env.PROJECT_KEY,
+  DD_VERSION: process.env.npm_package_version,
+}
+```
+
+## Local Development
+
+### .env Files
+
+```bash
+# .env.local (not committed)
+PROJECT_ENV=local
+PROJECT_KEY=my-api
+LOG_LEVEL=debug
+MONGODB_URI=mongodb://localhost:27017/dev
+```
+
+### Loading .env
+
+```typescript
+import "dotenv/config";
+
+// Or in package.json
+"scripts": {
+  "dev": "dotenv -- node src/index.js"
+}
+```
+
+## Environment Detection
+
+```typescript
+const isProduction = process.env.PROJECT_ENV === "production";
+const isLocal = process.env.PROJECT_ENV === "local";
+const isDevelopment = !isProduction;
+```
+

package/skills/writing.md

@@ -0,0 +1,153 @@
+---
+description: Documentation and writing style
+---
+
+# Writing Style
+
+Guidelines for writing Jaypie documentation.
+
+## Principles
+
+1. **Concise** - Fewer words, more clarity
+2. **Scannable** - Use headings, lists, tables
+3. **Actionable** - Show, don't tell
+4. **Current** - Keep examples up to date
+
+## Formatting
+
+### Headings
+
+```markdown
+# Page Title (H1 - one per file)
+## Major Section (H2)
+### Subsection (H3)
+```
+
+### Code Blocks
+
+Always specify language:
+
+```typescript
+import { log } from "jaypie";
+log.info("Message", { context });
+```
+
+### Lists
+
+Use bullets for unordered items:
+- First item
+- Second item
+
+Use numbers for sequential steps:
+1. First step
+2. Second step
+
+### Tables
+
+Use for structured comparisons:
+
+| Option | Description |
+|--------|-------------|
+| `verbose` | Enable verbose logging |
+| `timeout` | Request timeout in ms |
+
+## Voice
+
+- **Active voice**: "Run the command" not "The command should be run"
+- **Present tense**: "Returns a string" not "Will return a string"
+- **Second person**: "You can configure" not "Users can configure"
+- **Imperative mood**: "Create a file" not "You should create a file"
+
+## Code Examples
+
+### Good Example
+
+```typescript
+// Clear purpose
+import { NotFoundError } from "jaypie";
+
+throw new NotFoundError("User not found");
+```
+
+### Bad Example
+
+```typescript
+// Avoid: no explanation, poor naming
+import { NotFoundError } from "jaypie";
+const e = new NotFoundError("err");
+throw e;
+```
+
+## Structure
+
+### Skill Files
+
+```markdown
+---
+description: Brief description for index listing
+related: alias1, alias2
+---
+
+# Skill Title
+
+One sentence overview.
+
+## Quick Start
+
+Minimal working example.
+
+## Details
+
+Deeper explanation with examples.
+
+## Reference
+
+Tables, options, API details.
+```
+
+### README Files
+
+```markdown
+# Package Name
+
+One-line description.
+
+## Installation
+
+\`\`\`bash
+npm install package-name
+\`\`\`
+
+## Usage
+
+\`\`\`typescript
+import { feature } from "package-name";
+feature();
+\`\`\`
+
+## API
+
+Document exports.
+
+## License
+
+MIT
+```
+
+## Anti-Patterns
+
+Avoid:
+- Long paragraphs (use lists)
+- Vague language ("various", "etc.")
+- Redundant words ("in order to" → "to")
+- Future promises ("will be added")
+- Passive voice ("is used by" → "uses")
+
+## Checklist
+
+Before publishing:
+- [ ] Code examples run without errors
+- [ ] All links work
+- [ ] No placeholder text
+- [ ] Spelling and grammar checked
+- [ ] Frontmatter complete