@jaypie/mcp 0.1.0 → 0.1.1

package/prompts/Jaypie_Llm_Tools.md

@@ -0,0 +1,124 @@
+---
+trigger: glob
+globs: packages/tools/*
+---
+
+# LLM Tools with Jaypie 🔧
+
+Extend LLM capabilities with tools for external actions and data retrieval
+
+## Goal
+
+Create and integrate tools that enable LLMs to perform specific functions beyond their training data
+
+## Interface
+
+Implement the `LlmTool` interface:
+
+```typescript
+interface LlmTool {
+  description: string;
+  name: string;
+  parameters: JsonObject;
+  type: "function" | string;
+  call: (args?: JsonObject) => Promise<AnyValue> | AnyValue;
+}
+```
+
+Properties:
+- `description`: Clear explanation of tool functionality
+- `name`: Unique identifier
+- `parameters`: JSON Schema defining input parameters
+- `type`: Usually "function" (OpenAI convention)
+- `call`: Implementation function executed on invocation
+
+## Example: Dice Roller
+
+```typescript
+import { LlmTool } from "../types/LlmTool.interface.js";
+import { log, random, tryParseNumber } from "../util";
+
+export const roll: LlmTool = {
+  description: "Roll one or more dice with a specified number of sides",
+  name: "roll",
+  parameters: {
+    type: "object",
+    properties: {
+      number: {
+        type: "number",
+        description: "Number of dice to roll. Default: 1",
+      },
+      sides: {
+        type: "number",
+        description: "Number of sides on each die. Default: 6",
+      },
+    },
+    required: ["number", "sides"],
+  },
+  type: "function",
+  call: ({ number = 1, sides = 6 } = {}): {
+    rolls: number[];
+    total: number;
+  } => {
+    const rng = random();
+    const rolls: number[] = [];
+    let total = 0;
+
+    const parsedNumber = tryParseNumber(number, {
+      defaultValue: 1,
+      warnFunction: log.warn,
+    }) as number;
+    const parsedSides = tryParseNumber(sides, {
+      defaultValue: 6,
+      warnFunction: log.warn,
+    }) as number;
+
+    for (let i = 0; i < parsedNumber; i++) {
+      const rollValue = rng({ min: 1, max: parsedSides, integer: true });
+      rolls.push(rollValue);
+      total += rollValue;
+    }
+
+    return { rolls, total };
+  },
+};
+```
+
+## Best Practices
+
+### Input Validation
+Validate and sanitize parameters with utilities like `tryParseNumber`.
+
+### Clear Descriptions
+Write precise descriptions for tools and parameters to guide LLM usage.
+
+### Consistent Returns
+Return consistent data structures for predictable LLM interpretation.
+
+### Error Handling
+Implement robust error handling to prevent crashes and provide meaningful messages.
+
+## Integration
+
+```typescript
+import { Llm } from "jaypie";
+import { roll } from "./tools/roll.js";
+
+const llm = new Llm({
+  provider: "openai",
+  model: "gpt-4o"
+});
+
+const response = await llm.operate([
+  { role: "user", content: "Roll 3d20 and tell me the result" },
+  {
+    tools: [roll],
+  },
+]);
+```
+
+## References
+
+- [Jaypie Library](https://github.com/finlaysonstudio/jaypie)
+- [OpenAI Function Calling](https://platform.openai.com/docs/guides/function-calling)
+- [Jaypie_Llm_Calls.md](./Jaypie_Llm_Calls.md) to better understand Llm.operate()

package/prompts/Jaypie_Mocks_and_Testkit.md

@@ -0,0 +1,137 @@
+---
+description: Jaypie projects rely heavily on mocking the entire jaypie package, often in setup files, as well as manual mocks. Recommended when creating new tests or addressing failures.
+---
+
+# Jaypie Mocks and Testkit
+
+Adds unit tests for a JavaScript or TypeScript file.
+
+## Requirements
+
+- Use **Vitest** for all test files.
+- Create a new test file as a sibling to the implementation, not a separate directory or tree
+- Use **ECMAScript module syntax** (`import/export`), not CommonJS.
+- Import the function under test using a relative path and include the `.js` extension.
+- Use `describe` blocks for each function and `it` blocks for each behavior.
+- Include tests for:
+  - Normal/expected input
+  - Edge cases
+  - Error handling (if applicable)
+- Ensure all tests are deterministic and do not rely on randomness or network calls unless mocked.
+
+## File Style Rules
+
+- Use double quotes.
+- Use ES6+ syntax.
+- Do not modify the original file.
+- Do not include any setup or installation instructions.
+
+## Jaypie Testkit
+`@jaypie/testkit` is the testing library.
+`matchers` are exported and extend expect in the test setup.
+All jaypie functions can be mocked with `vi.mock("jaypie", async () => vi.importActual("@jaypie/testkit/mock"));`
+### Classes
+Mocked jaypie classes should mocked members for each mocked implementation.
+```
+Llm.operate.mockResolvedValue("Bueno");
+const llm = new Llm();
+const response = llm.operate();
+expect(response).toBeString("Bueno");
+expect(Llm.operate).toHaveBeenCalled()
+```
+### Errors
+Use matchers to test errors.
+`expect(fn).toThrowBadGatewayError();`
+`await expect(async() => fn()).toThrowBadGatewayError();`
+Do not use `.rejects`
+### Express
+Most express functions are wrapped in `expressHandler` which is mocked.
+Test express functions directly with a `req` object.
+Handle cases where the `req` object is undefined or incomplete.
+supertest is also available to test http responses.
+### Logging
+`log` is mocked by `@jaypie/testkit/mock` or separately using `spyLog` and `restoreLog` in `@jaypie/testkit`.
+Use matchers on `log` functions and `toBeCalledAboveTrace` on `log` itself.
+`expect(log).not.toBeCalledAboveTrace();`
+`expect(log.warn).toBeCalled();`
+### Matchers
+toBeCalledAboveTrace, toBeCalledWithInitialParams, toBeClass, toBeJaypieError, toMatchBase64, toMatchJwt, toMatchMongoId, toMatchSchema, toMatchSignedCookie, toMatchUuid4, toMatchUuid5, toMatchUuid, toThrowBadGatewayError, toThrowBadRequestError, toThrowConfigurationError, toThrowForbiddenError, toThrowGatewayTimeoutError, toThrowInternalError, toThrowJaypieError, toThrowNotFoundError, toThrowUnauthorizedError, toThrowUnavailableError,
+### Order of Tests
+Tests are named `./__tests__/<subject>.spec.<js|ts>`.
+Each file should have one top-level `describe` block.
+Organize tests in one of seven second-level describe block sections in this order:
+1. Base Cases - it is the type we expect ("It is a Function"). For functions, the simplest possible call works and returns not undefined ("It Works"). For objects, the expected shape.
+2. Error Conditions - any error handling the code performs
+3. Security - any security checks the code performs
+4. Observability - any logging the code performs
+5. Happy Paths - The most common use case
+6. Features - Features in addition to the happy path
+7. Specific Scenarios - Special cases
+Omit describe blocks for sections that are not applicable or empty.
+Whenever possible, especially when refactoring, write the test first so the user can confirm the expected behavior passes/fails.
+### Test Coverage
+Aim for complete coverage of all happy paths, features, and error conditions.
+Whenever possible, confirm mocked functions are called.
+Confirm calls to log above debug in Observability. Do not confirm calls to debug, var, or trace.
+
+## Configuration
+
+### Typical Package
+
+`package.json`
+```json
+"scripts": {
+  "test": "vitest run",
+  "test:watch": "vitest watch",
+}
+```
+
+`vitest.config.ts`
+```typescript
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  test: {
+    setupFiles: ["./vitest.setup.ts"],
+  },
+});
+```
+
+`vitest.setup.ts`
+```typescript
+// This file left intentionally blank
+```
+
+* `vitest.setup.ts` can be used to extend the jest matchers, for example, or setting up other mocks
+```typescript
+import * as extendedMatchers from "jest-extended";
+import { expect } from "vitest";
+
+expect.extend(extendedMatchers);
+```
+* Before creating a `vitest.setup.ts`, check if `testSetup.js` exists.
+
+## NPM Workspaces (monorepos)
+
+* Configure sub-packages following the above
+* Usually only sub-packages have `vitest.config.ts` and `vitest.setup.ts`
+* Configure the root package as follows, iterating for each `<package>` below
+
+`package.json`
+```json
+"scripts": {
+  "test": "vitest run",
+  "test:watch": "vitest watch",
+  "test:<package>": "npm run test --workspace packages/<package>"
+  "test:<package>:watch": "npm run test:watch --workspace packages/<package>"
+}
+```
+
+`vitest.workspace.ts`
+```typescript
+import { defineWorkspace } from "vitest/config";
+
+export default defineWorkspace([
+  "packages/<package>",
+]);
+```

package/prompts/Jaypie_Mongoose_Models_Package.md

@@ -0,0 +1,231 @@
+---
+description: Document describes a Jaypie pattern repeated in many projects but not yet offered as a package within Jaypie
+globs: packages/models/**
+status: Work in Progress
+---
+
+# Jaypie Mongoose Models Package
+
+Create reusable MongoDB models with rich relationship management using Mongoose and Jaypie.
+
+## Goal
+
+Define document schemas with bidirectional relationships and consistent utilities for mongoose models.
+
+## Guidelines
+
+- Uses ES modules with `.js` extensions (`"type": "module"`)
+- Requires mongoose and jaypie as dependencies
+- Follows schema organization pattern: definition → hooks → methods → statics → export
+- Every schema should use `projectSchema.plugin.js` for relationship methods
+- Every document has `uuid` field for external references
+
+## Process
+
+### Package Setup
+
+1. Create package structure:
+   ```
+   models/
+   ├── package.json
+   ├── src/
+   │   ├── constants.js
+   │   ├── index.js
+   │   ├── user.schema.js
+   │   ├── projectSchema.plugin.js
+   │   └── __tests__/
+   │       ├── constants.spec.js
+   │       ├── index.spec.js
+   │       ├── user.schema.spec.js
+   │       └── projectSchema.plugin.spec.js
+   ├── testSetup.js
+   └── vite.config.js
+   ```
+
+2. Configure package.json:
+   ```json
+   {
+     "name": "@yournamespace/models",
+     "type": "module",
+     "exports": {
+       ".": {
+         "default": {
+           "require": "./dist/module.cjs.js",
+           "default": "./src/index.js"
+         }
+       }
+     },
+     "main": "src/index.js",
+     "dependencies": {
+       "jaypie": "^1.1.0",
+       "mongoose": "^7.0.0"
+     }
+   }
+   ```
+
+### Core Files Implementation
+
+1. projectSchema.plugin.js
+   - Plugin providing relationship management methods
+   - Key functions: allLeanByIds, allLeanByUuids, createWithRelationships, deleteWithRelationships, toJsonWithRelationships, updateWithRelationships
+   - Utility functions: idsToUuids, uuidsToIds, oneByUuid, oneByXid
+
+2. constants.ts
+   ```typescript
+   import { v5 as uuidv5 } from "uuid";
+
+   const NAMESPACE_ROOT = "your-namespace-uuid";
+   export const NAMESPACE = {
+     USER: uuidv5("USER", NAMESPACE_ROOT),
+   };
+
+   export const SCHEMA = {
+     USER: "user",
+   };
+
+   export default {
+     NAMESPACE,
+     SCHEMA,
+   };
+   ```
+
+3. user.schema.ts
+   ```typescript
+   import { Schema } from "mongoose";
+   import projectSchema from "./projectSchema.plugin.js";
+
+   const schema = new Schema(
+     {
+       deletedAt: {
+         type: Schema.Types.Date,
+       },
+       name: {
+         type: Schema.Types.String,
+       },
+       uuid: {
+         index: true,
+         type: Schema.Types.String,
+       },
+       xid: {
+         index: true,
+         type: Schema.Types.String,
+       },
+     },
+     { timestamps: true },
+   );
+
+   schema.plugin(projectSchema);
+
+   export default schema;
+   ```
+
+4. index.ts
+   ```typescript
+   import { connect, disconnect, envsKey, log } from "jaypie";
+   import mongoose, { Model, Schema } from "mongoose";
+   import { SCHEMA } from "./constants.js";
+   import userSchema from "./user.schema.js";
+
+   let instantiatedModel: Record<string, Model<any>> | null;
+   const { model } = mongoose;
+
+   function getModel(name: string, schema: Schema): Model<any> {
+     if (!instantiatedModel) {
+       log.warn("[@yournamespace/models] Models have not been instantiated");
+       instantiatedModel = {};
+     }
+     return instantiatedModel[name] || (instantiatedModel[name] = model(name, schema));
+   }
+
+   export default {
+     connect: async (uri: string = envsKey("MONGODB_URI")) => {
+       if (instantiatedModel) {
+         log.warn("[@yournamespace/models] Models already instantiated");
+       } else {
+         instantiatedModel = {};
+       }
+       return uri ? mongoose.connect(uri) : connect();
+     },
+     disconnect: () => {
+       instantiatedModel = null;
+       return disconnect();
+     },
+     get User() {
+       return getModel(SCHEMA.USER, userSchema);
+     },
+   };
+
+   export { default as MODEL } from "./constants.js";
+   ```
+
+### Testing
+
+1. vite.config.ts
+   ```typescript
+   import { defineConfig } from "vite";
+
+   export default defineConfig({
+     test: {
+       globals: false,
+       setupFiles: ["./testSetup.ts"],
+     },
+   });
+   ```
+
+2. testSetup.ts
+   ```typescript
+   import { beforeEach, vi } from "vitest";
+   import mongoose from "mongoose";
+
+   // Mock mongoose methods
+   vi.mock("mongoose", async () => {
+     const actual = await vi.importActual("mongoose");
+     return {
+       ...actual,
+       connect: vi.fn().mockResolvedValue({}),
+       disconnect: vi.fn().mockResolvedValue({}),
+     };
+   });
+
+   // Reset mocks before each test
+   beforeEach(() => {
+     vi.clearAllMocks();
+   });
+   ```
+
+### Usage
+
+1. Connect to database:
+   ```typescript
+   import Model from "@yournamespace/models";
+
+   await Model.connect();
+   ```
+
+2. Create document:
+   ```typescript
+   const user = await Model.User.createWithRelationships({
+     uuid: "user-uuid",
+     values: { name: "Test User" },
+   });
+   ```
+
+3. Find document:
+   ```typescript
+   const user = await Model.User.oneByUuid("user-uuid");
+   ```
+
+4. Update with relationships:
+   ```typescript
+   await Model.User.updateWithRelationships({
+     uuid: "user-uuid",
+     values: { name: "Updated Name" },
+   });
+   ```
+
+5. Delete with relationships:
+   ```typescript
+   await Model.User.deleteWithRelationships({
+     uuid: "user-uuid",
+   });
+   ```