@ctxprotocol/sdk 0.5.2 → 0.5.3

package/README.md

@@ -269,6 +269,8 @@ import {
   CONTEXT_REQUIREMENTS_KEY,
   // Auth utilities for tool contributors
   verifyContextRequest,
+  isProtectedMcpMethod,
+  isOpenMcpMethod,
 } from "@ctxprotocol/sdk";
 
 import type {
@@ -393,74 +395,69 @@ try {
 
 If you're building an MCP server (tool contributor), you should verify that incoming requests are legitimate and originate from the Context Protocol Platform.
 
+### Security Model
+
+The SDK implements a **selective authentication** model:
+
+| MCP Method | Auth Required | Reason |
+|------------|---------------|--------|
+| `tools/list` | ❌ No | Discovery - just returns tool schemas |
+| `tools/call` | ✅ Yes | Execution - runs code, may cost money |
+| `initialize` | ❌ No | Session setup |
+| `resources/list` | ❌ No | Discovery |
+| `prompts/list` | ❌ No | Discovery |
+
+This matches standard API patterns (OpenAPI schemas are public, GraphQL introspection is open).
+
 ### 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.
+The Context Platform signs **execution requests** (`tools/call`) using **RS256** (RSA-SHA256) asymmetric cryptography. Each request includes an `Authorization: Bearer <jwt>` header containing a signed JWT.
 
-### Using `verifyContextRequest`
+### Using `isProtectedMcpMethod` and `verifyContextRequest`
 
-The SDK provides a utility function to verify incoming requests:
+The SDK provides utilities to implement this security model:
 
 ```typescript
-import { verifyContextRequest, ContextError } from "@ctxprotocol/sdk";
+import { 
+  verifyContextRequest, 
+  isProtectedMcpMethod, 
+  ContextError 
+} from "@ctxprotocol/sdk";
 ```
 
-#### Express.js Example
+#### Express.js MCP Server Example
 
 ```typescript
 import express from "express";
-import { verifyContextRequest, ContextError } from "@ctxprotocol/sdk";
+import { verifyContextRequest, isProtectedMcpMethod, ContextError } from "@ctxprotocol/sdk";
 
 const app = express();
+app.use(express.json());
 
-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);
+// Auth middleware - only protects tools/call, not tools/list
+async function verifyContextAuth(req, res, next) {
+  const method = req.body?.method;
 
-    // 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" });
+  // Only require auth for protected methods (tools/call)
+  // Discovery methods (tools/list, initialize) are open
+  if (!method || !isProtectedMcpMethod(method)) {
+    return next();
   }
-});
-```
-
-#### 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,
+      authorizationHeader: req.headers.authorization,
     });
-
-    // Request is verified - process tool logic
-    return NextResponse.json({ result: "success" });
+    next();
   } 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 }
-    );
+    const statusCode = err instanceof ContextError ? err.statusCode || 401 : 401;
+    res.status(statusCode).json({ error: "Unauthorized" });
   }
 }
+
+app.post("/mcp", verifyContextAuth, async (req, res) => {
+  // Handle MCP request...
+});
 ```
 
 ### Options

package/dist/index.cjs

@@ -193,6 +193,26 @@ var CONTEXT_REQUIREMENTS_KEY = "x-context-requirements";
 var CONTEXT_PLATFORM_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
 MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
 -----END PUBLIC KEY-----`;
+var PROTECTED_MCP_METHODS = /* @__PURE__ */ new Set([
+  "tools/call"
+  // Uncomment these if you want to protect resource/prompt access:
+  // "resources/read",
+  // "prompts/get",
+]);
+var OPEN_MCP_METHODS = /* @__PURE__ */ new Set([
+  "initialize",
+  "tools/list",
+  "resources/list",
+  "prompts/list",
+  "ping",
+  "notifications/initialized"
+]);
+function isProtectedMcpMethod(method) {
+  return PROTECTED_MCP_METHODS.has(method);
+}
+function isOpenMcpMethod(method) {
+  return OPEN_MCP_METHODS.has(method);
+}
 async function verifyContextRequest(options) {
   const { authorizationHeader, audience } = options;
   if (!authorizationHeader || !authorizationHeader.startsWith("Bearer ")) {
@@ -224,6 +244,8 @@ exports.ContextClient = ContextClient;
 exports.ContextError = ContextError;
 exports.Discovery = Discovery;
 exports.Tools = Tools;
+exports.isOpenMcpMethod = isOpenMcpMethod;
+exports.isProtectedMcpMethod = isProtectedMcpMethod;
 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","../src/auth/index.ts"],"names":["importSPKI","jwtVerify"],"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","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"]}
+{"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":"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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","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\n/**\n * MCP methods that require authentication.\n * - tools/call: Executes tool logic, may cost money\n * - resources/read: Reads potentially sensitive data\n * - prompts/get: Gets prompt content\n */\nconst PROTECTED_MCP_METHODS = new Set([\n  \"tools/call\",\n  // Uncomment these if you want to protect resource/prompt access:\n  // \"resources/read\",\n  // \"prompts/get\",\n]);\n\n/**\n * MCP methods that are always open (no auth required).\n * These are discovery/listing operations that return metadata only.\n */\nconst OPEN_MCP_METHODS = new Set([\n  \"initialize\",\n  \"tools/list\",\n  \"resources/list\",\n  \"prompts/list\",\n  \"ping\",\n  \"notifications/initialized\",\n]);\n\n/**\n * Determines if a given MCP method requires authentication.\n *\n * Discovery methods (tools/list, resources/list, etc.) are open.\n * Execution methods (tools/call) require authentication.\n *\n * @param method The MCP JSON-RPC method (e.g., \"tools/list\", \"tools/call\")\n * @returns true if the method requires authentication\n *\n * @example\n * ```typescript\n * if (isProtectedMcpMethod(body.method)) {\n *   await verifyContextRequest({ authorizationHeader: req.headers.authorization });\n * }\n * ```\n */\nexport function isProtectedMcpMethod(method: string): boolean {\n  return PROTECTED_MCP_METHODS.has(method);\n}\n\n/**\n * Determines if a given MCP method is explicitly open (no auth).\n *\n * @param method The MCP JSON-RPC method\n * @returns true if the method is known to be open\n */\nexport function isOpenMcpMethod(method: string): boolean {\n  return OPEN_MCP_METHODS.has(method);\n}\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

@@ -335,6 +335,30 @@ interface UserContext {
     hyperliquid?: HyperliquidContext;
 }
 
+/**
+ * Determines if a given MCP method requires authentication.
+ *
+ * Discovery methods (tools/list, resources/list, etc.) are open.
+ * Execution methods (tools/call) require authentication.
+ *
+ * @param method The MCP JSON-RPC method (e.g., "tools/list", "tools/call")
+ * @returns true if the method requires authentication
+ *
+ * @example
+ * ```typescript
+ * if (isProtectedMcpMethod(body.method)) {
+ *   await verifyContextRequest({ authorizationHeader: req.headers.authorization });
+ * }
+ * ```
+ */
+declare function isProtectedMcpMethod(method: string): boolean;
+/**
+ * Determines if a given MCP method is explicitly open (no auth).
+ *
+ * @param method The MCP JSON-RPC method
+ * @returns true if the method is known to be open
+ */
+declare function isOpenMcpMethod(method: string): boolean;
 interface VerifyRequestOptions {
     /** The full Authorization header string (e.g. "Bearer eyJ...") */
     authorizationHeader?: string;
@@ -350,4 +374,4 @@ interface VerifyRequestOptions {
  */
 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 };
+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, isOpenMcpMethod, isProtectedMcpMethod, verifyContextRequest };

package/dist/index.d.ts

@@ -335,6 +335,30 @@ interface UserContext {
     hyperliquid?: HyperliquidContext;
 }
 
+/**
+ * Determines if a given MCP method requires authentication.
+ *
+ * Discovery methods (tools/list, resources/list, etc.) are open.
+ * Execution methods (tools/call) require authentication.
+ *
+ * @param method The MCP JSON-RPC method (e.g., "tools/list", "tools/call")
+ * @returns true if the method requires authentication
+ *
+ * @example
+ * ```typescript
+ * if (isProtectedMcpMethod(body.method)) {
+ *   await verifyContextRequest({ authorizationHeader: req.headers.authorization });
+ * }
+ * ```
+ */
+declare function isProtectedMcpMethod(method: string): boolean;
+/**
+ * Determines if a given MCP method is explicitly open (no auth).
+ *
+ * @param method The MCP JSON-RPC method
+ * @returns true if the method is known to be open
+ */
+declare function isOpenMcpMethod(method: string): boolean;
 interface VerifyRequestOptions {
     /** The full Authorization header string (e.g. "Bearer eyJ...") */
     authorizationHeader?: string;
@@ -350,4 +374,4 @@ interface VerifyRequestOptions {
  */
 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 };
+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, isOpenMcpMethod, isProtectedMcpMethod, verifyContextRequest };

package/dist/index.js

@@ -191,6 +191,26 @@ var CONTEXT_REQUIREMENTS_KEY = "x-context-requirements";
 var CONTEXT_PLATFORM_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
 MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
 -----END PUBLIC KEY-----`;
+var PROTECTED_MCP_METHODS = /* @__PURE__ */ new Set([
+  "tools/call"
+  // Uncomment these if you want to protect resource/prompt access:
+  // "resources/read",
+  // "prompts/get",
+]);
+var OPEN_MCP_METHODS = /* @__PURE__ */ new Set([
+  "initialize",
+  "tools/list",
+  "resources/list",
+  "prompts/list",
+  "ping",
+  "notifications/initialized"
+]);
+function isProtectedMcpMethod(method) {
+  return PROTECTED_MCP_METHODS.has(method);
+}
+function isOpenMcpMethod(method) {
+  return OPEN_MCP_METHODS.has(method);
+}
 async function verifyContextRequest(options) {
   const { authorizationHeader, audience } = options;
   if (!authorizationHeader || !authorizationHeader.startsWith("Bearer ")) {
@@ -217,6 +237,6 @@ async function verifyContextRequest(options) {
   }
 }
 
-export { CONTEXT_REQUIREMENTS_KEY, ContextClient, ContextError, Discovery, Tools, verifyContextRequest };
+export { CONTEXT_REQUIREMENTS_KEY, ContextClient, ContextError, Discovery, Tools, isOpenMcpMethod, isProtectedMcpMethod, 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","../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"]}
+{"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\n/**\n * MCP methods that require authentication.\n * - tools/call: Executes tool logic, may cost money\n * - resources/read: Reads potentially sensitive data\n * - prompts/get: Gets prompt content\n */\nconst PROTECTED_MCP_METHODS = new Set([\n  \"tools/call\",\n  // Uncomment these if you want to protect resource/prompt access:\n  // \"resources/read\",\n  // \"prompts/get\",\n]);\n\n/**\n * MCP methods that are always open (no auth required).\n * These are discovery/listing operations that return metadata only.\n */\nconst OPEN_MCP_METHODS = new Set([\n  \"initialize\",\n  \"tools/list\",\n  \"resources/list\",\n  \"prompts/list\",\n  \"ping\",\n  \"notifications/initialized\",\n]);\n\n/**\n * Determines if a given MCP method requires authentication.\n *\n * Discovery methods (tools/list, resources/list, etc.) are open.\n * Execution methods (tools/call) require authentication.\n *\n * @param method The MCP JSON-RPC method (e.g., \"tools/list\", \"tools/call\")\n * @returns true if the method requires authentication\n *\n * @example\n * ```typescript\n * if (isProtectedMcpMethod(body.method)) {\n *   await verifyContextRequest({ authorizationHeader: req.headers.authorization });\n * }\n * ```\n */\nexport function isProtectedMcpMethod(method: string): boolean {\n  return PROTECTED_MCP_METHODS.has(method);\n}\n\n/**\n * Determines if a given MCP method is explicitly open (no auth).\n *\n * @param method The MCP JSON-RPC method\n * @returns true if the method is known to be open\n */\nexport function isOpenMcpMethod(method: string): boolean {\n  return OPEN_MCP_METHODS.has(method);\n}\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.2",
+  "version": "0.5.3",
   "description": "Official TypeScript SDK for the Context Protocol - Discover and execute AI tools programmatically",
   "type": "module",
   "main": "./dist/index.cjs",