@jaypie/mcp 0.3.2 → 0.4.0

package/skills/fabric.md

@@ -0,0 +1,191 @@
+---
+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 { fabricMcp, FabricMcpServer } from "@jaypie/fabric/mcp";
+
+// Single service registration
+fabricMcp({ service: greetService, server });
+
+// Multi-service server (preferred)
+const server = FabricMcpServer({
+  name: "my-server",
+  version: "1.0.0",
+  services: [greetService, searchService],
+});
+// Available as MCP tools "greet" and "search"
+```
+
+### 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");
+
+// Access services
+suite.services;                    // ServiceMeta[] - metadata for listing
+suite.getServiceFunctions();       // Service[] - actual functions
+suite.execute("user_get", { id }); // Direct execution
+```
+
+### Suite to MCP Server
+
+Connect suites directly to MCP:
+
+```typescript
+import { createMcpServerFromSuite } from "@jaypie/fabric/mcp";
+
+const server = createMcpServerFromSuite(suite, {
+  name: "users-api",    // Optional override
+  version: "1.0.0",
+});
+// All suite services now available as MCP tools
+```
+
+## 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

package/skills/legacy.md

@@ -0,0 +1,97 @@
+---
+description: Legacy libraries and deprecated patterns
+related: dynamodb, fabric, mocks
+---
+
+# Legacy Patterns
+
+Deprecated libraries and patterns that may exist in older Jaypie projects.
+
+## @jaypie/core (Deprecated)
+
+Migrated to `@jaypie/kit`. Update imports:
+
+```typescript
+// Old
+import { someUtil } from "@jaypie/core";
+
+// New
+import { someUtil } from "@jaypie/kit";
+```
+
+## @jaypie/mongoose (Legacy)
+
+MongoDB/Mongoose integration. Consider DynamoDB for new projects.
+
+### Connection
+
+```typescript
+import { connectMongoose } from "@jaypie/mongoose";
+
+export const handler = async (event) => {
+  await connectMongoose();
+  // Connection cached for Lambda warm starts
+};
+```
+
+### Models
+
+```typescript
+import mongoose, { Schema, Document } from "mongoose";
+
+interface IUser extends Document {
+  email: string;
+  name: string;
+}
+
+const userSchema = new Schema<IUser>({
+  email: { type: String, required: true },
+  name: { type: String, required: true },
+}, { timestamps: true });
+
+export const User = mongoose.model<IUser>("User", userSchema);
+```
+
+### Mocking
+
+```typescript
+vi.mock("@jaypie/mongoose", async () => {
+  const { mockMongoose } = await import("@jaypie/testkit");
+  return mockMongoose(vi);
+});
+```
+
+## Migration Guides
+
+### Mongoose to DynamoDB
+
+1. Define DynamoDB item types (see `skill("dynamodb")`)
+2. Update data access patterns for single-table design
+3. Replace Mongoose queries with DynamoDB operations
+4. Update tests to mock DynamoDB instead of Mongoose
+
+### Core to Kit
+
+Direct replacement - same exports, new package name:
+
+```bash
+npm uninstall @jaypie/core
+npm install @jaypie/kit
+```
+
+Update imports throughout codebase.
+
+## When to Keep Legacy
+
+Keep legacy patterns when:
+- Existing production system is stable
+- Migration cost outweighs benefits
+- Team expertise is in legacy stack
+- Database has significant existing data
+
+Migrate when:
+- Starting new features
+- Performance issues arise
+- Scaling requirements change
+- Simplifying architecture
+

package/skills/logs.md

@@ -0,0 +1,160 @@
+---
+description: Logging patterns and conventions
+related: debugging, datadog, variables
+---
+
+# Logging Patterns
+
+Jaypie provides structured logging for observability.
+
+## Basic Usage
+
+```typescript
+import { log } from "jaypie";
+
+log.trace("Detailed debug info");
+log.debug("Debug information");
+log.info("Informational message");
+log.warn("Warning message");
+log.error("Error message");
+log.fatal("Fatal error");
+```
+
+## Structured Logging
+
+Always include context as the second argument:
+
+```typescript
+log.info("User logged in", {
+  userId: user.id,
+  email: user.email,
+  method: "oauth",
+});
+
+log.error("Payment failed", {
+  orderId: order.id,
+  amount: order.total,
+  error: error.message,
+});
+```
+
+## Log Levels
+
+| Level | Use For |
+|-------|---------|
+| trace | Very detailed debugging (loops, iterations) |
+| debug | Development debugging |
+| info | Normal operations, business events |
+| warn | Unexpected but handled situations |
+| error | Errors that need attention |
+| fatal | Application cannot continue |
+
+## Setting Log Level
+
+Via environment variable:
+
+```bash
+LOG_LEVEL=debug npm run dev
+LOG_LEVEL=trace npm test
+```
+
+In production, typically `info` or `warn`.
+
+## Request Context
+
+Include request identifiers for tracing:
+
+```typescript
+log.info("Processing request", {
+  requestId: req.id,
+  path: req.path,
+  userId: req.user?.id,
+});
+```
+
+## Error Logging
+
+Log errors with full context:
+
+```typescript
+try {
+  await riskyOperation();
+} catch (error) {
+  log.error("Operation failed", {
+    error: error.message,
+    stack: error.stack,
+    input: sanitizedInput,
+  });
+  throw error;
+}
+```
+
+## Sensitive Data
+
+Never log sensitive data:
+
+```typescript
+// BAD
+log.info("User auth", { password: user.password });
+
+// GOOD
+log.info("User auth", { userId: user.id, hasPassword: !!user.password });
+```
+
+## Searching Logs
+
+### Via MCP (Datadog)
+
+```
+# Search by requestId
+datadog_logs --query "@requestId:abc-123"
+
+# Search errors
+datadog_logs --query "status:error" --from "now-1h"
+
+# Search by user
+datadog_logs --query "@userId:user-456"
+```
+
+### Via MCP (CloudWatch)
+
+```
+aws_logs_filter_log_events \
+  --logGroupName "/aws/lambda/my-function" \
+  --filterPattern "ERROR"
+```
+
+## Log Format
+
+Jaypie logs are JSON-formatted for Datadog:
+
+```json
+{
+  "level": "info",
+  "message": "User logged in",
+  "timestamp": "2024-01-15T10:00:00.000Z",
+  "userId": "user-123",
+  "method": "oauth",
+  "dd": {
+    "trace_id": "abc123",
+    "span_id": "def456"
+  }
+}
+```
+
+## Lambda Logging
+
+Lambda handlers automatically add context:
+
+```typescript
+import { lambdaHandler } from "@jaypie/lambda";
+
+export const handler = lambdaHandler(async (event) => {
+  // Logs automatically include:
+  // - requestId
+  // - functionName
+  // - cold_start indicator
+  log.info("Processing", { customField: "value" });
+});
+```
+

package/skills/mocks.md

@@ -0,0 +1,174 @@
+---
+description: Mock patterns via @jaypie/testkit
+related: tests, errors
+---
+
+# Testing Mocks
+
+`@jaypie/testkit` provides mocks for Jaypie packages in tests.
+
+## Installation
+
+```bash
+npm install -D @jaypie/testkit
+```
+
+## Setup
+
+In your test setup file:
+
+```typescript
+// vitest.setup.ts
+import { vi } from "vitest";
+
+vi.mock("jaypie", async () => {
+  const { mockJaypie } = await import("@jaypie/testkit");
+  return mockJaypie(vi);
+});
+```
+
+Configure in vitest.config.ts:
+
+```typescript
+export default defineConfig({
+  test: {
+    setupFiles: ["./vitest.setup.ts"],
+  },
+});
+```
+
+## Available Mocks
+
+### Main Package (jaypie)
+
+```typescript
+vi.mock("jaypie", async () => {
+  const { mockJaypie } = await import("@jaypie/testkit");
+  return mockJaypie(vi);
+});
+
+// Mocked: log, getSecret, sendMessage, etc.
+```
+
+### Logger
+
+```typescript
+vi.mock("@jaypie/logger", async () => {
+  const { mockLogger } = await import("@jaypie/testkit");
+  return mockLogger(vi);
+});
+```
+
+### AWS
+
+```typescript
+vi.mock("@jaypie/aws", async () => {
+  const { mockAws } = await import("@jaypie/testkit");
+  return mockAws(vi);
+});
+```
+
+### Legacy Mocks
+
+For legacy packages, see `skill("legacy")`.
+
+## Using Mocks in Tests
+
+### Verify Logging
+
+```typescript
+import { log } from "jaypie";
+
+it("logs the operation", async () => {
+  await myFunction();
+
+  expect(log.info).toHaveBeenCalledWith(
+    "Operation completed",
+    expect.objectContaining({ userId: "123" })
+  );
+});
+```
+
+### Mock Secret Values
+
+```typescript
+import { getSecret } from "jaypie";
+
+beforeEach(() => {
+  vi.mocked(getSecret).mockResolvedValue("mock-api-key");
+});
+
+it("uses the API key", async () => {
+  const result = await myFunction();
+
+  expect(getSecret).toHaveBeenCalledWith("api-key-name");
+  expect(result.authenticated).toBe(true);
+});
+```
+
+### Mock Errors
+
+```typescript
+import { getSecret } from "jaypie";
+import { ConfigurationError } from "jaypie";
+
+it("handles missing secrets", async () => {
+  vi.mocked(getSecret).mockRejectedValue(
+    new ConfigurationError("Secret not found")
+  );
+
+  await expect(myFunction()).rejects.toThrow(ConfigurationError);
+});
+```
+
+## Mock Matchers
+
+### toBeJaypieError
+
+```typescript
+import { matchers } from "@jaypie/testkit";
+
+expect.extend(matchers);
+
+it("throws a Jaypie error", async () => {
+  await expect(myFunction()).rejects.toBeJaypieError();
+});
+```
+
+### toBeValidSchema
+
+```typescript
+it("returns valid schema", () => {
+  const result = buildSchema();
+  expect(result).toBeValidSchema();
+});
+```
+
+## Per-Test Mock Reset
+
+```typescript
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+afterEach(() => {
+  vi.resetAllMocks();
+});
+```
+
+## Export Verification
+
+When adding exports to packages, update testkit:
+
+```typescript
+// packages/testkit/src/mocks/mockJaypie.ts
+export function mockJaypie(vi) {
+  return {
+    log: mockLog(vi),
+    getSecret: vi.fn().mockResolvedValue("mock"),
+    // Add new exports here
+    newFunction: vi.fn(),
+  };
+}
+```
+