ctxprotocol 0.5.5__py3-none-any.whl

ctxprotocol/client/resources/__init__.py

@@ -0,0 +1,11 @@
+"""
+ctxprotocol.client.resources
+
+Resource modules for the Context Protocol client.
+"""
+
+from ctxprotocol.client.resources.discovery import Discovery
+from ctxprotocol.client.resources.tools import Tools
+
+__all__ = ["Discovery", "Tools"]
+

ctxprotocol/client/resources/discovery.py

@@ -0,0 +1,70 @@
+"""
+Discovery resource for searching and finding tools on the Context Protocol marketplace.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ctxprotocol.client.types import SearchResponse, Tool
+
+if TYPE_CHECKING:
+    from ctxprotocol.client.client import ContextClient
+
+
+class Discovery:
+    """Discovery resource for searching and finding tools on the Context Protocol marketplace."""
+
+    def __init__(self, client: ContextClient) -> None:
+        """Initialize the Discovery resource.
+
+        Args:
+            client: The parent ContextClient instance
+        """
+        self._client = client
+
+    async def search(self, query: str, limit: int | None = None) -> list[Tool]:
+        """Search for tools matching a query string.
+
+        Args:
+            query: The search query (e.g., "gas prices", "nft metadata")
+            limit: Maximum number of results (1-50, default 10)
+
+        Returns:
+            Array of matching tools
+
+        Example:
+            >>> tools = await client.discovery.search("gas prices")
+            >>> print(tools[0].name)  # "Gas Price Oracle"
+            >>> print(tools[0].mcp_tools)  # Available methods
+        """
+        params: dict[str, str] = {}
+
+        if query:
+            params["q"] = query
+
+        if limit is not None:
+            params["limit"] = str(limit)
+
+        query_string = "&".join(f"{k}={v}" for k, v in params.items())
+        endpoint = f"/api/v1/tools/search{'?' + query_string if query_string else ''}"
+
+        response = await self._client.fetch(endpoint)
+        search_response = SearchResponse.model_validate(response)
+
+        return search_response.tools
+
+    async def get_featured(self, limit: int | None = None) -> list[Tool]:
+        """Get featured/popular tools (empty query search).
+
+        Args:
+            limit: Maximum number of results (1-50, default 10)
+
+        Returns:
+            Array of featured tools
+
+        Example:
+            >>> featured = await client.discovery.get_featured(5)
+        """
+        return await self.search("", limit)
+

ctxprotocol/client/resources/tools.py

@@ -0,0 +1,103 @@
+"""
+Tools resource for executing tools on the Context Protocol marketplace.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ctxprotocol.client.types import (
+    ContextError,
+    ExecuteApiErrorResponse,
+    ExecuteApiSuccessResponse,
+    ExecutionResult,
+    ToolInfo,
+)
+
+if TYPE_CHECKING:
+    from ctxprotocol.client.client import ContextClient
+
+
+class Tools:
+    """Tools resource for executing tools on the Context Protocol marketplace."""
+
+    def __init__(self, client: ContextClient) -> None:
+        """Initialize the Tools resource.
+
+        Args:
+            client: The parent ContextClient instance
+        """
+        self._client = client
+
+    async def execute(
+        self,
+        tool_id: str,
+        tool_name: str,
+        args: dict[str, Any] | None = None,
+    ) -> ExecutionResult:
+        """Execute a tool with the provided arguments.
+
+        Args:
+            tool_id: The UUID of the tool (from search results)
+            tool_name: The specific MCP tool method to call (from tool's mcp_tools array)
+            args: Arguments to pass to the tool
+
+        Returns:
+            The execution result with the tool's output data
+
+        Raises:
+            ContextError: With code `no_wallet` if wallet not set up
+            ContextError: With code `insufficient_allowance` if Auto Pay not enabled
+            ContextError: With code `payment_failed` if on-chain payment fails
+            ContextError: With code `execution_failed` if tool execution fails
+
+        Example:
+            >>> # First, search for a tool
+            >>> tools = await client.discovery.search("gas prices")
+            >>> tool = tools[0]
+            >>>
+            >>> # Execute a specific method from the tool's mcp_tools
+            >>> result = await client.tools.execute(
+            ...     tool_id=tool.id,
+            ...     tool_name=tool.mcp_tools[0].name,  # e.g., "get_gas_prices"
+            ...     args={"chainId": 1}
+            ... )
+            >>>
+            >>> print(result.result)  # The tool's output
+            >>> print(result.duration_ms)  # Execution time
+        """
+        response = await self._client.fetch(
+            "/api/v1/tools/execute",
+            method="POST",
+            json_body={
+                "toolId": tool_id,
+                "toolName": tool_name,
+                "args": args or {},
+            },
+        )
+
+        # Handle error response
+        if "error" in response:
+            error_response = ExecuteApiErrorResponse.model_validate(response)
+            raise ContextError(
+                message=error_response.error,
+                code=error_response.code,
+                status_code=400,
+                help_url=error_response.help_url,
+            )
+
+        # Handle success response
+        if response.get("success"):
+            success_response = ExecuteApiSuccessResponse.model_validate(response)
+            return ExecutionResult(
+                result=success_response.result,
+                tool=ToolInfo(
+                    id=success_response.tool.id,
+                    name=success_response.tool.name,
+                ),
+                duration_ms=success_response.duration_ms,
+            )
+
+        # Fallback - shouldn't reach here with valid API responses
+        raise ContextError("Unexpected response format from API")
+

ctxprotocol/client/types.py

@@ -0,0 +1,265 @@
+"""
+Type definitions for the Context Protocol SDK.
+
+This module contains all Pydantic models and type definitions used by the client.
+"""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class ContextClientOptions(BaseModel):
+    """Configuration options for initializing the ContextClient.
+
+    Attributes:
+        api_key: Your Context Protocol API key (e.g., "sk_live_abc123...")
+        base_url: Base URL for the Context Protocol API. Defaults to "https://ctxprotocol.com"
+    """
+
+    api_key: str = Field(..., description="Your Context Protocol API key")
+    base_url: str = Field(
+        default="https://ctxprotocol.com",
+        description="Base URL for the Context Protocol API",
+    )
+
+
+class McpTool(BaseModel):
+    """An individual MCP tool exposed by a tool listing.
+
+    Attributes:
+        name: Name of the MCP tool method
+        description: Description of what this method does
+        input_schema: JSON Schema for the input arguments this tool accepts
+        output_schema: JSON Schema for the output this tool returns
+    """
+
+    name: str = Field(..., description="Name of the MCP tool method")
+    description: str = Field(..., description="Description of what this method does")
+    input_schema: dict[str, Any] | None = Field(
+        default=None,
+        alias="inputSchema",
+        description="JSON Schema for the input arguments this tool accepts",
+    )
+    output_schema: dict[str, Any] | None = Field(
+        default=None,
+        alias="outputSchema",
+        description="JSON Schema for the output this tool returns",
+    )
+
+    model_config = {"populate_by_name": True}
+
+
+class Tool(BaseModel):
+    """Represents a tool available on the Context Protocol marketplace.
+
+    Attributes:
+        id: Unique identifier for the tool (UUID)
+        name: Human-readable name of the tool
+        description: Description of what the tool does
+        price: Price per execution in USDC
+        category: Tool category (e.g., "defi", "nft")
+        is_verified: Whether the tool is verified by Context Protocol
+        mcp_tools: Available MCP tool methods
+        created_at: Creation timestamp
+        updated_at: Last update timestamp
+    """
+
+    id: str = Field(..., description="Unique identifier for the tool (UUID)")
+    name: str = Field(..., description="Human-readable name of the tool")
+    description: str = Field(..., description="Description of what the tool does")
+    price: str = Field(..., description="Price per execution in USDC")
+    category: str | None = Field(default=None, description="Tool category")
+    is_verified: bool | None = Field(
+        default=None,
+        alias="isVerified",
+        description="Whether the tool is verified by Context Protocol",
+    )
+    mcp_tools: list[McpTool] | None = Field(
+        default=None,
+        alias="mcpTools",
+        description="Available MCP tool methods",
+    )
+    created_at: str | None = Field(
+        default=None,
+        alias="createdAt",
+        description="Creation timestamp",
+    )
+    updated_at: str | None = Field(
+        default=None,
+        alias="updatedAt",
+        description="Last update timestamp",
+    )
+
+    model_config = {"populate_by_name": True}
+
+
+class SearchResponse(BaseModel):
+    """Response from the tools search endpoint.
+
+    Attributes:
+        tools: Array of matching tools
+        query: The search query that was used
+        count: Total number of results
+    """
+
+    tools: list[Tool] = Field(..., description="Array of matching tools")
+    query: str = Field(..., description="The search query that was used")
+    count: int = Field(..., description="Total number of results")
+
+
+class SearchOptions(BaseModel):
+    """Options for searching tools.
+
+    Attributes:
+        query: Search query (semantic search)
+        limit: Maximum number of results (1-50, default 10)
+    """
+
+    query: str | None = Field(default=None, description="Search query (semantic search)")
+    limit: int | None = Field(
+        default=None,
+        ge=1,
+        le=50,
+        description="Maximum number of results (1-50, default 10)",
+    )
+
+
+class ExecuteOptions(BaseModel):
+    """Options for executing a tool.
+
+    Attributes:
+        tool_id: The UUID of the tool to execute (from search results)
+        tool_name: The specific MCP tool name to call (from tool's mcp_tools array)
+        args: Arguments to pass to the tool
+    """
+
+    tool_id: str = Field(
+        ...,
+        alias="toolId",
+        description="The UUID of the tool to execute (from search results)",
+    )
+    tool_name: str = Field(
+        ...,
+        alias="toolName",
+        description="The specific MCP tool name to call (from tool's mcp_tools array)",
+    )
+    args: dict[str, Any] | None = Field(
+        default=None,
+        description="Arguments to pass to the tool",
+    )
+
+    model_config = {"populate_by_name": True}
+
+
+class ToolInfo(BaseModel):
+    """Information about an executed tool."""
+
+    id: str
+    name: str
+
+
+class ExecuteApiSuccessResponse(BaseModel):
+    """Successful execution response from the API.
+
+    Attributes:
+        success: Always True for success responses
+        result: The result data from the tool execution
+        tool: Information about the executed tool
+        duration_ms: Execution duration in milliseconds
+    """
+
+    success: Literal[True] = Field(..., description="Always True for success responses")
+    result: Any = Field(..., description="The result data from the tool execution")
+    tool: ToolInfo = Field(..., description="Information about the executed tool")
+    duration_ms: int = Field(
+        ...,
+        alias="durationMs",
+        description="Execution duration in milliseconds",
+    )
+
+    model_config = {"populate_by_name": True}
+
+
+class ExecuteApiErrorResponse(BaseModel):
+    """Error response from the API.
+
+    Attributes:
+        error: Human-readable error message
+        code: Error code for programmatic handling
+        help_url: URL to help resolve the issue
+    """
+
+    error: str = Field(..., description="Human-readable error message")
+    code: str | None = Field(
+        default=None,
+        description="Error code for programmatic handling",
+    )
+    help_url: str | None = Field(
+        default=None,
+        alias="helpUrl",
+        description="URL to help resolve the issue",
+    )
+
+    model_config = {"populate_by_name": True}
+
+
+class ExecutionResult(BaseModel):
+    """The resolved result returned to the user after SDK processing.
+
+    Attributes:
+        result: The data returned by the tool
+        tool: Information about the executed tool
+        duration_ms: Execution duration in milliseconds
+    """
+
+    result: Any = Field(..., description="The data returned by the tool")
+    tool: ToolInfo = Field(..., description="Information about the executed tool")
+    duration_ms: int = Field(..., description="Execution duration in milliseconds")
+
+
+# Type alias for specific error codes returned by the Context Protocol API
+ContextErrorCode = Literal[
+    "unauthorized",
+    "no_wallet",
+    "insufficient_allowance",
+    "payment_failed",
+    "execution_failed",
+]
+
+
+class ContextError(Exception):
+    """Error thrown by the Context Protocol client.
+
+    Attributes:
+        message: Human-readable error message
+        code: Error code for programmatic handling
+        status_code: HTTP status code
+        help_url: URL to help resolve the issue
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: str | None = None,
+        status_code: int | None = None,
+        help_url: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.help_url = help_url
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.code:
+            parts.append(f"[{self.code}]")
+        return " ".join(parts)
+
+    def __repr__(self) -> str:
+        return (
+            f"ContextError(message={self.message!r}, code={self.code!r}, "
+            f"status_code={self.status_code!r}, help_url={self.help_url!r})"
+        )
+

ctxprotocol/context/__init__.py

@@ -0,0 +1,184 @@
+"""
+Context types for portfolio and protocol data injection.
+
+These types allow MCP tools to receive personalized user context
+(wallet addresses, positions, balances) for analysis.
+
+=============================================================================
+DECLARING CONTEXT REQUIREMENTS
+=============================================================================
+
+Since the MCP protocol only transmits standard fields (name, description,
+inputSchema, outputSchema), context requirements MUST be embedded in the
+inputSchema using the "x-context-requirements" JSON Schema extension.
+
+Example:
+    >>> from ctxprotocol import CONTEXT_REQUIREMENTS_KEY, ContextRequirementType
+    >>> from ctxprotocol.context import HyperliquidContext
+    >>>
+    >>> tool = {
+    ...     "name": "analyze_my_positions",
+    ...     "inputSchema": {
+    ...         "type": "object",
+    ...         CONTEXT_REQUIREMENTS_KEY: ["hyperliquid"],
+    ...         "properties": {
+    ...             "portfolio": {"type": "object"}
+    ...         },
+    ...         "required": ["portfolio"]
+    ...     }
+    ... }
+    >>>
+    >>> # Your handler receives the injected context:
+    >>> def handle_analyze_my_positions(portfolio: HyperliquidContext):
+    ...     positions = portfolio.perp_positions
+    ...     account = portfolio.account_summary
+    ...     # ... analyze and return insights
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+# Wallet context types
+from ctxprotocol.context.wallet import ERC20Context, ERC20TokenBalance, WalletContext
+
+# Protocol-specific context types
+from ctxprotocol.context.polymarket import (
+    PolymarketContext,
+    PolymarketOrder,
+    PolymarketPosition,
+)
+from ctxprotocol.context.hyperliquid import (
+    CrossMarginSummary,
+    CumFunding,
+    HyperliquidAccountSummary,
+    HyperliquidContext,
+    HyperliquidOrder,
+    HyperliquidPerpPosition,
+    HyperliquidSpotBalance,
+    LeverageInfo,
+)
+
+# ============================================================================
+# CONTEXT REQUIREMENTS
+#
+# MCP tools that need user portfolio data MUST declare this in inputSchema.
+# The MCP protocol only transmits standard fields (name, description,
+# inputSchema, outputSchema). Custom fields get stripped by the MCP SDK.
+# ============================================================================
+
+CONTEXT_REQUIREMENTS_KEY = "x-context-requirements"
+"""
+JSON Schema extension key for declaring context requirements.
+
+WHY THIS APPROACH?
+- MCP protocol only transmits: name, description, inputSchema, outputSchema
+- Custom fields like `requirements` get stripped by MCP SDK during transport
+- JSON Schema allows custom "x-" prefixed extension properties
+- inputSchema is preserved end-to-end through MCP transport
+
+Example:
+    >>> tool = {
+    ...     "name": "analyze_my_positions",
+    ...     "inputSchema": {
+    ...         "type": "object",
+    ...         CONTEXT_REQUIREMENTS_KEY: ["hyperliquid"],
+    ...         "properties": {"portfolio": {"type": "object"}},
+    ...         "required": ["portfolio"]
+    ...     }
+    ... }
+"""
+
+# Context requirement types supported by the Context marketplace
+ContextRequirementType = Literal["polymarket", "hyperliquid", "wallet"]
+"""
+Context requirement types supported by the Context marketplace.
+Maps to protocol-specific context builders on the platform.
+
+Example:
+    >>> input_schema = {
+    ...     "type": "object",
+    ...     "x-context-requirements": ["hyperliquid"],  # type: ContextRequirementType
+    ...     "properties": {"portfolio": {"type": "object"}},
+    ...     "required": ["portfolio"]
+    ... }
+"""
+
+
+class ToolRequirements(BaseModel):
+    """
+    DEPRECATED: The `requirements` field at tool level gets stripped by MCP SDK.
+    Use `x-context-requirements` inside `inputSchema` instead.
+
+    Example:
+        >>> # ❌ OLD (doesn't work - stripped by MCP SDK)
+        >>> {"requirements": {"context": ["hyperliquid"]}}
+        >>>
+        >>> # ✅ NEW (works - preserved through MCP transport)
+        >>> {"inputSchema": {"x-context-requirements": ["hyperliquid"], ...}}
+    """
+
+    context: list[ContextRequirementType] | None = Field(
+        default=None,
+        description="DEPRECATED: Use x-context-requirements in inputSchema instead.",
+    )
+
+
+class UserContext(BaseModel):
+    """Composite context for tools that need multiple data sources.
+
+    This is the unified structure that can be passed to MCP tools
+    to provide comprehensive user context.
+
+    Attributes:
+        wallet: Base wallet information
+        erc20: ERC20 token holdings
+        polymarket: Polymarket positions and orders
+        hyperliquid: Hyperliquid perpetual positions and account data
+    """
+
+    wallet: WalletContext | None = Field(
+        default=None,
+        description="Base wallet information",
+    )
+    erc20: ERC20Context | None = Field(
+        default=None,
+        description="ERC20 token holdings",
+    )
+    polymarket: PolymarketContext | None = Field(
+        default=None,
+        description="Polymarket positions and orders",
+    )
+    hyperliquid: HyperliquidContext | None = Field(
+        default=None,
+        description="Hyperliquid perpetual positions and account data",
+    )
+
+
+__all__ = [
+    # Constants
+    "CONTEXT_REQUIREMENTS_KEY",
+    # Type aliases
+    "ContextRequirementType",
+    # Wallet types
+    "WalletContext",
+    "ERC20Context",
+    "ERC20TokenBalance",
+    # Polymarket types
+    "PolymarketContext",
+    "PolymarketPosition",
+    "PolymarketOrder",
+    # Hyperliquid types
+    "HyperliquidContext",
+    "HyperliquidPerpPosition",
+    "HyperliquidOrder",
+    "HyperliquidSpotBalance",
+    "HyperliquidAccountSummary",
+    "CrossMarginSummary",
+    "LeverageInfo",
+    "CumFunding",
+    # Composite types
+    "UserContext",
+    "ToolRequirements",
+]
+