@jaypie/mcp 0.1.0 → 0.1.1

package/prompts/Jaypie_Init_Express_on_Lambda.md

@@ -0,0 +1,87 @@
+---
+trigger: model_decision
+description: When asked to create a new workspace or subpackage for express, usually packages/express, to run as serverless Lambdas behind API Gateway
+---
+
+# Jaypie Initialize Express on Lambda Subpackage
+
+## Process
+
+1. Follow Jaypie_Init_Project_Subpackage.md:
+   * Use @project-org/express in packages/express
+   * This creates the basic subpackage structure with package.json, tsconfig.json, and vitest config files
+
+2. Copy Express-specific template files:
+   * Copy `prompts/templates/express-subpackage/index.ts` to `packages/express/index.ts`
+   * Copy `prompts/templates/express-subpackage/src/app.ts` to `packages/express/src/app.ts`
+   * Copy `prompts/templates/express-subpackage/src/handler.config.ts` to `packages/express/src/handler.config.ts`
+   * Copy `prompts/templates/express-subpackage/src/routes/resource.router.ts` to `packages/express/src/routes/resource.router.ts`
+   * Copy `prompts/templates/express-subpackage/src/routes/resource/resourceGet.route.ts` to `packages/express/src/routes/resource/resourceGet.route.ts`
+   * Copy `prompts/templates/express-subpackage/src/routes/resource/__tests__/resourceGet.route.spec.ts` to `packages/express/src/routes/resource/__tests__/resourceGet.route.spec.ts`
+   * Copy `prompts/templates/express-subpackage/src/types/express.ts` to `packages/express/src/types/express.ts`
+
+3. Update package.json scripts:
+   * Modify the existing scripts section to include:
+     * `"dev": "tsx watch index.ts"`
+     * `"start": "node dist/index.js"`
+     * `"build": "tsc"`
+   * Run `npm run format:package`
+
+4. Install dependencies:
+   * `npm --workspace ./packages/express install jaypie express @codegenie/serverless-express`
+   * `npm --workspace ./packages/express install --save-dev @types/express @types/cors`
+   * Always run `npm install`, never update package.json with dependencies from memory
+
+5. Update TypeScript configuration:
+   * Update packages/express/tsconfig.json to include index.ts in the include array: `"include": ["src/**/*", "index.ts"]`
+   * Change exclude to: `"exclude": ["node_modules", "dist", "**/*.spec.ts"]`
+   * Test the build
+   * Ensure dist/ is in gitignore
+
+6. Update the top-level package.json:
+   * Add `"dev:express": "npm --workspace packages/express run dev"` and `"start:express": "npm --workspace packages/express run start"`
+   * If there is no stand-alone `dev` or `start`, create a `dev` running `dev:express` and `start` running `start:express`
+   * If `dev` or `start` exist, add calls to express if it fits the goal of the current commands
+
+## Pattern
+
+- TypeScript with ES modules (`"type": "module"`)
+- Handler pattern: configuration → lifecycle → processing → response
+- Optional `handlerConfig` for shared configuration and lifecycle management
+- Clean separation of concerns with middleware patterns
+- Lambda-optimized Express configuration
+
+## Structure
+
+```
+express/
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts
+├── vitest.setup.ts
+├── index.ts
+├── src/
+│   ├── app.ts
+│   ├── handler.config.ts
+│   ├── routes/
+│   │   ├── resource.router.ts
+│   │   └── resource/
+│   │       ├── resourceGet.route.ts
+│   │       └── __tests__/
+│   │           └── resourceGet.route.spec.ts
+│   └── types/
+│       └── express.ts
+└── dist/
+```
+
+## Local Development
+
+### Listening on Port 8080
+
+A local entrypoint, usually index.ts, may check `process.env.NODE_ENV === "development"` and be allowed to listen on port 8080 (preserving 3000 for front ends).
+`npm run dev:express` should be configured to initialize this mode locally.
+
+## Version Compatibility
+
+Jaypie uses Express 4.
+There is no immediately planned upgrade to Express 5.

package/prompts/Jaypie_Init_Jaypie_CDK_Package.md

@@ -0,0 +1,35 @@
+---
+trigger: model_decision
+description: When asked to create a new workspace or subpackage for cdk, usually packages/cdk
+---
+
+# Jaypie Initialize CDK Subpackage
+
+## Process
+
+1. Follow Jaypie_Init_Project_Subpackage.md:
+   * Use @project-org/cdk in packages/cdk
+   * Skip the src structure
+
+2. Copy template files:
+   * Copy `prompts/templates/cdk-subpackage/bin/cdk.ts` to `packages/cdk/bin/cdk.ts`
+   * Copy `prompts/templates/cdk-subpackage/lib/cdk-app.ts` to `packages/cdk/lib/cdk-app.ts`
+   * Copy `prompts/templates/cdk-subpackage/lib/cdk-infrastructure.ts` to `packages/cdk/lib/cdk-infrastructure.ts`
+   * Copy `prompts/templates/cdk-subpackage/cdk.json` to `packages/cdk/cdk.json`
+
+3. Update package.json:
+   * Add `"bin": {"cdk": "dist/cdk.js"}`
+   * In `scripts`,
+       * Make `"clean": "rimfaf cdk.out",`
+       * Add `"cdk": "cdk",`
+   * Run `npm run format:package`
+
+4. Install dependencies:
+   * `npm --workspace ./packages/cdk install @jaypie/constructs aws-cdk-lib constructs`
+   * `npm --workspace ./packages/cdk install --save-dev aws-cdk`
+   * Always run `npm install`, never update package.json with dependencies from memory
+
+5. Update TypeScript build:
+   * Update packages/cdk/tsconfig.json and packages/cdk/vite.config.ts to build from bin and lib while creating dist/cdk.js
+   * Test the build
+   * Make sure `cdk.out` is in gitignore

package/prompts/Jaypie_Init_Lambda_Package.md

@@ -0,0 +1,245 @@
+---
+trigger: model_decision
+description: When asked to create a new workspace or subpackage for lambdas
+---
+
+# Jaypie Lambda Package
+
+Lambda package structure for AWS Lambda functions using Jaypie.
+
+## Goal
+
+Create AWS Lambda functions that integrate with Jaypie for event-driven processing.
+
+## Guidelines
+
+- Uses TypeScript with ES modules
+- Leverages Jaypie's lambdaHandler wrapper for setup/teardown
+- Built with Rollup for optimized deployment packages
+- Tests with Vitest and Jaypie testkit
+
+## Process
+
+### 1. Setup Package Structure
+
+```
+packages/lambda/
+├── package.json       # Define dependencies and scripts
+├── tsconfig.json      # TypeScript configuration 
+├── rollup.config.ts   # Bundle configuration
+├── vitest.config.ts   # Test configuration
+├── vitest.setup.ts    # Test setup and mocks
+└── src/
+    ├── index.ts       # Export handlers
+    ├── worker.ts      # Lambda function implementation
+    └── __tests__/     # Test files
+        └── worker.spec.ts
+```
+
+### 2. Configure package.json
+
+```json
+{
+  "name": "@yourorg/lambda",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "rollup --config",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "jaypie": "^1.1.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^12.0.0",
+    "@types/aws-lambda": "^8.10.0",
+    "rollup": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}
+```
+
+### 3. Configure TypeScript
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### 4. Configure Rollup
+
+```typescript
+import typescript from "@rollup/plugin-typescript";
+import type { RollupOptions } from "rollup";
+
+const config: RollupOptions[] = [
+  {
+    input: "src/worker.ts",
+    output: {
+      file: "dist/worker.js",
+      format: "es",
+      sourcemap: true
+    },
+    plugins: [
+      typescript({
+        exclude: ["**/__tests__/**/*"]
+      })
+    ],
+    external: ["jaypie"]
+  },
+  {
+    input: "src/index.ts",
+    output: {
+      file: "dist/index.js",
+      format: "es",
+      sourcemap: true
+    },
+    plugins: [
+      typescript({
+        exclude: ["**/__tests__/**/*"]
+      })
+    ],
+    external: ["jaypie"]
+  }
+];
+
+export default config;
+```
+
+### 5. Setup Vitest
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  test: {
+    setupFiles: ["./vitest.setup.ts"]
+  }
+});
+
+// vitest.setup.ts
+import { matchers as jaypieMatchers } from "@jaypie/testkit";
+import * as extendedMatchers from "jest-extended";
+import { expect, vi } from "vitest";
+
+expect.extend(extendedMatchers);
+expect.extend(jaypieMatchers);
+
+vi.mock("jaypie", async () => vi.importActual("@jaypie/testkit/mock"));
+```
+
+### 6. Create Handler Implementation
+
+```typescript
+// src/worker.ts
+import { lambdaHandler, log } from "jaypie";
+import type { Context } from "jaypie";
+
+export interface WorkerEvent {
+  message?: string;
+}
+
+export const handler = lambdaHandler(
+  async (event: WorkerEvent, context: Context) => {
+    log.trace("worker: start");
+    
+    const message = event?.message || "Hello, world!";
+    
+    log.trace("worker: processing message", { message });
+    
+    const response = {
+      status: "success",
+      message,
+      timestamp: new Date().toISOString()
+    };
+    
+    log.trace("worker: complete");
+    return response;
+  },
+  {
+    name: "worker"
+  }
+);
+```
+
+### 7. Export Handler
+
+```typescript
+// src/index.ts
+export { handler as workerHandler } from "./worker.js";
+```
+
+### 8. Write Tests
+
+```typescript
+// src/__tests__/worker.spec.ts
+import { vi, describe, it, expect, beforeEach } from "vitest";
+import { handler, WorkerEvent } from "../worker.js";
+import { log } from "jaypie";
+import type { Context } from "jaypie";
+
+vi.mock("jaypie", async () => vi.importActual("@jaypie/testkit/mock"));
+
+describe("worker Lambda handler", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns success with provided message", async () => {
+    const event: WorkerEvent = {
+      message: "Test message"
+    };
+
+    const result = await handler(event, {} as Context);
+    
+    expect(result).toHaveProperty("status", "success");
+    expect(result).toHaveProperty("message", "Test message");
+    expect(result).toHaveProperty("timestamp");
+  });
+
+  it("returns default message when none provided", async () => {
+    const event = {} as WorkerEvent;
+
+    const result = await handler(event, {} as Context);
+    
+    expect(result).toHaveProperty("message", "Hello, world!");
+  });
+
+  it("logs trace for operations", async () => {
+    const event: WorkerEvent = {
+      message: "Test message"
+    };
+
+    await handler(event, {} as Context);
+    
+    expect(log.trace).toHaveBeenCalled();
+    expect(log).not.toBeCalledAboveTrace();
+  });
+});
+```
+
+### 9. Build and Deploy
+
+```bash
+# Build the Lambda package
+npm run build
+
+# Deploy using AWS CDK or other deployment tool
+# The Lambda handler will be referenced as "workerHandler"
+```

package/prompts/Jaypie_Init_Monorepo_Project.md

@@ -0,0 +1,44 @@
+---
+description: Monorepo setup using Jaypie conventions and utilities
+---
+
+# Jaypie Initialize Monorepo Project
+
+Monorepo setup using Jaypie conventions and utilities
+
+## Goal
+
+* Jaypie project opinions and tooling
+* ESLint 9+ flat config with @jaypie/eslint
+* NPM with Workspaces ("monorepo")
+* TypeScript
+* Vite and Vitest
+
+## Guidelines
+
+* This guide should compliment Jaypie_Project_Structure.md. The two should not conflict. Raise any conflicts with the user.
+* Run `npm install` to get the latest version of all software and generate a package-lock.json. Do not hard-code package versions from memory.
+* If this is the very first commit, you should make it on main. This is the only time a commit should be made and pushed on main.
+
+## Process
+
+1. Copy all the files from `prompts/templates/project-monorepo/` to the root directory
+2. Edit name in "@project-org/project-name" based on user instruction or infer from the directory name
+3. Remove the sample paths from tsconfig.base.json
+4. Remove the sample references from tsconfig.json
+5. Install requisite packages
+
+```bash
+npm install --save-dev @jaypie/eslint @jaypie/testkit eslint rimraf sort-package-json tsx vite vite-plugin-dts vitest
+```
+
+## Context
+
+prompts/Jaypie_Ideal_Project_Structure.md
+prompts/templates/project-monorepo/.gitignore
+prompts/templates/project-monorepo/.vscode/settings.json
+prompts/templates/project-monorepo/eslint.config.mjs
+prompts/templates/project-monorepo/package.json
+prompts/templates/project-monorepo/tsconfig.base.json
+prompts/templates/project-monorepo/tsconfig.json
+prompts/templates/project-monorepo/vitest.workspace.js

package/prompts/Jaypie_Init_Project_Subpackage.md

@@ -0,0 +1,70 @@
+---
+description: Create a subpackage within an existing monorepo project
+---
+
+# Jaypie Initialize Project Subpackage
+
+Create a subpackage within an existing monorepo project.
+
+## Goal
+
+* TypeScript subpackage with Vite/Vitest
+* Standard Jaypie project structure
+* NPM workspace integration
+* ESLint configuration inheritance
+
+## Guidelines
+
+* Follow Jaypie_Project_Structure.md conventions
+* Subpackage names follow "@project-org/package-name" pattern
+* Use `"version": "0.0.1"`, `"type": "module"`, and `"private": true`
+* Place packages in `packages/<package-name>/` directory
+
+## Process
+
+1. Create package directory structure:
+   ```
+   packages/<package-name>/
+   ├── src/
+   ├── package.json
+   └── tsconfig.json
+   ```
+
+2. Copy template files:
+   * Copy `prompts/templates/project-subpackage/package.json` to `packages/<package-name>/package.json`
+   * Copy `prompts/templates/project-subpackage/tsconfig.json` to `packages/<package-name>/tsconfig.json`
+   * Copy `prompts/templates/project-subpackage/vite.config.ts` to `packages/<package-name>/vite.config.ts`
+   * Copy `prompts/templates/project-subpackage/vitest.config.ts` to `packages/<package-name>/vitest.config.ts`
+   * Copy `prompts/templates/project-subpackage/vitest.setup.ts` to `packages/<package-name>/vitest.setup.ts`
+
+3. Update package.json:
+   * Edit name from "@project-org/project-name" to "@project-org/<package-name>"
+   * Keep all other fields as-is from template
+
+4. Create basic src structure:
+   * Create `src/index.ts` with basic export
+   * Create `src/index.spec.ts` with basic test
+
+5. Update workspace configuration:
+   * Update `references` in root `tsconfig.json`
+   * Update `paths` in root `tsconfig.base.json`
+   * Add package path to root `vitest.workspace.js`
+   * Remove wildcards from `vitest.workspace.js` if present
+
+6. Install requested software:
+   * Always use `npm --workspace ./packages/new-package install`
+   * Never edit `package.json` from memory
+
+## Context
+
+prompts/prompts/Jaypie_Project_Structure.md
+prompts/templates/project-monorepo/tsconfig.base.json
+prompts/templates/project-subpackage/package.json
+prompts/templates/project-subpackage/tsconfig.json
+prompts/templates/project-subpackage/vite.config.ts
+prompts/templates/project-subpackage/vitest.config.ts
+prompts/templates/project-subpackage/vitest.setup.ts
+package.json
+tsconfig.json
+tsconfig.base.json
+vitest.workspace.js

package/prompts/Jaypie_Legacy_Patterns.md

@@ -0,0 +1,11 @@
+---
+description: Old conventions repositories should update and the new conventions they should follow
+---
+
+# Jaypie Legacy Patterns
+
+## TypeScript, Not Vanilla JavaScript
+
+## Vite for Builds
+
+Subpackage `build` script should run `vite build && tsc --emitDeclarationOnly`

package/prompts/Jaypie_Llm_Calls.md

@@ -0,0 +1,113 @@
+---
+trigger: model_decision
+description: Calling OpenAI and other provider LLM functions from Jaypie, specifically using Jaypie's Llm class and Llm.operate() function
+---
+
+# LLM Calls with Jaypie 🗣️
+
+Streamline API calls with multi-model capabilities
+
+## Types
+
+```
+export interface LlmProvider {
+  operate(
+    input: string | LlmHistory | LlmInputMessage,
+    options?: LlmOperateOptions,
+  ): Promise<LlmOperateResponse>;
+  send(
+    message: string,
+    options?: LlmMessageOptions,
+  ): Promise<string | JsonObject>;
+}
+
+export interface LlmOperateOptions {
+  data?: NaturalMap;
+  explain?: boolean;
+  format?: JsonObject | NaturalSchema | z.ZodType;
+  history?: LlmHistory;
+  instructions?: string;
+  model?: string;
+  placeholders?: {
+    input?: boolean;
+    instructions?: boolean;
+    system?: boolean;
+  };
+  providerOptions?: JsonObject;
+  system?: string;
+  tools?: LlmTool[];
+  turns?: boolean | number;
+  user?: string;
+}
+
+export interface LlmOperateResponse {
+  content?: string | JsonObject;
+  error?: LlmError;
+  history: LlmHistory;
+  output: LlmOutput;
+  responses: JsonReturn[];
+  status: LlmResponseStatus;
+  usage: LlmUsage;
+}
+
+interface LlmUsage {
+  input: number;
+  output: number;
+  reasoning: number;
+  total: number;
+}
+```
+
+## Declaring an Llm
+
+```
+import { Llm } from "jaypie";
+
+const llm = new Llm();
+
+const result = await llm.operate("Give me advice on Yahtzee");
+```
+
+## "Operating" an Llm
+
+operate takes an optional second object of options
+
+```
+import { Llm, toolkit } from "jaypie";
+
+const result = await llm.operate("Take a Yahtzee turn and report the results", {
+  format: {
+    throws: Array,
+    score: Number,
+    category: String,
+  },
+  tools: [toolkit.roll]
+});
+```
+
+data is an object that will be used for variable replacements in input, instruction, and system.
+explain will pass a rationale explaining its choice to the tool call.
+format causes structured output to follow the provided schema.
+history is an existing llm history.
+Calls to the same instance automatically pass history.
+instructions are one-time instructions.
+placeholders object toggles what data applies to.
+providerOptions passes additional options to the provider.
+system is a permanent starting instruction.
+See ./Llm_Tool_with_Jaypie.md for tool formats.
+turns disables or restricts the number of turns that can be taken.
+user tracks the end user
+
+## Response
+
+content is a convenience string for the model's response.
+content will be an object when format was passed and the provider supports structured data.
+error will include any errors.
+output is just the output components of full responses.
+responses are the complete responses.
+
+## Footnotes
+
+Llm.operate(input, options)
+The Llm.send function is an older version replaced by operate.
+Llm.send's `response` option is `format` in operate.