traia-iatp 0.1.29__py3-none-any.whl

traia_iatp/mcp/templates/README.md.j2

@@ -0,0 +1,310 @@
+# {{ api_name }} MCP Server
+
+This is an MCP (Model Context Protocol) server that provides{{ auth_details }} access to the {{ api_name }} API. It enables AI agents and LLMs to interact with {{ api_name }} through standardized tools.
+
+## Features
+
+- 🔧 **MCP Protocol**: Built on the Model Context Protocol for seamless AI integration
+- 🌐 **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
+
+## API Documentation
+
+- **{{ api_name }} Website**: [{{ api_url }}]({{ api_url }})
+- **API Documentation**: [{{ docs_url }}]({{ docs_url }})
+
+## Available Tools
+
+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.*
+
+## Installation
+
+### Using Docker (Recommended)
+
+1. Clone this repository:
+   ```bash
+   git clone https://github.com/Traia-IO/{{ api_slug }}-mcp-server.git
+   cd {{ api_slug }}-mcp-server
+   ```
+
+{% if requires_auth %}
+2. Set your API key:
+   ```bash
+   export {{ api_key_env_var }}="your-api-key-here"
+   ```
+
+3. Run with Docker:
+{% else %}
+2. Run with Docker:
+{% endif %}
+   ```bash
+   ./run_local_docker.sh
+   ```
+
+### Using Docker Compose
+
+1. Create a `.env` file with your configuration:
+   ```env
+   {% 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
+   ```
+
+2. Start the server:
+   ```bash
+   docker-compose up
+   ```
+
+### Manual Installation
+
+1. Install dependencies using `uv`:
+   ```bash
+   uv pip install -e .
+   ```
+
+2. Run the server:
+   ```bash
+   {% if requires_auth %}{{ api_key_env_var }}="your-api-key-here" {% endif %}uv run python -m server
+   ```
+
+## Usage
+
+### Health Check
+
+Test if the server is running:
+```bash
+python mcp_health_check.py
+```
+
+### Using with CrewAI
+
+```python
+{% if requires_auth %}from traia_iatp.mcp.traia_mcp_adapter import create_mcp_adapter_with_auth
+
+# Connect with authentication
+with create_mcp_adapter_with_auth(
+    url="http://localhost:8000/mcp/",
+    api_key="your-api-key"
+) as tools:
+    # Use the tools
+    for tool in tools:
+        print(f"Available tool: {tool.name}")
+        
+    # Example usage
+    result = await tool.example_tool(query="test")
+    print(result)
+{% else %}from traia_iatp.mcp.traia_mcp_adapter import create_mcp_adapter
+
+# Connect to the MCP server
+with create_mcp_adapter(
+    url="http://localhost:8000/mcp/"
+) as tools:
+    # Use the tools
+    for tool in tools:
+        print(f"Available tool: {tool.name}")
+        
+    # Example usage
+    result = await tool.example_tool(query="test")
+    print(result)
+{% endif %}
+```
+
+{% if requires_auth %}
+## Authentication & Payment (HTTP 402 Protocol)
+
+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"}}}'
+```
+
+**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
+```
+
+**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
+
+### Testing the Server
+
+1. Start the server locally
+2. Run the health check: `python mcp_health_check.py`
+3. Test individual tools using the CrewAI adapter
+
+### Adding New Tools
+
+To add new tools, edit `server.py` and:
+
+1. Create API client functions for {{ api_name }} endpoints
+2. Add `@mcp.tool()` decorated functions
+3. Update this README with the new tools
+4. Update `deployment_params.json` with the tool names in the capabilities array
+
+## Deployment
+
+### Deployment Configuration
+
+The `deployment_params.json` file contains the deployment configuration for this MCP server:
+
+```json
+{
+  "github_url": "https://github.com/Traia-IO/{{ api_slug }}-mcp-server",
+  "mcp_server": {
+    "name": "{{ api_slug }}-mcp",
+    "description": "{{ api_description|capitalize }}",
+    "server_type": "streamable-http",
+    {% if requires_auth %}"requires_api_key": true,
+    "api_key_header": "Authorization",
+    {% endif %}"capabilities": [
+      // List all implemented tool names here
+      "example_tool",
+      "get_api_info"
+    ]
+  },
+  "deployment_method": "cloud_run",
+  "gcp_project_id": "traia-mcp-servers",
+  "gcp_region": "us-central1",
+  "tags": ["{{ api_name_lower }}", "api"],
+  "ref": "main"
+}
+```
+
+**Important**: Always update the `capabilities` array when you add or remove tools!
+
+### Google Cloud Run
+
+This server is designed to be deployed on Google Cloud Run. The deployment will:
+
+1. Build a container from the Dockerfile
+2. Deploy to Cloud Run with the specified configuration
+3. Expose the `/mcp` endpoint for client connections
+
+## Environment Variables
+
+- `PORT`: Server port (default: 8000)
+- `STAGE`: Environment stage (default: MAINNET, options: MAINNET, TESTNET)
+- `LOG_LEVEL`: Logging level (default: INFO)
+{% if requires_auth %}- `{{ api_key_env_var }}`: Your {{ api_name }} API key (required){% endif %}
+
+## Troubleshooting
+
+1. **Server not starting**: Check Docker logs with `docker logs <container-id>`
+{% if requires_auth %}2. **Authentication errors**: Ensure your API key is correctly set in the environment
+3. **API errors**: Verify your API key has the necessary permissions{% else %}2. **Connection errors**: Ensure the server is running on the expected port{% endif %}
+3. **Tool errors**: Check the server logs for detailed error messages
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Implement new tools or improvements
+4. Update the README and deployment_params.json
+5. Submit a pull request
+
+## License
+
+[MIT License](LICENSE)