@jaypie/mcp 0.3.2 → 0.4.0

package/skills/style.md

@@ -0,0 +1,190 @@
+---
+description: Code style conventions and patterns
+related: errors, tests
+---
+
+# Code Style
+
+Jaypie coding conventions and patterns.
+
+## General Rules
+
+### TypeScript Everywhere
+
+Use TypeScript for all code:
+
+```typescript
+// GOOD
+function greet(name: string): string {
+  return `Hello, ${name}!`;
+}
+
+// BAD
+function greet(name) {
+  return `Hello, ${name}!`;
+}
+```
+
+### ESM Over CommonJS
+
+Use ES modules:
+
+```typescript
+// GOOD
+import { log } from "jaypie";
+export function myFunction() {}
+
+// BAD
+const { log } = require("jaypie");
+module.exports = { myFunction };
+```
+
+### Alphabetize Everything
+
+Alphabetize imports, object keys, exports:
+
+```typescript
+// GOOD
+import { ConfigurationError, log, NotFoundError } from "jaypie";
+
+const config = {
+  apiKey: "...",
+  baseUrl: "...",
+  timeout: 5000,
+};
+
+// BAD
+import { NotFoundError, log, ConfigurationError } from "jaypie";
+```
+
+## Function Signatures
+
+### Object Parameters
+
+Use destructured objects for multiple parameters:
+
+```typescript
+// GOOD
+function createUser({ email, name, role }: CreateUserInput) {}
+
+// GOOD (single required + optional config)
+function fetchData(url: string, { timeout, retries }: FetchOptions = {}) {}
+
+// BAD (multiple positional parameters)
+function createUser(email: string, name: string, role: string) {}
+```
+
+### Allow Zero Arguments
+
+Functions with optional config should allow no arguments:
+
+```typescript
+// GOOD
+function initialize(options: InitOptions = {}) {
+  const { timeout = 5000, retries = 3 } = options;
+}
+
+// Call with or without args
+initialize();
+initialize({ timeout: 10000 });
+```
+
+## Constants
+
+### File-Level Constants
+
+Use SCREAMING_SNAKE_CASE for constants:
+
+```typescript
+const DEFAULT_TIMEOUT = 5000;
+const DATADOG_SITE = "datadoghq.com";
+const HTTP_STATUS = {
+  OK: 200,
+  NOT_FOUND: 404,
+} as const;
+```
+
+### Magic Numbers
+
+Never use magic numbers inline:
+
+```typescript
+// BAD
+if (retries > 3) { ... }
+await sleep(5000);
+
+// GOOD
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 5000;
+
+if (retries > MAX_RETRIES) { ... }
+await sleep(RETRY_DELAY_MS);
+```
+
+## Error Handling
+
+### Never Vanilla Error
+
+```typescript
+// BAD
+throw new Error("Missing config");
+
+// GOOD
+import { ConfigurationError } from "jaypie";
+throw new ConfigurationError("Missing config");
+```
+
+### Error Context
+
+Include relevant context:
+
+```typescript
+throw new NotFoundError("User not found", {
+  context: { userId, searchedAt: new Date() }
+});
+```
+
+## Avoid Over-Engineering
+
+### No Premature Abstraction
+
+```typescript
+// BAD - Unnecessary abstraction for one use
+const formatName = (name) => name.toUpperCase();
+const processUser = (user) => ({ ...user, name: formatName(user.name) });
+
+// GOOD - Simple and direct
+const processUser = (user) => ({ ...user, name: user.name.toUpperCase() });
+```
+
+### Minimal Changes
+
+Only modify what's requested:
+
+- Bug fix? Fix the bug, nothing else.
+- Add feature? Add only that feature.
+- Don't add docstrings to unchanged code.
+- Don't refactor surrounding code.
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|-----------|---------|
+| Functions | camelCase | `getUser`, `createOrder` |
+| Classes | PascalCase | `UserService`, `OrderModel` |
+| Constants | SCREAMING_SNAKE | `MAX_RETRIES`, `API_URL` |
+| Files | kebab-case | `user-service.ts`, `order-model.ts` |
+| Types/Interfaces | PascalCase | `UserInput`, `IUserService` |
+
+## Lint Rules
+
+Use `@jaypie/eslint`:
+
+```javascript
+// eslint.config.mjs
+import jaypie from "@jaypie/eslint";
+export default [...jaypie];
+```
+
+Always run `npm run format` before committing.
+

package/skills/tests.md

@@ -0,0 +1,209 @@
+---
+description: Testing patterns with Vitest
+related: mocks, errors
+---
+
+# Testing Patterns
+
+Jaypie uses Vitest for testing with specific patterns and mocks.
+
+## Setup
+
+### vitest.config.ts
+
+```typescript
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    coverage: {
+      reporter: ["text", "json", "html"],
+    },
+    globals: true,
+    setupFiles: ["./vitest.setup.ts"],
+  },
+});
+```
+
+### vitest.setup.ts
+
+```typescript
+import { vi } from "vitest";
+
+vi.mock("jaypie", async () => {
+  const { mockJaypie } = await import("@jaypie/testkit");
+  return mockJaypie(vi);
+});
+```
+
+## Test Structure
+
+### File Organization
+
+```
+src/
+├── services/
+│   └── user.ts
+└── __tests__/
+    └── user.spec.ts
+
+# Or co-located:
+src/
+└── services/
+    ├── user.ts
+    └── user.spec.ts
+```
+
+### Test File Pattern
+
+```typescript
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+describe("UserService", () => {
+  describe("getUser", () => {
+    it("returns user when found", async () => {
+      // Arrange
+      const mockUser = { id: "123", name: "John" };
+      vi.mocked(User.findById).mockResolvedValue(mockUser);
+
+      // Act
+      const result = await getUser("123");
+
+      // Assert
+      expect(result).toEqual(mockUser);
+    });
+  });
+});
+```
+
+## Running Tests
+
+```bash
+# Run all tests (non-watch mode)
+npm test
+
+# Run specific package
+npm test -w packages/my-package
+
+# Watch mode (development)
+npx vitest
+
+# With coverage
+npm test -- --coverage
+```
+
+**Important**: Always use `npm test` or `vitest run`, not bare `vitest` which runs in watch mode.
+
+## Mocking
+
+### Module Mocks
+
+```typescript
+vi.mock("./user-service.js", () => ({
+  getUser: vi.fn(),
+  createUser: vi.fn(),
+}));
+
+// Access mocked functions
+import { getUser } from "./user-service.js";
+
+vi.mocked(getUser).mockResolvedValue({ id: "123" });
+```
+
+### Jaypie Mocks
+
+```typescript
+import { log, getSecret } from "jaypie";
+
+it("logs the operation", async () => {
+  await myFunction();
+  expect(log.info).toHaveBeenCalledWith("Operation started");
+});
+
+it("uses secrets", async () => {
+  vi.mocked(getSecret).mockResolvedValue("test-key");
+  await myFunction();
+  expect(getSecret).toHaveBeenCalledWith("api-key");
+});
+```
+
+## Testing Errors
+
+```typescript
+import { NotFoundError } from "jaypie";
+
+it("throws NotFoundError when user missing", async () => {
+  vi.mocked(User.findById).mockResolvedValue(null);
+
+  await expect(getUser("invalid")).rejects.toThrow(NotFoundError);
+});
+
+it("includes error context", async () => {
+  vi.mocked(User.findById).mockResolvedValue(null);
+
+  try {
+    await getUser("invalid");
+    expect.fail("Should have thrown");
+  } catch (error) {
+    expect(error.context.userId).toBe("invalid");
+  }
+});
+```
+
+## Async Testing
+
+```typescript
+it("handles async operations", async () => {
+  const result = await asyncFunction();
+  expect(result).toBeDefined();
+});
+
+it("handles promises", () => {
+  return expect(asyncFunction()).resolves.toBeDefined();
+});
+
+it("handles rejections", () => {
+  return expect(failingFunction()).rejects.toThrow();
+});
+```
+
+## Before/After Hooks
+
+```typescript
+describe("UserService", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.resetAllMocks();
+  });
+
+  beforeAll(async () => {
+    // One-time setup
+  });
+
+  afterAll(async () => {
+    // One-time cleanup
+  });
+});
+```
+
+## Snapshot Testing
+
+```typescript
+it("renders expected output", () => {
+  const result = buildConfig({ env: "production" });
+  expect(result).toMatchSnapshot();
+});
+```
+
+## Test Coverage
+
+Aim for meaningful coverage, not 100%:
+
+- Test business logic thoroughly
+- Test error paths
+- Skip trivial getters/setters
+- Skip generated code
+

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")`