ctxprotocol 0.5.5__tar.gz → 0.5.7__tar.gz

ctxprotocol-0.5.7/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+
+# md files
+*.md
+!README.md
+!docs/mcp-builder-template.md
+
+# Shell scripts (deployment)
+*.sh
+
+

{ctxprotocol-0.5.5 → ctxprotocol-0.5.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxprotocol
-Version: 0.5.5
+Version: 0.5.7
 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?
 
@@ -263,15 +277,40 @@ if is_protected_mcp_method(body["method"]):
         raise HTTPException(status_code=401, detail="Unauthorized")
 ```
 
-### Security Model
+### MCP Security Model
+
+The SDK implements a **selective authentication** model — discovery is open, execution is protected:
 
-| MCP Method | Auth Required | Reason |
-|------------|---------------|--------|
-| `tools/list` | ❌ No | Discovery - just returns tool schemas |
-| `tools/call` | ✅ Yes | Execution - runs code, may cost money |
+| MCP Method | Auth Required | Why |
+|------------|---------------|-----|
 | `initialize` | ❌ No | Session setup |
+| `tools/list` | ❌ No | Discovery - agents need to see your schemas |
 | `resources/list` | ❌ No | Discovery |
 | `prompts/list` | ❌ No | Discovery |
+| `tools/call` | ✅ **Yes** | **Execution - costs money, runs your code** |
+
+**What this means in practice:**
+- ✅ `https://your-mcp.com/mcp` + `initialize` → Works without auth
+- ✅ `https://your-mcp.com/mcp` + `tools/list` → Works without auth  
+- ❌ `https://your-mcp.com/mcp` + `tools/call` → **Requires Context Protocol JWT**
+
+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)
 

{ctxprotocol-0.5.5 → ctxprotocol-0.5.7}/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?
 
@@ -225,15 +239,40 @@ if is_protected_mcp_method(body["method"]):
         raise HTTPException(status_code=401, detail="Unauthorized")
 ```
 
-### Security Model
+### MCP Security Model
+
+The SDK implements a **selective authentication** model — discovery is open, execution is protected:
 
-| MCP Method | Auth Required | Reason |
-|------------|---------------|--------|
-| `tools/list` | ❌ No | Discovery - just returns tool schemas |
-| `tools/call` | ✅ Yes | Execution - runs code, may cost money |
+| MCP Method | Auth Required | Why |
+|------------|---------------|-----|
 | `initialize` | ❌ No | Session setup |
+| `tools/list` | ❌ No | Discovery - agents need to see your schemas |
 | `resources/list` | ❌ No | Discovery |
 | `prompts/list` | ❌ No | Discovery |
+| `tools/call` | ✅ **Yes** | **Execution - costs money, runs your code** |
+
+**What this means in practice:**
+- ✅ `https://your-mcp.com/mcp` + `initialize` → Works without auth
+- ✅ `https://your-mcp.com/mcp` + `tools/list` → Works without auth  
+- ❌ `https://your-mcp.com/mcp` + `tools/call` → **Requires Context Protocol JWT**
+
+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)
 

{ctxprotocol-0.5.5 → ctxprotocol-0.5.7}/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.5 → ctxprotocol-0.5.7}/ctxprotocol/auth/__init__.py

@@ -160,17 +160,32 @@ async def verify_context_request(
             CONTEXT_PLATFORM_PUBLIC_KEY_PEM.encode()
         )
 
+        # Build decode options - match TypeScript SDK behavior
+        decode_options: dict[str, Any] = {
+            "verify_signature": True,
+            "verify_exp": True,
+            "verify_iat": True,
+            "require": ["exp", "iat"],
+        }
+        
+        # Only verify issuer if we expect it (TypeScript SDK does this)
+        # But don't require it in case the platform doesn't always include it
+        decode_options["verify_iss"] = True
+        
+        # Only verify audience if explicitly provided
+        if audience:
+            decode_options["verify_aud"] = True
+        else:
+            decode_options["verify_aud"] = False
+
         # Verify the JWT
         payload = jwt.decode(
             token,
             public_key,
             algorithms=["RS256"],
             issuer="https://ctxprotocol.com",
-            audience=audience,
-            options={
-                "require": ["iss", "sub", "exp", "iat"],
-                "verify_aud": audience is not None,
-            },
+            audience=audience if audience else None,
+            options=decode_options,
         )
 
         return payload
@@ -193,9 +208,21 @@ async def verify_context_request(
             code="unauthorized",
             status_code=401,
         )
-    except jwt.PyJWTError:
+    except jwt.DecodeError as e:
+        raise ContextError(
+            message=f"JWT decode error: {e}",
+            code="unauthorized",
+            status_code=401,
+        )
+    except jwt.InvalidSignatureError:
+        raise ContextError(
+            message="Invalid JWT signature",
+            code="unauthorized",
+            status_code=401,
+        )
+    except jwt.PyJWTError as e:
         raise ContextError(
-            message="Invalid Context Protocol signature",
+            message=f"JWT verification failed: {e}",
             code="unauthorized",
             status_code=401,
         )