@jaypie/mcp 0.2.3 → 0.2.5

package/prompts/Jaypie_Vocabulary_Package.md

@@ -1,17 +1,26 @@
 ---
-description: Complete guide to using Jaypie Vocabulary for type coercion, service handlers, and Commander CLI integration
+description: Core guide to Jaypie Vocabulary for type coercion, service handlers, and entity types
 ---
 
 # Jaypie Vocabulary Package
 
-Jaypie Vocabulary (`@jaypie/vocabulary`) provides type coercion utilities and service handler patterns for consistent input handling across Jaypie applications. It includes adapters for integrating service handlers with Commander.js CLIs.
+Jaypie Vocabulary (`@jaypie/vocabulary`) provides type coercion utilities and service handler patterns for consistent input handling across Jaypie applications.
+
+## Related Adapter Guides
+
+Vocabulary includes adapters for integrating service handlers with various platforms. See these guides for platform-specific integration:
+
+| Guide | Import | Description |
+|-------|--------|-------------|
+| [Jaypie_Vocabulary_Commander.md](Jaypie_Vocabulary_Commander.md) | `@jaypie/vocabulary/commander` | Commander.js CLI integration with callbacks |
+| [Jaypie_Vocabulary_Lambda.md](Jaypie_Vocabulary_Lambda.md) | `@jaypie/vocabulary/lambda` | AWS Lambda handler wrapping |
+| [Jaypie_Vocabulary_LLM.md](Jaypie_Vocabulary_LLM.md) | `@jaypie/vocabulary/llm` | LLM tool creation for `@jaypie/llm` Toolkit |
+| [Jaypie_Vocabulary_MCP.md](Jaypie_Vocabulary_MCP.md) | `@jaypie/vocabulary/mcp` | MCP server tool registration |
 
 ## Installation
 
 ```bash
 npm install @jaypie/vocabulary
-# For CLI integration:
-npm install commander
 ```
 
 ## Core Concepts
@@ -104,6 +113,46 @@ await validateUser({ age: "25", email: "bob@example.com" });
 // → { age: 25, email: "bob@example.com", role: "user" }
 ```
 
+### ServiceContext
+
+Services receive an optional second parameter with context utilities:
+
+```typescript
+interface ServiceContext {
+  onError?: (error: unknown) => void | Promise<void>;
+  onFatal?: (error: unknown) => void | Promise<void>;
+  sendMessage?: (message: Message) => void | Promise<void>;
+}
+
+const handler = serviceHandler({
+  input: { jobId: { type: String } },
+  service: async ({ jobId }, context) => {
+    context?.sendMessage?.({ content: `Starting job ${jobId}` });
+
+    // Handle recoverable errors without throwing
+    try {
+      await riskyOperation();
+    } catch (err) {
+      context?.onError?.(err);  // Reports error but continues
+    }
+
+    // Or report fatal errors explicitly
+    if (criticalFailure) {
+      context?.onFatal?.(new Error("Cannot continue"));
+    }
+
+    return { jobId, status: "complete" };
+  },
+});
+```
+
+Context callbacks connect to adapter registration:
+- `sendMessage` → `onMessage` callback
+- `onError` → `onError` callback (recoverable errors)
+- `onFatal` → `onFatal` callback (fatal errors)
+
+**Note:** Any error that escapes the service (is thrown) is treated as fatal and routes to `onFatal`.
+
 ## Type Coercion
 
 ### Supported Types
@@ -187,185 +236,90 @@ input: {
 }
 ```
 
-## Commander.js Integration
-
-### registerServiceCommand (Recommended)
+## Entity Types
 
-The simplest way to register a service handler as a Commander command:
+The vocabulary provides standard entity types for consistent data modeling:
 
 ```typescript
-import { Command } from "commander";
-import { serviceHandler } from "@jaypie/vocabulary";
-import { registerServiceCommand } from "@jaypie/vocabulary/commander";
-
-const handler = serviceHandler({
-  alias: "greet",
-  description: "Greet a user",
-  input: {
-    userName: { type: String, flag: "user", letter: "u" },
-    loud: { type: Boolean, letter: "l", default: false },
-  },
-  service: ({ loud, userName }) => {
-    const greeting = `Hello, ${userName}!`;
-    console.log(loud ? greeting.toUpperCase() : greeting);
-  },
-});
-
-const program = new Command();
-registerServiceCommand({ handler, program });
-program.parse();
-// Usage: greet --user Alice -l
-// Output: HELLO, ALICE!
+import type {
+  BaseEntity,
+  BaseEntityInput,
+  BaseEntityUpdate,
+  BaseEntityFilter,
+  HistoryEntry,
+  Job,
+  MessageEntity,
+  Progress,
+} from "@jaypie/vocabulary";
 ```
 
-### registerServiceCommand Options
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `handler` | `ServiceHandlerFunction` | Required. The service handler |
-| `program` | `Command` | Required. Commander program or command |
-| `name` | `string` | Override command name (default: handler.alias) |
-| `description` | `string` | Override description (default: handler.description) |
-| `exclude` | `string[]` | Field names to exclude from options |
-| `overrides` | `Record<string, override>` | Per-field option overrides |
+### BaseEntity (base for all entities)
 
-### Input Flag and Letter Properties
-
-Define CLI flags directly in input definitions:
-
-```typescript
-input: {
-  userName: {
-    type: String,
-    flag: "user",     // Long flag: --user (instead of --user-name)
-    letter: "u",      // Short flag: -u
-    description: "User name to greet",
-  },
-  verbose: {
-    type: Boolean,
-    letter: "v",      // -v
-  },
-}
-// Generates: --user <userName>, -u and --verbose, -v
 ```
-
-### Manual Integration
-
-For more control, use `createCommanderOptions` and `parseCommanderOptions`:
-
-```typescript
-import { Command } from "commander";
-import { serviceHandler } from "@jaypie/vocabulary";
-import {
-  createCommanderOptions,
-  parseCommanderOptions,
-} from "@jaypie/vocabulary/commander";
-
-const handler = serviceHandler({
-  input: {
-    userName: { type: String, description: "User name" },
-    maxRetries: { type: Number, default: 3 },
-    verbose: { type: Boolean },
-  },
-  service: (input) => console.log(input),
-});
-
-const program = new Command();
-
-// Create options from handler input
-const { options } = createCommanderOptions(handler.input, {
-  exclude: ["internalField"],
-  overrides: {
-    userName: { short: "u", description: "Override description" },
-  },
-});
-options.forEach((opt) => program.addOption(opt));
-
-// Wire up action
-program.action(async (opts) => {
-  const input = parseCommanderOptions(opts, { input: handler.input });
-  await handler(input);
-});
-
-program.parse();
+model: <varies>
+id: String (auto)
+createdAt: Date (auto)
+updatedAt: Date (auto)
+history?: [HistoryEntry] (auto)
+name?: String
+label?: String
+abbreviation?: String
+alias?: String
+xid?: String
+description?: String
+class?: String
+type?: String
+content?: String
+metadata?: Object
+emoji?: String
+icon?: String
+archivedAt?: Date
+deletedAt?: Date
 ```
 
-### Boolean Flag Behavior
-
-Commander.js automatically handles boolean flags:
-- `--verbose` sets to `true`
-- `--no-verbose` sets to `false` (for flags with `default: true`)
-
-## Complete CLI Example
-
-```typescript
-// src/commands/evaluate.ts
-import { Command } from "commander";
-import { serviceHandler } from "@jaypie/vocabulary";
-import { registerServiceCommand } from "@jaypie/vocabulary/commander";
-
-export const evaluateHandler = serviceHandler({
-  alias: "evaluate",
-  description: "Run an evaluation job",
-  input: {
-    jobId: {
-      type: String,
-      flag: "job",
-      letter: "j",
-      description: "Job identifier",
-    },
-    priority: {
-      type: [1, 2, 3, 4, 5],
-      default: 3,
-      letter: "p",
-      description: "Job priority (1-5)",
-    },
-    tags: {
-      type: [String],
-      letter: "t",
-      required: false,
-      description: "Tags to apply",
-    },
-    dryRun: {
-      type: Boolean,
-      letter: "d",
-      default: false,
-      description: "Run without executing",
-    },
-  },
-  service: async ({ dryRun, jobId, priority, tags }) => {
-    console.log(`Running job ${jobId} with priority ${priority}`);
-    if (tags?.length) console.log(`Tags: ${tags.join(", ")}`);
-    if (dryRun) {
-      console.log("(dry run - no changes made)");
-      return;
-    }
-    // Execute job...
-  },
-});
+### MessageEntity (extends BaseEntity)
 
-export function evaluateCommand(program: Command): Command {
-  registerServiceCommand({ handler: evaluateHandler, program });
-  return program;
-}
+```
+model: message
+content: String (required)
+type?: String (e.g., "assistant", "user", "system")
 ```
 
-Usage:
-```bash
-# Required job, default priority
-cli evaluate --job abc123
-
-# With all options
-cli evaluate -j abc123 -p 1 -t urgent -t critical --dry-run
+### Job (extends BaseEntity)
 
-# Help
-cli evaluate --help
+```
+model: job
+type?: String (e.g., "batch", "realtime", "scheduled")
+class?: String (e.g., "evaluation", "export", "import")
+status: String (required)
+startedAt?: Date
+completedAt?: Date
+messages?: [MessageEntity]
+progress?:
+    elapsedTime?: Number
+    estimatedTime?: Number
+    percentageComplete?: Number
+    nextPercentageCheckpoint?: Number
 ```
 
 ## TypeScript Types
 
 ```typescript
 import type {
+  // Entity types
+  BaseEntity,
+  BaseEntityFilter,
+  BaseEntityInput,
+  BaseEntityUpdate,
+  HistoryEntry,
+  Job,
+  MessageEntity,
+  Progress,
+
+  // Message types
+  Message,
+  MessageLevel,
+
   // Coercion types
   CoercionType,
   ScalarType,
@@ -378,21 +332,25 @@ import type {
 
   // Service handler types
   InputFieldDefinition,
-  ValidateFunction,
+  ServiceContext,
   ServiceFunction,
   ServiceHandlerConfig,
   ServiceHandlerFunction,
+  ValidateFunction,
 } from "@jaypie/vocabulary";
+```
 
-import type {
-  // Commander adapter types
-  CommanderOptionOverride,
-  CreateCommanderOptionsConfig,
-  CreateCommanderOptionsResult,
-  ParseCommanderOptionsConfig,
-  RegisterServiceCommandConfig,
-  RegisterServiceCommandResult,
-} from "@jaypie/vocabulary/commander";
+### Message Type
+
+Standard message structure for callbacks and notifications:
+
+```typescript
+type MessageLevel = "trace" | "debug" | "info" | "warn" | "error";
+
+interface Message {
+  content: string;
+  level?: MessageLevel;  // Defaults to "info" if not specified
+}
 ```
 
 ## Exports
@@ -415,21 +373,19 @@ export {
 // Service Handler
 export { serviceHandler } from "./serviceHandler.js";
 
-// Commander namespace
+// Adapter namespaces
 export * as commander from "./commander/index.js";
+export * as lambda from "./lambda/index.js";
+export * as llm from "./llm/index.js";
+export * as mcp from "./mcp/index.js";
+
+// Types (including Message vocabulary and ServiceContext)
+export type { Message, MessageLevel, ServiceContext } from "./types.js";
 
 // Version
 export const VOCABULARY_VERSION: string;
 ```
 
-### Commander Export (`@jaypie/vocabulary/commander`)
-
-```typescript
-export { createCommanderOptions } from "./createCommanderOptions.js";
-export { parseCommanderOptions } from "./parseCommanderOptions.js";
-export { registerServiceCommand } from "./registerServiceCommand.js";
-```
-
 ## Error Handling
 
 Invalid coercions throw `BadRequestError` from `@jaypie/errors`:
@@ -448,4 +404,6 @@ await handler({});                              // Missing required field
 Vocabulary is designed to be consumed by:
 - **`@jaypie/lambda`** - Lambda handler input processing
 - **`@jaypie/express`** - Express route input validation
+- **`@jaypie/llm`** - LLM tool parameter coercion via the llm adapter
+- **`@jaypie/mcp`** - MCP server tool registration via the mcp adapter
 - **CLI packages** - Commander.js integration via the commander adapter