traia-iatp 0.1.1__py3-none-any.whl

traia_iatp/mcp/templates/README.md.j2

@@ -0,0 +1,212 @@
+# {{ 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
+{% 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 %}{{ api_key_env_var }}=your-api-key-here
+   {% 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
+
+This server requires API key authentication. Clients must provide their API key in the `Authorization` header:
+
+```
+Authorization: Bearer YOUR_API_KEY
+```
+
+The API key is then used to authenticate requests to the {{ api_name }} API.
+{% 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)

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

@@ -0,0 +1,326 @@
+# {{ api_name }} MCP Server Implementation Guide
+
+You are working on implementing the {{ api_name }} MCP (Model Context Protocol) server. The basic structure has been set up, and your task is to implement the actual API integration.
+
+## API Information
+
+- **API Name**: {{ api_name }}
+- **Documentation**: [{{ docs_url }}]({{ docs_url }})
+- **Website**: [{{ api_url }}]({{ api_url }})
+{% if sdk_package %}
+- **SDK**: `{{ sdk_package }}` (already included in pyproject.toml)
+{% endif %}
+- **Authentication**: {% if requires_auth %}Required - API key via `{{ api_key_env_var }}` environment variable{% else %}Not required{% endif %}
+
+## Implementation Checklist
+
+### 1. Update Deployment Configuration
+
+**IMPORTANT**: Update the `deployment_params.json` file with all implemented capabilities:
+
+```json
+{
+  "mcp_server": {
+    "capabilities": [
+      // Replace these with your actual implemented tool names
+      "search_{{ api_slug.replace('-', '_') }}",
+      "get_{{ api_slug.replace('-', '_') }}_info",
+      // Add all other tools you implement
+    ]
+  },
+  "tags": ["{{ api_name_lower }}", "api", /* add relevant tags like "search", "data", etc. */]
+}
+```
+
+### 2. Study the API Documentation
+
+First, thoroughly review the API documentation at {{ docs_url }} to understand:
+- Available endpoints
+- Request/response formats
+- Rate limits
+- Error handling
+{% if requires_auth %}- Authentication method (API key placement in headers, query params, etc.){% endif %}
+- Specific features and capabilities to expose as tools
+
+### 3. Implement API Client Functions
+
+Add functions to call the {{ api_name }} API with retry support. Example pattern:
+
+```python
+from retry import retry
+
+{% if sdk_package %}# Using the SDK with retry decorator
+@retry(tries=2, delay=1, backoff=2, jitter=(1, 3))
+def call_{{ api_slug.replace('-', '_') }}_api(endpoint: str, params: Dict[str, Any], api_key: str) -> Dict[str, Any]:
+    """Call {{ api_name }} API using the SDK with automatic retry."""
+    # Initialize the SDK client
+    client = {{ sdk_module }}.Client(api_key=api_key)
+    
+    # Make the API call - will retry once on any exception
+    try:
+        response = client.call_endpoint(params)
+        return response.to_dict()
+    except Exception as e:
+        raise Exception(f"{{ api_name }} API error: {str(e)}")
+{% else %}# Using requests library with retry decorator
+@retry(tries=2, delay=1, backoff=2, jitter=(1, 3))
+def call_{{ api_slug.replace('-', '_') }}_api(endpoint: str, params: Dict[str, Any], api_key: str) -> Dict[str, Any]:
+    """Call {{ api_name }} API endpoint with automatic retry."""
+    base_url = "https://api.example.com/v1"  # TODO: Get actual base URL from docs
+    
+    headers = {
+        {% if requires_auth %}"Authorization": f"Bearer {api_key}",  # Or "X-API-Key": api_key
+        {% endif %}"Content-Type": "application/json"
+    }
+    
+    # Will retry once on any requests.RequestException
+    try:
+        response = requests.get(f"{base_url}/{endpoint}", 
+                              params=params, 
+                              headers=headers,
+                              timeout=30)
+        response.raise_for_status()
+        return response.json()
+    except requests.RequestException as e:
+        raise Exception(f"{{ api_name }} API error: {str(e)}")
+{% endif %}```
+
+#### Retry Configuration Explained
+
+- `tries=2`: Total attempts (1 original + 1 retry)
+- `delay=1`: Wait 1 second before retry
+- `backoff=2`: Multiply delay by 2 for subsequent retries (if more than 2 tries)
+- `jitter=(1, 3)`: Add random delay between 1-3 seconds to avoid thundering herd
+
+### 4. Create MCP Tools
+
+Replace the `example_tool` placeholder with actual tools. **Each tool you implement MUST be added to the `capabilities` array in `deployment_params.json`**.
+
+#### Search/Query Tool
+```python
+@mcp.tool()
+async def search_{{ api_slug.replace('-', '_') }}(
+    context: Context,
+    query: str,
+    limit: int = 10
+) -> Dict[str, Any]:
+    """
+    Search {{ api_name }} for [specific data type].
+    
+    Args:
+        context: MCP context (injected automatically)
+        query: Search query
+        limit: Maximum number of results
+        
+    Returns:
+        Dictionary with search results
+    """
+    {% if requires_auth %}
+    api_key = get_session_api_key(context)
+    if not api_key:
+        return {"error": "No API key found. Please authenticate with Authorization: Bearer YOUR_API_KEY"}
+    {% endif %}
+    
+    try:
+        # The call_{{ api_slug.replace('-', '_') }}_api function already has retry logic
+        results = call_{{ api_slug.replace('-', '_') }}_api(
+            "search",  # TODO: Use actual endpoint
+            {"q": query, "limit": limit},
+            {% if requires_auth %}api_key{% else %}None{% endif %})
+        return {
+            "status": "success",
+            "results": results
+        }
+    except Exception as e:
+        return {"error": str(e)}
+```
+
+#### Get/Fetch Tool
+```python
+@mcp.tool()
+async def get_{{ api_slug.replace('-', '_') }}_info(
+    context: Context,
+    item_id: str
+) -> Dict[str, Any]:
+    """
+    Get detailed information about a specific item.
+    
+    Args:
+        context: MCP context (injected automatically)
+        item_id: ID of the item to fetch
+        
+    Returns:
+        Dictionary with item details
+    """
+    # Similar implementation pattern
+```
+
+#### Create/Update Tool (if applicable)
+```python
+@mcp.tool()
+async def create_{{ api_slug.replace('-', '_') }}_item(
+    context: Context,
+    name: str,
+    data: Dict[str, Any]
+) -> Dict[str, Any]:
+    """
+    Create a new item in {{ api_name }}.
+    
+    Args:
+        context: MCP context (injected automatically)
+        name: Name of the item
+        data: Additional data for the item
+        
+    Returns:
+        Dictionary with creation result
+    """
+    # Implementation here
+```
+
+### 5. Best Practices
+
+1. **Error Handling**: Always wrap API calls in try-except blocks and return user-friendly error messages
+2. **Input Validation**: Validate parameters before making API calls
+3. **Rate Limiting**: Respect API rate limits, implement delays if needed
+4. **Response Formatting**: Return consistent response structures across all tools
+5. **Logging**: Use the logger for debugging but don't log sensitive data like API keys
+6. **Documentation**: Write clear docstrings for each tool explaining parameters and return values
+7. **Retry Strategy**: Use the `@retry` decorator on API client functions for resilience
+
+#### Retry Best Practices
+
+- **Only use retry for external API calls** - Don't add retry to internal functions, database operations, or file operations
+- **Apply retry to API client functions**, not MCP tool functions directly
+- **Use `tries=2`** (1 original attempt + 1 retry) to balance reliability and responsiveness
+- **Add jitter** to prevent thundering herd when multiple clients retry simultaneously
+- **Don't retry on authentication errors** - use conditional retry if needed:
+  ```python
+  from retry import retry
+  import requests
+  
+  def retry_on_server_error(exception):
+      """Only retry on server errors (5xx), not client errors (4xx)"""
+      if isinstance(exception, requests.HTTPError):
+          return 500 <= exception.response.status_code < 600
+      return True  # Retry on other exceptions like network errors
+  
+  @retry(tries=2, delay=1, backoff=2, jitter=(1, 3), exceptions=retry_on_server_error)
+  def call_api_with_smart_retry(endpoint, params, api_key):
+      # API implementation
+      pass
+  ```
+- **Log retry attempts** for debugging:
+  ```python
+  @retry(tries=2, delay=1, logger=logger)
+  def call_{{ api_slug.replace('-', '_') }}_api(...):
+      # Implementation
+  ```
+
+#### When to Use Retry
+
+**✅ DO use retry for:**
+- HTTP requests to external APIs
+- Network operations that can fail temporarily
+- Remote service calls that may experience transient errors
+
+**❌ DON'T use retry for:**
+- MCP tool functions (they should handle errors gracefully instead)
+- Local file operations
+- Database queries (unless specifically needed for connection issues)
+- Authentication/validation logic
+- Data processing or computation functions
+
+### 6. Testing
+
+After implementing tools, test them:
+
+1. Run the server locally:
+   ```bash
+   ./run_local_docker.sh
+   ```
+
+2. Use the health check script:
+   ```bash
+   python mcp_health_check.py
+   ```
+
+3. Test with CrewAI:
+   ```python
+   {% if requires_auth %}from traia_iatp.mcp.traia_mcp_adapter import create_mcp_adapter_with_auth
+   
+   # Authenticated connection
+   with create_mcp_adapter_with_auth(
+       url="http://localhost:8000/mcp/",
+       api_key="your-api-key"
+   ) as tools:
+       # Test your tools
+       for tool in tools:
+           print(f"Tool: {tool.name}")
+   {% else %}from traia_iatp.mcp.traia_mcp_adapter import create_mcp_adapter
+   
+   # Standard connection (no authentication)
+   with create_mcp_adapter(
+       url="http://localhost:8000/mcp/"
+   ) as tools:
+       # Test your tools
+       for tool in tools:
+           print(f"Tool: {tool.name}")
+   {% endif %}
+   ```
+
+### 7. Update Documentation
+
+After implementing the tools:
+
+1. **Update README.md**:
+   - List all implemented tools with descriptions
+   - Add usage examples for each tool
+   - Include any specific setup instructions
+
+2. **Update deployment_params.json**:
+   - Ensure ALL tool names are in the `capabilities` array
+   - Add relevant tags based on functionality
+   - Verify authentication settings match implementation
+
+3. **Add Tool Examples** in README.md:
+   ```python
+   # Example usage of each tool
+   result = await tool.search_{{ api_slug.replace('-', '_') }}(query="example", limit=5)
+   ```
+
+### 8. Pre-Deployment Checklist
+
+Before marking the implementation as complete:
+
+- [ ] All placeholder code has been replaced with actual implementation
+- [ ] All tools are properly documented with docstrings
+- [ ] Error handling is implemented for all API calls
+- [ ] `deployment_params.json` contains all tool names in capabilities
+- [ ] README.md has been updated with usage examples
+- [ ] Server runs successfully with `./run_local_docker.sh`
+- [ ] Health check passes
+- [ ] At least one tool works end-to-end
+
+### 9. Common {{ api_name }} Use Cases
+
+Based on the API documentation, consider implementing tools for these common use cases:
+
+1. **TODO**: List specific use cases based on {{ api_name }} capabilities
+2. **TODO**: Add more relevant use cases
+3. **TODO**: Include any special features of this API
+
+### 10. Example API Calls
+
+Here are some example API calls from the {{ api_name }} documentation that you should implement:
+
+```
+TODO: Add specific examples from the API docs
+```
+
+## Need Help?
+
+- Check the {{ api_name }} API documentation: {{ docs_url }}
+- Review the MCP specification: https://modelcontextprotocol.io
+- Look at other MCP server examples in the Traia-IO organization
+
+Remember: The goal is to make {{ api_name }}'s capabilities easily accessible to AI agents through standardized MCP tools. 

traia_iatp/mcp/templates/deployment_params.json.j2

@@ -0,0 +1,20 @@
+{
+  "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",
+    "requires_api_key": {{ requires_auth|lower }},
+    {% if requires_auth %}"api_key_header": "Authorization",
+    "api_keys": ["{{ api_key_env_var }}"],
+    {% endif %}"capabilities": [
+      "example_tool",
+      "get_api_info"
+    ]
+  },
+  "deployment_method": "cloud_run",
+  "gcp_project_id": "traia-mcp-servers",
+  "gcp_region": "us-central1",
+  "tags": ["{{ api_name_lower }}", "api", "mcp"],
+  "ref": "main"
+} 

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

@@ -0,0 +1,23 @@
+version: '3.8'
+
+services:
+  {{ api_slug }}-mcp:
+    build: .
+    container_name: {{ api_slug }}-mcp-server
+    ports:
+      - "8000:8000"
+    environment:
+      - PORT=8000
+      - STAGE=${STAGE:-MAINNET}
+      - LOG_LEVEL=${LOG_LEVEL:-INFO}
+{% if api_key_env_var %}
+      - {{ api_key_env_var }}={% raw %}${{% endraw %}{{ api_key_env_var }}{% raw %}}{% endraw %}
+{% endif %}
+    volumes:
+      - ./logs:/app/logs
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3 

traia_iatp/mcp/templates/dockerignore.j2

@@ -0,0 +1,47 @@
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Git
+.git/
+.gitignore
+
+# Documentation
+README.md
+docs/
+
+# Tests
+tests/
+pytest_cache/
+.coverage
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+*.log
+*.tmp
+.cache/
+
+# uv
+uv.lock
+
+# Docker
+Dockerfile
+docker-compose.yml
+.dockerignore 

traia_iatp/mcp/templates/gitignore.j2

@@ -0,0 +1,77 @@
+# 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 Environment
+venv/
+ENV/
+env/
+.venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.hypothesis/
+
+# Package managers
+uv.lock
+poetry.lock
+pip-log.txt
+
+# Docker
+.dockerignore
+
+# Output files
+output_tests/
+*.txt
+*.json
+
+# Temporary files
+*.tmp
+*.temp
+*.bak
+
+# {{ api_name }} specific
+{% if additional_gitignore_entries -%}
+{{ additional_gitignore_entries }}
+{%- endif %}