@jaypie/mcp 0.2.3 → 0.2.5

package/prompts/Jaypie_Vocabulary_Commander.md

@@ -0,0 +1,411 @@
+---
+description: Commander.js CLI integration with serviceHandler callbacks (onMessage, onComplete, onError, onFatal)
+include: "**/cli/**"
+---
+
+# Jaypie Vocabulary Commander Adapter
+
+The Commander adapter (`@jaypie/vocabulary/commander`) integrates Jaypie service handlers with Commander.js CLI applications, providing automatic option generation, type coercion, and callback hooks for progress reporting.
+
+**See also:** [Jaypie_Vocabulary_Package.md](Jaypie_Vocabulary_Package.md) for core serviceHandler documentation.
+
+## Installation
+
+```bash
+npm install @jaypie/vocabulary commander
+```
+
+## Quick Start
+
+```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
+```
+
+## registerServiceCommand
+
+The primary function for registering a service handler as a Commander command.
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `handler` | `ServiceHandlerFunction` | Required. The service handler to register |
+| `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 CLI options |
+| `onComplete` | `OnCompleteCallback` | Called with handler's return value on success |
+| `onError` | `OnErrorCallback` | Receives errors reported via `context.onError()` |
+| `onFatal` | `OnFatalCallback` | Receives fatal errors (thrown or via `context.onFatal()`) |
+| `onMessage` | `OnMessageCallback` | Receives messages from `context.sendMessage` |
+| `overrides` | `Record<string, override>` | Per-field option overrides |
+
+## Callback Hooks
+
+### onMessage
+
+Receives progress messages sent by the service via `context.sendMessage`:
+
+```typescript
+import { Command } from "commander";
+import { serviceHandler } from "@jaypie/vocabulary";
+import { registerServiceCommand } from "@jaypie/vocabulary/commander";
+
+const handler = serviceHandler({
+  alias: "process",
+  input: { jobId: { type: String, letter: "j" } },
+  service: async ({ jobId }, context) => {
+    // Send progress messages during execution
+    context?.sendMessage?.({ content: `Starting job ${jobId}` });
+
+    // Simulate work
+    await doStep1();
+    context?.sendMessage?.({ content: "Step 1 complete", level: "debug" });
+
+    await doStep2();
+    context?.sendMessage?.({ content: "Step 2 complete", level: "debug" });
+
+    context?.sendMessage?.({ content: "Job finished!", level: "info" });
+    return { jobId, status: "complete" };
+  },
+});
+
+const program = new Command();
+registerServiceCommand({
+  handler,
+  program,
+  onMessage: (msg) => {
+    // msg: { content: string, level?: "trace"|"debug"|"info"|"warn"|"error" }
+    const level = msg.level || "info";
+    console[level](msg.content);
+  },
+});
+program.parse();
+```
+
+**Important:** Errors in `onMessage` are swallowed to ensure messaging failures never halt service execution.
+
+### onComplete
+
+Called with the handler's return value on successful completion:
+
+```typescript
+registerServiceCommand({
+  handler,
+  program,
+  onComplete: (response) => {
+    // Called after service completes successfully
+    console.log("Result:", JSON.stringify(response, null, 2));
+
+    // Common patterns:
+    // - Save results to file
+    // - Display formatted output
+    // - Trigger follow-up actions
+  },
+});
+```
+
+### onError
+
+Receives errors that the service explicitly reports via `context.onError()`. Use this for recoverable errors that don't halt execution:
+
+```typescript
+registerServiceCommand({
+  handler,
+  program,
+  onError: (error) => {
+    // Log recoverable errors
+    console.warn("Warning:", error.message);
+  },
+});
+```
+
+### onFatal
+
+Receives fatal errors - either thrown errors or errors reported via `context.onFatal()`. Any error that escapes the service (is thrown) is treated as fatal:
+
+```typescript
+registerServiceCommand({
+  handler,
+  program,
+  onFatal: (error) => {
+    console.error("Fatal error:", error.message);
+    process.exit(1);
+  },
+});
+```
+
+**Error handling priority:**
+1. If `onFatal` is provided, thrown errors go to `onFatal`
+2. If only `onError` is provided, thrown errors fall back to `onError`
+3. If neither is provided, errors are re-thrown
+
+## Complete Example with All Callbacks
+
+```typescript
+import { Command } from "commander";
+import { serviceHandler } from "@jaypie/vocabulary";
+import { registerServiceCommand } from "@jaypie/vocabulary/commander";
+
+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 }, context) => {
+    context?.sendMessage?.({ content: `Initializing job ${jobId}...` });
+
+    if (dryRun) {
+      context?.sendMessage?.({ content: "Dry run mode - skipping execution", level: "warn" });
+      return { jobId, status: "dry-run", skipped: true };
+    }
+
+    // Handle recoverable errors without throwing
+    try {
+      await riskyOperation();
+    } catch (err) {
+      context?.onError?.(err);  // Reports error but continues
+    }
+
+    context?.sendMessage?.({ content: `Running with priority ${priority}` });
+
+    if (tags?.length) {
+      context?.sendMessage?.({ content: `Applying tags: ${tags.join(", ")}`, level: "debug" });
+    }
+
+    // Simulate processing
+    for (let i = 1; i <= 5; i++) {
+      await new Promise(resolve => setTimeout(resolve, 100));
+      context?.sendMessage?.({ content: `Progress: ${i * 20}%`, level: "debug" });
+    }
+
+    context?.sendMessage?.({ content: "Evaluation complete!" });
+    return { jobId, status: "complete", results: 42 };
+  },
+});
+
+const program = new Command();
+program.version("1.0.0").description("Evaluation CLI");
+
+registerServiceCommand({
+  handler: evaluateHandler,
+  program,
+  onMessage: (msg) => {
+    const prefix = msg.level === "warn" ? "WARNING: " :
+                   msg.level === "error" ? "ERROR: " : "";
+    console.log(`${prefix}${msg.content}`);
+  },
+  onComplete: (response) => {
+    console.log("\n--- Results ---");
+    console.log(JSON.stringify(response, null, 2));
+  },
+  onError: (error) => {
+    // Recoverable errors reported via context.onError()
+    console.warn("Warning:", error.message);
+  },
+  onFatal: (error) => {
+    // Fatal errors (thrown or via context.onFatal())
+    console.error("\nFatal:", error.message);
+    process.exit(1);
+  },
+});
+
+program.parse();
+```
+
+Usage:
+```bash
+# Basic execution
+cli evaluate --job abc123
+
+# With all options
+cli evaluate -j abc123 -p 1 -t urgent -t critical --dry-run
+
+# Help
+cli evaluate --help
+```
+
+## 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
+```
+
+### Naming Convention
+
+| Property | CLI Flag | Example |
+|----------|----------|---------|
+| `userName` (camelCase) | `--user-name` | Default behavior |
+| `flag: "user"` | `--user` | Override long flag |
+| `letter: "u"` | `-u` | Short flag |
+
+## Boolean Flag Behavior
+
+Commander.js automatically handles boolean flags:
+- `--verbose` sets to `true`
+- `--no-verbose` sets to `false` (for flags with `default: true`)
+
+## 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();
+```
+
+## TypeScript Types
+
+```typescript
+import type {
+  CommanderOptionOverride,
+  CreateCommanderOptionsConfig,
+  CreateCommanderOptionsResult,
+  OnCompleteCallback,
+  OnErrorCallback,
+  OnFatalCallback,
+  OnMessageCallback,
+  ParseCommanderOptionsConfig,
+  RegisterServiceCommandConfig,
+  RegisterServiceCommandResult,
+} from "@jaypie/vocabulary/commander";
+```
+
+### Callback Type Definitions
+
+```typescript
+// Message received from context.sendMessage
+interface Message {
+  content: string;
+  level?: "trace" | "debug" | "info" | "warn" | "error";
+}
+
+// onMessage callback
+type OnMessageCallback = (message: Message) => void | Promise<void>;
+
+// onComplete callback - receives handler return value
+type OnCompleteCallback<T = unknown> = (response: T) => void | Promise<void>;
+
+// onError callback - receives errors from context.onError()
+type OnErrorCallback = (error: unknown) => void | Promise<void>;
+
+// onFatal callback - receives fatal errors (thrown or context.onFatal())
+type OnFatalCallback = (error: unknown) => void | Promise<void>;
+```
+
+## Exports
+
+```typescript
+// @jaypie/vocabulary/commander
+export { createCommanderOptions } from "./createCommanderOptions.js";
+export { parseCommanderOptions } from "./parseCommanderOptions.js";
+export { registerServiceCommand } from "./registerServiceCommand.js";
+
+export type {
+  CommanderOptionOverride,
+  CreateCommanderOptionsConfig,
+  CreateCommanderOptionsResult,
+  OnCompleteCallback,
+  OnErrorCallback,
+  OnFatalCallback,
+  OnMessageCallback,
+  ParseCommanderOptionsConfig,
+  RegisterServiceCommandConfig,
+  RegisterServiceCommandResult,
+} from "./types.js";
+```
+
+## Related
+
+- [Jaypie_Commander_CLI_Package.md](Jaypie_Commander_CLI_Package.md) - Setting up a Commander CLI project from scratch
+- [Jaypie_Vocabulary_Package.md](Jaypie_Vocabulary_Package.md) - Core serviceHandler and type coercion

package/prompts/Jaypie_Vocabulary_LLM.md

@@ -0,0 +1,312 @@
+---
+description: LLM tool creation from serviceHandler for use with @jaypie/llm Toolkit
+---
+
+# Jaypie Vocabulary LLM Adapter
+
+The LLM adapter (`@jaypie/vocabulary/llm`) creates LLM tools from Jaypie service handlers for use with `@jaypie/llm` Toolkit, automatically generating JSON Schema from input definitions.
+
+**See also:** [Jaypie_Vocabulary_Package.md](Jaypie_Vocabulary_Package.md) for core serviceHandler documentation.
+
+## Installation
+
+```bash
+npm install @jaypie/vocabulary @jaypie/llm
+```
+
+## Quick Start
+
+```typescript
+import { serviceHandler } from "@jaypie/vocabulary";
+import { createLlmTool } from "@jaypie/vocabulary/llm";
+import { Toolkit } from "@jaypie/llm";
+
+const handler = serviceHandler({
+  alias: "greet",
+  description: "Greet a user by name",
+  input: {
+    userName: { type: String, description: "The user's name" },
+    loud: { type: Boolean, default: false, description: "Shout the greeting" },
+  },
+  service: ({ userName, loud }) => {
+    const greeting = `Hello, ${userName}!`;
+    return loud ? greeting.toUpperCase() : greeting;
+  },
+});
+
+const { tool } = createLlmTool({ handler });
+const toolkit = new Toolkit([tool]);
+```
+
+## createLlmTool
+
+Creates an LLM tool from a serviceHandler.
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `handler` | `ServiceHandlerFunction` | Required. The service handler to adapt |
+| `name` | `string` | Override tool name (defaults to handler.alias) |
+| `description` | `string` | Override tool description (defaults to handler.description) |
+| `message` | `string \| function` | Custom message for logging |
+| `exclude` | `string[]` | Fields to exclude from tool parameters |
+| `onComplete` | `OnCompleteCallback` | Called with tool's return value on success |
+| `onError` | `OnErrorCallback` | Receives errors reported via `context.onError()` in service |
+| `onFatal` | `OnFatalCallback` | Receives fatal errors (thrown or via `context.onFatal()`) |
+| `onMessage` | `OnMessageCallback` | Receives messages from `context.sendMessage` in service |
+
+### Basic Usage
+
+```typescript
+import { serviceHandler } from "@jaypie/vocabulary";
+import { createLlmTool } from "@jaypie/vocabulary/llm";
+
+const calculateHandler = serviceHandler({
+  alias: "calculate",
+  description: "Perform a mathematical calculation",
+  input: {
+    operation: { type: ["add", "subtract", "multiply", "divide"] },
+    a: { type: Number, description: "First operand" },
+    b: { type: Number, description: "Second operand" },
+  },
+  service: ({ operation, a, b }) => {
+    switch (operation) {
+      case "add": return a + b;
+      case "subtract": return a - b;
+      case "multiply": return a * b;
+      case "divide": return a / b;
+    }
+  },
+});
+
+const { tool } = createLlmTool({ handler: calculateHandler });
+
+// Tool has these properties:
+// tool.name: "calculate"
+// tool.description: "Perform a mathematical calculation"
+// tool.parameters: JSON Schema for inputs
+// tool.function: The callable function
+```
+
+### Overriding Name and Description
+
+```typescript
+const { tool } = createLlmTool({
+  handler,
+  name: "math_calculator",
+  description: "A tool for performing basic math operations",
+});
+```
+
+### Excluding Fields
+
+```typescript
+const handler = serviceHandler({
+  alias: "search",
+  input: {
+    query: { type: String },
+    limit: { type: Number, default: 10 },
+    _internalId: { type: String },  // Internal field
+  },
+  service: async (params) => { /* ... */ },
+});
+
+const { tool } = createLlmTool({
+  handler,
+  exclude: ["_internalId"],  // Not exposed to LLM
+});
+```
+
+### Lifecycle Callbacks
+
+Services can use context callbacks to report progress, errors, and completion:
+
+```typescript
+const handler = serviceHandler({
+  alias: "evaluate",
+  input: { jobId: { type: String } },
+  service: async ({ jobId }, context) => {
+    context?.sendMessage?.({ content: `Processing ${jobId}` });
+
+    try {
+      await riskyOperation();
+    } catch (err) {
+      context?.onError?.(err); // Reports error but continues
+    }
+
+    return { jobId, status: "complete" };
+  },
+});
+
+const { tool } = createLlmTool({
+  handler,
+  onComplete: (result) => console.log("Tool completed:", result),
+  onError: (error) => console.warn("Recoverable error:", error),
+  onFatal: (error) => console.error("Fatal error:", error),
+  onMessage: (msg) => console.log(`[${msg.level || "info"}] ${msg.content}`),
+});
+```
+
+**Error handling**: Services receive `context.onError()` and `context.onFatal()` callbacks to report errors without throwing. Any error that escapes the service (is thrown) is treated as fatal and routes to `onFatal`. If `onFatal` is not provided, thrown errors fall back to `onError`. Callback errors are swallowed to ensure failures never halt service execution.
+
+## inputToJsonSchema
+
+Converts vocabulary input definitions to JSON Schema:
+
+```typescript
+import { inputToJsonSchema } from "@jaypie/vocabulary/llm";
+
+const schema = inputToJsonSchema({
+  userName: { type: String, description: "User's name" },
+  age: { type: Number, required: false },
+  role: { type: ["admin", "user", "guest"], default: "user" },
+});
+
+// Returns:
+{
+  type: "object",
+  properties: {
+    userName: { type: "string", description: "User's name" },
+    age: { type: "number" },
+    role: { type: "string", enum: ["admin", "user", "guest"] },
+  },
+  required: ["userName"],
+}
+```
+
+### Type Mappings
+
+| Vocabulary Type | JSON Schema |
+|-----------------|-------------|
+| `String` | `{ type: "string" }` |
+| `Number` | `{ type: "number" }` |
+| `Boolean` | `{ type: "boolean" }` |
+| `Array` | `{ type: "array" }` |
+| `Object` | `{ type: "object" }` |
+| `[String]` | `{ type: "array", items: { type: "string" } }` |
+| `[Number]` | `{ type: "array", items: { type: "number" } }` |
+| `/regex/` | `{ type: "string", pattern: "..." }` |
+| `["a", "b"]` | `{ type: "string", enum: ["a", "b"] }` |
+| `[1, 2, 3]` | `{ type: "number", enum: [1, 2, 3] }` |
+
+### Excluding Fields
+
+```typescript
+const schema = inputToJsonSchema(handler.input, {
+  exclude: ["internalField", "debugMode"],
+});
+```
+
+## Complete Example
+
+```typescript
+import { serviceHandler } from "@jaypie/vocabulary";
+import { createLlmTool } from "@jaypie/vocabulary/llm";
+import { Llm, Toolkit } from "@jaypie/llm";
+
+// Define service handlers
+const weatherHandler = serviceHandler({
+  alias: "get_weather",
+  description: "Get current weather for a location",
+  input: {
+    location: { type: String, description: "City name or coordinates" },
+    units: { type: ["celsius", "fahrenheit"], default: "celsius" },
+  },
+  service: async ({ location, units }) => {
+    const weather = await fetchWeather(location);
+    return {
+      location,
+      temperature: units === "celsius" ? weather.tempC : weather.tempF,
+      units,
+      conditions: weather.conditions,
+    };
+  },
+});
+
+const searchHandler = serviceHandler({
+  alias: "search_web",
+  description: "Search the web for information",
+  input: {
+    query: { type: String, description: "Search query" },
+    maxResults: { type: Number, default: 5, description: "Maximum results" },
+  },
+  service: async ({ query, maxResults }) => {
+    return await performSearch(query, maxResults);
+  },
+});
+
+// Create tools
+const { tool: weatherTool } = createLlmTool({ handler: weatherHandler });
+const { tool: searchTool } = createLlmTool({ handler: searchHandler });
+
+// Use with Toolkit
+const toolkit = new Toolkit([weatherTool, searchTool]);
+const llm = new Llm({ toolkit });
+
+const response = await llm.ask("What's the weather in Tokyo?");
+```
+
+## TypeScript Types
+
+```typescript
+import type {
+  CreateLlmToolConfig,
+  CreateLlmToolResult,
+  LlmTool,
+  OnCompleteCallback,
+  OnErrorCallback,
+  OnFatalCallback,
+  OnMessageCallback,
+} from "@jaypie/vocabulary/llm";
+```
+
+### Type Definitions
+
+```typescript
+interface LlmTool {
+  name: string;
+  description: string;
+  parameters: JsonSchema;
+  function: (params: Record<string, unknown>) => Promise<unknown>;
+}
+
+interface CreateLlmToolConfig {
+  handler: ServiceHandlerFunction;
+  name?: string;
+  description?: string;
+  message?: string | ((params: Record<string, unknown>) => string);
+  exclude?: string[];
+  onComplete?: OnCompleteCallback;
+  onError?: OnErrorCallback;
+  onFatal?: OnFatalCallback;
+  onMessage?: OnMessageCallback;
+}
+
+interface CreateLlmToolResult {
+  tool: LlmTool;
+}
+```
+
+## Exports
+
+```typescript
+// @jaypie/vocabulary/llm
+export { createLlmTool } from "./createLlmTool.js";
+export { inputToJsonSchema } from "./inputToJsonSchema.js";
+
+export type {
+  CreateLlmToolConfig,
+  CreateLlmToolResult,
+  LlmTool,
+  OnCompleteCallback,
+  OnErrorCallback,
+  OnFatalCallback,
+  OnMessageCallback,
+} from "./types.js";
+```
+
+## Related
+
+- [Jaypie_Vocabulary_Package.md](Jaypie_Vocabulary_Package.md) - Core serviceHandler and type coercion
+- [Jaypie_Llm_Tools.md](Jaypie_Llm_Tools.md) - LLM tools and Toolkit usage