traia-iatp 0.1.2__py3-none-any.whl → 0.1.67__py3-none-any.whl

traia_iatp/mcp/templates/Dockerfile.j2

@@ -25,7 +25,31 @@ USER appuser
 # Copy project files
 COPY --chown=appuser:appuser . .
 
+# Copy IATP package if available (for local development only)
+# This Dockerfile works for both local and remote deployments:
+# 
+# LOCAL DEPLOYMENT (via run_local_docker.sh):
+#   - run_local_docker.sh detects local IATP path in pyproject.toml
+#   - Copies IATP to .docker-iatp/IATP before building
+#   - Temporarily modifies pyproject.toml to use file:///tmp/IATP
+#   - Dockerfile finds .docker-iatp/IATP and copies it to /tmp/IATP
+#   - uv install uses the local IATP from /tmp/IATP
+#
+# REMOTE DEPLOYMENT (Cloud Run, etc.):
+#   - .docker-iatp/IATP does NOT exist in build context
+#   - pyproject.toml has published version (traia-iatp>=0.1.27)
+#   - Dockerfile skips IATP copy, uv install uses published package
+#
+RUN if [ -d .docker-iatp/IATP ]; then \
+        cp -r .docker-iatp/IATP /tmp/IATP && \
+        echo "Using local IATP package (local development mode)"; \
+    else \
+        echo "Using published IATP package (remote deployment mode)"; \
+    fi
+
 # Install Python dependencies
+# - Local mode: pyproject.toml references file:///tmp/IATP (set by run_local_docker.sh)
+# - Remote mode: pyproject.toml references traia-iatp>=0.1.27 (from template)
 RUN uv venv .venv && \
     uv pip install -r pyproject.toml
 
@@ -36,7 +60,6 @@ ENV HOST=0.0.0.0
 ENV PYTHONUNBUFFERED=1
 ENV UV_SYSTEM_PYTHON=1
 ENV STAGE=MAINNET
-ENV PORT=8000
 ENV LOG_LEVEL=INFO
 {% if environment_variables %}
 # Additional environment variables
@@ -45,12 +68,12 @@ ENV {{ env_var.name }}="{{ env_var.value }}"
 {% endfor %}
 {% endif %}
 
-# Health check
+# Health check - uses dedicated health endpoint
 HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
-    CMD curl -f http://localhost:${PORT:-8000}/health || exit 1
+    CMD curl -f http://localhost:${PORT:-8080}/health || exit 1
 
 # Expose port (uses PORT environment variable with default)
-EXPOSE ${PORT:-8000}
+EXPOSE ${PORT:-8080}
 
 # Run the application
 CMD ["uv", "run", "python", "server.py"] 

traia_iatp/mcp/templates/README.md.j2

@@ -8,6 +8,8 @@ This is an MCP (Model Context Protocol) server that provides{{ auth_details }} a
 - 🌐 **Full API Access**: Provides tools for interacting with {{ api_name }} endpoints
 {% if requires_auth %}
 - 🔐 **Secure Authentication**: Supports API key authentication via Bearer tokens
+- 💳 **HTTP 402 Payment Protocol**: Dual-mode operation (authenticated or paid access)
+- 🔗 **D402 Integration**: Uses traia_iatp.d402 for blockchain payment verification
 {% endif %}
 - 🐳 **Docker Support**: Easy deployment with Docker and Docker Compose
 - ⚡ **Async Operations**: Built with FastMCP for efficient async handling
@@ -22,7 +24,6 @@ This is an MCP (Model Context Protocol) server that provides{{ auth_details }} a
 This server provides the following tools:
 
 - **`example_tool`**: Placeholder tool (to be implemented)
-- **`get_api_info`**: Get information about the API service and authentication status
 
 *Note: Replace `example_tool` with actual {{ api_name }} API tools based on the documentation.*
 
@@ -54,7 +55,18 @@ This server provides the following tools:
 
 1. Create a `.env` file with your configuration:
    ```env
-   {% if requires_auth %}{{ api_key_env_var }}=your-api-key-here
+   {% if requires_auth %}# Server's internal API key (for payment mode)
+   {{ api_key_env_var }}=your-api-key-here
+   
+   # Server payment address (for HTTP 402 protocol)
+   SERVER_ADDRESS=0x1234567890123456789012345678901234567890
+   
+   # Operator keys (for signing settlement attestations)
+   MCP_OPERATOR_PRIVATE_KEY=0x1234567890abcdef...
+   MCP_OPERATOR_ADDRESS=0x9876543210fedcba...
+   
+   # Optional: Testing mode (skip settlement for local dev)
+   D402_TESTING_MODE=false
    {% endif %}PORT=8000
    ```
 
@@ -118,15 +130,100 @@ with create_mcp_adapter(
 ```
 
 {% if requires_auth %}
-## Authentication
+## Authentication & Payment (HTTP 402 Protocol)
 
-This server requires API key authentication. Clients must provide their API key in the `Authorization` header:
+This server supports **two modes of operation**:
 
+### Mode 1: Authenticated Access (Free)
+
+Clients with their own {{ api_name }} API key can use the server for free:
+
+```bash
+# Request with client's API key
+curl -X POST http://localhost:8000/mcp \
+  -H "Authorization: Bearer CLIENT_{{ api_key_env_var }}" \
+  -H "Content-Type: application/json" \
+  -d '{"method":"tools/call","params":{"name":"example_tool","arguments":{"query":"test"}}}'
 ```
-Authorization: Bearer YOUR_API_KEY
+
+**Flow**:
+1. Client provides their {{ api_name }} API key
+2. Server uses client's API key to call {{ api_name }} API
+3. No payment required
+4. Client pays {{ api_name }} directly
+
+### Mode 2: Payment Required (Paid Access)
+
+Clients without an API key can pay-per-use via HTTP 402 protocol:
+
+```bash
+# Request with payment proof (x402/d402 protocol)
+curl -X POST http://localhost:8000/mcp \
+  -H "X-PAYMENT: <base64_encoded_x402_payment>" \
+  -H "Content-Type: application/json" \
+  -d '{"method":"tools/call","params":{"name":"example_tool","arguments":{"query":"test"}}}'
+```
+
+**Flow**:
+1. Client makes initial request without payment
+2. Server returns HTTP 402 with PaymentRequirements (token, network, amount)
+3. Client creates EIP-3009 transferWithAuthorization payment signature
+4. Client base64-encodes payment and sends in X-PAYMENT header
+5. Server verifies payment via traia_iatp.d402.mcp_middleware
+6. Server uses its INTERNAL {{ api_name }} API key to call the API
+7. Client receives result
+
+### D402 Protocol Details
+
+This server uses the **traia_iatp.d402** module for payment verification:
+
+- **Payment Method**: EIP-3009 transferWithAuthorization (gasless)
+- **Supported Tokens**: USDC, TRAIA, or any ERC20 token
+- **Default Price**: $0.001 per request (configurable via `DEFAULT_PRICE_USD`)
+- **Networks**: Base Sepolia, Sepolia, Polygon, etc.
+- **Facilitator**: d402.org (public) or custom facilitator
+
+### Environment Variables for Payment Mode
+
+```bash
+# Required
+{{ api_key_env_var }}=your_internal_{{ api_slug }}_api_key  # Server's API key (for payment mode)
+SERVER_ADDRESS=0x1234567890123456789012345678901234567890  # Server's payment address
+
+# Required for Settlement (Production)
+MCP_OPERATOR_PRIVATE_KEY=0x1234...  # Private key for signing settlement attestations
+MCP_OPERATOR_ADDRESS=0x5678...      # Operator's public address (for verification)
+
+# Optional
+D402_FACILITATOR_URL=https://facilitator.d402.net  # Facilitator service URL
+D402_FACILITATOR_API_KEY=your_key  # For private facilitator
+D402_TESTING_MODE=false  # Set to 'true' for local testing without settlement
 ```
 
-The API key is then used to authenticate requests to the {{ api_name }} API.
+**Operator Keys**:
+- **MCP_OPERATOR_PRIVATE_KEY**: Used to sign settlement attestations (proof of service completion)
+- **MCP_OPERATOR_ADDRESS**: Public address corresponding to the private key
+- Required for on-chain settlement via IATP Settlement Layer
+- Can be the same as SERVER_ADDRESS or a separate operator key
+
+**Note on Per-Endpoint Configuration**:
+Each endpoint's payment requirements (token address, network, price) are embedded in the tool code.
+They come from the endpoint configuration when the server is generated.
+
+### How It Works
+
+1. **Client Decision**:
+   - Has {{ api_name }} API key? → Mode 1 (Authenticated)
+   - No API key but willing to pay? → Mode 2 (Payment)
+
+2. **Server Response**:
+   - Mode 1: Uses client's API key (free for client)
+   - Mode 2: Uses server's API key (client pays server)
+
+3. **Business Model**:
+   - Mode 1: No revenue (passthrough)
+   - Mode 2: Revenue from pay-per-use (monetize server's API subscription)
+
 {% endif %}
 
 ## Development
@@ -163,8 +260,7 @@ The `deployment_params.json` file contains the deployment configuration for this
     "api_key_header": "Authorization",
     {% endif %}"capabilities": [
       // List all implemented tool names here
-      "example_tool",
-      "get_api_info"
+      "example_tool"
     ]
   },
   "deployment_method": "cloud_run",

traia_iatp/mcp/templates/cursor-rules.md.j2

@@ -12,6 +12,200 @@ You are working on implementing the {{ api_name }} MCP (Model Context Protocol)
 {% endif %}
 - **Authentication**: {% if requires_auth %}Required - API key via `{{ api_key_env_var }}` environment variable{% else %}Not required{% endif %}
 
+{% if requires_auth %}
+## 🔒 HTTP 402 Payment Protocol - Dual-Mode Operation
+
+This MCP server implements the **HTTP 402 Payment Required** protocol using the **traia_iatp.d402** module with dual-mode support:
+
+### Mode 1: Authenticated (Free Access)
+
+When a client provides their own {{ api_name }} API key:
+
+```
+Request Headers:
+  Authorization: Bearer CLIENT_API_KEY
+
+Flow:
+  1. Client connects with their {{ api_name }} API key
+  2. MCP server uses client's API key to call {{ api_name }} API
+  3. No payment required
+  4. Client pays {{ api_name }} directly (not the MCP server)
+```
+
+**Use Case**: Clients who already have a {{ api_name }} subscription/API key
+
+### Mode 2: Payment Required (Paid Access)
+
+When a client doesn't have their own API key but pays via x402/d402 protocol:
+
+```
+Request Headers:
+  X-PAYMENT: <base64_encoded_x402_payment>
+
+X402 Payment Header Format (created by x402.clients.base.create_payment_header()):
+  {
+    "x402Version": 1,
+    "scheme": "exact",
+    "network": "base-sepolia",
+    "payload": {
+      "signature": "0x...",
+      "authorization": {
+        "from": "0xCLIENT_ADDRESS",
+        "to": "0xSERVER_ADDRESS",
+        "value": "1000",  // atomic units (wei)
+        "validAfter": "1700000000",
+        "validBefore": "1700000300",
+        "nonce": "hex..."
+      }
+    }
+  }
+
+Flow:
+  1. Client creates EIP-3009 transferWithAuthorization signature
+  2. Client sends Payment header with encoded payment payload
+  3. MCP server verifies payment using traia_iatp.d402.facilitator
+  4. MCP server uses its INTERNAL {{ api_name }} API key to call the API
+  5. Client pays the MCP server (not {{ api_name }})
+```
+
+**Use Case**: Pay-per-use clients without their own {{ api_name }} subscription
+
+### D402 Protocol Integration
+
+This server uses the **traia_iatp.d402** module which implements:
+- EIP-3009 transferWithAuthorization for gasless payments
+- Payment verification via IATP Settlement Facilitator
+- On-chain transaction verification
+- Multiple token support (USDC, TRAIA, etc.)
+
+**Dependencies** (already in pyproject.toml):
+- `traia-iatp>=0.1.27` - Provides d402 module
+- `web3>=6.15.0` - For blockchain verification
+
+### Implementation Pattern for Tools
+
+**For auto-generated tools** (from OpenAPI), the endpoint implementer will generate code like this:
+
+```python
+from traia_iatp.d402.mcp_middleware import EndpointPaymentInfo, verify_endpoint_payment
+
+@mcp.tool()
+async def your_tool_name(context: Context, param1: str) -> Dict[str, Any]:
+    """Your tool description."""
+    
+    # Get client's API key (if provided)
+    api_key = get_session_api_key(context)
+    
+    # If no API key, verify payment for this specific endpoint
+    if not api_key:
+        # Each endpoint has specific payment requirements
+        endpoint_payment = EndpointPaymentInfo(
+            settlement_token_address="0xUSDC...",  # From endpoint config
+            settlement_token_network="base-sepolia",  # From endpoint config
+            payment_price_float=0.001,  # From endpoint config
+            payment_price_wei="1000",  # From endpoint config
+            server_address="0xSERVER..."  # Server's payment address
+        )
+        
+        # Verify payment matches this endpoint's requirements
+        if not verify_endpoint_payment(context, endpoint_payment):
+            return {
+                "error": "Payment required or insufficient",
+                "code": 402,
+                "required_payment": {
+                    "token": "0xUSDC...",
+                    "network": "base-sepolia",
+                    "amount": 0.001
+                }
+            }
+    
+    # Dual-mode: determine which API key to use
+    if api_key:
+        # MODE 1: Use client's API key (free for client)
+        api_key_to_use = api_key
+    else:
+        # MODE 2: Use server's internal API key (client paid)
+        api_key_to_use = os.getenv("{{ api_key_env_var }}")
+    
+    # Call API
+    headers = {"Authorization": f"Bearer {api_key_to_use}"}
+    response = requests.get("{{ api_url }}/endpoint", headers=headers)
+    return response.json()
+```
+
+**Key points**:
+1. Each tool verifies payment against **its specific endpoint requirements**
+2. Different endpoints can have different tokens, networks, and prices
+3. Payment amount/token/network are verified per-endpoint
+4. The middleware just extracts payment payload globally
+
+### Middleware Chain
+
+The server has TWO middleware in sequence:
+
+1. **AuthMiddleware**: Extracts client's API key from Authorization header
+2. **D402MCPMiddleware**: Extracts and validates payment payload from Payment header
+
+### How Per-Endpoint Payment Works
+
+Unlike FastAPI where middleware can be applied per-route, FastMCP has global middleware.
+Therefore:
+
+1. **D402MCPMiddleware**: Extracts payment payload globally, stores in `context.state.payment_payload`
+2. **Each Tool**: Calls `verify_endpoint_payment()` with its specific requirements
+   - Verifies payment token matches endpoint's settlement token
+   - Verifies payment amount meets endpoint's price
+   - Verifies payment network matches endpoint's network
+
+**Result**: Different endpoints can accept different tokens, on different networks, at different prices!
+
+### Environment Variables
+
+**Required**:
+- `{{ api_key_env_var }}`: Server's internal {{ api_name }} API key (used when clients pay via 402)
+- `SERVER_ADDRESS`: MCP server's payment address (where 402 payments are sent)
+
+**Required for Settlement (Production)**:
+- `MCP_OPERATOR_PRIVATE_KEY`: Private key for signing settlement attestations (proof of service completion)
+- `MCP_OPERATOR_ADDRESS`: Public address corresponding to operator private key (for verification)
+
+**Optional**:
+- `D402_FACILITATOR_URL`: Custom d402 facilitator URL (default: "https://facilitator.d402.net")
+- `D402_FACILITATOR_API_KEY`: API key for private facilitator
+- `D402_TESTING_MODE`: Set to "true" for local testing without settlement (default: "false")
+
+**Example .env file**:
+```bash
+# API Authentication (server's internal key for payment mode)
+{{ api_key_env_var }}=your_{{ api_slug }}_api_key_here
+
+# Server Payment Address (where 402 payments are received)
+SERVER_ADDRESS=0x1234567890123456789012345678901234567890
+
+# Operator Keys (for signing settlement attestations)
+MCP_OPERATOR_PRIVATE_KEY=0x1234567890abcdef...  # Keep secure!
+MCP_OPERATOR_ADDRESS=0x9876543210fedcba...      # Derived from private key
+
+# Optional: Custom facilitator
+D402_FACILITATOR_URL=https://facilitator.d402.net
+D402_FACILITATOR_API_KEY=facilitator_api_key
+
+# Optional: Testing mode (skip settlement for local dev)
+D402_TESTING_MODE=false  # Set to 'true' for testing without facilitator
+```
+
+**About Operator Keys**:
+- The operator signs settlement attestations after completing each paid request
+- Attestation proves: service was completed + output hash is valid
+- Can use the same key as SERVER_ADDRESS or a separate signing key
+- Required for on-chain settlement via IATP Settlement Layer
+
+**Note on Endpoint-Specific Configuration**:
+Each endpoint's payment requirements (token, network, price) are embedded in the tool code.
+These come from the endpoint configuration in the database/OpenAPI schema.
+
+{% endif %}
+
 ## Implementation Checklist
 
 ### 1. Update Deployment Configuration

traia_iatp/mcp/templates/deployment_params.json.j2

@@ -8,8 +8,7 @@
     {% if requires_auth %}"api_key_header": "Authorization",
     "api_keys": ["{{ api_key_env_var }}"],
     {% endif %}"capabilities": [
-      "example_tool",
-      "get_api_info"
+      "example_tool"
     ]
   },
   "deployment_method": "cloud_run",

traia_iatp/mcp/templates/docker-compose.yml.j2

@@ -5,19 +5,29 @@ services:
     build: .
     container_name: {{ api_slug }}-mcp-server
     ports:
-      - "8000:8000"
+      - "8080:8080"
     environment:
       - PORT=8000
       - STAGE=${STAGE:-MAINNET}
       - LOG_LEVEL=${LOG_LEVEL:-INFO}
-{% if api_key_env_var %}
+{% if requires_auth %}
+      # API Authentication (server's internal key for payment mode)
+      # Set this in .env file when deploying (creator provides their master API key)
       - {{ api_key_env_var }}={% raw %}${{% endraw %}{{ api_key_env_var }}{% raw %}}{% endraw %}
 {% endif %}
+      # D402 Payment Protocol Configuration
+      - SERVER_ADDRESS=${SERVER_ADDRESS:-}
+      - MCP_OPERATOR_PRIVATE_KEY=${MCP_OPERATOR_PRIVATE_KEY:-}  # For signing settlement attestations
+      - MCP_OPERATOR_ADDRESS=${MCP_OPERATOR_ADDRESS:-}  # Operator's public address (for verification)
+      - D402_FACILITATOR_URL=${D402_FACILITATOR_URL:-https://test-facilitator.d402.net}
+      - D402_FACILITATOR_API_KEY=${D402_FACILITATOR_API_KEY:-}
+      - D402_TESTING_MODE=${D402_TESTING_MODE:-false}  # Set to 'true' for local testing without facilitator
+      - NETWORK=${NETWORK:-sepolia}
     volumes:
       - ./logs:/app/logs
     restart: unless-stopped
     healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
       interval: 30s
       timeout: 10s
       retries: 3 

traia_iatp/mcp/templates/env.example.j2

@@ -0,0 +1,60 @@
+# {{ api_name }} MCP Server Environment Configuration
+# 
+# IMPORTANT: These values will be set during deployment (Phase 2)
+# This file is a template - actual .env will be created with real values
+
+# ============================================
+# Server Configuration
+# ============================================
+PORT=8080
+STAGE=MAINNET
+LOG_LEVEL=INFO
+
+{% if requires_auth %}
+# ============================================
+# API Authentication (Set during deployment)
+# ============================================
+# Server's internal {{ api_name }} API key
+# This is used when clients pay via HTTP 402 (payment mode)
+# Will be provided by MCP server creator during deployment
+{{ api_key_env_var }}=
+
+{% endif %}
+# ============================================
+# D402 Payment Protocol (Set during deployment)
+# ============================================
+# MCP server's payment address (IATP wallet contract address)
+# Generated during deployment when IATP wallet contract is created
+SERVER_ADDRESS=
+
+# Operator keys for signing settlement attestations
+# Generated during deployment from IATP wallet contract
+MCP_OPERATOR_PRIVATE_KEY=
+MCP_OPERATOR_ADDRESS=
+
+# Facilitator configuration
+# Options:
+#   - Remote (production): https://test-facilitator.d402.net
+#   - Local (development): http://host.docker.internal:7070
+D402_FACILITATOR_URL=https://test-facilitator.d402.net
+D402_FACILITATOR_API_KEY=
+
+# Default settlement token configuration
+# Used as defaults for example tools and fallback for endpoints
+DEFAULT_SETTLEMENT_TOKEN=0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238
+DEFAULT_SETTLEMENT_NETWORK=sepolia
+
+# Testing mode (set to 'true' to bypass facilitator for local testing)
+D402_TESTING_MODE=false
+
+# ============================================
+# Deployment Process
+# ============================================
+# Phase 1 (Completed): Code generation
+# Phase 2 (Next): Deployment via deploy_mcp_lambda_handler
+#   1. Create IATP wallet contract → Get SERVER_ADDRESS
+#   2. Generate operator keys → Get MCP_OPERATOR_PRIVATE_KEY & MCP_OPERATOR_ADDRESS
+#   3. Get API key from creator{% if requires_auth %} → Set {{ api_key_env_var }}{% endif %}
+#   4. Deploy to GCP with actual environment variables
+#   5. Register in MongoDB
+

traia_iatp/mcp/templates/mcp_health_check.py.j2

@@ -91,7 +91,7 @@ def check_mcp_server_health(url: str) -> bool:
             print(f"📋 Available tools: {', '.join(tool_names)}")
             
             # Check for expected tools
-            expected_tools = ["example_tool", "get_api_info"]
+            expected_tools = ["example_tool"]
             missing_tools = [tool for tool in expected_tools if tool not in tool_names]
             
             if missing_tools:
@@ -136,7 +136,7 @@ def main():
     
     print(f"🚀 {{ api_name }} MCP Server Health Check")
     print(f"📍 Server URL: {args.url}")
-    print(f"📰 Expected tools: example_tool, get_api_info")
+    print(f"📰 Expected tools: example_tool")
     print("="*50)
     
     if check_mcp_server_health(args.url):

traia_iatp/mcp/templates/pyproject.toml.j2

@@ -1,15 +1,18 @@
 [project]
 name = "{{ api_slug }}-mcp-server"
 version = "0.1.0"
-description = "MCP server for {{ api_name }} API{% if auth_description %} with authentication support{% endif %}"
+description = "MCP server for {{ api_name }} API with {% if auth_description %} authentication and {% endif %} HTTP 402 payment protocol support"
 requires-python = ">=3.12"
 dependencies = [
-    "crewai-tools[mcp]>=0.48.0",
-    "fastmcp>=2.10.1",
+    "anyio>=4.0.0",
+    "mcp>=1.1.2",
     "python-dotenv>=1.1.1",
-    "requests>=2.32.4",
-    "starlette>=0.46.2",
+    "requests>=2.32.5",
+    "starlette>=0.45.0",
     "retry>=0.9.2",
+    "traia-iatp>=0.1.67",  # For d402 payment protocol and RPC fallback support
+    "uvicorn>=0.37.0",
+    "web3>=6.15.0",  # For blockchain payment verification
 {% if sdk_package %}
     "{{ sdk_package }}",
 {% endif %}
@@ -19,6 +22,9 @@ dependencies = [
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.metadata]
+allow-direct-references = true
+
 [tool.hatch.build.targets.wheel]
 include = [
     "server.py",

traia_iatp/mcp/templates/pyrightconfig.json.j2

@@ -0,0 +1,22 @@
+{
+  "include": [
+    "server.py",
+    "mcp_health_check.py"
+  ],
+  "exclude": [
+    "**/__pycache__",
+    ".venv",
+    "**/*.pyc"
+  ],
+  "extraPaths": [
+    "../../../../IATP/src",
+    "/Users/eitanlavi/workspace/traia/IATP/src"
+  ],
+  "pythonVersion": "3.12",
+  "typeCheckingMode": "basic",
+  "reportMissingImports": true,
+  "reportMissingTypeStubs": false,
+  "venvPath": ".",
+  "venv": ".venv"
+}
+