@jaypie/mcp 0.7.46 → 0.8.0

package/skills/tools.md

@@ -1,115 +1,200 @@
 ---
-description: Available MCP tools reference
-related: tools-aws, tools-datadog, tools-dynamodb, tools-llm, debugging
+description: Writing LLM tools with Toolkit, Fabric services, and best practices
+related: fabric, llm, mcp, services
 ---
 
-# MCP Tools Reference
+# Writing Tools
+
+Define tools for LLM agents using `@jaypie/llm` Toolkit or Fabric services.
+
+## Toolkit Tool Definition
+
+```typescript
+import { Toolkit } from "@jaypie/llm";
+
+const toolkit = new Toolkit([
+  {
+    name: "get_order",
+    description: "Look up an order by ID",
+    type: "function",
+    parameters: {
+      type: "object",
+      properties: {
+        orderId: { type: "string", description: "Order ID" },
+      },
+      required: ["orderId"],
+    },
+    call: async ({ orderId }) => {
+      return getOrder(orderId);
+    },
+  },
+]);
+```
 
-Tools available through the Jaypie MCP server. All tools use a unified router-style API.
+## Fabric Service as Tool
+
+Define once, use as LLM tool, MCP tool, Lambda handler, or CLI command:
+
+```typescript
+import { fabricService } from "@jaypie/fabric";
+import { fabricLlmTool } from "@jaypie/fabric";
+import { Toolkit } from "@jaypie/llm";
+
+const orderService = fabricService({
+  alias: "get_order",
+  description: "Look up an order by ID",
+  input: {
+    orderId: {
+      type: String,
+      required: true,
+      description: "Order ID to look up",
+    },
+  },
+  service: async ({ orderId }) => {
+    return getOrder(orderId);
+  },
+});
+
+// As LLM tool
+const toolkit = new Toolkit([fabricLlmTool(orderService)]);
+
+// As MCP tool
+fabricMcp({ service: orderService, server });
+```
 
-## Documentation Tools
+## Service-Backed Tools
+
+Keep business logic in services, tools as thin wrappers:
+
+```typescript
+// services/order.ts
+import { log, NotFoundError } from "jaypie";
+import { Order } from "../models/order.js";
+
+export async function getOrder(orderId: string) {
+  log.debug("Looking up order", { orderId });
+  const order = await Order.findById(orderId);
+  if (!order) {
+    throw new NotFoundError(`Order ${orderId} not found`);
+  }
+  return order;
+}
+
+export async function listOrders({ status, limit = 10 }: {
+  status?: string;
+  limit?: number;
+} = {}) {
+  log.debug("Listing orders", { status, limit });
+  return Order.find({ ...(status && { status }) }, { limit });
+}
+```
 
-| Tool | Description |
-|------|-------------|
-| `skill` | Access Jaypie skill documentation |
-| `version` | Get MCP server version |
-| `release_notes` | Browse package release notes |
+```typescript
+// tools/order.ts
+import { fabricService } from "@jaypie/fabric";
+import { getOrder, listOrders } from "../services/order.js";
+
+export const getOrderService = fabricService({
+  alias: "get_order",
+  description: "Look up an order by ID",
+  input: {
+    orderId: { type: String, required: true, description: "Order ID" },
+  },
+  service: async ({ orderId }) => getOrder(orderId),
+});
+
+export const listOrdersService = fabricService({
+  alias: "list_orders",
+  description: "List orders, optionally filtered by status",
+  input: {
+    status: { type: String, required: false, description: "Filter by status" },
+    limit: { type: Number, required: false, description: "Max results (default 10)" },
+  },
+  service: async ({ status, limit }) => listOrders({ status, limit }),
+});
+```
 
-### Using Skills
+## Wiring Tools to LLM
 
-```
-skill("index")          # List all skills
-skill("jaypie")         # Jaypie overview
-skill("tests")          # Testing patterns
-```
+```typescript
+import Llm, { Toolkit } from "@jaypie/llm";
+import { fabricLlmTool } from "@jaypie/fabric";
+import { getOrderService, listOrdersService } from "./tools/order.js";
 
-### Release Notes
+const toolkit = new Toolkit([
+  fabricLlmTool(getOrderService),
+  fabricLlmTool(listOrdersService),
+]);
 
-```
-release_notes()                                    # Show help
-release_notes("list")                              # List all release notes
-release_notes("list", { package: "mcp" })          # Filter by package
-release_notes("read", { package: "mcp", version: "0.5.0" })  # Read specific note
+const response = await Llm.operate("Find all pending orders", {
+  model: "claude-sonnet-4",
+  tools: toolkit,
+  turns: 3,
+});
 ```
 
-## AWS Tool
+## Built-in Tools
 
-Unified tool for Lambda, S3, SQS, CloudWatch Logs, Step Functions, CloudFormation, and DynamoDB.
+```typescript
+import Llm, { tools, JaypieToolkit } from "@jaypie/llm";
 
-See **tools-aws** for complete documentation.
+// Individual built-in tools: random, roll, time, weather
+const response = await Llm.operate("Roll 2d6", {
+  model: "gpt-5.1",
+  tools,
+});
 
+// Or use the pre-configured toolkit
+const toolkit = new JaypieToolkit();
 ```
-aws()                   # Show help with all commands
-aws("list_profiles")    # List AWS profiles
-aws("lambda_list_functions", { region: "us-east-1" })
-aws("dynamodb_query", { tableName: "...", keyConditionExpression: "..." })
-```
-
-| Command | Description |
-|---------|-------------|
-| `list_profiles` | List AWS profiles from ~/.aws |
-| `lambda_list_functions`, `lambda_get_function` | Lambda management |
-| `logs_filter_log_events` | CloudWatch Logs search |
-| `s3_list_objects` | S3 bucket operations |
-| `sqs_list_queues`, `sqs_get_queue_attributes`, `sqs_receive_message`, `sqs_purge_queue` | SQS operations |
-| `stepfunctions_list_executions`, `stepfunctions_stop_execution` | Step Functions |
-| `cloudformation_describe_stack` | CloudFormation stack details |
-| `dynamodb_describe_table`, `dynamodb_query`, `dynamodb_scan`, `dynamodb_get_item` | DynamoDB |
 
-## Datadog Tool
+## Explain Mode
 
-Unified tool for logs, monitors, metrics, synthetics, and RUM.
+Require the LLM to state its reasoning before each tool call:
 
-See **tools-datadog** for complete documentation.
+```typescript
+const toolkit = new Toolkit([myTool], { explain: true });
 
+// Or per-call
+const response = await Llm.operate("What's the weather?", {
+  model: "gpt-5.1",
+  tools: myTools,
+  explain: true,
+});
 ```
-datadog()               # Show help with all commands
-datadog("logs", { query: "status:error", from: "now-1h" })
-datadog("monitors", { status: ["Alert", "Warn"] })
-```
-
-| Command | Description |
-|---------|-------------|
-| `logs` | Search log entries |
-| `log_analytics` | Aggregate logs with groupBy |
-| `monitors` | List and check monitors |
-| `synthetics` | List synthetic tests |
-| `metrics` | Query timeseries metrics |
-| `rum` | Search RUM events |
 
-## LLM Tool
+The `__Explanation` parameter is stripped before the tool executes.
 
-Debug and inspect LLM provider responses.
+## Input Types
 
-See **tools-llm** for complete documentation.
+Fabric services validate inputs automatically:
 
+```typescript
+input: {
+  name: { type: String, required: true, description: "User name" },
+  count: { type: Number, required: false, description: "Result limit" },
+  status: {
+    type: ["active", "inactive"] as const,
+    required: false,
+    description: "Filter by status",
+  },
+}
 ```
-llm()                   # Show help
-llm("list_providers")   # List available LLM providers
-llm("debug_call", { provider: "openai", message: "Hello" })
-```
-
-| Command | Description |
-|---------|-------------|
-| `list_providers` | List available LLM providers |
-| `debug_call` | Debug LLM API call |
-
-## Environment Variables
 
-### AWS Tools
-- `AWS_PROFILE` - Default profile
-- `AWS_REGION` - Default region
+## Best Practices
 
-### Datadog Tools
-- `DATADOG_API_KEY` or `DD_API_KEY` - API key
-- `DATADOG_APP_KEY` or `DD_APP_KEY` - App key
-- `DD_ENV` - Default environment filter
-- `DD_SERVICE` - Default service filter
-- `DD_SOURCE` - Default log source
+1. **Service layer first** -- business logic in services, tools are thin adapters
+2. **One tool, one action** -- each tool does one thing
+3. **Descriptive names** -- use `noun_verb` format (`order_get`, `user_list`)
+4. **Clear descriptions** -- LLMs choose tools based on description text
+5. **Document parameters** -- every input needs a description
+6. **Return JSON-serializable data** -- tools return data, not formatted text
+7. **Use Jaypie errors** -- `NotFoundError`, `BadRequestError` for clear failure signals
+8. **Set turns > 1** -- multi-tool workflows need room to loop
 
-### LLM Tools
-- `OPENAI_API_KEY` - OpenAI API key
-- `ANTHROPIC_API_KEY` - Anthropic API key
-- `GOOGLE_API_KEY` - Google/Gemini API key
-- `OPENROUTER_API_KEY` - OpenRouter API key
+## See Also
 
+- **`skill("fabric")`** -- Fabric service pattern and adapters
+- **`skill("llm")`** -- Full `@jaypie/llm` reference
+- **`skill("services")`** -- Service layer architecture
+- **`skill("mcp")`** -- Jaypie MCP server tools

package/dist/suites/aws/aws.d.ts

@@ -1,207 +0,0 @@
-interface Logger {
-    info: (message: string, ...args: unknown[]) => void;
-    error: (message: string, ...args: unknown[]) => void;
-}
-export interface AwsCommandOptions {
-    profile?: string;
-    region?: string;
-}
-export interface AwsCommandResult<T> {
-    success: boolean;
-    data?: T;
-    error?: string;
-}
-export interface StepFunctionExecution {
-    executionArn: string;
-    stateMachineArn: string;
-    name: string;
-    status: string;
-    startDate: string;
-    stopDate?: string;
-}
-export interface StepFunctionsListExecutionsOptions extends AwsCommandOptions {
-    stateMachineArn: string;
-    statusFilter?: "RUNNING" | "SUCCEEDED" | "FAILED" | "TIMED_OUT" | "ABORTED" | "PENDING_REDRIVE";
-    maxResults?: number;
-}
-export interface StepFunctionsStopExecutionOptions extends AwsCommandOptions {
-    executionArn: string;
-    cause?: string;
-}
-export interface LambdaFunction {
-    FunctionName: string;
-    FunctionArn: string;
-    Runtime?: string;
-    Handler?: string;
-    CodeSize: number;
-    Description?: string;
-    Timeout?: number;
-    MemorySize?: number;
-    LastModified: string;
-    Version?: string;
-}
-export interface LambdaListFunctionsOptions extends AwsCommandOptions {
-    functionNamePrefix?: string;
-    maxResults?: number;
-}
-export interface LambdaGetFunctionOptions extends AwsCommandOptions {
-    functionName: string;
-}
-export interface LogEvent {
-    timestamp: number;
-    message: string;
-    ingestionTime?: number;
-    logStreamName?: string;
-}
-export interface CloudWatchLogsFilterOptions extends AwsCommandOptions {
-    logGroupName: string;
-    filterPattern?: string;
-    startTime?: string;
-    endTime?: string;
-    limit?: number;
-}
-export interface S3Object {
-    Key: string;
-    LastModified: string;
-    ETag: string;
-    Size: number;
-    StorageClass: string;
-}
-export interface S3ListObjectsOptions extends AwsCommandOptions {
-    bucket: string;
-    prefix?: string;
-    maxResults?: number;
-}
-export interface CloudFormationStack {
-    StackName: string;
-    StackId: string;
-    StackStatus: string;
-    StackStatusReason?: string;
-    CreationTime: string;
-    LastUpdatedTime?: string;
-    Description?: string;
-    Outputs?: Array<{
-        OutputKey: string;
-        OutputValue: string;
-        Description?: string;
-    }>;
-    Parameters?: Array<{
-        ParameterKey: string;
-        ParameterValue: string;
-    }>;
-}
-export interface CloudFormationDescribeStackOptions extends AwsCommandOptions {
-    stackName: string;
-}
-export interface DynamoDBDescribeTableOptions extends AwsCommandOptions {
-    tableName: string;
-}
-export interface DynamoDBScanOptions extends AwsCommandOptions {
-    tableName: string;
-    filterExpression?: string;
-    expressionAttributeValues?: string;
-    limit?: number;
-}
-export interface DynamoDBQueryOptions extends AwsCommandOptions {
-    tableName: string;
-    keyConditionExpression: string;
-    expressionAttributeValues: string;
-    indexName?: string;
-    filterExpression?: string;
-    limit?: number;
-    scanIndexForward?: boolean;
-}
-export interface DynamoDBGetItemOptions extends AwsCommandOptions {
-    tableName: string;
-    key: string;
-}
-export interface SQSQueue {
-    QueueUrl: string;
-}
-export interface SQSListQueuesOptions extends AwsCommandOptions {
-    queueNamePrefix?: string;
-}
-export interface SQSGetQueueAttributesOptions extends AwsCommandOptions {
-    queueUrl: string;
-}
-export interface SQSReceiveMessageOptions extends AwsCommandOptions {
-    queueUrl: string;
-    maxNumberOfMessages?: number;
-    visibilityTimeout?: number;
-}
-export interface SQSPurgeQueueOptions extends AwsCommandOptions {
-    queueUrl: string;
-}
-export interface AwsProfile {
-    name: string;
-    source: "config" | "credentials";
-    region?: string;
-    sso_start_url?: string;
-}
-export interface AwsValidationResult {
-    success: boolean;
-    cliAvailable: boolean;
-    cliVersion?: string;
-    profiles: AwsProfile[];
-}
-/**
- * Execute an AWS CLI command and return parsed JSON output
- */
-export declare function executeAwsCommand<T>(service: string, command: string, args: string[], options?: AwsCommandOptions, logger?: Logger): Promise<AwsCommandResult<T>>;
-/**
- * Validate AWS setup without making API calls
- */
-export declare function validateAwsSetup(): Promise<AwsValidationResult>;
-/**
- * List available AWS profiles from ~/.aws/config and ~/.aws/credentials
- */
-export declare function listAwsProfiles(logger?: Logger): Promise<AwsCommandResult<AwsProfile[]>>;
-export declare function listStepFunctionExecutions(options: StepFunctionsListExecutionsOptions, logger?: Logger): Promise<AwsCommandResult<{
-    executions: StepFunctionExecution[];
-}>>;
-export declare function stopStepFunctionExecution(options: StepFunctionsStopExecutionOptions, logger?: Logger): Promise<AwsCommandResult<{
-    stopDate: string;
-}>>;
-export declare function listLambdaFunctions(options?: LambdaListFunctionsOptions, logger?: Logger): Promise<AwsCommandResult<{
-    Functions: LambdaFunction[];
-}>>;
-export declare function getLambdaFunction(options: LambdaGetFunctionOptions, logger?: Logger): Promise<AwsCommandResult<{
-    Configuration: LambdaFunction;
-}>>;
-export declare function filterLogEvents(options: CloudWatchLogsFilterOptions, logger?: Logger): Promise<AwsCommandResult<{
-    events: LogEvent[];
-}>>;
-export declare function listS3Objects(options: S3ListObjectsOptions, logger?: Logger): Promise<AwsCommandResult<{
-    Contents: S3Object[];
-}>>;
-export declare function describeStack(options: CloudFormationDescribeStackOptions, logger?: Logger): Promise<AwsCommandResult<{
-    Stacks: CloudFormationStack[];
-}>>;
-export declare function describeDynamoDBTable(options: DynamoDBDescribeTableOptions, logger?: Logger): Promise<AwsCommandResult<{
-    Table: Record<string, unknown>;
-}>>;
-export declare function scanDynamoDB(options: DynamoDBScanOptions, logger?: Logger): Promise<AwsCommandResult<{
-    Items: Record<string, unknown>[];
-}>>;
-export declare function queryDynamoDB(options: DynamoDBQueryOptions, logger?: Logger): Promise<AwsCommandResult<{
-    Items: Record<string, unknown>[];
-}>>;
-export declare function getDynamoDBItem(options: DynamoDBGetItemOptions, logger?: Logger): Promise<AwsCommandResult<{
-    Item: Record<string, unknown>;
-}>>;
-export declare function listSQSQueues(options?: SQSListQueuesOptions, logger?: Logger): Promise<AwsCommandResult<{
-    QueueUrls: string[];
-}>>;
-export declare function getSQSQueueAttributes(options: SQSGetQueueAttributesOptions, logger?: Logger): Promise<AwsCommandResult<{
-    Attributes: Record<string, string>;
-}>>;
-export declare function receiveSQSMessage(options: SQSReceiveMessageOptions, logger?: Logger): Promise<AwsCommandResult<{
-    Messages: Array<{
-        MessageId: string;
-        ReceiptHandle: string;
-        Body: string;
-        Attributes?: Record<string, string>;
-    }>;
-}>>;
-export declare function purgeSQSQueue(options: SQSPurgeQueueOptions, logger?: Logger): Promise<AwsCommandResult<void>>;
-export {};