@ctxprotocol/sdk 0.5.1 → 0.5.2

package/README.md

@@ -267,6 +267,8 @@ const result = await client.tools.execute({
 import {
   // Constant for declaring context requirements
   CONTEXT_REQUIREMENTS_KEY,
+  // Auth utilities for tool contributors
+  verifyContextRequest,
 } from "@ctxprotocol/sdk";
 
 import type {
@@ -277,6 +279,8 @@ import type {
   ExecuteOptions,
   ExecutionResult,
   ContextErrorCode,
+  // Auth types (for MCP server contributors)
+  VerifyRequestOptions,
   // Context types (for MCP server contributors receiving injected data)
   ContextRequirementType,
   HyperliquidContext,
@@ -385,6 +389,99 @@ try {
 
 ---
 
+## 🔒 Securing Your Tool
+
+If you're building an MCP server (tool contributor), you should verify that incoming requests are legitimate and originate from the Context Protocol Platform.
+
+### How It Works
+
+The Context Platform signs all requests to your tool using **RS256** (RSA-SHA256) asymmetric cryptography. Each request includes an `Authorization: Bearer <jwt>` header containing a signed JWT. Your server should verify this signature using the Platform's public key.
+
+### Using `verifyContextRequest`
+
+The SDK provides a utility function to verify incoming requests:
+
+```typescript
+import { verifyContextRequest, ContextError } from "@ctxprotocol/sdk";
+```
+
+#### Express.js Example
+
+```typescript
+import express from "express";
+import { verifyContextRequest, ContextError } from "@ctxprotocol/sdk";
+
+const app = express();
+
+app.post("/api/tool", async (req, res) => {
+  try {
+    // Verify the request came from Context Platform
+    const payload = await verifyContextRequest({
+      authorizationHeader: req.headers.authorization,
+    });
+
+    // Request is legitimate - payload contains the decoded JWT claims
+    console.log("Verified request from:", payload.sub);
+
+    // Process your tool logic here...
+    res.json({ result: "success" });
+  } catch (err) {
+    if (err instanceof ContextError) {
+      return res.status(err.statusCode || 401).json({ error: err.message });
+    }
+    return res.status(500).json({ error: "Internal server error" });
+  }
+});
+```
+
+#### Next.js API Route Example
+
+```typescript
+import { verifyContextRequest, ContextError } from "@ctxprotocol/sdk";
+import { NextRequest, NextResponse } from "next/server";
+
+export async function POST(req: NextRequest) {
+  try {
+    await verifyContextRequest({
+      authorizationHeader: req.headers.get("authorization") ?? undefined,
+    });
+
+    // Request is verified - process tool logic
+    return NextResponse.json({ result: "success" });
+  } catch (err) {
+    if (err instanceof ContextError) {
+      return NextResponse.json(
+        { error: err.message },
+        { status: err.statusCode || 401 }
+      );
+    }
+    return NextResponse.json(
+      { error: "Internal server error" },
+      { status: 500 }
+    );
+  }
+}
+```
+
+### Options
+
+| Option                | Type     | Required | Description                                           |
+| --------------------- | -------- | -------- | ----------------------------------------------------- |
+| `authorizationHeader` | `string` | Yes      | The full Authorization header (e.g., `"Bearer eyJ..."`) |
+| `audience`            | `string` | No       | Expected audience claim for stricter validation       |
+
+### JWT Claims
+
+The verified JWT payload includes standard claims:
+
+- `iss` - Issuer (`https://ctxprotocol.com`)
+- `sub` - Subject (user or request identifier)
+- `aud` - Audience (your tool URL, if specified)
+- `exp` - Expiration time
+- `iat` - Issued at time
+
+---
+
 ## 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):

package/dist/index.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+var jose = require('jose');
+
 // src/client/types.ts
 var ContextError = class extends Error {
   constructor(message, code, statusCode, helpUrl) {
@@ -188,11 +190,40 @@ var ContextClient = class {
 
 // src/context/index.ts
 var CONTEXT_REQUIREMENTS_KEY = "x-context-requirements";
+var CONTEXT_PLATFORM_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
+-----END PUBLIC KEY-----`;
+async function verifyContextRequest(options) {
+  const { authorizationHeader, audience } = options;
+  if (!authorizationHeader || !authorizationHeader.startsWith("Bearer ")) {
+    throw new ContextError(
+      "Missing or invalid Authorization header",
+      "unauthorized",
+      401
+    );
+  }
+  const token = authorizationHeader.split(" ")[1];
+  try {
+    const publicKey = await jose.importSPKI(CONTEXT_PLATFORM_PUBLIC_KEY_PEM, "RS256");
+    const { payload } = await jose.jwtVerify(token, publicKey, {
+      issuer: "https://ctxprotocol.com",
+      audience
+    });
+    return payload;
+  } catch (error) {
+    throw new ContextError(
+      "Invalid Context Protocol signature",
+      "unauthorized",
+      401
+    );
+  }
+}
 
 exports.CONTEXT_REQUIREMENTS_KEY = CONTEXT_REQUIREMENTS_KEY;
 exports.ContextClient = ContextClient;
 exports.ContextError = ContextError;
 exports.Discovery = Discovery;
 exports.Tools = Tools;
+exports.verifyContextRequest = verifyContextRequest;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client/types.ts","../src/client/resources/discovery.ts","../src/client/resources/tools.ts","../src/client/client.ts","../src/context/index.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","/**\n * Context types for portfolio and protocol data injection.\n *\n * These types allow MCP tools to receive personalized user context\n * (wallet addresses, positions, balances) for analysis.\n *\n * =============================================================================\n * DECLARING CONTEXT REQUIREMENTS\n * =============================================================================\n *\n * Since the MCP protocol only transmits standard fields (name, description,\n * inputSchema, outputSchema), context requirements MUST be embedded in the\n * inputSchema using the \"x-context-requirements\" JSON Schema extension.\n *\n * @example\n * ```typescript\n * import { CONTEXT_REQUIREMENTS_KEY, type ContextRequirementType } from \"@ctxprotocol/sdk\";\n * import type { HyperliquidContext } from \"@ctxprotocol/sdk\";\n *\n * const tool = {\n *   name: \"analyze_my_positions\",\n *   inputSchema: {\n *     type: \"object\",\n *     [CONTEXT_REQUIREMENTS_KEY]: [\"hyperliquid\"] as ContextRequirementType[],\n *     properties: {\n *       portfolio: { type: \"object\" }\n *     },\n *     required: [\"portfolio\"]\n *   }\n * };\n *\n * // Your handler receives the injected context:\n * function handleAnalyzeMyPositions(args: { portfolio: HyperliquidContext }) {\n *   const { perpPositions, accountSummary } = args.portfolio;\n *   // ... analyze and return insights\n * }\n * ```\n *\n * @packageDocumentation\n */\n\n// Wallet context types\nexport * from \"./wallet.js\";\n\n// Protocol-specific context types\nexport * from \"./polymarket.js\";\nexport * from \"./hyperliquid.js\";\n\n// Re-import for composite type\nimport type { WalletContext, ERC20Context } from \"./wallet.js\";\nimport type { PolymarketContext } from \"./polymarket.js\";\nimport type { HyperliquidContext } from \"./hyperliquid.js\";\n\n// ============================================================================\n// CONTEXT REQUIREMENTS\n//\n// MCP tools that need user portfolio data MUST declare this in inputSchema.\n// The MCP protocol only transmits standard fields (name, description,\n// inputSchema, outputSchema). Custom fields get stripped by the MCP SDK.\n// ============================================================================\n\n/**\n * JSON Schema extension key for declaring context requirements.\n *\n * WHY THIS APPROACH?\n * - MCP protocol only transmits: name, description, inputSchema, outputSchema\n * - Custom fields like `requirements` get stripped by MCP SDK during transport\n * - JSON Schema allows custom \"x-\" prefixed extension properties\n * - inputSchema is preserved end-to-end through MCP transport\n *\n * @example\n * ```typescript\n * import { CONTEXT_REQUIREMENTS_KEY } from \"@ctxprotocol/sdk\";\n *\n * const tool = {\n *   name: \"analyze_my_positions\",\n *   inputSchema: {\n *     type: \"object\",\n *     [CONTEXT_REQUIREMENTS_KEY]: [\"hyperliquid\"],\n *     properties: { portfolio: { type: \"object\" } },\n *     required: [\"portfolio\"]\n *   }\n * };\n * ```\n */\nexport const CONTEXT_REQUIREMENTS_KEY = \"x-context-requirements\" as const;\n\n/**\n * Context requirement types supported by the Context marketplace.\n * Maps to protocol-specific context builders on the platform.\n *\n * @example\n * ```typescript\n * inputSchema: {\n *   type: \"object\",\n *   \"x-context-requirements\": [\"hyperliquid\"] as ContextRequirementType[],\n *   properties: { portfolio: { type: \"object\" } },\n *   required: [\"portfolio\"]\n * }\n * ```\n */\nexport type ContextRequirementType = \"polymarket\" | \"hyperliquid\" | \"wallet\";\n\n/**\n * @deprecated The `requirements` field at tool level gets stripped by MCP SDK.\n * Use `x-context-requirements` inside `inputSchema` instead.\n *\n * @example\n * ```typescript\n * // ❌ OLD (doesn't work - stripped by MCP SDK)\n * { requirements: { context: [\"hyperliquid\"] } }\n *\n * // ✅ NEW (works - preserved through MCP transport)\n * { inputSchema: { \"x-context-requirements\": [\"hyperliquid\"], ... } }\n * ```\n */\nexport interface ToolRequirements {\n  /**\n   * @deprecated Use `x-context-requirements` in inputSchema instead.\n   */\n  context?: ContextRequirementType[];\n}\n\n/**\n * Composite context for tools that need multiple data sources.\n *\n * This is the unified structure that can be passed to MCP tools\n * to provide comprehensive user context.\n */\nexport interface UserContext {\n  /** Base wallet information */\n  wallet?: WalletContext;\n  /** ERC20 token holdings */\n  erc20?: ERC20Context;\n  /** Polymarket positions and orders */\n  polymarket?: PolymarketContext;\n  /** Hyperliquid perpetual positions and account data */\n  hyperliquid?: HyperliquidContext;\n  // Future protocols:\n  // aave?: AaveContext;\n}\n"]}
+{"version":3,"sources":["../src/client/types.ts","../src/client/resources/discovery.ts","../src/client/resources/tools.ts","../src/client/client.ts","../src/context/index.ts","../src/auth/index.ts"],"names":["importSPKI","jwtVerify"],"mappings":";;;;;AAsLO,IAAM,YAAA,GAAN,cAA2B,KAAA,CAAM;AAAA,EACtC,WAAA,CACE,OAAA,EACgB,IAAA,EACA,UAAA,EACA,OAAA,EAChB;AACA,IAAA,KAAA,CAAM,OAAO,CAAA;AAJG,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AACA,IAAA,IAAA,CAAA,UAAA,GAAA,UAAA;AACA,IAAA,IAAA,CAAA,OAAA,GAAA,OAAA;AAGhB,IAAA,IAAA,CAAK,IAAA,GAAO,cAAA;AAAA,EACd;AACF;;;AC1LO,IAAM,YAAN,MAAgB;AAAA,EACrB,YAAoB,MAAA,EAAuB;AAAvB,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAAA,EAAwB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAgB5C,MAAM,MAAA,CAAO,KAAA,EAAe,KAAA,EAAiC;AAC3D,IAAA,MAAM,MAAA,GAAS,IAAI,eAAA,EAAgB;AAEnC,IAAA,IAAI,KAAA,EAAO;AACT,MAAA,MAAA,CAAO,GAAA,CAAI,KAAK,KAAK,CAAA;AAAA,IACvB;AAEA,IAAA,IAAI,UAAU,MAAA,EAAW;AACvB,MAAA,MAAA,CAAO,GAAA,CAAI,OAAA,EAAS,MAAA,CAAO,KAAK,CAAC,CAAA;AAAA,IACnC;AAEA,IAAA,MAAM,WAAA,GAAc,OAAO,QAAA,EAAS;AACpC,IAAA,MAAM,WAAW,CAAA,oBAAA,EAAuB,WAAA,GAAc,CAAA,CAAA,EAAI,WAAW,KAAK,EAAE,CAAA,CAAA;AAE5E,IAAA,MAAM,QAAA,GAAW,MAAM,IAAA,CAAK,MAAA,CAAO,MAAsB,QAAQ,CAAA;AAEjE,IAAA,OAAO,QAAA,CAAS,KAAA;AAAA,EAClB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,MAAM,YAAY,KAAA,EAAiC;AACjD,IAAA,OAAO,IAAA,CAAK,MAAA,CAAO,EAAA,EAAI,KAAK,CAAA;AAAA,EAC9B;AACF;;;AC7CO,IAAM,QAAN,MAAY;AAAA,EACjB,YAAoB,MAAA,EAAuB;AAAvB,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAAA,EAAwB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiC5C,MAAM,QAAqB,OAAA,EAAsD;AAC/E,IAAA,MAAM,EAAE,MAAA,EAAQ,QAAA,EAAU,IAAA,EAAK,GAAI,OAAA;AAEnC,IAAA,MAAM,QAAA,GAAW,MAAM,IAAA,CAAK,MAAA,CAAO,KAAA;AAAA,MACjC,uBAAA;AAAA,MACA;AAAA,QACE,MAAA,EAAQ,MAAA;AAAA,QACR,MAAM,IAAA,CAAK,SAAA,CAAU,EAAE,MAAA,EAAQ,QAAA,EAAU,MAAM;AAAA;AACjD,KACF;AAGA,IAAA,IAAI,WAAW,QAAA,EAAU;AACvB,MAAA,MAAM,IAAI,YAAA;AAAA,QACR,QAAA,CAAS,KAAA;AAAA,QACT,QAAA,CAAS,IAAA;AAAA,QACT,GAAA;AAAA,QACA,QAAA,CAAS;AAAA,OACX;AAAA,IACF;AAGA,IAAA,IAAI,SAAS,OAAA,EAAS;AACpB,MAAA,OAAO;AAAA,QACL,QAAQ,QAAA,CAAS,MAAA;AAAA,QACjB,MAAM,QAAA,CAAS,IAAA;AAAA,QACf,YAAY,QAAA,CAAS;AAAA,OACvB;AAAA,IACF;AAGA,IAAA,MAAM,IAAI,aAAa,qCAAqC,CAAA;AAAA,EAC9D;AACF;;;ACjDO,IAAM,gBAAN,MAAoB;AAAA,EACR,MAAA;AAAA,EACA,OAAA;AAAA;AAAA;AAAA;AAAA,EAKD,SAAA;AAAA;AAAA;AAAA;AAAA,EAKA,KAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAShB,YAAY,OAAA,EAA+B;AACzC,IAAA,IAAI,CAAC,QAAQ,MAAA,EAAQ;AACnB,MAAA,MAAM,IAAI,aAAa,qBAAqB,CAAA;AAAA,IAC9C;AAEA,IAAA,IAAA,CAAK,SAAS,OAAA,CAAQ,MAAA;AACtB,IAAA,IAAA,CAAK,WAAW,OAAA,CAAQ,OAAA,IAAW,yBAAA,EAA2B,OAAA,CAAQ,OAAO,EAAE,CAAA;AAG/E,IAAA,IAAA,CAAK,SAAA,GAAY,IAAI,SAAA,CAAU,IAAI,CAAA;AACnC,IAAA,IAAA,CAAK,KAAA,GAAQ,IAAI,KAAA,CAAM,IAAI,CAAA;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,KAAA,CAAS,QAAA,EAAkB,OAAA,GAAuB,EAAC,EAAe;AACtE,IAAA,MAAM,GAAA,GAAM,CAAA,EAAG,IAAA,CAAK,OAAO,GAAG,QAAQ,CAAA,CAAA;AAEtC,IAAA,MAAM,QAAA,GAAW,MAAM,KAAA,CAAM,GAAA,EAAK;AAAA,MAChC,GAAG,OAAA;AAAA,MACH,OAAA,EAAS;AAAA,QACP,cAAA,EAAgB,kBAAA;AAAA,QAChB,aAAA,EAAe,CAAA,OAAA,EAAU,IAAA,CAAK,MAAM,CAAA,CAAA;AAAA,QACpC,GAAG,OAAA,CAAQ;AAAA;AACb,KACD,CAAA;AAED,IAAA,IAAI,CAAC,SAAS,EAAA,EAAI;AAChB,MAAA,IAAI,eAAe,CAAA,KAAA,EAAQ,QAAA,CAAS,MAAM,CAAA,EAAA,EAAK,SAAS,UAAU,CAAA,CAAA;AAClE,MAAA,IAAI,SAAA;AACJ,MAAA,IAAI,OAAA;AAEJ,MAAA,IAAI;AACF,QAAA,MAAM,SAAA,GAAY,MAAM,QAAA,CAAS,IAAA,EAAK;AACtC,QAAA,IAAI,UAAU,KAAA,EAAO;AACnB,UAAA,YAAA,GAAe,SAAA,CAAU,KAAA;AACzB,UAAA,SAAA,GAAY,SAAA,CAAU,IAAA;AACtB,UAAA,OAAA,GAAU,SAAA,CAAU,OAAA;AAAA,QACtB;AAAA,MACF,CAAA,CAAA,MAAQ;AAAA,MAER;AAEA,MAAA,MAAM,IAAI,YAAA,CAAa,YAAA,EAAc,SAAA,EAAW,QAAA,CAAS,QAAQ,OAAO,CAAA;AAAA,IAC1E;AAEA,IAAA,OAAO,SAAS,IAAA,EAAK;AAAA,EACvB;AACF;;;ACjBO,IAAM,wBAAA,GAA2B;AC9ExC,IAAM,+BAAA,GAAkC,CAAA;AAAA;AAAA,wBAAA,CAAA;AAkBxC,eAAsB,qBAAqB,OAAA,EAA+B;AACxE,EAAA,MAAM,EAAE,mBAAA,EAAqB,QAAA,EAAS,GAAI,OAAA;AAE1C,EAAA,IAAI,CAAC,mBAAA,IAAuB,CAAC,mBAAA,CAAoB,UAAA,CAAW,SAAS,CAAA,EAAG;AACtE,IAAA,MAAM,IAAI,YAAA;AAAA,MACR,yCAAA;AAAA,MACA,cAAA;AAAA,MACA;AAAA,KACF;AAAA,EACF;AAEA,EAAA,MAAM,KAAA,GAAQ,mBAAA,CAAoB,KAAA,CAAM,GAAG,EAAE,CAAC,CAAA;AAE9C,EAAA,IAAI;AACF,IAAA,MAAM,SAAA,GAAY,MAAMA,eAAA,CAAW,+BAAA,EAAiC,OAAO,CAAA;AAE3E,IAAA,MAAM,EAAE,OAAA,EAAQ,GAAI,MAAMC,cAAA,CAAU,OAAO,SAAA,EAAW;AAAA,MACpD,MAAA,EAAQ,yBAAA;AAAA,MACR;AAAA,KACD,CAAA;AAED,IAAA,OAAO,OAAA;AAAA,EACT,SAAS,KAAA,EAAO;AACd,IAAA,MAAM,IAAI,YAAA;AAAA,MACR,oCAAA;AAAA,MACA,cAAA;AAAA,MACA;AAAA,KACF;AAAA,EACF;AACF","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","/**\n * Context types for portfolio and protocol data injection.\n *\n * These types allow MCP tools to receive personalized user context\n * (wallet addresses, positions, balances) for analysis.\n *\n * =============================================================================\n * DECLARING CONTEXT REQUIREMENTS\n * =============================================================================\n *\n * Since the MCP protocol only transmits standard fields (name, description,\n * inputSchema, outputSchema), context requirements MUST be embedded in the\n * inputSchema using the \"x-context-requirements\" JSON Schema extension.\n *\n * @example\n * ```typescript\n * import { CONTEXT_REQUIREMENTS_KEY, type ContextRequirementType } from \"@ctxprotocol/sdk\";\n * import type { HyperliquidContext } from \"@ctxprotocol/sdk\";\n *\n * const tool = {\n *   name: \"analyze_my_positions\",\n *   inputSchema: {\n *     type: \"object\",\n *     [CONTEXT_REQUIREMENTS_KEY]: [\"hyperliquid\"] as ContextRequirementType[],\n *     properties: {\n *       portfolio: { type: \"object\" }\n *     },\n *     required: [\"portfolio\"]\n *   }\n * };\n *\n * // Your handler receives the injected context:\n * function handleAnalyzeMyPositions(args: { portfolio: HyperliquidContext }) {\n *   const { perpPositions, accountSummary } = args.portfolio;\n *   // ... analyze and return insights\n * }\n * ```\n *\n * @packageDocumentation\n */\n\n// Wallet context types\nexport * from \"./wallet.js\";\n\n// Protocol-specific context types\nexport * from \"./polymarket.js\";\nexport * from \"./hyperliquid.js\";\n\n// Re-import for composite type\nimport type { WalletContext, ERC20Context } from \"./wallet.js\";\nimport type { PolymarketContext } from \"./polymarket.js\";\nimport type { HyperliquidContext } from \"./hyperliquid.js\";\n\n// ============================================================================\n// CONTEXT REQUIREMENTS\n//\n// MCP tools that need user portfolio data MUST declare this in inputSchema.\n// The MCP protocol only transmits standard fields (name, description,\n// inputSchema, outputSchema). Custom fields get stripped by the MCP SDK.\n// ============================================================================\n\n/**\n * JSON Schema extension key for declaring context requirements.\n *\n * WHY THIS APPROACH?\n * - MCP protocol only transmits: name, description, inputSchema, outputSchema\n * - Custom fields like `requirements` get stripped by MCP SDK during transport\n * - JSON Schema allows custom \"x-\" prefixed extension properties\n * - inputSchema is preserved end-to-end through MCP transport\n *\n * @example\n * ```typescript\n * import { CONTEXT_REQUIREMENTS_KEY } from \"@ctxprotocol/sdk\";\n *\n * const tool = {\n *   name: \"analyze_my_positions\",\n *   inputSchema: {\n *     type: \"object\",\n *     [CONTEXT_REQUIREMENTS_KEY]: [\"hyperliquid\"],\n *     properties: { portfolio: { type: \"object\" } },\n *     required: [\"portfolio\"]\n *   }\n * };\n * ```\n */\nexport const CONTEXT_REQUIREMENTS_KEY = \"x-context-requirements\" as const;\n\n/**\n * Context requirement types supported by the Context marketplace.\n * Maps to protocol-specific context builders on the platform.\n *\n * @example\n * ```typescript\n * inputSchema: {\n *   type: \"object\",\n *   \"x-context-requirements\": [\"hyperliquid\"] as ContextRequirementType[],\n *   properties: { portfolio: { type: \"object\" } },\n *   required: [\"portfolio\"]\n * }\n * ```\n */\nexport type ContextRequirementType = \"polymarket\" | \"hyperliquid\" | \"wallet\";\n\n/**\n * @deprecated The `requirements` field at tool level gets stripped by MCP SDK.\n * Use `x-context-requirements` inside `inputSchema` instead.\n *\n * @example\n * ```typescript\n * // ❌ OLD (doesn't work - stripped by MCP SDK)\n * { requirements: { context: [\"hyperliquid\"] } }\n *\n * // ✅ NEW (works - preserved through MCP transport)\n * { inputSchema: { \"x-context-requirements\": [\"hyperliquid\"], ... } }\n * ```\n */\nexport interface ToolRequirements {\n  /**\n   * @deprecated Use `x-context-requirements` in inputSchema instead.\n   */\n  context?: ContextRequirementType[];\n}\n\n/**\n * Composite context for tools that need multiple data sources.\n *\n * This is the unified structure that can be passed to MCP tools\n * to provide comprehensive user context.\n */\nexport interface UserContext {\n  /** Base wallet information */\n  wallet?: WalletContext;\n  /** ERC20 token holdings */\n  erc20?: ERC20Context;\n  /** Polymarket positions and orders */\n  polymarket?: PolymarketContext;\n  /** Hyperliquid perpetual positions and account data */\n  hyperliquid?: HyperliquidContext;\n  // Future protocols:\n  // aave?: AaveContext;\n}\n","import { jwtVerify, importSPKI } from \"jose\";\nimport { ContextError } from \"../client/types.js\";\n\n// The Context Protocol Public Key\n// In a real scenario, this might be fetched from a well-known URL or passed in config.\n// For now, we hardcode the Official Platform Public Key.\n// TODO: REPLACE THIS WITH THE ACTUAL GENERATED PUBLIC KEY FROM THE PLATFORM SETUP\nconst CONTEXT_PLATFORM_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END PUBLIC KEY-----`;\n\nexport interface VerifyRequestOptions {\n  /** The full Authorization header string (e.g. \"Bearer eyJ...\") */\n  authorizationHeader?: string;\n  /** Expected Audience (your tool URL) for stricter validation */\n  audience?: string;\n}\n\n/**\n * Verifies that an incoming request originated from the Context Protocol Platform.\n *\n * @param options Contains the Authorization header\n * @returns The decoded payload if valid\n * @throws ContextError if invalid\n */\nexport async function verifyContextRequest(options: VerifyRequestOptions) {\n  const { authorizationHeader, audience } = options;\n\n  if (!authorizationHeader || !authorizationHeader.startsWith(\"Bearer \")) {\n    throw new ContextError(\n      \"Missing or invalid Authorization header\",\n      \"unauthorized\",\n      401\n    );\n  }\n\n  const token = authorizationHeader.split(\" \")[1];\n\n  try {\n    const publicKey = await importSPKI(CONTEXT_PLATFORM_PUBLIC_KEY_PEM, \"RS256\");\n\n    const { payload } = await jwtVerify(token, publicKey, {\n      issuer: \"https://ctxprotocol.com\",\n      audience: audience,\n    });\n\n    return payload;\n  } catch (error) {\n    throw new ContextError(\n      \"Invalid Context Protocol signature\",\n      \"unauthorized\",\n      401\n    );\n  }\n}\n"]}

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 export { ContextClient, ContextClientOptions, ContextError, ContextErrorCode, Discovery, ExecuteApiErrorResponse, ExecuteApiResponse, ExecuteApiSuccessResponse, ExecuteOptions, ExecutionResult, McpTool, SearchOptions, SearchResponse, Tool, Tools } from './client/index.cjs';
+import * as jose from 'jose';
 
 /**
  * Wallet context types for portfolio tracking.
@@ -334,4 +335,19 @@ interface UserContext {
     hyperliquid?: HyperliquidContext;
 }
 
-export { CONTEXT_REQUIREMENTS_KEY, type ContextRequirementType, type ERC20Context, type ERC20TokenBalance, type HyperliquidAccountSummary, type HyperliquidContext, type HyperliquidOrder, type HyperliquidPerpPosition, type HyperliquidSpotBalance, type PolymarketContext, type PolymarketOrder, type PolymarketPosition, type ToolRequirements, type UserContext, type WalletContext };
+interface VerifyRequestOptions {
+    /** The full Authorization header string (e.g. "Bearer eyJ...") */
+    authorizationHeader?: string;
+    /** Expected Audience (your tool URL) for stricter validation */
+    audience?: string;
+}
+/**
+ * Verifies that an incoming request originated from the Context Protocol Platform.
+ *
+ * @param options Contains the Authorization header
+ * @returns The decoded payload if valid
+ * @throws ContextError if invalid
+ */
+declare function verifyContextRequest(options: VerifyRequestOptions): Promise<jose.JWTPayload>;
+
+export { CONTEXT_REQUIREMENTS_KEY, type ContextRequirementType, type ERC20Context, type ERC20TokenBalance, type HyperliquidAccountSummary, type HyperliquidContext, type HyperliquidOrder, type HyperliquidPerpPosition, type HyperliquidSpotBalance, type PolymarketContext, type PolymarketOrder, type PolymarketPosition, type ToolRequirements, type UserContext, type VerifyRequestOptions, type WalletContext, verifyContextRequest };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { ContextClient, ContextClientOptions, ContextError, ContextErrorCode, Discovery, ExecuteApiErrorResponse, ExecuteApiResponse, ExecuteApiSuccessResponse, ExecuteOptions, ExecutionResult, McpTool, SearchOptions, SearchResponse, Tool, Tools } from './client/index.js';
+import * as jose from 'jose';
 
 /**
  * Wallet context types for portfolio tracking.
@@ -334,4 +335,19 @@ interface UserContext {
     hyperliquid?: HyperliquidContext;
 }
 
-export { CONTEXT_REQUIREMENTS_KEY, type ContextRequirementType, type ERC20Context, type ERC20TokenBalance, type HyperliquidAccountSummary, type HyperliquidContext, type HyperliquidOrder, type HyperliquidPerpPosition, type HyperliquidSpotBalance, type PolymarketContext, type PolymarketOrder, type PolymarketPosition, type ToolRequirements, type UserContext, type WalletContext };
+interface VerifyRequestOptions {
+    /** The full Authorization header string (e.g. "Bearer eyJ...") */
+    authorizationHeader?: string;
+    /** Expected Audience (your tool URL) for stricter validation */
+    audience?: string;
+}
+/**
+ * Verifies that an incoming request originated from the Context Protocol Platform.
+ *
+ * @param options Contains the Authorization header
+ * @returns The decoded payload if valid
+ * @throws ContextError if invalid
+ */
+declare function verifyContextRequest(options: VerifyRequestOptions): Promise<jose.JWTPayload>;
+
+export { CONTEXT_REQUIREMENTS_KEY, type ContextRequirementType, type ERC20Context, type ERC20TokenBalance, type HyperliquidAccountSummary, type HyperliquidContext, type HyperliquidOrder, type HyperliquidPerpPosition, type HyperliquidSpotBalance, type PolymarketContext, type PolymarketOrder, type PolymarketPosition, type ToolRequirements, type UserContext, type VerifyRequestOptions, type WalletContext, verifyContextRequest };

package/dist/index.js

@@ -1,3 +1,5 @@
+import { importSPKI, jwtVerify } from 'jose';
+
 // src/client/types.ts
 var ContextError = class extends Error {
   constructor(message, code, statusCode, helpUrl) {
@@ -186,7 +188,35 @@ var ContextClient = class {
 
 // src/context/index.ts
 var CONTEXT_REQUIREMENTS_KEY = "x-context-requirements";
+var CONTEXT_PLATFORM_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
+-----END PUBLIC KEY-----`;
+async function verifyContextRequest(options) {
+  const { authorizationHeader, audience } = options;
+  if (!authorizationHeader || !authorizationHeader.startsWith("Bearer ")) {
+    throw new ContextError(
+      "Missing or invalid Authorization header",
+      "unauthorized",
+      401
+    );
+  }
+  const token = authorizationHeader.split(" ")[1];
+  try {
+    const publicKey = await importSPKI(CONTEXT_PLATFORM_PUBLIC_KEY_PEM, "RS256");
+    const { payload } = await jwtVerify(token, publicKey, {
+      issuer: "https://ctxprotocol.com",
+      audience
+    });
+    return payload;
+  } catch (error) {
+    throw new ContextError(
+      "Invalid Context Protocol signature",
+      "unauthorized",
+      401
+    );
+  }
+}
 
-export { CONTEXT_REQUIREMENTS_KEY, ContextClient, ContextError, Discovery, Tools };
+export { CONTEXT_REQUIREMENTS_KEY, ContextClient, ContextError, Discovery, Tools, verifyContextRequest };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client/types.ts","../src/client/resources/discovery.ts","../src/client/resources/tools.ts","../src/client/client.ts","../src/context/index.ts"],"names":[],"mappings":"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","file":"index.js","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","/**\n * Context types for portfolio and protocol data injection.\n *\n * These types allow MCP tools to receive personalized user context\n * (wallet addresses, positions, balances) for analysis.\n *\n * =============================================================================\n * DECLARING CONTEXT REQUIREMENTS\n * =============================================================================\n *\n * Since the MCP protocol only transmits standard fields (name, description,\n * inputSchema, outputSchema), context requirements MUST be embedded in the\n * inputSchema using the \"x-context-requirements\" JSON Schema extension.\n *\n * @example\n * ```typescript\n * import { CONTEXT_REQUIREMENTS_KEY, type ContextRequirementType } from \"@ctxprotocol/sdk\";\n * import type { HyperliquidContext } from \"@ctxprotocol/sdk\";\n *\n * const tool = {\n *   name: \"analyze_my_positions\",\n *   inputSchema: {\n *     type: \"object\",\n *     [CONTEXT_REQUIREMENTS_KEY]: [\"hyperliquid\"] as ContextRequirementType[],\n *     properties: {\n *       portfolio: { type: \"object\" }\n *     },\n *     required: [\"portfolio\"]\n *   }\n * };\n *\n * // Your handler receives the injected context:\n * function handleAnalyzeMyPositions(args: { portfolio: HyperliquidContext }) {\n *   const { perpPositions, accountSummary } = args.portfolio;\n *   // ... analyze and return insights\n * }\n * ```\n *\n * @packageDocumentation\n */\n\n// Wallet context types\nexport * from \"./wallet.js\";\n\n// Protocol-specific context types\nexport * from \"./polymarket.js\";\nexport * from \"./hyperliquid.js\";\n\n// Re-import for composite type\nimport type { WalletContext, ERC20Context } from \"./wallet.js\";\nimport type { PolymarketContext } from \"./polymarket.js\";\nimport type { HyperliquidContext } from \"./hyperliquid.js\";\n\n// ============================================================================\n// CONTEXT REQUIREMENTS\n//\n// MCP tools that need user portfolio data MUST declare this in inputSchema.\n// The MCP protocol only transmits standard fields (name, description,\n// inputSchema, outputSchema). Custom fields get stripped by the MCP SDK.\n// ============================================================================\n\n/**\n * JSON Schema extension key for declaring context requirements.\n *\n * WHY THIS APPROACH?\n * - MCP protocol only transmits: name, description, inputSchema, outputSchema\n * - Custom fields like `requirements` get stripped by MCP SDK during transport\n * - JSON Schema allows custom \"x-\" prefixed extension properties\n * - inputSchema is preserved end-to-end through MCP transport\n *\n * @example\n * ```typescript\n * import { CONTEXT_REQUIREMENTS_KEY } from \"@ctxprotocol/sdk\";\n *\n * const tool = {\n *   name: \"analyze_my_positions\",\n *   inputSchema: {\n *     type: \"object\",\n *     [CONTEXT_REQUIREMENTS_KEY]: [\"hyperliquid\"],\n *     properties: { portfolio: { type: \"object\" } },\n *     required: [\"portfolio\"]\n *   }\n * };\n * ```\n */\nexport const CONTEXT_REQUIREMENTS_KEY = \"x-context-requirements\" as const;\n\n/**\n * Context requirement types supported by the Context marketplace.\n * Maps to protocol-specific context builders on the platform.\n *\n * @example\n * ```typescript\n * inputSchema: {\n *   type: \"object\",\n *   \"x-context-requirements\": [\"hyperliquid\"] as ContextRequirementType[],\n *   properties: { portfolio: { type: \"object\" } },\n *   required: [\"portfolio\"]\n * }\n * ```\n */\nexport type ContextRequirementType = \"polymarket\" | \"hyperliquid\" | \"wallet\";\n\n/**\n * @deprecated The `requirements` field at tool level gets stripped by MCP SDK.\n * Use `x-context-requirements` inside `inputSchema` instead.\n *\n * @example\n * ```typescript\n * // ❌ OLD (doesn't work - stripped by MCP SDK)\n * { requirements: { context: [\"hyperliquid\"] } }\n *\n * // ✅ NEW (works - preserved through MCP transport)\n * { inputSchema: { \"x-context-requirements\": [\"hyperliquid\"], ... } }\n * ```\n */\nexport interface ToolRequirements {\n  /**\n   * @deprecated Use `x-context-requirements` in inputSchema instead.\n   */\n  context?: ContextRequirementType[];\n}\n\n/**\n * Composite context for tools that need multiple data sources.\n *\n * This is the unified structure that can be passed to MCP tools\n * to provide comprehensive user context.\n */\nexport interface UserContext {\n  /** Base wallet information */\n  wallet?: WalletContext;\n  /** ERC20 token holdings */\n  erc20?: ERC20Context;\n  /** Polymarket positions and orders */\n  polymarket?: PolymarketContext;\n  /** Hyperliquid perpetual positions and account data */\n  hyperliquid?: HyperliquidContext;\n  // Future protocols:\n  // aave?: AaveContext;\n}\n"]}
+{"version":3,"sources":["../src/client/types.ts","../src/client/resources/discovery.ts","../src/client/resources/tools.ts","../src/client/client.ts","../src/context/index.ts","../src/auth/index.ts"],"names":[],"mappings":"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","file":"index.js","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","/**\n * Context types for portfolio and protocol data injection.\n *\n * These types allow MCP tools to receive personalized user context\n * (wallet addresses, positions, balances) for analysis.\n *\n * =============================================================================\n * DECLARING CONTEXT REQUIREMENTS\n * =============================================================================\n *\n * Since the MCP protocol only transmits standard fields (name, description,\n * inputSchema, outputSchema), context requirements MUST be embedded in the\n * inputSchema using the \"x-context-requirements\" JSON Schema extension.\n *\n * @example\n * ```typescript\n * import { CONTEXT_REQUIREMENTS_KEY, type ContextRequirementType } from \"@ctxprotocol/sdk\";\n * import type { HyperliquidContext } from \"@ctxprotocol/sdk\";\n *\n * const tool = {\n *   name: \"analyze_my_positions\",\n *   inputSchema: {\n *     type: \"object\",\n *     [CONTEXT_REQUIREMENTS_KEY]: [\"hyperliquid\"] as ContextRequirementType[],\n *     properties: {\n *       portfolio: { type: \"object\" }\n *     },\n *     required: [\"portfolio\"]\n *   }\n * };\n *\n * // Your handler receives the injected context:\n * function handleAnalyzeMyPositions(args: { portfolio: HyperliquidContext }) {\n *   const { perpPositions, accountSummary } = args.portfolio;\n *   // ... analyze and return insights\n * }\n * ```\n *\n * @packageDocumentation\n */\n\n// Wallet context types\nexport * from \"./wallet.js\";\n\n// Protocol-specific context types\nexport * from \"./polymarket.js\";\nexport * from \"./hyperliquid.js\";\n\n// Re-import for composite type\nimport type { WalletContext, ERC20Context } from \"./wallet.js\";\nimport type { PolymarketContext } from \"./polymarket.js\";\nimport type { HyperliquidContext } from \"./hyperliquid.js\";\n\n// ============================================================================\n// CONTEXT REQUIREMENTS\n//\n// MCP tools that need user portfolio data MUST declare this in inputSchema.\n// The MCP protocol only transmits standard fields (name, description,\n// inputSchema, outputSchema). Custom fields get stripped by the MCP SDK.\n// ============================================================================\n\n/**\n * JSON Schema extension key for declaring context requirements.\n *\n * WHY THIS APPROACH?\n * - MCP protocol only transmits: name, description, inputSchema, outputSchema\n * - Custom fields like `requirements` get stripped by MCP SDK during transport\n * - JSON Schema allows custom \"x-\" prefixed extension properties\n * - inputSchema is preserved end-to-end through MCP transport\n *\n * @example\n * ```typescript\n * import { CONTEXT_REQUIREMENTS_KEY } from \"@ctxprotocol/sdk\";\n *\n * const tool = {\n *   name: \"analyze_my_positions\",\n *   inputSchema: {\n *     type: \"object\",\n *     [CONTEXT_REQUIREMENTS_KEY]: [\"hyperliquid\"],\n *     properties: { portfolio: { type: \"object\" } },\n *     required: [\"portfolio\"]\n *   }\n * };\n * ```\n */\nexport const CONTEXT_REQUIREMENTS_KEY = \"x-context-requirements\" as const;\n\n/**\n * Context requirement types supported by the Context marketplace.\n * Maps to protocol-specific context builders on the platform.\n *\n * @example\n * ```typescript\n * inputSchema: {\n *   type: \"object\",\n *   \"x-context-requirements\": [\"hyperliquid\"] as ContextRequirementType[],\n *   properties: { portfolio: { type: \"object\" } },\n *   required: [\"portfolio\"]\n * }\n * ```\n */\nexport type ContextRequirementType = \"polymarket\" | \"hyperliquid\" | \"wallet\";\n\n/**\n * @deprecated The `requirements` field at tool level gets stripped by MCP SDK.\n * Use `x-context-requirements` inside `inputSchema` instead.\n *\n * @example\n * ```typescript\n * // ❌ OLD (doesn't work - stripped by MCP SDK)\n * { requirements: { context: [\"hyperliquid\"] } }\n *\n * // ✅ NEW (works - preserved through MCP transport)\n * { inputSchema: { \"x-context-requirements\": [\"hyperliquid\"], ... } }\n * ```\n */\nexport interface ToolRequirements {\n  /**\n   * @deprecated Use `x-context-requirements` in inputSchema instead.\n   */\n  context?: ContextRequirementType[];\n}\n\n/**\n * Composite context for tools that need multiple data sources.\n *\n * This is the unified structure that can be passed to MCP tools\n * to provide comprehensive user context.\n */\nexport interface UserContext {\n  /** Base wallet information */\n  wallet?: WalletContext;\n  /** ERC20 token holdings */\n  erc20?: ERC20Context;\n  /** Polymarket positions and orders */\n  polymarket?: PolymarketContext;\n  /** Hyperliquid perpetual positions and account data */\n  hyperliquid?: HyperliquidContext;\n  // Future protocols:\n  // aave?: AaveContext;\n}\n","import { jwtVerify, importSPKI } from \"jose\";\nimport { ContextError } from \"../client/types.js\";\n\n// The Context Protocol Public Key\n// In a real scenario, this might be fetched from a well-known URL or passed in config.\n// For now, we hardcode the Official Platform Public Key.\n// TODO: REPLACE THIS WITH THE ACTUAL GENERATED PUBLIC KEY FROM THE PLATFORM SETUP\nconst CONTEXT_PLATFORM_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END PUBLIC KEY-----`;\n\nexport interface VerifyRequestOptions {\n  /** The full Authorization header string (e.g. \"Bearer eyJ...\") */\n  authorizationHeader?: string;\n  /** Expected Audience (your tool URL) for stricter validation */\n  audience?: string;\n}\n\n/**\n * Verifies that an incoming request originated from the Context Protocol Platform.\n *\n * @param options Contains the Authorization header\n * @returns The decoded payload if valid\n * @throws ContextError if invalid\n */\nexport async function verifyContextRequest(options: VerifyRequestOptions) {\n  const { authorizationHeader, audience } = options;\n\n  if (!authorizationHeader || !authorizationHeader.startsWith(\"Bearer \")) {\n    throw new ContextError(\n      \"Missing or invalid Authorization header\",\n      \"unauthorized\",\n      401\n    );\n  }\n\n  const token = authorizationHeader.split(\" \")[1];\n\n  try {\n    const publicKey = await importSPKI(CONTEXT_PLATFORM_PUBLIC_KEY_PEM, \"RS256\");\n\n    const { payload } = await jwtVerify(token, publicKey, {\n      issuer: \"https://ctxprotocol.com\",\n      audience: audience,\n    });\n\n    return payload;\n  } catch (error) {\n    throw new ContextError(\n      \"Invalid Context Protocol signature\",\n      \"unauthorized\",\n      401\n    );\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctxprotocol/sdk",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Official TypeScript SDK for the Context Protocol - Discover and execute AI tools programmatically",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -57,7 +57,9 @@
   "bugs": {
     "url": "https://github.com/ctxprotocol/sdk/issues"
   },
-  "dependencies": {},
+  "dependencies": {
+    "jose": "^6.1.3"
+  },
   "devDependencies": {
     "tsup": "^8.3.5",
     "typescript": "^5.7.2"