npm - @ctxprotocol/sdk - Versions diffs - 0.5.5 → 0.6.0 - Mend

@ctxprotocol/sdk 0.5.5 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/README.md CHANGED Viewed

@@ -9,23 +9,41 @@ Context Protocol is **npm for AI capabilities**. Just as you install packages to
 [![npm version](https://img.shields.io/npm/v/@ctxprotocol/sdk.svg)](https://www.npmjs.com/package/@ctxprotocol/sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+---
+### 💰 $10,000 Developer Grant Program
+We're funding the initial supply of MCP Tools for the Context Marketplace. **Become a Data Broker.**
+- **🛠️ Build:** Create an MCP Server using this SDK (Solana data, Trading tools, Scrapers, etc.)
+- **📦 List:** Publish it to the Context Registry
+- **💵 Earn:** Get a **$250–$1,000 Grant** + earn USDC every time an agent queries your tool
+👉 [**View Open Bounties & Apply Here**](https://docs.ctxprotocol.com/grants)
+---
 ## Why use Context?
 - **🔌 One Interface, Everything:** Stop integrating APIs one by one. Use a single SDK to access any tool in the marketplace.
 - **🧠 Zero-Ops:** We're a gateway to the best MCP tools. Just send the JSON and get the result.
 - **⚡️ 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.
+- **💸 Pay-Per-Response:** The $500/year subscription? Now $0.01/response. No monthly fees, just results.
 ## 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 |
+| **Tool Contributor (Data Broker)** | `@modelcontextprotocol/sdk` + `@ctxprotocol/sdk` — Standard MCP server + security middleware |
-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.
+**For AI Agent Developers:** Use this SDK to search the marketplace, execute tools, and handle micro-payments.
+**For Tool Contributors:** You need **both** SDKs:
+- `@modelcontextprotocol/sdk` — Build your MCP server (tools, schemas, handlers)
+- `@ctxprotocol/sdk` — Secure your endpoint with `createContextMiddleware()` and receive injected user portfolio data
+See [Building MCP Servers](#building-mcp-servers-tool-contributors) and [Securing Your Tool](#-securing-your-tool) for the complete pattern.
 ## Installation
@@ -265,8 +283,6 @@ const result = await client.tools.execute({
 ```typescript
 import {
-  // Constant for declaring context requirements
-  CONTEXT_REQUIREMENTS_KEY,
   // Auth utilities for tool contributors
   verifyContextRequest,
   isProtectedMcpMethod,
@@ -330,21 +346,27 @@ interface ExecutionResult<T = unknown> {
 ### Context Requirement Types (MCP Server Contributors)
 ```typescript
-import { CONTEXT_REQUIREMENTS_KEY, type ContextRequirementType } from "@ctxprotocol/sdk";
+import type { ContextRequirementType } from "@ctxprotocol/sdk";
 /** Context types supported by the marketplace */
 type ContextRequirementType = "polymarket" | "hyperliquid" | "wallet";
-/** JSON Schema extension key for declaring context requirements */
-const CONTEXT_REQUIREMENTS_KEY = "x-context-requirements";
-// Usage in inputSchema:
-inputSchema: {
-  type: "object",
-  [CONTEXT_REQUIREMENTS_KEY]: ["hyperliquid"] as ContextRequirementType[],
-  properties: { portfolio: { type: "object" } },
-  required: ["portfolio"]
-}
+// Usage: Add _meta.contextRequirements to your tool definition
+const TOOLS = [{
+  name: "analyze_my_positions",
+  description: "...",
+  // ⭐ Declare context requirements in _meta (MCP spec)
+  _meta: {
+    contextRequirements: ["wallet"] as ContextRequirementType[],
+  },
+  inputSchema: {
+    type: "object",
+    properties: { wallet: { type: "object" } },
+    required: ["wallet"]
+  },
+}];
 ```
 ## Error Handling
@@ -431,17 +453,22 @@ app.post("/mcp", (req, res) => {
 | **Free Tools ($0.00)** | Optional | Perfect for distribution and adoption |
 | **Paid Tools ($0.01+)** | **Mandatory** | We cannot route payments to insecure endpoints |
-### Security Model
+### MCP Security Model
-The SDK implements a **selective authentication** model:
+The SDK implements a **selective authentication** model — discovery is open, execution is protected:
-| MCP Method | Auth Required | Reason |
-|------------|---------------|--------|
-| `tools/list` | ❌ No | Discovery - just returns tool schemas |
-| `tools/call` | ✅ Yes | Execution - runs code, may cost money |
+| MCP Method | Auth Required | Why |
+|------------|---------------|-----|
 | `initialize` | ❌ No | Session setup |
+| `tools/list` | ❌ No | Discovery - agents need to see your schemas |
 | `resources/list` | ❌ No | Discovery |
 | `prompts/list` | ❌ No | Discovery |
+| `tools/call` | ✅ **Yes** | **Execution - costs money, runs your code** |
+**What this means in practice:**
+- ✅ `https://your-mcp.com/mcp` + `initialize` → Works without auth
+- ✅ `https://your-mcp.com/mcp` + `tools/list` → Works without auth
+- ❌ `https://your-mcp.com/mcp` + `tools/call` → **Requires Context Protocol JWT**
 This matches standard API patterns (OpenAPI schemas are public, GraphQL introspection is open).
@@ -505,48 +532,86 @@ Want to earn money by contributing tools to the Context marketplace? Build a sta
 | `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. |
-### Context Injection (Portfolio Analysis Tools)
+### Context Injection (Personalized Tools)
-Building tools that analyze user portfolios? Context automatically injects user portfolio data into your tools—no authentication required.
+Building tools that analyze user data? Context automatically injects user context into your tools no authentication required.
-**📖 Read the full guide: [Context Injection Architecture](./docs/context-injection.md)**
-Key benefits:
-- **No Auth Required** — User data is injected automatically from their linked wallets
-- **Type-Safe** — Use SDK types like `PolymarketContext`, `HyperliquidContext`
+**How it works:**
+1. User connects their wallet in the Context app (we start with blockchain user data, but we're open to other client-side personal data types in the future)
+2. When your tool is selected, the platform reads `_meta.contextRequirements` from your tool definition
+3. Platform fetches the user's data (wallet balances, protocol positions, etc.)
+4. Data is injected as an argument to your tool
+**Key benefits:**
+- **No Auth Required** — User data is injected automatically from connected wallets
+- **Type-Safe** — Use SDK types like `WalletContext`, `PolymarketContext`, `HyperliquidContext`
 - **Focus on Analysis** — You receive structured data, you provide insights
+**What gets injected:**
+```typescript
+// For hyperliquid context requirement
+interface HyperliquidContext {
+  walletAddress: string;
+  perpPositions: HyperliquidPerpPosition[];
+  spotBalances: HyperliquidSpotBalance[];
+  openOrders: HyperliquidOrder[];
+  accountSummary: HyperliquidAccountSummary;
+  fetchedAt: string;
+}
+// For polymarket context requirement
+interface PolymarketContext {
+  walletAddress: string;
+  positions: PolymarketPosition[];
+  openOrders: PolymarketOrder[];
+  totalValue?: number;
+  fetchedAt: string;
+}
+// For wallet context requirement
+interface WalletContext {
+  address: string;
+  chainId: number;
+  balances: TokenBalance[];
+  fetchedAt: string;
+}
+```
 ### Context Requirements Declaration
-If your tool needs user portfolio data, you **MUST** declare this using the `x-context-requirements` JSON Schema extension inside `inputSchema`:
+If your tool needs user portfolio data, you **MUST** declare this using `_meta.contextRequirements` on the tool definition:
 ```typescript
-import { CONTEXT_REQUIREMENTS_KEY, type ContextRequirementType } from "@ctxprotocol/sdk";
+import type { ContextRequirementType } from "@ctxprotocol/sdk";
 const TOOLS = [{
   name: "analyze_my_positions",
   description: "Analyze your positions with personalized insights",
+  // ⭐ REQUIRED: Context requirements in _meta (MCP spec for arbitrary metadata)
+  // The Context platform reads this to inject user data
+  _meta: {
+    contextRequirements: ["wallet"] as ContextRequirementType[],
+  },
   inputSchema: {
     type: "object",
-    // ⭐ REQUIRED: Context requirements embedded in inputSchema
-    [CONTEXT_REQUIREMENTS_KEY]: ["hyperliquid"] as ContextRequirementType[],
-    // Or use the string directly: "x-context-requirements": ["hyperliquid"]
     properties: {
-      portfolio: {
+      wallet: {
         type: "object",
-        description: "Portfolio context (injected by platform)",
+        description: "Wallet context (injected by platform)",
       },
     },
-    required: ["portfolio"],
+    required: ["wallet"],
   },
   outputSchema: { /* ... */ },
 }];
 ```
-**Why `x-context-requirements` in inputSchema (not a top-level field)?**
+**Why `_meta` at the tool level?**
-The MCP protocol only transmits standard fields (`name`, `description`, `inputSchema`, `outputSchema`). Custom top-level fields like `requirements` get **stripped** by the MCP SDK during `listTools()` transport. JSON Schema allows `x-` prefixed extension properties, and `inputSchema` is preserved through transport.
+The `_meta` field is part of the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-definition) for arbitrary tool metadata. The Context platform reads `_meta.contextRequirements` to determine what user data to inject. This is preserved through MCP transport because it's a standard field.
 **Available context types:**
@@ -556,12 +621,6 @@ The MCP protocol only transmits standard fields (`name`, `description`, `inputSc
 | `"polymarket"` | Polymarket prediction markets | `PolymarketContext` |
 | `"wallet"` | Generic EVM wallet | `WalletContext` |
-**How it works:**
-1. User links their wallet in Context app settings
-2. When your tool is selected, platform reads `inputSchema["x-context-requirements"]`
-3. Platform fetches user's portfolio data from protocol APIs
-4. Data is injected as the `portfolio` argument to your tool
 ### Example: Standard MCP Server
 Build your server with the standard `@modelcontextprotocol/sdk`:
@@ -619,6 +678,22 @@ 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)
+### Execution Timeout & Product Design
+⚠️ **Important**: MCP tool execution has a **~60 second timeout** (enforced at the platform/client level, not by MCP itself). This is intentional—it encourages building pre-computed insight products rather than raw data access.
+**Best practice**: Run heavy queries offline (via cron jobs), store results in your database, and serve instant results via MCP. This is how Bloomberg, Nansen, and Arkham work—they don't give raw SQL access, they serve curated insights.
+```typescript
+// ❌ BAD: Raw access (timeout-prone, no moat)
+{ name: "run_sql", description: "Run any SQL against blockchain data" }
+// ✅ GOOD: Pre-computed product (instant, defensible)
+{ name: "get_smart_money_wallets", description: "Top 100 wallets that timed market tops" }
+```
+See the [full documentation](https://docs.ctxprotocol.com/guides/build-tools#execution-limits--product-design) for detailed guidance.
 ### 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.
@@ -643,6 +718,7 @@ When you execute a tool:
 | Document | Description |
 |----------|-------------|
+| [MCP Builder Template](./docs/mcp-builder-template.md) | **Start here!** AI-powered template for designing MCP servers with Cursor. Generates discovery questions and tool schemas automatically. |
 | [Context Injection Guide](./docs/context-injection.md) | Architecture guide for building portfolio analysis tools with automatic user data injection |
 | [Polymarket Example](./examples/server/polymarket-contributor) | Complete MCP server for Polymarket intelligence |
 | [Hyperliquid Example](./examples/server/hyperliquid-contributor) | Complete MCP server for Hyperliquid analytics |

package/dist/client/index.cjs CHANGED Viewed

@@ -1,13 +1,14 @@
 'use strict';
 // src/client/types.ts
-var ContextError = class extends Error {
+var ContextError = class _ContextError extends Error {
   constructor(message, code, statusCode, helpUrl) {
     super(message);
     this.code = code;
     this.statusCode = statusCode;
     this.helpUrl = helpUrl;
     this.name = "ContextError";
+    Object.setPrototypeOf(this, _ContextError.prototype);
   }
 };
@@ -40,7 +41,7 @@ var Discovery = class {
     }
     const queryString = params.toString();
     const endpoint = `/api/v1/tools/search${queryString ? `?${queryString}` : ""}`;
-    const response = await this.client.fetch(endpoint);
+    const response = await this.client._fetch(endpoint);
     return response.tools;
   }
   /**
@@ -97,7 +98,7 @@ var Tools = class {
    */
   async execute(options) {
     const { toolId, toolName, args } = options;
-    const response = await this.client.fetch(
+    const response = await this.client._fetch(
       "/api/v1/tools/execute",
       {
         method: "POST",
@@ -108,7 +109,8 @@ var Tools = class {
       throw new ContextError(
         response.error,
         response.code,
-        400,
+        void 0,
+        // Don't hardcode - this was a 200 OK with error body
         response.helpUrl
       );
     }
@@ -127,6 +129,7 @@ var Tools = class {
 var ContextClient = class {
   apiKey;
   baseUrl;
+  _closed = false;
   /**
    * Discovery resource for searching tools
    */
@@ -151,38 +154,89 @@ var ContextClient = class {
     this.discovery = new Discovery(this);
     this.tools = new Tools(this);
   }
+  /**
+   * Close the client and clean up resources.
+   * After calling close(), any in-flight requests may be aborted.
+   */
+  close() {
+    this._closed = true;
+  }
   /**
    * Internal method for making authenticated HTTP requests
-   * All requests include the Authorization header with the API key
+   * Includes timeout (30s) and retry with exponential backoff for transient errors
    *
    * @internal
    */
-  async fetch(endpoint, options = {}) {
+  async _fetch(endpoint, options = {}) {
+    if (this._closed) {
+      throw new ContextError("Client has been closed");
+    }
     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;
+    const maxRetries = 3;
+    const timeoutMs = 3e4;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
       try {
-        const errorBody = await response.json();
-        if (errorBody.error) {
-          errorMessage = errorBody.error;
-          errorCode = errorBody.code;
-          helpUrl = errorBody.helpUrl;
+        const response = await fetch(url, {
+          ...options,
+          signal: controller.signal,
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
+            ...options.headers
+          }
+        });
+        clearTimeout(timeout);
+        if (!response.ok) {
+          if (response.status >= 500 && attempt < maxRetries) {
+            const delay = Math.min(1e3 * 2 ** attempt, 1e4);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            continue;
+          }
+          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();
+      } catch (error) {
+        clearTimeout(timeout);
+        if (error instanceof ContextError) {
+          throw error;
+        }
+        lastError = error instanceof Error ? error : new Error(String(error));
+        const isRetryable = lastError.name === "AbortError" || lastError.message.includes("fetch failed") || lastError.message.includes("ECONNRESET") || lastError.message.includes("ETIMEDOUT");
+        if (isRetryable && attempt < maxRetries) {
+          const delay = Math.min(1e3 * 2 ** attempt, 1e4);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          continue;
+        }
+        if (lastError.name === "AbortError") {
+          throw new ContextError(
+            `Request timed out after ${timeoutMs / 1e3}s`,
+            void 0,
+            408
+          );
         }
-      } catch {
+        throw new ContextError(
+          lastError.message,
+          void 0,
+          void 0
+        );
       }
-      throw new ContextError(errorMessage, errorCode, response.status, helpUrl);
     }
-    return response.json();
+    throw lastError ?? new ContextError("Request failed after retries");
   }
 };

package/dist/client/index.cjs.map CHANGED Viewed

	@@ -1 +1 @@
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"]}
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 /* Tool type - currently always \"mcp\" /\n kind?: string;\n\n /\n Available MCP tool methods\n * Use items from this array as `toolName` when executing\n /\n mcpTools?: McpTool[];\n\n // Trust metrics (Level 2 - Reputation Ledger)\n /* Total number of queries processed /\n totalQueries?: number;\n\n /* Success rate percentage (0-100) /\n successRate?: string;\n\n /* Uptime percentage (0-100) /\n uptimePercent?: string;\n\n /* Total USDC staked by the developer /\n totalStaked?: string;\n\n /* Whether the tool has \"Proven\" status (100+ queries, >95% success, >98% uptime) /\n isProven?: boolean;\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 Object.setPrototypeOf(this, ContextError.prototype);\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 undefined, // Don't hardcode - this was a 200 OK with error body\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 private _closed = false;\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 Close the client and clean up resources.\n * After calling close(), any in-flight requests may be aborted.\n /\n close(): void {\n this._closed = true;\n }\n\n /\n Internal method for making authenticated HTTP requests\n * Includes timeout (30s) and retry with exponential backoff for transient errors\n \n @internal\n /\n async _fetch<T>(endpoint: string, options: RequestInit = {}): Promise<T> {\n if (this._closed) {\n throw new ContextError(\"Client has been closed\");\n }\n\n const url = `${this.baseUrl}${endpoint}`;\n const maxRetries = 3;\n const timeoutMs = 30_000;\n\n let lastError: Error \| undefined;\n\n for (let attempt = 0; attempt <= maxRetries; attempt++) {\n const controller = new AbortController();\n const timeout = setTimeout(() => controller.abort(), timeoutMs);\n\n try {\n const response = await fetch(url, {\n ...options,\n signal: controller.signal,\n headers: {\n \"Content-Type\": \"application/json\",\n Authorization: `Bearer ${this.apiKey}`,\n ...options.headers,\n },\n });\n\n clearTimeout(timeout);\n\n if (!response.ok) {\n // Retry on 5xx server errors\n if (response.status >= 500 && attempt < maxRetries) {\n const delay = Math.min(1000 2 ** attempt, 10_000);\n await new Promise((resolve) => setTimeout(resolve, delay));\n continue;\n }\n\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 } catch (error) {\n clearTimeout(timeout);\n\n if (error instanceof ContextError) {\n throw error;\n }\n\n lastError = error instanceof Error ? error : new Error(String(error));\n\n // Retry on network errors and timeouts\n const isRetryable =\n lastError.name === \"AbortError\" \|\|\n lastError.message.includes(\"fetch failed\") \|\|\n lastError.message.includes(\"ECONNRESET\") \|\|\n lastError.message.includes(\"ETIMEDOUT\");\n\n if (isRetryable && attempt < maxRetries) {\n const delay = Math.min(1000 * 2 ** attempt, 10_000);\n await new Promise((resolve) => setTimeout(resolve, delay));\n continue;\n }\n\n if (lastError.name === \"AbortError\") {\n throw new ContextError(\n `Request timed out after ${timeoutMs / 1000}s`,\n undefined,\n 408\n );\n }\n\n throw new ContextError(\n lastError.message,\n undefined,\n undefined\n );\n }\n }\n\n throw lastError ?? new ContextError(\"Request failed after retries\");\n }\n}\n"]}

package/dist/client/index.d.cts CHANGED Viewed

@@ -48,15 +48,23 @@ interface Tool {
     category?: string;
     /** Whether the tool is verified by Context Protocol */
     isVerified?: boolean;
+    /** Tool type - currently always "mcp" */
+    kind?: string;
     /**
      * Available MCP tool methods
      * Use items from this array as `toolName` when executing
      */
     mcpTools?: McpTool[];
-    /** Creation timestamp */
-    createdAt?: string;
-    /** Last update timestamp */
-    updatedAt?: string;
+    /** Total number of queries processed */
+    totalQueries?: number;
+    /** Success rate percentage (0-100) */
+    successRate?: string;
+    /** Uptime percentage (0-100) */
+    uptimePercent?: string;
+    /** Total USDC staked by the developer */
+    totalStaked?: string;
+    /** Whether the tool has "Proven" status (100+ queries, >95% success, >98% uptime) */
+    isProven?: boolean;
 }
 /**
  * Response from the tools search endpoint
@@ -249,6 +257,7 @@ declare class Tools {
 declare class ContextClient {
     private readonly apiKey;
     private readonly baseUrl;
+    private _closed;
     /**
      * Discovery resource for searching tools
      */
@@ -265,13 +274,18 @@ declare class ContextClient {
      * @param options.baseUrl - Optional base URL override (defaults to https://ctxprotocol.com)
      */
     constructor(options: ContextClientOptions);
+    /**
+     * Close the client and clean up resources.
+     * After calling close(), any in-flight requests may be aborted.
+     */
+    close(): void;
     /**
      * Internal method for making authenticated HTTP requests
-     * All requests include the Authorization header with the API key
+     * Includes timeout (30s) and retry with exponential backoff for transient errors
      *
      * @internal
      */
-    fetch<T>(endpoint: string, options?: RequestInit): Promise<T>;
+    _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 };

package/dist/client/index.d.ts CHANGED Viewed

@@ -48,15 +48,23 @@ interface Tool {
     category?: string;
     /** Whether the tool is verified by Context Protocol */
     isVerified?: boolean;
+    /** Tool type - currently always "mcp" */
+    kind?: string;
     /**
      * Available MCP tool methods
      * Use items from this array as `toolName` when executing
      */
     mcpTools?: McpTool[];
-    /** Creation timestamp */
-    createdAt?: string;
-    /** Last update timestamp */
-    updatedAt?: string;
+    /** Total number of queries processed */
+    totalQueries?: number;
+    /** Success rate percentage (0-100) */
+    successRate?: string;
+    /** Uptime percentage (0-100) */
+    uptimePercent?: string;
+    /** Total USDC staked by the developer */
+    totalStaked?: string;
+    /** Whether the tool has "Proven" status (100+ queries, >95% success, >98% uptime) */
+    isProven?: boolean;
 }
 /**
  * Response from the tools search endpoint
@@ -249,6 +257,7 @@ declare class Tools {
 declare class ContextClient {
     private readonly apiKey;
     private readonly baseUrl;
+    private _closed;
     /**
      * Discovery resource for searching tools
      */
@@ -265,13 +274,18 @@ declare class ContextClient {
      * @param options.baseUrl - Optional base URL override (defaults to https://ctxprotocol.com)
      */
     constructor(options: ContextClientOptions);
+    /**
+     * Close the client and clean up resources.
+     * After calling close(), any in-flight requests may be aborted.
+     */
+    close(): void;
     /**
      * Internal method for making authenticated HTTP requests
-     * All requests include the Authorization header with the API key
+     * Includes timeout (30s) and retry with exponential backoff for transient errors
      *
      * @internal
      */
-    fetch<T>(endpoint: string, options?: RequestInit): Promise<T>;
+    _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 };