@ctxprotocol/sdk 0.4.0 → 0.5.0

package/README.md

@@ -265,12 +265,20 @@ const result = await client.tools.execute({
 
 ```typescript
 import type {
+  // Client types
   ContextClientOptions,
   Tool,
   McpTool,
   ExecuteOptions,
   ExecutionResult,
   ContextErrorCode,
+  // Context types (for MCP server contributors)
+  ToolRequirements,
+  ContextRequirementType,
+  HyperliquidContext,
+  PolymarketContext,
+  WalletContext,
+  UserContext,
 } from "@ctxprotocol/sdk";
 ```
 
@@ -309,6 +317,18 @@ interface ExecutionResult<T = unknown> {
 }
 ```
 
+### ToolRequirements (MCP Server Contributors)
+
+```typescript
+/** Context types supported by the marketplace */
+type ContextRequirementType = "polymarket" | "hyperliquid" | "wallet";
+
+/** Declare what context your tool needs */
+interface ToolRequirements {
+  context?: ContextRequirementType[];
+}
+```
+
 ## Error Handling
 
 The SDK throws `ContextError` with specific error codes. In an agentic context, you can feed errors back to your LLM so it can self-correct.
@@ -369,6 +389,61 @@ Want to earn money by contributing tools to the Context marketplace? Build a sta
 | `outputSchema` | AI agents use this to generate type-safe code. Context uses it for dispute resolution. |
 | `structuredContent` | Agents parse this for programmatic access. Text `content` is for humans. |
 
+### Context Injection (Portfolio Analysis Tools)
+
+Building tools that analyze user portfolios? Context automatically injects user portfolio data into your tools—no authentication required.
+
+**📖 Read the full guide: [Context Injection Architecture](./docs/context-injection.md)**
+
+Key benefits:
+- **No Auth Required** — User data is injected automatically from their linked wallets
+- **Type-Safe** — Use SDK types like `PolymarketContext`, `HyperliquidContext`
+- **Focus on Analysis** — You receive structured data, you provide insights
+
+### Context Requirements Declaration
+
+If your tool needs user portfolio data, you **MUST** declare this explicitly using `requirements.context`:
+
+```typescript
+import type { ToolRequirements } from "@ctxprotocol/sdk";
+
+const TOOLS = [{
+  name: "analyze_my_positions",
+  description: "Analyze your positions with personalized insights",
+
+  // ⭐ REQUIRED: Explicit context requirements for portfolio tools
+  requirements: {
+    context: ["hyperliquid"],  // or "polymarket", "wallet"
+  } satisfies ToolRequirements,
+
+  inputSchema: {
+    type: "object",
+    properties: {
+      portfolio: {
+        type: "object",
+        description: "Portfolio context (injected by platform)",
+      },
+    },
+    required: ["portfolio"],
+  },
+  outputSchema: { /* ... */ },
+}];
+```
+
+**Available context types:**
+
+| Type | Description | Injected Data |
+|------|-------------|---------------|
+| `"hyperliquid"` | Hyperliquid perpetuals & spot | `HyperliquidContext` |
+| `"polymarket"` | Polymarket prediction markets | `PolymarketContext` |
+| `"wallet"` | Generic EVM wallet | `WalletContext` |
+
+**How it works:**
+1. User links their wallet in Context app settings
+2. When your tool is selected, platform checks `requirements.context`
+3. Platform fetches user's portfolio data from protocol APIs
+4. Data is injected as the `portfolio` argument to your tool
+
 ### Example: Standard MCP Server
 
 Build your server with the standard `@modelcontextprotocol/sdk`:
@@ -446,6 +521,15 @@ When you execute a tool:
 3. **10%** goes to the protocol
 4. Tool executes and returns results
 
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Context Injection Guide](./docs/context-injection.md) | Architecture guide for building portfolio analysis tools with automatic user data injection |
+| [Polymarket Example](./examples/server/polymarket-contributor) | Complete MCP server for Polymarket intelligence |
+| [Hyperliquid Example](./examples/server/hyperliquid-contributor) | Complete MCP server for Hyperliquid analytics |
+| [Blocknative Example](./examples/server/blocknative-contributor) | Simple gas price MCP server |
+
 ## Links
 
 - [Context Protocol](https://ctxprotocol.com) — Main website

package/dist/index.d.cts

@@ -225,7 +225,7 @@ interface HyperliquidContext {
  *
  * @example
  * ```typescript
- * import type { PolymarketContext, UserContext } from "@ctxprotocol/sdk";
+ * import type { PolymarketContext, UserContext, ToolRequirements } from "@ctxprotocol/sdk";
  *
  * // Build context for a user's portfolio
  * const context: UserContext = {
@@ -237,11 +237,74 @@ interface HyperliquidContext {
  *     fetchedAt: new Date().toISOString(),
  *   },
  * };
+ *
+ * // Declare context requirements for a tool
+ * const requirements: ToolRequirements = {
+ *   context: ["polymarket"],
+ * };
  * ```
  *
  * @packageDocumentation
  */
 
+/**
+ * Context requirement types supported by the Context marketplace.
+ * Maps to protocol-specific context builders on the platform.
+ *
+ * @example
+ * ```typescript
+ * // Tool that needs Hyperliquid positions
+ * requirements: {
+ *   context: ["hyperliquid"]
+ * }
+ *
+ * // Tool that needs multiple context types
+ * requirements: {
+ *   context: ["hyperliquid", "wallet"]
+ * }
+ * ```
+ */
+type ContextRequirementType = "polymarket" | "hyperliquid" | "wallet";
+/**
+ * Tool-level requirements declaration.
+ *
+ * MCP tools that need user portfolio data MUST declare this explicitly
+ * in their tool definition. The Context marketplace checks this field
+ * to determine what context to inject.
+ *
+ * @example
+ * ```typescript
+ * const tool = {
+ *   name: "analyze_my_positions",
+ *   description: "Analyze your positions",
+ *
+ *   // ⭐ REQUIRED for portfolio tools
+ *   requirements: {
+ *     context: ["hyperliquid"],
+ *   } satisfies ToolRequirements,
+ *
+ *   inputSchema: {
+ *     type: "object",
+ *     properties: {
+ *       portfolio: {
+ *         type: "object",
+ *         description: "Portfolio context (injected by platform)",
+ *       },
+ *     },
+ *     required: ["portfolio"],
+ *   },
+ * };
+ * ```
+ */
+interface ToolRequirements {
+    /**
+     * Context types required by this tool.
+     * - "polymarket": User's Polymarket positions (prediction markets)
+     * - "hyperliquid": User's Hyperliquid perp/spot positions
+     * - "wallet": Generic EVM wallet context (address, balances)
+     */
+    context?: ContextRequirementType[];
+}
 /**
  * Composite context for tools that need multiple data sources.
  *
@@ -259,4 +322,4 @@ interface UserContext {
     hyperliquid?: HyperliquidContext;
 }
 
-export type { ERC20Context, ERC20TokenBalance, HyperliquidAccountSummary, HyperliquidContext, HyperliquidOrder, HyperliquidPerpPosition, HyperliquidSpotBalance, PolymarketContext, PolymarketOrder, PolymarketPosition, UserContext, WalletContext };
+export type { ContextRequirementType, ERC20Context, ERC20TokenBalance, HyperliquidAccountSummary, HyperliquidContext, HyperliquidOrder, HyperliquidPerpPosition, HyperliquidSpotBalance, PolymarketContext, PolymarketOrder, PolymarketPosition, ToolRequirements, UserContext, WalletContext };

package/dist/index.d.ts

@@ -225,7 +225,7 @@ interface HyperliquidContext {
  *
  * @example
  * ```typescript
- * import type { PolymarketContext, UserContext } from "@ctxprotocol/sdk";
+ * import type { PolymarketContext, UserContext, ToolRequirements } from "@ctxprotocol/sdk";
  *
  * // Build context for a user's portfolio
  * const context: UserContext = {
@@ -237,11 +237,74 @@ interface HyperliquidContext {
  *     fetchedAt: new Date().toISOString(),
  *   },
  * };
+ *
+ * // Declare context requirements for a tool
+ * const requirements: ToolRequirements = {
+ *   context: ["polymarket"],
+ * };
  * ```
  *
  * @packageDocumentation
  */
 
+/**
+ * Context requirement types supported by the Context marketplace.
+ * Maps to protocol-specific context builders on the platform.
+ *
+ * @example
+ * ```typescript
+ * // Tool that needs Hyperliquid positions
+ * requirements: {
+ *   context: ["hyperliquid"]
+ * }
+ *
+ * // Tool that needs multiple context types
+ * requirements: {
+ *   context: ["hyperliquid", "wallet"]
+ * }
+ * ```
+ */
+type ContextRequirementType = "polymarket" | "hyperliquid" | "wallet";
+/**
+ * Tool-level requirements declaration.
+ *
+ * MCP tools that need user portfolio data MUST declare this explicitly
+ * in their tool definition. The Context marketplace checks this field
+ * to determine what context to inject.
+ *
+ * @example
+ * ```typescript
+ * const tool = {
+ *   name: "analyze_my_positions",
+ *   description: "Analyze your positions",
+ *
+ *   // ⭐ REQUIRED for portfolio tools
+ *   requirements: {
+ *     context: ["hyperliquid"],
+ *   } satisfies ToolRequirements,
+ *
+ *   inputSchema: {
+ *     type: "object",
+ *     properties: {
+ *       portfolio: {
+ *         type: "object",
+ *         description: "Portfolio context (injected by platform)",
+ *       },
+ *     },
+ *     required: ["portfolio"],
+ *   },
+ * };
+ * ```
+ */
+interface ToolRequirements {
+    /**
+     * Context types required by this tool.
+     * - "polymarket": User's Polymarket positions (prediction markets)
+     * - "hyperliquid": User's Hyperliquid perp/spot positions
+     * - "wallet": Generic EVM wallet context (address, balances)
+     */
+    context?: ContextRequirementType[];
+}
 /**
  * Composite context for tools that need multiple data sources.
  *
@@ -259,4 +322,4 @@ interface UserContext {
     hyperliquid?: HyperliquidContext;
 }
 
-export type { ERC20Context, ERC20TokenBalance, HyperliquidAccountSummary, HyperliquidContext, HyperliquidOrder, HyperliquidPerpPosition, HyperliquidSpotBalance, PolymarketContext, PolymarketOrder, PolymarketPosition, UserContext, WalletContext };
+export type { ContextRequirementType, ERC20Context, ERC20TokenBalance, HyperliquidAccountSummary, HyperliquidContext, HyperliquidOrder, HyperliquidPerpPosition, HyperliquidSpotBalance, PolymarketContext, PolymarketOrder, PolymarketPosition, ToolRequirements, UserContext, WalletContext };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctxprotocol/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Official TypeScript SDK for the Context Protocol - Discover and execute AI tools programmatically",
   "type": "module",
   "main": "./dist/index.cjs",