@ctxprotocol/sdk 0.1.3 → 0.4.0

package/README.md

@@ -16,6 +16,17 @@ Context Protocol is **npm for AI capabilities**. Just as you install packages to
 - **⚡️ Agentic Discovery:** Your Agent can search the marketplace at runtime to find tools it didn't know it needed.
 - **💸 Micro-Billing:** Pay only for what you use (e.g., $0.001/query). No monthly subscriptions for tools you rarely use.
 
+## Who Is This SDK For?
+
+**This SDK is for AI Agent developers** who want to query the Context marketplace and execute tools.
+
+| Role | What You Use |
+|------|--------------|
+| **AI Agent Developer** | `@ctxprotocol/sdk` — Query marketplace, execute tools, handle payments |
+| **Tool Contributor (Data Broker)** | `@modelcontextprotocol/sdk` — Standard MCP server + Context extensions |
+
+If you're building an MCP server to contribute tools and earn money, you **don't need this SDK**. See [Building MCP Servers](#building-mcp-servers-tool-contributors) for the simple pattern.
+
 ## Installation
 
 ```bash
@@ -340,6 +351,92 @@ try {
 | `payment_failed`         | USDC payment failed                      | Check balance                       |
 | `execution_failed`       | Tool error                               | Feed error to LLM for retry         |
 
+---
+
+## Building MCP Servers (Tool Contributors)
+
+Want to earn money by contributing tools to the Context marketplace? Build a standard MCP server that uses `outputSchema` and `structuredContent` from the [official MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#output-schema):
+
+1. **`outputSchema`** in tool definitions — JSON Schema describing your response
+2. **`structuredContent`** in responses — Machine-readable data matching the schema
+
+> **Note:** These are standard MCP features defined in the [MCP Tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#output-schema). While optional in vanilla MCP, Context requires them for payment verification, dispute resolution, and AI code generation.
+
+### Why These Matter
+
+| Requirement | Purpose |
+|------------|---------|
+| `outputSchema` | AI agents use this to generate type-safe code. Context uses it for dispute resolution. |
+| `structuredContent` | Agents parse this for programmatic access. Text `content` is for humans. |
+
+### Example: Standard MCP Server
+
+Build your server with the standard `@modelcontextprotocol/sdk`:
+
+```typescript
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+
+// Define tools with outputSchema (standard MCP feature, required by Context)
+const TOOLS = [{
+  name: "get_gas_price",
+  description: "Get current gas prices",
+  inputSchema: {
+    type: "object",
+    properties: {
+      chainId: { type: "number", description: "EVM chain ID" },
+    },
+  },
+  // 👇 Standard MCP feature (see: modelcontextprotocol.io/specification)
+  outputSchema: {
+    type: "object",
+    properties: {
+      gasPrice: { type: "number" },
+      unit: { type: "string" },
+    },
+    required: ["gasPrice", "unit"],
+  },
+}];
+
+// Standard MCP server setup
+const server = new Server(
+  { name: "my-gas-tool", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS,  // outputSchema is included automatically
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const data = await fetchGasData(request.params.arguments.chainId);
+  
+  // 👇 Standard MCP feature (see: modelcontextprotocol.io/specification)
+  return {
+    content: [{ type: "text", text: JSON.stringify(data) }],  // Backward compat
+    structuredContent: data,  // Machine-readable, matches outputSchema
+  };
+});
+```
+
+### Example Servers
+
+See complete working examples in `/examples/server/`:
+
+- **[blocknative-contributor](./examples/server/blocknative-contributor)** — Gas price API (3 tools)
+- **[hyperliquid-contributor](./examples/server/hyperliquid-contributor)** — DeFi analytics (16 tools)
+
+### Schema Accuracy = Revenue
+
+⚠️ **Important**: Your `outputSchema` is a contract. Context's "Robot Judge" validates that your `structuredContent` matches your declared schema. Schema violations result in automatic refunds to users.
+
+### Server Dependencies
+
+```bash
+pnpm add @modelcontextprotocol/sdk express
+pnpm add -D @types/express
+```
+
 ## Payment Flow
 
 When you execute a tool:

package/dist/client/index.cjs

@@ -0,0 +1,194 @@
+'use strict';
+
+// src/client/types.ts
+var ContextError = class extends Error {
+  constructor(message, code, statusCode, helpUrl) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.helpUrl = helpUrl;
+    this.name = "ContextError";
+  }
+};
+
+// src/client/resources/discovery.ts
+var Discovery = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Search for tools matching a query string
+   *
+   * @param query - The search query (e.g., "gas prices", "nft metadata")
+   * @param limit - Maximum number of results (1-50, default 10)
+   * @returns Array of matching tools
+   *
+   * @example
+   * ```typescript
+   * const tools = await client.discovery.search("gas prices");
+   * console.log(tools[0].name); // "Gas Price Oracle"
+   * console.log(tools[0].mcpTools); // Available methods
+   * ```
+   */
+  async search(query, limit) {
+    const params = new URLSearchParams();
+    if (query) {
+      params.set("q", query);
+    }
+    if (limit !== void 0) {
+      params.set("limit", String(limit));
+    }
+    const queryString = params.toString();
+    const endpoint = `/api/v1/tools/search${queryString ? `?${queryString}` : ""}`;
+    const response = await this.client.fetch(endpoint);
+    return response.tools;
+  }
+  /**
+   * Get featured/popular tools (empty query search)
+   *
+   * @param limit - Maximum number of results (1-50, default 10)
+   * @returns Array of featured tools
+   *
+   * @example
+   * ```typescript
+   * const featured = await client.discovery.getFeatured(5);
+   * ```
+   */
+  async getFeatured(limit) {
+    return this.search("", limit);
+  }
+};
+
+// src/client/resources/tools.ts
+var Tools = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Execute a tool with the provided arguments
+   *
+   * @param options - Execution options
+   * @param options.toolId - The UUID of the tool (from search results)
+   * @param options.toolName - The specific MCP tool method to call (from tool's mcpTools array)
+   * @param options.args - Arguments to pass to the tool
+   * @returns The execution result with the tool's output data
+   *
+   * @throws {ContextError} With code `no_wallet` if wallet not set up
+   * @throws {ContextError} With code `insufficient_allowance` if Auto Pay not enabled
+   * @throws {ContextError} With code `payment_failed` if on-chain payment fails
+   * @throws {ContextError} With code `execution_failed` if tool execution fails
+   *
+   * @example
+   * ```typescript
+   * // First, search for a tool
+   * const tools = await client.discovery.search("gas prices");
+   * const tool = tools[0];
+   *
+   * // Execute a specific method from the tool's mcpTools
+   * const result = await client.tools.execute({
+   *   toolId: tool.id,
+   *   toolName: tool.mcpTools[0].name, // e.g., "get_gas_prices"
+   *   args: { chainId: 1 }
+   * });
+   *
+   * console.log(result.result); // The tool's output
+   * console.log(result.durationMs); // Execution time
+   * ```
+   */
+  async execute(options) {
+    const { toolId, toolName, args } = options;
+    const response = await this.client.fetch(
+      "/api/v1/tools/execute",
+      {
+        method: "POST",
+        body: JSON.stringify({ toolId, toolName, args })
+      }
+    );
+    if ("error" in response) {
+      throw new ContextError(
+        response.error,
+        response.code,
+        400,
+        response.helpUrl
+      );
+    }
+    if (response.success) {
+      return {
+        result: response.result,
+        tool: response.tool,
+        durationMs: response.durationMs
+      };
+    }
+    throw new ContextError("Unexpected response format from API");
+  }
+};
+
+// src/client/client.ts
+var ContextClient = class {
+  apiKey;
+  baseUrl;
+  /**
+   * Discovery resource for searching tools
+   */
+  discovery;
+  /**
+   * Tools resource for executing tools
+   */
+  tools;
+  /**
+   * Creates a new Context Protocol client
+   *
+   * @param options - Client configuration options
+   * @param options.apiKey - Your Context Protocol API key (format: sk_live_...)
+   * @param options.baseUrl - Optional base URL override (defaults to https://ctxprotocol.com)
+   */
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new ContextError("API key is required");
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? "https://ctxprotocol.com").replace(/\/$/, "");
+    this.discovery = new Discovery(this);
+    this.tools = new Tools(this);
+  }
+  /**
+   * Internal method for making authenticated HTTP requests
+   * All requests include the Authorization header with the API key
+   *
+   * @internal
+   */
+  async fetch(endpoint, options = {}) {
+    const url = `${this.baseUrl}${endpoint}`;
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+        ...options.headers
+      }
+    });
+    if (!response.ok) {
+      let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+      let errorCode;
+      let helpUrl;
+      try {
+        const errorBody = await response.json();
+        if (errorBody.error) {
+          errorMessage = errorBody.error;
+          errorCode = errorBody.code;
+          helpUrl = errorBody.helpUrl;
+        }
+      } catch {
+      }
+      throw new ContextError(errorMessage, errorCode, response.status, helpUrl);
+    }
+    return response.json();
+  }
+};
+
+exports.ContextClient = ContextClient;
+exports.ContextError = ContextError;
+exports.Discovery = Discovery;
+exports.Tools = Tools;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/client/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/types.ts","../../src/client/resources/discovery.ts","../../src/client/resources/tools.ts","../../src/client/client.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Configuration options for initializing the ContextClient\n */\nexport interface ContextClientOptions {\n  /**\n   * Your Context Protocol API key\n   * @example \"sk_live_abc123...\"\n   */\n  apiKey: string;\n\n  /**\n   * Base URL for the Context Protocol API\n   * @default \"https://ctxprotocol.com\"\n   */\n  baseUrl?: string;\n}\n\n/**\n * An individual MCP tool exposed by a tool listing\n */\nexport interface McpTool {\n  /** Name of the MCP tool method */\n  name: string;\n\n  /** Description of what this method does */\n  description: string;\n\n  /**\n   * JSON Schema for the input arguments this tool accepts.\n   * Used by LLMs to generate correct arguments.\n   */\n  inputSchema?: Record<string, unknown>;\n\n  /**\n   * JSON Schema for the output this tool returns.\n   * Used by LLMs to understand the response structure.\n   */\n  outputSchema?: Record<string, unknown>;\n}\n\n/**\n * Represents a tool available on the Context Protocol marketplace\n */\nexport interface Tool {\n  /** Unique identifier for the tool (UUID) */\n  id: string;\n\n  /** Human-readable name of the tool */\n  name: string;\n\n  /** Description of what the tool does */\n  description: string;\n\n  /** Price per execution in USDC */\n  price: string;\n\n  /** Tool category (e.g., \"defi\", \"nft\") */\n  category?: string;\n\n  /** Whether the tool is verified by Context Protocol */\n  isVerified?: boolean;\n\n  /**\n   * Available MCP tool methods\n   * Use items from this array as `toolName` when executing\n   */\n  mcpTools?: McpTool[];\n\n  /** Creation timestamp */\n  createdAt?: string;\n\n  /** Last update timestamp */\n  updatedAt?: string;\n}\n\n/**\n * Response from the tools search endpoint\n */\nexport interface SearchResponse {\n  /** Array of matching tools */\n  tools: Tool[];\n\n  /** The search query that was used */\n  query: string;\n\n  /** Total number of results */\n  count: number;\n}\n\n/**\n * Options for searching tools\n */\nexport interface SearchOptions {\n  /** Search query (semantic search) */\n  query?: string;\n\n  /** Maximum number of results (1-50, default 10) */\n  limit?: number;\n}\n\n/**\n * Options for executing a tool\n */\nexport interface ExecuteOptions {\n  /** The UUID of the tool to execute (from search results) */\n  toolId: string;\n\n  /** The specific MCP tool name to call (from tool's mcpTools array) */\n  toolName: string;\n\n  /** Arguments to pass to the tool */\n  args?: Record<string, unknown>;\n}\n\n/**\n * Successful execution response from the API\n */\nexport interface ExecuteApiSuccessResponse {\n  success: true;\n\n  /** The result data from the tool execution */\n  result: unknown;\n\n  /** Information about the executed tool */\n  tool: {\n    id: string;\n    name: string;\n  };\n\n  /** Execution duration in milliseconds */\n  durationMs: number;\n}\n\n/**\n * Error response from the API\n */\nexport interface ExecuteApiErrorResponse {\n  /** Human-readable error message */\n  error: string;\n\n  /** Error code for programmatic handling */\n  code?: ContextErrorCode;\n\n  /** URL to help resolve the issue */\n  helpUrl?: string;\n}\n\n/**\n * Raw API response from the execute endpoint\n */\nexport type ExecuteApiResponse = ExecuteApiSuccessResponse | ExecuteApiErrorResponse;\n\n/**\n * The resolved result returned to the user after SDK processing\n */\nexport interface ExecutionResult<T = unknown> {\n  /** The data returned by the tool */\n  result: T;\n\n  /** Information about the executed tool */\n  tool: {\n    id: string;\n    name: string;\n  };\n\n  /** Execution duration in milliseconds */\n  durationMs: number;\n}\n\n/**\n * Specific error codes returned by the Context Protocol API\n */\nexport type ContextErrorCode =\n  | \"unauthorized\"\n  | \"no_wallet\"\n  | \"insufficient_allowance\"\n  | \"payment_failed\"\n  | \"execution_failed\";\n\n/**\n * Error thrown by the Context Protocol client\n */\nexport class ContextError extends Error {\n  constructor(\n    message: string,\n    public readonly code?: ContextErrorCode | string,\n    public readonly statusCode?: number,\n    public readonly helpUrl?: string\n  ) {\n    super(message);\n    this.name = \"ContextError\";\n  }\n}\n","import type { Tool, SearchResponse } from \"../types.js\";\nimport type { ContextClient } from \"../client.js\";\n\n/**\n * Discovery resource for searching and finding tools on the Context Protocol marketplace\n */\nexport class Discovery {\n  constructor(private client: ContextClient) {}\n\n  /**\n   * Search for tools matching a query string\n   *\n   * @param query - The search query (e.g., \"gas prices\", \"nft metadata\")\n   * @param limit - Maximum number of results (1-50, default 10)\n   * @returns Array of matching tools\n   *\n   * @example\n   * ```typescript\n   * const tools = await client.discovery.search(\"gas prices\");\n   * console.log(tools[0].name); // \"Gas Price Oracle\"\n   * console.log(tools[0].mcpTools); // Available methods\n   * ```\n   */\n  async search(query: string, limit?: number): Promise<Tool[]> {\n    const params = new URLSearchParams();\n\n    if (query) {\n      params.set(\"q\", query);\n    }\n\n    if (limit !== undefined) {\n      params.set(\"limit\", String(limit));\n    }\n\n    const queryString = params.toString();\n    const endpoint = `/api/v1/tools/search${queryString ? `?${queryString}` : \"\"}`;\n\n    const response = await this.client.fetch<SearchResponse>(endpoint);\n\n    return response.tools;\n  }\n\n  /**\n   * Get featured/popular tools (empty query search)\n   *\n   * @param limit - Maximum number of results (1-50, default 10)\n   * @returns Array of featured tools\n   *\n   * @example\n   * ```typescript\n   * const featured = await client.discovery.getFeatured(5);\n   * ```\n   */\n  async getFeatured(limit?: number): Promise<Tool[]> {\n    return this.search(\"\", limit);\n  }\n}\n","import type {\n  ExecuteOptions,\n  ExecuteApiResponse,\n  ExecutionResult,\n} from \"../types.js\";\nimport { ContextError } from \"../types.js\";\nimport type { ContextClient } from \"../client.js\";\n\n/**\n * Tools resource for executing tools on the Context Protocol marketplace\n */\nexport class Tools {\n  constructor(private client: ContextClient) {}\n\n  /**\n   * Execute a tool with the provided arguments\n   *\n   * @param options - Execution options\n   * @param options.toolId - The UUID of the tool (from search results)\n   * @param options.toolName - The specific MCP tool method to call (from tool's mcpTools array)\n   * @param options.args - Arguments to pass to the tool\n   * @returns The execution result with the tool's output data\n   *\n   * @throws {ContextError} With code `no_wallet` if wallet not set up\n   * @throws {ContextError} With code `insufficient_allowance` if Auto Pay not enabled\n   * @throws {ContextError} With code `payment_failed` if on-chain payment fails\n   * @throws {ContextError} With code `execution_failed` if tool execution fails\n   *\n   * @example\n   * ```typescript\n   * // First, search for a tool\n   * const tools = await client.discovery.search(\"gas prices\");\n   * const tool = tools[0];\n   *\n   * // Execute a specific method from the tool's mcpTools\n   * const result = await client.tools.execute({\n   *   toolId: tool.id,\n   *   toolName: tool.mcpTools[0].name, // e.g., \"get_gas_prices\"\n   *   args: { chainId: 1 }\n   * });\n   *\n   * console.log(result.result); // The tool's output\n   * console.log(result.durationMs); // Execution time\n   * ```\n   */\n  async execute<T = unknown>(options: ExecuteOptions): Promise<ExecutionResult<T>> {\n    const { toolId, toolName, args } = options;\n\n    const response = await this.client.fetch<ExecuteApiResponse>(\n      \"/api/v1/tools/execute\",\n      {\n        method: \"POST\",\n        body: JSON.stringify({ toolId, toolName, args }),\n      }\n    );\n\n    // Handle error response\n    if (\"error\" in response) {\n      throw new ContextError(\n        response.error,\n        response.code,\n        400,\n        response.helpUrl\n      );\n    }\n\n    // Handle success response\n    if (response.success) {\n      return {\n        result: response.result as T,\n        tool: response.tool,\n        durationMs: response.durationMs,\n      };\n    }\n\n    // Fallback - shouldn't reach here with valid API responses\n    throw new ContextError(\"Unexpected response format from API\");\n  }\n}\n","import type { ContextClientOptions } from \"./types.js\";\nimport { ContextError } from \"./types.js\";\nimport { Discovery } from \"./resources/discovery.js\";\nimport { Tools } from \"./resources/tools.js\";\n\n/**\n * The official TypeScript client for the Context Protocol.\n *\n * Use this client to discover and execute AI tools programmatically.\n *\n * @example\n * ```typescript\n * import { ContextClient } from \"@contextprotocol/client\";\n *\n * const client = new ContextClient({\n *   apiKey: \"sk_live_...\"\n * });\n *\n * // Discover tools\n * const tools = await client.discovery.search(\"gas prices\");\n *\n * // Execute a tool method\n * const result = await client.tools.execute({\n *   toolId: tools[0].id,\n *   toolName: tools[0].mcpTools[0].name,\n *   args: { chainId: 1 }\n * });\n * ```\n */\nexport class ContextClient {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n\n  /**\n   * Discovery resource for searching tools\n   */\n  public readonly discovery: Discovery;\n\n  /**\n   * Tools resource for executing tools\n   */\n  public readonly tools: Tools;\n\n  /**\n   * Creates a new Context Protocol client\n   *\n   * @param options - Client configuration options\n   * @param options.apiKey - Your Context Protocol API key (format: sk_live_...)\n   * @param options.baseUrl - Optional base URL override (defaults to https://ctxprotocol.com)\n   */\n  constructor(options: ContextClientOptions) {\n    if (!options.apiKey) {\n      throw new ContextError(\"API key is required\");\n    }\n\n    this.apiKey = options.apiKey;\n    this.baseUrl = (options.baseUrl ?? \"https://ctxprotocol.com\").replace(/\\/$/, \"\");\n\n    // Initialize resources\n    this.discovery = new Discovery(this);\n    this.tools = new Tools(this);\n  }\n\n  /**\n   * Internal method for making authenticated HTTP requests\n   * All requests include the Authorization header with the API key\n   *\n   * @internal\n   */\n  async fetch<T>(endpoint: string, options: RequestInit = {}): Promise<T> {\n    const url = `${this.baseUrl}${endpoint}`;\n\n    const response = await fetch(url, {\n      ...options,\n      headers: {\n        \"Content-Type\": \"application/json\",\n        Authorization: `Bearer ${this.apiKey}`,\n        ...options.headers,\n      },\n    });\n\n    if (!response.ok) {\n      let errorMessage = `HTTP ${response.status}: ${response.statusText}`;\n      let errorCode: string | undefined;\n      let helpUrl: string | undefined;\n\n      try {\n        const errorBody = await response.json();\n        if (errorBody.error) {\n          errorMessage = errorBody.error;\n          errorCode = errorBody.code;\n          helpUrl = errorBody.helpUrl;\n        }\n      } catch {\n        // Use default error message if JSON parsing fails\n      }\n\n      throw new ContextError(errorMessage, errorCode, response.status, helpUrl);\n    }\n\n    return response.json() as Promise<T>;\n  }\n}\n"]}

package/dist/client/index.d.cts

@@ -0,0 +1,277 @@
+/**
+ * Configuration options for initializing the ContextClient
+ */
+interface ContextClientOptions {
+    /**
+     * Your Context Protocol API key
+     * @example "sk_live_abc123..."
+     */
+    apiKey: string;
+    /**
+     * Base URL for the Context Protocol API
+     * @default "https://ctxprotocol.com"
+     */
+    baseUrl?: string;
+}
+/**
+ * An individual MCP tool exposed by a tool listing
+ */
+interface McpTool {
+    /** Name of the MCP tool method */
+    name: string;
+    /** Description of what this method does */
+    description: string;
+    /**
+     * JSON Schema for the input arguments this tool accepts.
+     * Used by LLMs to generate correct arguments.
+     */
+    inputSchema?: Record<string, unknown>;
+    /**
+     * JSON Schema for the output this tool returns.
+     * Used by LLMs to understand the response structure.
+     */
+    outputSchema?: Record<string, unknown>;
+}
+/**
+ * Represents a tool available on the Context Protocol marketplace
+ */
+interface Tool {
+    /** Unique identifier for the tool (UUID) */
+    id: string;
+    /** Human-readable name of the tool */
+    name: string;
+    /** Description of what the tool does */
+    description: string;
+    /** Price per execution in USDC */
+    price: string;
+    /** Tool category (e.g., "defi", "nft") */
+    category?: string;
+    /** Whether the tool is verified by Context Protocol */
+    isVerified?: boolean;
+    /**
+     * Available MCP tool methods
+     * Use items from this array as `toolName` when executing
+     */
+    mcpTools?: McpTool[];
+    /** Creation timestamp */
+    createdAt?: string;
+    /** Last update timestamp */
+    updatedAt?: string;
+}
+/**
+ * Response from the tools search endpoint
+ */
+interface SearchResponse {
+    /** Array of matching tools */
+    tools: Tool[];
+    /** The search query that was used */
+    query: string;
+    /** Total number of results */
+    count: number;
+}
+/**
+ * Options for searching tools
+ */
+interface SearchOptions {
+    /** Search query (semantic search) */
+    query?: string;
+    /** Maximum number of results (1-50, default 10) */
+    limit?: number;
+}
+/**
+ * Options for executing a tool
+ */
+interface ExecuteOptions {
+    /** The UUID of the tool to execute (from search results) */
+    toolId: string;
+    /** The specific MCP tool name to call (from tool's mcpTools array) */
+    toolName: string;
+    /** Arguments to pass to the tool */
+    args?: Record<string, unknown>;
+}
+/**
+ * Successful execution response from the API
+ */
+interface ExecuteApiSuccessResponse {
+    success: true;
+    /** The result data from the tool execution */
+    result: unknown;
+    /** Information about the executed tool */
+    tool: {
+        id: string;
+        name: string;
+    };
+    /** Execution duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * Error response from the API
+ */
+interface ExecuteApiErrorResponse {
+    /** Human-readable error message */
+    error: string;
+    /** Error code for programmatic handling */
+    code?: ContextErrorCode;
+    /** URL to help resolve the issue */
+    helpUrl?: string;
+}
+/**
+ * Raw API response from the execute endpoint
+ */
+type ExecuteApiResponse = ExecuteApiSuccessResponse | ExecuteApiErrorResponse;
+/**
+ * The resolved result returned to the user after SDK processing
+ */
+interface ExecutionResult<T = unknown> {
+    /** The data returned by the tool */
+    result: T;
+    /** Information about the executed tool */
+    tool: {
+        id: string;
+        name: string;
+    };
+    /** Execution duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * Specific error codes returned by the Context Protocol API
+ */
+type ContextErrorCode = "unauthorized" | "no_wallet" | "insufficient_allowance" | "payment_failed" | "execution_failed";
+/**
+ * Error thrown by the Context Protocol client
+ */
+declare class ContextError extends Error {
+    readonly code?: (ContextErrorCode | string) | undefined;
+    readonly statusCode?: number | undefined;
+    readonly helpUrl?: string | undefined;
+    constructor(message: string, code?: (ContextErrorCode | string) | undefined, statusCode?: number | undefined, helpUrl?: string | undefined);
+}
+
+/**
+ * Discovery resource for searching and finding tools on the Context Protocol marketplace
+ */
+declare class Discovery {
+    private client;
+    constructor(client: ContextClient);
+    /**
+     * Search for tools matching a query string
+     *
+     * @param query - The search query (e.g., "gas prices", "nft metadata")
+     * @param limit - Maximum number of results (1-50, default 10)
+     * @returns Array of matching tools
+     *
+     * @example
+     * ```typescript
+     * const tools = await client.discovery.search("gas prices");
+     * console.log(tools[0].name); // "Gas Price Oracle"
+     * console.log(tools[0].mcpTools); // Available methods
+     * ```
+     */
+    search(query: string, limit?: number): Promise<Tool[]>;
+    /**
+     * Get featured/popular tools (empty query search)
+     *
+     * @param limit - Maximum number of results (1-50, default 10)
+     * @returns Array of featured tools
+     *
+     * @example
+     * ```typescript
+     * const featured = await client.discovery.getFeatured(5);
+     * ```
+     */
+    getFeatured(limit?: number): Promise<Tool[]>;
+}
+
+/**
+ * Tools resource for executing tools on the Context Protocol marketplace
+ */
+declare class Tools {
+    private client;
+    constructor(client: ContextClient);
+    /**
+     * Execute a tool with the provided arguments
+     *
+     * @param options - Execution options
+     * @param options.toolId - The UUID of the tool (from search results)
+     * @param options.toolName - The specific MCP tool method to call (from tool's mcpTools array)
+     * @param options.args - Arguments to pass to the tool
+     * @returns The execution result with the tool's output data
+     *
+     * @throws {ContextError} With code `no_wallet` if wallet not set up
+     * @throws {ContextError} With code `insufficient_allowance` if Auto Pay not enabled
+     * @throws {ContextError} With code `payment_failed` if on-chain payment fails
+     * @throws {ContextError} With code `execution_failed` if tool execution fails
+     *
+     * @example
+     * ```typescript
+     * // First, search for a tool
+     * const tools = await client.discovery.search("gas prices");
+     * const tool = tools[0];
+     *
+     * // Execute a specific method from the tool's mcpTools
+     * const result = await client.tools.execute({
+     *   toolId: tool.id,
+     *   toolName: tool.mcpTools[0].name, // e.g., "get_gas_prices"
+     *   args: { chainId: 1 }
+     * });
+     *
+     * console.log(result.result); // The tool's output
+     * console.log(result.durationMs); // Execution time
+     * ```
+     */
+    execute<T = unknown>(options: ExecuteOptions): Promise<ExecutionResult<T>>;
+}
+
+/**
+ * The official TypeScript client for the Context Protocol.
+ *
+ * Use this client to discover and execute AI tools programmatically.
+ *
+ * @example
+ * ```typescript
+ * import { ContextClient } from "@contextprotocol/client";
+ *
+ * const client = new ContextClient({
+ *   apiKey: "sk_live_..."
+ * });
+ *
+ * // Discover tools
+ * const tools = await client.discovery.search("gas prices");
+ *
+ * // Execute a tool method
+ * const result = await client.tools.execute({
+ *   toolId: tools[0].id,
+ *   toolName: tools[0].mcpTools[0].name,
+ *   args: { chainId: 1 }
+ * });
+ * ```
+ */
+declare class ContextClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    /**
+     * Discovery resource for searching tools
+     */
+    readonly discovery: Discovery;
+    /**
+     * Tools resource for executing tools
+     */
+    readonly tools: Tools;
+    /**
+     * Creates a new Context Protocol client
+     *
+     * @param options - Client configuration options
+     * @param options.apiKey - Your Context Protocol API key (format: sk_live_...)
+     * @param options.baseUrl - Optional base URL override (defaults to https://ctxprotocol.com)
+     */
+    constructor(options: ContextClientOptions);
+    /**
+     * Internal method for making authenticated HTTP requests
+     * All requests include the Authorization header with the API key
+     *
+     * @internal
+     */
+    fetch<T>(endpoint: string, options?: RequestInit): Promise<T>;
+}
+
+export { ContextClient, type ContextClientOptions, ContextError, type ContextErrorCode, Discovery, type ExecuteApiErrorResponse, type ExecuteApiResponse, type ExecuteApiSuccessResponse, type ExecuteOptions, type ExecutionResult, type McpTool, type SearchOptions, type SearchResponse, type Tool, Tools };