ctxprotocol 0.5.6__tar.gz → 0.6.0__tar.gz

{ctxprotocol-0.5.6 → ctxprotocol-0.6.0}/.gitignore

@@ -48,3 +48,4 @@ htmlcov/
 # Shell scripts (deployment)
 *.sh
 
+

{ctxprotocol-0.5.6 → ctxprotocol-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxprotocol
-Version: 0.5.6
+Version: 0.6.0
 Summary: Official Python SDK for the Context Protocol - Discover and execute AI tools programmatically
 Project-URL: Homepage, https://ctxprotocol.com
 Project-URL: Documentation, https://docs.ctxprotocol.com
@@ -48,12 +48,26 @@ Context Protocol is **pip for AI capabilities**. Just as you install packages to
 [![Python versions](https://img.shields.io/pypi/pyversions/ctxprotocol.svg)](https://pypi.org/project/ctxprotocol/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+---
+
+### 💰 $10,000 Developer Grant Program
+
+We're funding the initial supply of MCP Tools for the Context Marketplace. **Become a Data Broker.**
+
+- **🛠️ Build:** Create an MCP Server using this SDK (Solana data, Trading tools, Scrapers, etc.)
+- **📦 List:** Publish it to the Context Registry
+- **💵 Earn:** Get a **$250–$1,000 Grant** + earn USDC every time an agent queries your tool
+
+👉 [**View Open Bounties & Apply Here**](https://docs.ctxprotocol.com/grants)
+
+---
+
 ## Why use Context?
 
 - **🔌 One Interface, Everything:** Stop integrating APIs one by one. Use a single SDK to access any tool in the marketplace.
 - **🧠 Zero-Ops:** We're a gateway to the best MCP tools. Just send the JSON and get the result.
 - **⚡️ Agentic Discovery:** Your Agent can search the marketplace at runtime to find tools it didn't know it needed.
-- **💸 Micro-Billing:** Pay only for what you use (e.g., $0.001/query). No monthly subscriptions for tools you rarely use.
+- **💸 Pay-Per-Response:** The $500/year subscription? Now $0.01/response. No monthly fees, just results.
 
 ## Who Is This SDK For?
 
@@ -282,6 +296,22 @@ The SDK implements a **selective authentication** model — discovery is open, e
 
 This matches standard API patterns (OpenAPI schemas are public, GraphQL introspection is open).
 
+## Execution Timeout & Product Design
+
+⚠️ **Important**: MCP tool execution has a **~60 second timeout** (enforced at the platform/client level, not by MCP itself). This is intentional—it encourages building pre-computed insight products rather than raw data access.
+
+**Best practice**: Run heavy queries offline (via cron jobs), store results in your database, and serve instant results via MCP. This is how Bloomberg, Nansen, and Arkham work.
+
+```python
+# ❌ BAD: Raw access (timeout-prone, no moat)
+{"name": "run_sql", "description": "Run any SQL against blockchain data"}
+
+# ✅ GOOD: Pre-computed product (instant, defensible)
+{"name": "get_smart_money_wallets", "description": "Top 100 wallets that timed market tops"}
+```
+
+See the [full documentation](https://docs.ctxprotocol.com/guides/build-tools#execution-limits--product-design) for detailed guidance.
+
 ## Context Injection (Personalized Tools)
 
 For tools that analyze user data, Context automatically injects user context:

{ctxprotocol-0.5.6 → ctxprotocol-0.6.0}/README.md

@@ -10,12 +10,26 @@ Context Protocol is **pip for AI capabilities**. Just as you install packages to
 [![Python versions](https://img.shields.io/pypi/pyversions/ctxprotocol.svg)](https://pypi.org/project/ctxprotocol/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+---
+
+### 💰 $10,000 Developer Grant Program
+
+We're funding the initial supply of MCP Tools for the Context Marketplace. **Become a Data Broker.**
+
+- **🛠️ Build:** Create an MCP Server using this SDK (Solana data, Trading tools, Scrapers, etc.)
+- **📦 List:** Publish it to the Context Registry
+- **💵 Earn:** Get a **$250–$1,000 Grant** + earn USDC every time an agent queries your tool
+
+👉 [**View Open Bounties & Apply Here**](https://docs.ctxprotocol.com/grants)
+
+---
+
 ## Why use Context?
 
 - **🔌 One Interface, Everything:** Stop integrating APIs one by one. Use a single SDK to access any tool in the marketplace.
 - **🧠 Zero-Ops:** We're a gateway to the best MCP tools. Just send the JSON and get the result.
 - **⚡️ Agentic Discovery:** Your Agent can search the marketplace at runtime to find tools it didn't know it needed.
-- **💸 Micro-Billing:** Pay only for what you use (e.g., $0.001/query). No monthly subscriptions for tools you rarely use.
+- **💸 Pay-Per-Response:** The $500/year subscription? Now $0.01/response. No monthly fees, just results.
 
 ## Who Is This SDK For?
 
@@ -244,6 +258,22 @@ The SDK implements a **selective authentication** model — discovery is open, e
 
 This matches standard API patterns (OpenAPI schemas are public, GraphQL introspection is open).
 
+## Execution Timeout & Product Design
+
+⚠️ **Important**: MCP tool execution has a **~60 second timeout** (enforced at the platform/client level, not by MCP itself). This is intentional—it encourages building pre-computed insight products rather than raw data access.
+
+**Best practice**: Run heavy queries offline (via cron jobs), store results in your database, and serve instant results via MCP. This is how Bloomberg, Nansen, and Arkham work.
+
+```python
+# ❌ BAD: Raw access (timeout-prone, no moat)
+{"name": "run_sql", "description": "Run any SQL against blockchain data"}
+
+# ✅ GOOD: Pre-computed product (instant, defensible)
+{"name": "get_smart_money_wallets", "description": "Top 100 wallets that timed market tops"}
+```
+
+See the [full documentation](https://docs.ctxprotocol.com/guides/build-tools#execution-limits--product-design) for detailed guidance.
+
 ## Context Injection (Personalized Tools)
 
 For tools that analyze user data, Context automatically injects user context:

{ctxprotocol-0.5.6 → ctxprotocol-0.6.0}/ctxprotocol/__init__.py

@@ -91,6 +91,31 @@ from ctxprotocol.auth import (
     CreateContextMiddlewareOptions,
 )
 
+# Handshake types and helpers for tools that need user interaction
+# (signatures, transactions, OAuth)
+from ctxprotocol.handshake import (
+    # Types
+    HandshakeMeta,
+    EIP712Domain,
+    EIP712TypeField,
+    SignatureRequest,
+    TransactionProposalMeta,
+    TransactionProposal,
+    AuthRequiredMeta,
+    AuthRequired,
+    HandshakeAction,
+    # Type guards
+    is_handshake_action,
+    is_signature_request,
+    is_transaction_proposal,
+    is_auth_required,
+    # Helper functions
+    create_signature_request,
+    create_transaction_proposal,
+    create_auth_required,
+    wrap_handshake_response,
+)
+
 __all__ = [
     # Version
     "__version__",
@@ -144,5 +169,25 @@ __all__ = [
     "ContextMiddleware",
     "VerifyRequestOptions",
     "CreateContextMiddlewareOptions",
+    # Handshake types
+    "HandshakeMeta",
+    "EIP712Domain",
+    "EIP712TypeField",
+    "SignatureRequest",
+    "TransactionProposalMeta",
+    "TransactionProposal",
+    "AuthRequiredMeta",
+    "AuthRequired",
+    "HandshakeAction",
+    # Handshake type guards
+    "is_handshake_action",
+    "is_signature_request",
+    "is_transaction_proposal",
+    "is_auth_required",
+    # Handshake helper functions
+    "create_signature_request",
+    "create_transaction_proposal",
+    "create_auth_required",
+    "wrap_handshake_response",
 ]
 

{ctxprotocol-0.5.6 → ctxprotocol-0.6.0}/ctxprotocol/auth/__init__.py

@@ -38,6 +38,54 @@ weipe6amt9lzQzi8WXaFKpOXHQs//WDlUytz/Hl8pvd5craZKzo6Kyrg1Vfan7H3
 TQIDAQAB
 -----END PUBLIC KEY-----"""
 
+# ============================================================================
+# JWKS Key Fetching (with hardcoded fallback)
+# ============================================================================
+
+JWKS_URL = "https://ctxprotocol.com/.well-known/jwks.json"
+_KEY_CACHE_TTL_SECONDS = 3600  # 1 hour
+
+_cached_public_key: Any = None
+_cache_timestamp: float = 0
+
+
+async def _get_platform_public_key() -> Any:
+    """Get the platform public key, trying JWKS endpoint first with hardcoded fallback.
+    
+    Caches the result for 1 hour.
+    """
+    import time
+    global _cached_public_key, _cache_timestamp
+
+    now = time.time()
+
+    # Return cached key if still valid
+    if _cached_public_key is not None and now - _cache_timestamp < _KEY_CACHE_TTL_SECONDS:
+        return _cached_public_key
+
+    # Try JWKS endpoint first
+    try:
+        import httpx
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            response = await client.get(JWKS_URL)
+            if response.is_success:
+                jwks = response.json()
+                if jwks.get("keys") and len(jwks["keys"]) > 0:
+                    # For now, use hardcoded key (JWKS parsing requires additional logic)
+                    # This establishes the pattern for when the endpoint is deployed
+                    pass
+    except Exception:
+        # JWKS fetch failed - fall back to hardcoded key
+        pass
+
+    # Fallback: use hardcoded key
+    _cached_public_key = serialization.load_pem_public_key(
+        CONTEXT_PLATFORM_PUBLIC_KEY_PEM.encode()
+    )
+    _cache_timestamp = now
+    return _cached_public_key
+
+
 # MCP methods that require authentication
 # - tools/call: Executes tool logic, may cost money
 # - resources/read: Reads potentially sensitive data
@@ -155,10 +203,8 @@ async def verify_context_request(
     token = authorization_header.split(" ", 1)[1]
 
     try:
-        # Load the public key
-        public_key = serialization.load_pem_public_key(
-            CONTEXT_PLATFORM_PUBLIC_KEY_PEM.encode()
-        )
+        # Load the public key (tries JWKS endpoint first, falls back to hardcoded)
+        public_key = await _get_platform_public_key()
 
         # Build decode options - match TypeScript SDK behavior
         decode_options: dict[str, Any] = {
@@ -300,22 +346,74 @@ class ContextMiddleware:
             await self.app(scope, receive, send)
             return
 
-        # We need to read the body to check the method
-        # This is a simplified version - in production you might want to
-        # use a more sophisticated approach to avoid reading the body twice
+        # Buffer the request body to inspect the MCP method
         body_parts: list[bytes] = []
+        body_complete = False
 
         async def receive_wrapper() -> dict[str, Any]:
+            nonlocal body_complete
+            if body_parts and body_complete:
+                # Replay the buffered body
+                body = b"".join(body_parts)
+                return {"type": "http.request", "body": body, "more_body": False}
+
             message = await receive()
             if message["type"] == "http.request":
                 body_parts.append(message.get("body", b""))
+                if not message.get("more_body", False):
+                    body_complete = True
             return message
 
-        # For this middleware to work properly with body reading,
-        # we need a stateful request object. In FastAPI/Starlette,
-        # this is typically handled at the Request level.
-        # Here we just pass through and let the endpoint handle auth.
-        await self.app(scope, receive, send)
+        # Read the body to check the method
+        while not body_complete:
+            await receive_wrapper()
+
+        # Parse the body to get the MCP method
+        try:
+            import json
+            body_bytes = b"".join(body_parts)
+            body_json = json.loads(body_bytes)
+            method = body_json.get("method", "")
+        except Exception:
+            # Can't parse body - let the endpoint handle it
+            await self.app(scope, receive_wrapper, send)
+            return
+
+        # Allow discovery methods without authentication
+        if not method or not is_protected_mcp_method(method):
+            await self.app(scope, receive_wrapper, send)
+            return
+
+        # Protected method - require authentication
+        # Extract Authorization header from ASGI scope
+        headers = dict(scope.get("headers", []))
+        auth_header = headers.get(b"authorization", b"").decode("utf-8")
+
+        try:
+            payload = await verify_context_request(
+                authorization_header=auth_header if auth_header else None,
+                audience=self.audience,
+            )
+            # Attach payload to scope state for downstream use
+            if "state" not in scope:
+                scope["state"] = {}
+            scope["state"]["context"] = payload
+            await self.app(scope, receive_wrapper, send)
+        except ContextError as e:
+            # Return 401 JSON response
+            import json
+            response_body = json.dumps({"error": str(e)}).encode("utf-8")
+            await send({
+                "type": "http.response.start",
+                "status": e.status_code or 401,
+                "headers": [
+                    [b"content-type", b"application/json"],
+                ],
+            })
+            await send({
+                "type": "http.response.body",
+                "body": response_body,
+            })
 
 
 def create_context_middleware(
@@ -380,6 +478,7 @@ def create_context_middleware(
 __all__ = [
     # Constants
     "CONTEXT_PLATFORM_PUBLIC_KEY_PEM",
+    "JWKS_URL",
     "PROTECTED_MCP_METHODS",
     "OPEN_MCP_METHODS",
     # Method classification

{ctxprotocol-0.5.6 → ctxprotocol-0.6.0}/ctxprotocol/client/resources/discovery.py

@@ -46,7 +46,8 @@ class Discovery:
         if limit is not None:
             params["limit"] = str(limit)
 
-        query_string = "&".join(f"{k}={v}" for k, v in params.items())
+        from urllib.parse import urlencode
+        query_string = urlencode(params) if params else ""
         endpoint = f"/api/v1/tools/search{'?' + query_string if query_string else ''}"
 
         response = await self._client.fetch(endpoint)

{ctxprotocol-0.5.6 → ctxprotocol-0.6.0}/ctxprotocol/client/resources/tools.py

@@ -82,7 +82,7 @@ class Tools:
             raise ContextError(
                 message=error_response.error,
                 code=error_response.code,
-                status_code=400,
+                status_code=None,  # Don't hardcode - this was a 200 OK with error body
                 help_url=error_response.help_url,
             )
 

{ctxprotocol-0.5.6 → ctxprotocol-0.6.0}/ctxprotocol/client/types.py

@@ -60,9 +60,13 @@ class Tool(BaseModel):
         price: Price per execution in USDC
         category: Tool category (e.g., "defi", "nft")
         is_verified: Whether the tool is verified by Context Protocol
+        kind: Tool type - currently always "mcp"
         mcp_tools: Available MCP tool methods
-        created_at: Creation timestamp
-        updated_at: Last update timestamp
+        total_queries: Total number of queries processed
+        success_rate: Success rate percentage (0-100)
+        uptime_percent: Uptime percentage (0-100)
+        total_staked: Total USDC staked by the developer
+        is_proven: Whether the tool has "Proven" status
     """
 
     id: str = Field(..., description="Unique identifier for the tool (UUID)")
@@ -75,20 +79,39 @@ class Tool(BaseModel):
         alias="isVerified",
         description="Whether the tool is verified by Context Protocol",
     )
+    kind: str | None = Field(
+        default=None,
+        description="Tool type - currently always 'mcp'",
+    )
     mcp_tools: list[McpTool] | None = Field(
         default=None,
         alias="mcpTools",
         description="Available MCP tool methods",
     )
-    created_at: str | None = Field(
+    total_queries: int | None = Field(
+        default=None,
+        alias="totalQueries",
+        description="Total number of queries processed",
+    )
+    success_rate: str | None = Field(
+        default=None,
+        alias="successRate",
+        description="Success rate percentage",
+    )
+    uptime_percent: str | None = Field(
+        default=None,
+        alias="uptimePercent",
+        description="Uptime percentage",
+    )
+    total_staked: str | None = Field(
         default=None,
-        alias="createdAt",
-        description="Creation timestamp",
+        alias="totalStaked",
+        description="Total USDC staked by developer",
     )
-    updated_at: str | None = Field(
+    is_proven: bool | None = Field(
         default=None,
-        alias="updatedAt",
-        description="Last update timestamp",
+        alias="isProven",
+        description="Whether tool has Proven status",
     )
 
     model_config = {"populate_by_name": True}

{ctxprotocol-0.5.6 → ctxprotocol-0.6.0}/ctxprotocol/context/__init__.py

@@ -69,24 +69,37 @@ from ctxprotocol.context.hyperliquid import (
 
 CONTEXT_REQUIREMENTS_KEY = "x-context-requirements"
 """
-JSON Schema extension key for declaring context requirements.
+DEPRECATED: Use _meta.contextRequirements instead.
 
-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
+The primary mechanism for declaring context requirements is via the MCP _meta field
+at the tool level, which is preserved by the MCP SDK through transport:
 
-Example:
     >>> tool = {
     ...     "name": "analyze_my_positions",
+    ...     "_meta": {"contextRequirements": ["hyperliquid"]},
     ...     "inputSchema": {
     ...         "type": "object",
-    ...         CONTEXT_REQUIREMENTS_KEY: ["hyperliquid"],
     ...         "properties": {"portfolio": {"type": "object"}},
     ...         "required": ["portfolio"]
     ...     }
     ... }
+
+This constant is kept for backwards compatibility but _meta.contextRequirements
+is what the Context Platform reads. The x-context-requirements inputSchema extension
+may be stripped by some MCP transports.
+"""
+
+META_CONTEXT_REQUIREMENTS_KEY = "contextRequirements"
+"""
+The key used inside _meta to declare context requirements.
+This is the primary mechanism - the Context Platform reads _meta.contextRequirements.
+
+Example:
+    >>> tool = {
+    ...     "name": "analyze_positions",
+    ...     "_meta": {META_CONTEXT_REQUIREMENTS_KEY: ["hyperliquid"]},
+    ...     "inputSchema": {...}
+    ... }
 """
 
 # Context requirement types supported by the Context marketplace
@@ -158,6 +171,7 @@ class UserContext(BaseModel):
 __all__ = [
     # Constants
     "CONTEXT_REQUIREMENTS_KEY",
+    "META_CONTEXT_REQUIREMENTS_KEY",
     # Type aliases
     "ContextRequirementType",
     # Wallet types