opentool 0.4.6 → 0.6.0

package/README.md

@@ -3,20 +3,44 @@
 [![npm version](https://badge.fury.io/js/opentool.svg)](https://badge.fury.io/js/opentool)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## OpenPond Hosting launching August 2025
+A comprehensive TypeScript framework for building, deploying, and monetizing serverless MCP (Model Context Protocol) tools with integrated AI, blockchain wallets, and crypto payments.
 
-(current openpond.ai site hasn't been updated yet)
+## Overview
 
-A TypeScript framework for building serverless MCP (Model Context Protocol) tools that automatically deploy to AWS Lambda using [OpenPond](https://openpond.ai) hosting.
+OpenTool is a complete platform for creating intelligent, payment-enabled tools that run on AWS Lambda. It combines:
+
+- **MCP Protocol** - Full Model Context Protocol implementation with stdio and HTTP transports
+- **AI Integration** - Built-in AI client with text generation, streaming, and tool calling capabilities
+- **Wallet System** - Multi-chain blockchain wallet support with Turnkey and private key providers
+- **Payment Infrastructure** - Crypto payment integration for monetizing tools on-chain
+- **Serverless Deployment** - Automatic AWS Lambda deployment via [OpenPond](https://openpond.ai)
+- **Type Safety** - Full TypeScript support with Zod schema validation
 
 ## Features
 
-- **Serverless-first**: Tools automatically deploy to AWS Lambda
-- **Type-safe**: Full TypeScript support with Zod schema validation
-- **CLI Tools**: Build, develop, and validate your tools
-- **MCP Compatible**: Works with any MCP client
-- **Automatic Detection**: Detected by OpenPond hosting platform
-- **Local Development**: Test your tools locally before deployment
+### Core Framework
+- **Serverless-first**: Tools automatically deploy to AWS Lambda with Function URLs
+- **Type-safe**: Full TypeScript support with Zod schema validation and automatic JSON schema generation
+- **CLI Tools**: Build, develop, validate, and generate metadata with comprehensive CLI
+- **Hot Reloading**: Development server with optional watch mode for rapid iteration
+- **MCP Compatible**: Works with any MCP client (Claude Desktop, MCP Inspector, etc.)
+
+### AI Capabilities
+- **Multi-Model Support**: OpenAI, Anthropic, and compatible providers
+- **Text Generation**: Simple and streaming text generation with tool calling
+- **Built-in Tools**: Web search and custom tool integration
+- **Model Management**: Automatic model normalization and capability detection
+
+### Blockchain & Payments
+- **Multi-Chain Wallets**: Support for Ethereum, Base, Optimism, Arbitrum, Polygon, and more
+- **Provider Flexibility**: Private key or Turnkey-managed signing
+- **Crypto Payments**: On-chain payment integration with ERC-20 token support
+- **Token Registry**: Built-in registry for common tokens (USDC, USDT, DAI, etc.)
+
+### Discovery & Metadata
+- **Three-Tier Metadata**: Smart defaults, enhanced metadata, and per-tool overrides
+- **On-Chain Registration**: Metadata formatted for blockchain discovery
+- **Rich Annotations**: Icons, categories, tags, and custom branding
 
 ## Installation
 
@@ -47,8 +71,18 @@ export const schema = z.object({
   name: z.string().describe("The name of the user to greet"),
 });
 
-export async function TOOL({ name }: z.infer<typeof schema>) {
-  return `Hello, ${name}! 👋`;
+export const metadata = {
+  name: "greet",
+  description: "Simple greeting tool",
+};
+
+export async function POST(request: Request) {
+  const payload = await request.json();
+  const { name } = schema.parse(payload);
+
+  return Response.json({
+    message: `Hello, ${name}!`,
+  });
 }
 ```
 
@@ -62,6 +96,19 @@ npx opentool validate
 npx opentool dev
 ```
 
+### MCP Inspector
+
+The `examples/full-metadata` project includes an `inspector.json` preset so you can exercise MCP tools with the official MCP Inspector:
+
+```bash
+cd examples/full-metadata
+npx mcp-inspector --config inspector.json --server opentool-dev
+```
+
+Before starting the inspector, copy `examples/full-metadata/.env.example` to `examples/full-metadata/.env` and populate the Turnkey, 0x, and Alchemy secrets with your own credentials. The actual `.env` file is git-ignored so you can keep real keys out of version control.
+
+The inspector spawns `opentool dev --stdio --no-watch --input tools`, so you don’t need a second terminal. Only tools that export `mcp = { enabled: true }` (for example `mcp_ping`) appear in the inspector’s tool list; HTTP-only tools like `calculate` and `hello` keep responding on the local HTTP port.
+
 ### 4. Build for deployment
 
 ```bash
@@ -134,11 +181,11 @@ This command generates the `metadata.json` file that contains all the informatio
 
 ## Tool Definition
 
-Each tool is defined by exporting three things:
+Each tool is defined by exporting:
 
 1. **schema**: Zod schema for input validation
 2. **metadata**: Tool information and MCP annotations
-3. **TOOL**: Async function that implements the tool logic
+3. **HTTP handler**: Async function that implements the tool logic (e.g., POST, GET, PUT, DELETE)
 
 ```typescript
 import { z } from "zod";
@@ -147,23 +194,39 @@ export const schema = z.object({
   // Define your input parameters here
 });
 
-export async function TOOL(params: z.infer<typeof schema>) {
+export const metadata = {
+  name: "my_tool",
+  description: "Description of what this tool does",
+};
+
+export async function POST(request: Request) {
+  const payload = await request.json();
+  const params = schema.parse(payload);
+
   // Implement your tool logic here
-  // Just return a string - it will be wrapped in MCP format automatically
-  return "Tool response";
+  return Response.json({
+    result: "Tool response",
+  });
 }
 ```
 
 ## Error Handling
 
-Simply throw errors in your TOOL function - they will be automatically converted to MCP error responses:
+Return appropriate HTTP status codes and error messages in your response:
 
 ```typescript
-export async function TOOL(params: z.infer<typeof schema>) {
+export async function POST(request: Request) {
+  const payload = await request.json();
+  const params = schema.parse(payload);
+
   if (someCondition) {
-    throw new Error("Something went wrong");
+    return Response.json(
+      { error: "Something went wrong" },
+      { status: 400 }
+    );
   }
-  return "Success";
+
+  return Response.json({ result: "Success" });
 }
 ```
 
@@ -188,10 +251,9 @@ When you push a project with `opentool` dependency to GitHub and connect it to O
 
 ## Examples
 
-See the `examples/` directory for complete examples:
+See the `examples/` directory for a comprehensive example:
 
-- **`examples/full-metadata/`** - Complete metadata configuration with payment and discovery features
-- **`examples/minimal/`** - Minimal setup demonstrating smart defaults
+- **`examples/full-metadata/`** - Metadata configuration with payment and discovery features
 
 ### Testing Examples Locally
 
@@ -207,16 +269,16 @@ cd examples/full-metadata
 npm link opentool
 npm run build
 
-# Test the minimal example  
-cd ../minimal
-npm link opentool
-npm run build
-
 # Examine generated output
 cat dist/metadata.json
 
 # Test the MCP server
 echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/mcp-server.js
+
+# Quick regression helpers from the repo root
+npm run examples:build      # Build full metadata example (CJS+ESM)
+npm run examples:validate   # Validate example metadata and tools
+npm run examples:metadata   # Regenerate metadata.json without rebuilding tools
 ```
 
 ## Metadata System
@@ -224,16 +286,19 @@ echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/mcp-serve
 OpenTool features a sophisticated **three-tier metadata system**:
 
 1. **Smart Defaults** - Zero configuration, automatic generation from `package.json`
-2. **Enhanced Metadata** - Optional `metadata.ts` for custom branding and crypto payments  
+2. **Enhanced Metadata** - Optional `metadata.ts` for custom branding and crypto payments
 3. **Full Control** - Tool-level overrides for rich discovery metadata
 
 See [`METADATA.md`](./METADATA.md) for the complete guide to configuring metadata for on-chain registration and payments.
 
+## Future Work
+
+- Explore an esbuild-powered watch mode that keeps metadata and tool artifacts up to date for the dev server. This remains on the follow-up list once the new pipeline settles.
+
 ## Contributing
 
 We welcome contributions! Please see our [Contributing Guide](https://github.com/openpond/opentool/blob/master/CONTRIBUTING.md) for details.
 
-
 ## License
 
 MIT © [OpenTool](https://opentool.dev)

package/dist/ai/index.d.ts

@@ -0,0 +1,237 @@
+type ChatMessageRole = "system" | "user" | "assistant" | "tool";
+interface ChatMessageContentPartText {
+    type: "text";
+    text: string;
+}
+interface ChatMessageContentPartImageUrl {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "auto" | "high" | "low";
+    };
+}
+type ChatMessageContentPart = ChatMessageContentPartText | ChatMessageContentPartImageUrl | Record<string, unknown>;
+interface ChatMessage {
+    role: ChatMessageRole;
+    content: string | ChatMessageContentPart[];
+    name?: string;
+    tool_call_id?: string;
+}
+interface JsonSchema {
+    type?: string;
+    title?: string;
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema | JsonSchema[];
+    enum?: Array<string | number | boolean | null>;
+    additionalProperties?: boolean | JsonSchema;
+    [key: string]: unknown;
+}
+interface FunctionToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: JsonSchema;
+    };
+}
+type ToolDefinition = FunctionToolDefinition;
+type ToolChoice = "auto" | "required" | "none" | {
+    type: "function";
+    function: {
+        name: string;
+    };
+};
+interface GenerationParameters {
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+    stop?: string | string[];
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    responseFormat?: "json_object" | "text" | {
+        type: "json_schema";
+        json_schema: JsonSchema;
+    };
+}
+interface ToolExecutionPolicy {
+    enableTools?: boolean;
+    maxSteps?: number;
+    toolSources?: "internal" | "public" | "both";
+    webSearch?: WebSearchOptions | false;
+}
+interface WebSearchOptions {
+    limit?: number;
+    includeImages?: boolean;
+}
+interface AIRequestMetadata {
+    requestId?: string;
+    sessionId?: string;
+    tags?: string[];
+    openpond?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface GenerateTextOptions {
+    messages: ChatMessage[];
+    model?: string;
+    generation?: GenerationParameters;
+    tools?: ToolDefinition[];
+    toolChoice?: ToolChoice;
+    toolExecution?: ToolExecutionPolicy;
+    metadata?: AIRequestMetadata;
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+    headers?: Record<string, string>;
+}
+interface AIClientConfig {
+    baseUrl?: string;
+    apiKey?: string;
+    defaultModel?: string;
+    defaultHeaders?: Record<string, string>;
+    fetchImplementation?: typeof fetch;
+    timeoutMs?: number;
+}
+interface ResolvedAIClientConfig {
+    baseUrl: string;
+    apiKey?: string;
+    defaultModel: string;
+    defaultHeaders: Record<string, string>;
+    fetchImplementation: typeof fetch;
+    timeoutMs: number;
+}
+interface ChatCompletionResponse {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage?: ChatCompletionUsage;
+    system_fingerprint?: string;
+}
+interface ChatCompletionChoice {
+    index: number;
+    message: ChatMessage;
+    finish_reason?: string;
+    logprobs?: ChatCompletionLogProbs;
+}
+interface ChatCompletionUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    [key: string]: unknown;
+}
+interface ChatCompletionLogProbs {
+    content?: Array<{
+        token: string;
+        logprob: number;
+        bytes?: number[];
+    }>;
+}
+interface GenerateTextResult {
+    id: string;
+    model: string;
+    message: ChatMessage;
+    finishReason?: string;
+    usage?: ChatCompletionUsage;
+    raw: ChatCompletionResponse;
+}
+interface StreamingEventHandlers {
+    onTextDelta?: (delta: string) => void;
+    onToolCallDelta?: (toolCall: unknown) => void;
+    onReasoningDelta?: (delta: string) => void;
+    onUsage?: (usage: ChatCompletionUsage) => void;
+    onError?: (error: unknown) => void;
+    onDone?: () => void;
+}
+interface StreamTextOptions extends GenerateTextOptions {
+    handlers?: StreamingEventHandlers;
+    sendReasoning?: boolean;
+    includeUsage?: boolean;
+}
+interface StreamTextResult {
+    abort: () => void;
+    finished: Promise<void>;
+}
+
+interface ErrorInit {
+    cause?: unknown;
+}
+declare class AIError extends Error {
+    constructor(message: string, options?: ErrorInit);
+}
+interface ResponseErrorDetails {
+    status: number;
+    statusText: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+declare class AIFetchError extends AIError {
+    constructor(message: string, options?: ErrorInit);
+}
+declare class AIResponseError extends AIError {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body?: unknown;
+    readonly headers: Record<string, string>;
+    constructor(details: ResponseErrorDetails, message?: string);
+}
+declare class AIAbortError extends AIError {
+    constructor(message?: string);
+}
+
+type ModelProvider = "openai" | "anthropic" | "google" | "deepseek" | "custom";
+interface ModelConfig {
+    name: string;
+    label: string;
+    provider: ModelProvider;
+    supportsStreaming: boolean;
+    supportsTools: boolean;
+    reasoning?: boolean;
+    aliases?: string[];
+    default?: boolean;
+}
+declare function listModels(): ModelConfig[];
+declare function getModelConfig(modelName?: string): ModelConfig | undefined;
+declare function normalizeModelName(modelName?: string): string;
+declare function isStreamingSupported(modelName?: string): boolean;
+declare function isToolCallingSupported(modelName?: string): boolean;
+
+interface AIClient {
+    readonly config: ResolvedAIClientConfig;
+    generateText(options: GenerateTextOptions): Promise<GenerateTextResult>;
+    streamText(options: StreamTextOptions): Promise<StreamTextResult>;
+    listModels: typeof listModels;
+}
+declare function createAIClient(config?: AIClientConfig): AIClient;
+declare function generateText(options: GenerateTextOptions, clientConfig?: AIClientConfig): Promise<GenerateTextResult>;
+declare function streamText(options: StreamTextOptions, clientConfig?: AIClientConfig): Promise<StreamTextResult>;
+
+declare const DEFAULT_BASE_URL = "https://gateway.openpond.dev";
+declare const DEFAULT_TIMEOUT_MS = 60000;
+declare const DEFAULT_MODEL = "openai/gpt-5-mini";
+declare function resolveConfig(config?: AIClientConfig): ResolvedAIClientConfig;
+
+declare const WEBSEARCH_TOOL_NAME = "websearch";
+declare const WEBSEARCH_TOOL_DEFINITION: ToolDefinition;
+declare function resolveToolset(tools: ToolDefinition[] | undefined, policy: ToolExecutionPolicy | undefined): ToolDefinition[] | undefined;
+
+interface FlattenMessageContentOptions {
+    /**
+     * String used to join individual text segments when the content array contains multiple text parts.
+     * Defaults to an empty string.
+     */
+    separator?: string;
+    /**
+     * When true, JSON stringifies non-text segments instead of discarding them.
+     * Defaults to false (skip non-text parts).
+     */
+    includeUnknown?: boolean;
+}
+declare function flattenMessageContent(content: ChatMessage["content"], options?: FlattenMessageContentOptions): string | undefined;
+interface EnsureTextContentOptions extends FlattenMessageContentOptions {
+    errorMessage?: string;
+}
+declare function ensureTextContent(message: ChatMessage, options?: EnsureTextContentOptions): string;
+
+export { AIAbortError, type AIClientConfig, AIError, AIFetchError, type AIRequestMetadata, AIResponseError, type ChatCompletionChoice, type ChatCompletionLogProbs, type ChatCompletionResponse, type ChatCompletionUsage, type ChatMessage, type ChatMessageContentPart, type ChatMessageContentPartImageUrl, type ChatMessageContentPartText, type ChatMessageRole, DEFAULT_BASE_URL, DEFAULT_MODEL, DEFAULT_TIMEOUT_MS, type FunctionToolDefinition, type GenerateTextOptions, type GenerateTextResult, type GenerationParameters, type JsonSchema, type ResolvedAIClientConfig, type ResponseErrorDetails, type StreamTextOptions, type StreamTextResult, type StreamingEventHandlers, type ToolChoice, type ToolDefinition, type ToolExecutionPolicy, WEBSEARCH_TOOL_DEFINITION, WEBSEARCH_TOOL_NAME, type WebSearchOptions, createAIClient, ensureTextContent, flattenMessageContent, generateText, getModelConfig, isStreamingSupported, isToolCallingSupported, listModels, normalizeModelName, resolveConfig, resolveToolset, streamText };