defistream-mcp 0.2.0__py3-none-any.whl

defistream_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""DeFiStream MCP Server — Model Context Protocol server for the DeFiStream API."""
+
+__version__ = "0.1.0"

defistream_mcp/api_client.py

@@ -0,0 +1,102 @@
+"""Async HTTP client wrapper for the DeFiStream API."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from .config import ServerConfig
+
+logger = logging.getLogger(__name__)
+
+_client: DeFiStreamAPIClient | None = None
+
+
+def get_client() -> DeFiStreamAPIClient:
+    """Return the module-level API client. Must call ``init_client`` first."""
+    if _client is None:
+        raise RuntimeError("API client not initialised — call init_client() first")
+    return _client
+
+
+def init_client(config: ServerConfig) -> DeFiStreamAPIClient:
+    """Create and store the module-level API client."""
+    global _client
+    _client = DeFiStreamAPIClient(config)
+    return _client
+
+
+def create_client_with_key(api_key: str) -> DeFiStreamAPIClient:
+    """Create a temporary client with a user-provided API key.
+
+    Uses the base_url and other settings from the global client's config.
+    This allows users to authenticate requests with their own API keys.
+    """
+    if _client is None:
+        raise RuntimeError("API client not initialised — call init_client() first")
+
+    temp_config = ServerConfig(
+        api_key=api_key,
+        base_url=_client.config.base_url,
+        transport=_client.config.transport,
+        host=_client.config.host,
+        port=_client.config.port,
+        download_dir=_client.config.download_dir,
+        query_row_limit=_client.config.query_row_limit,
+        local=_client.config.local,
+    )
+    return DeFiStreamAPIClient(temp_config)
+
+
+class DeFiStreamAPIClient:
+    """Lightweight async wrapper around the DeFiStream REST API."""
+
+    def __init__(self, config: ServerConfig) -> None:
+        self.config = config
+        self._http = httpx.AsyncClient(
+            base_url=config.base_url,
+            headers={"X-API-Key": config.api_key},
+            timeout=httpx.Timeout(60.0, connect=10.0),
+        )
+
+    async def get_json(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+    ) -> tuple[Any, dict[str, str]]:
+        """GET *path* and return ``(parsed_json, response_headers)``."""
+        resp = await self._http.get(path, params=params)
+        resp.raise_for_status()
+        headers = {
+            k: v
+            for k, v in resp.headers.items()
+            if k.lower().startswith("x-ratelimit") or k.lower() == "x-request-cost"
+        }
+        return resp.json(), headers
+
+    async def download_to_file(
+        self,
+        path: str,
+        params: dict[str, Any],
+        output_path: Path,
+    ) -> int:
+        """Stream a GET response to *output_path*. Returns bytes written."""
+        total = 0
+        async with self._http.stream("GET", path, params=params) as resp:
+            resp.raise_for_status()
+            with open(output_path, "wb") as f:
+                async for chunk in resp.aiter_bytes(chunk_size=65_536):
+                    f.write(chunk)
+                    total += len(chunk)
+        return total
+
+    def build_url(self, path: str, params: dict[str, Any]) -> str:
+        """Build the full URL for *path* with query params (for SSE download links)."""
+        req = self._http.build_request("GET", path, params=params)
+        return str(req.url)
+
+    async def close(self) -> None:
+        await self._http.aclose()

defistream_mcp/config.py

@@ -0,0 +1,99 @@
+"""Environment-based configuration for the DeFiStream MCP server."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+_PRODUCTION_URL = "https://api.defistream.dev/v1"
+_LOCAL_URL = "http://localhost:8081/v1"
+
+
+def _load_dotenv() -> None:
+    """Load .env from mcp-server/ dir and monorepo root. Existing env vars take precedence."""
+    pkg_dir = Path(__file__).resolve().parents[2]  # mcp-server/
+    load_dotenv(pkg_dir / ".env", override=False)
+    # Also try monorepo root (one level up from mcp-server/)
+    load_dotenv(pkg_dir.parent / ".env", override=False)
+
+
+@dataclass(frozen=True)
+class ServerConfig:
+    """Server configuration loaded from environment variables."""
+
+    api_key: str = ""  # Optional - only for testing/utility tools; users provide their own
+    base_url: str = _PRODUCTION_URL
+    transport: str = "stdio"
+    host: str = "0.0.0.0"  # Bind address for SSE transport
+    port: int = 8000  # Port for SSE transport
+    download_dir: str = "."
+    query_row_limit: int = 10000
+    local: bool = False
+
+    @classmethod
+    def from_env(cls) -> ServerConfig:
+        """Build config from environment variables.
+
+        Env vars:
+            DEFISTREAM_API_KEY      (optional) — API key for utility tools; users provide their own for queries
+            DEFISTREAM_LOCAL        (optional) — "true" to use local gateway
+            DEFISTREAM_BASE_URL     (optional) — API base URL (overrides --local)
+            DEFISTREAM_MCP_TRANSPORT(optional) — "stdio" or "sse"
+            DEFISTREAM_MCP_HOST     (optional) — Bind address for SSE (default: 0.0.0.0)
+            DEFISTREAM_MCP_PORT     (optional) — Port for SSE (default: 8000)
+            DEFISTREAM_DOWNLOAD_DIR (optional) — default download directory
+            DEFISTREAM_QUERY_ROW_LIMIT (optional) — max rows for query_events
+        """
+        _load_dotenv()
+
+        # API key is now optional - users provide their own per-request
+        api_key = os.environ.get("DEFISTREAM_API_KEY", "")
+
+        local = os.environ.get("DEFISTREAM_LOCAL", "").lower() in ("1", "true", "yes")
+
+        # Explicit DEFISTREAM_BASE_URL takes precedence, then local flag, then production
+        explicit_url = os.environ.get("DEFISTREAM_BASE_URL")
+        if explicit_url:
+            base_url = explicit_url.rstrip("/")
+        elif local:
+            base_url = _LOCAL_URL
+        else:
+            base_url = _PRODUCTION_URL
+
+        transport = os.environ.get("DEFISTREAM_MCP_TRANSPORT", "stdio").lower()
+        if transport not in ("stdio", "sse", "http"):
+            raise ValueError(
+                f"DEFISTREAM_MCP_TRANSPORT must be 'stdio', 'sse', or 'http', got '{transport}'"
+            )
+
+        host = os.environ.get("DEFISTREAM_MCP_HOST", "0.0.0.0")
+
+        port_str = os.environ.get("DEFISTREAM_MCP_PORT", "8000")
+        try:
+            port = int(port_str)
+        except ValueError:
+            raise ValueError(
+                f"DEFISTREAM_MCP_PORT must be an integer, got '{port_str}'"
+            )
+
+        row_limit_str = os.environ.get("DEFISTREAM_QUERY_ROW_LIMIT", "10000")
+        try:
+            row_limit = int(row_limit_str)
+        except ValueError:
+            raise ValueError(
+                f"DEFISTREAM_QUERY_ROW_LIMIT must be an integer, got '{row_limit_str}'"
+            )
+
+        return cls(
+            api_key=api_key,
+            base_url=base_url,
+            transport=transport,
+            host=host,
+            port=port,
+            download_dir=os.environ.get("DEFISTREAM_DOWNLOAD_DIR", "."),
+            query_row_limit=row_limit,
+            local=local,
+        )

defistream_mcp/formatters.py

@@ -0,0 +1,247 @@
+"""Pure formatting helpers for MCP tool responses."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def format_events_response(
+    body: dict[str, Any],
+    headers: dict[str, str],
+    limit: int,
+) -> str:
+    """Format a JSON events response, truncating to *limit* rows."""
+    events = body.get("events", [])
+    total = body.get("count", len(events))
+
+    truncated = events[:limit]
+    parts: list[str] = []
+
+    if total > limit:
+        parts.append(f"Showing {limit} of {total} events (truncated).\n")
+    else:
+        parts.append(f"{total} event(s) returned.\n")
+
+    parts.append(json.dumps(truncated, indent=2))
+    parts.append(_format_quota(headers))
+    return "\n".join(parts)
+
+
+def format_aggregate_response(
+    body: dict[str, Any],
+    headers: dict[str, str],
+) -> str:
+    """Format an aggregate query response."""
+    data = body.get("data", [])
+    parts: list[str] = [
+        f"{body.get('count', len(data))} bucket(s) returned.",
+        f"group_by: {body.get('group_by', '?')}  period: {body.get('period', '?')}",
+    ]
+
+    cols = body.get("columns_aggregated", [])
+    if cols:
+        col_names = [c.get("output_column", "?") for c in cols]
+        parts.append(f"Aggregated columns: {', '.join(col_names)}")
+
+    parts.append("")
+    parts.append(json.dumps(data, indent=2))
+    parts.append(_format_quota(headers))
+    return "\n".join(parts)
+
+
+def format_download_summary(
+    file_path: str,
+    size_bytes: int,
+) -> str:
+    """Summarise a completed file download."""
+    if size_bytes < 1024:
+        size_str = f"{size_bytes} B"
+    elif size_bytes < 1024 * 1024:
+        size_str = f"{size_bytes / 1024:.1f} KB"
+    else:
+        size_str = f"{size_bytes / (1024 * 1024):.1f} MB"
+    return f"Downloaded to {file_path} ({size_str})"
+
+
+def build_download_url(
+    base_url: str,
+    protocol: str,
+    event_type: str,
+    params: dict[str, Any],
+) -> str:
+    """Build a full download URL for SSE transport."""
+    from urllib.parse import urlencode
+
+    qs = urlencode({k: v for k, v in params.items() if v is not None})
+    path = f"{base_url}/{protocol}/events/{event_type}"
+    return f"{path}?{qs}" if qs else path
+
+
+def format_link_response(
+    body: dict[str, Any],
+    headers: dict[str, str],
+) -> str:
+    """Format a link response from the API."""
+    filename = body.get("filename", "unknown")
+    link = body.get("link", "")
+    expiry = body.get("expiry", "unknown")
+    size = body.get("size")
+
+    parts: list[str] = [
+        "Download link generated:",
+        f"  Filename: {filename}",
+        f"  Link: {link}",
+        f"  Expires: {expiry}",
+    ]
+
+    if size is not None:
+        parts.append(f"  Size: {size}")
+
+    parts.append("")
+    parts.append("Use directly with polars/pandas:")
+    parts.append(f'  pl.read_{"parquet" if filename.endswith(".parquet") else "csv"}("{link}")')
+    parts.append(_format_quota(headers))
+
+    return "\n".join(parts)
+
+
+def _format_quota(headers: dict[str, str]) -> str:
+    """Format rate-limit / quota headers into a short summary line."""
+    remaining = headers.get("x-ratelimit-remaining")
+    cost = headers.get("x-request-cost")
+    if not remaining and not cost:
+        return ""
+    parts = []
+    if cost:
+        parts.append(f"cost={cost} CU")
+    if remaining:
+        parts.append(f"remaining={remaining} CU")
+    return "\n[Quota: " + ", ".join(parts) + "]"
+
+
+def format_local_execution_guide(query: str, base_url: str) -> str:
+    """Format a guide for executing a query locally using various methods."""
+    from urllib.parse import parse_qs, urlencode
+
+    # Parse the query to extract components for the Python client example
+    if "?" in query:
+        path, qs = query.split("?", 1)
+        params = parse_qs(qs, keep_blank_values=True)
+        # Flatten single-value lists
+        params_flat = {k: v[0] if len(v) == 1 else v for k, v in params.items()}
+    else:
+        path = query
+        params_flat = {}
+
+    # Build full URL
+    full_url = f"{base_url}{query}"
+
+    # Build URL with CSV format
+    csv_params = dict(params_flat)
+    csv_params["format"] = "csv"
+    csv_qs = urlencode(csv_params)
+    csv_url = f"{base_url}{path}?{csv_qs}"
+
+    # Build URL with JSON format
+    json_params = dict(params_flat)
+    json_params["format"] = "json"
+    json_qs = urlencode(json_params)
+    json_url = f"{base_url}{path}?{json_qs}"
+
+    # Build URL with parquet + link
+    parquet_params = dict(params_flat)
+    parquet_params["format"] = "parquet"
+    parquet_params["link"] = "true"
+    parquet_qs = urlencode(parquet_params)
+    parquet_url = f"{base_url}{path}?{parquet_qs}"
+
+    # Extract protocol info for Python client example
+    path_parts = path.strip("/").split("/")
+    protocol = path_parts[0] if path_parts else "erc20"
+    event_type = path_parts[2] if len(path_parts) > 2 else "transfer"
+
+    # Build Python client method call
+    client_params = []
+    for k, v in params_flat.items():
+        if k in ("format", "link", "verbose"):
+            continue
+        if isinstance(v, str):
+            client_params.append(f'{k}="{v}"')
+        else:
+            client_params.append(f"{k}={v}")
+    client_args = ", ".join(client_params)
+
+    guide = f"""## Query Local Execution Guide
+
+**Query**: {query}
+
+**Base URL**: {base_url}
+
+### Option 1: curl (CSV)
+```bash
+curl -H "X-API-Key: YOUR_API_KEY" \\
+  "{csv_url}"
+```
+
+### Option 2: curl (JSON)
+```bash
+curl -H "X-API-Key: YOUR_API_KEY" \\
+  "{json_url}"
+```
+
+### Option 3: curl (Parquet download link)
+```bash
+curl -H "X-API-Key: YOUR_API_KEY" \\
+  "{parquet_url}"
+```
+
+### Option 4: Python (requests)
+```python
+import requests
+
+headers = {{"X-API-Key": "YOUR_API_KEY"}}
+resp = requests.get("{csv_url}", headers=headers)
+print(resp.text)
+```
+
+### Option 5: Python (aiohttp)
+```python
+import aiohttp
+import asyncio
+
+async def fetch():
+    headers = {{"X-API-Key": "YOUR_API_KEY"}}
+    async with aiohttp.ClientSession() as session:
+        async with session.get("{csv_url}", headers=headers) as resp:
+            data = await resp.text()
+            print(data)
+
+asyncio.run(fetch())
+```
+
+### Option 6: JavaScript (fetch)
+```javascript
+const resp = await fetch("{csv_url}", {{
+  headers: {{ "X-API-Key": "YOUR_API_KEY" }}
+}});
+const data = await resp.text();
+console.log(data);
+```
+
+### Option 7: Python Client Library
+```python
+from defistream import DeFiStream
+
+client = DeFiStream(api_key="YOUR_API_KEY")
+df = client.{protocol}.{event_type}({client_args}).as_df()
+print(df)
+```
+
+### Format Options
+- `format=json` — JSON response (max 10,000 blocks)
+- `format=csv` — CSV streaming (unlimited blocks)
+- `format=parquet` — Parquet file (unlimited blocks)
+- `link=true` — Returns shareable download link (1 hour expiry, CSV/Parquet only)
+"""
+    return guide

defistream_mcp/resources.py

@@ -0,0 +1,65 @@
+"""Static MCP resources providing context to LLMs."""
+
+from __future__ import annotations
+
+PROTOCOLS_TEXT = """\
+DeFiStream supported protocols and their query builder tools:
+
+- erc20 — ERC-20 token transfer events (USDT, USDC, WETH, …) → erc20_query_builder
+- native_token — Native blockchain token transfers (ETH, MATIC, BNB, …) → native_token_query_builder
+- aave_v3 — AAVE V3 lending protocol events (deposit, withdraw, borrow, repay, flashloan, liquidation) → aave_v3_query_builder
+- uniswap_v3 — Uniswap V3 DEX events (swap, deposit, withdraw, collect) → uniswap_v3_query_builder
+- lido — Lido liquid staking events (deposit, withdrawal_request, withdrawal_claimed, l2_deposit, l2_withdrawal_request) → lido_query_builder
+- stader — Stader ETHx staking events → stader_query_builder
+- threshold — Threshold tBTC bridge events → threshold_query_builder
+
+Workflow:
+1. Use a protocol query builder to create a query path.
+2. Pass the query path to execute_query() for JSON results, or download_query() for CSV/Parquet.
+3. Use supported_networks(protocol) to check if a network is valid before building queries.
+"""
+
+API_LIMITS_TEXT = """\
+DeFiStream API limits and constraints:
+
+Block range limits per request:
+  - JSON format (execute_query): max 10,000 blocks
+  - CSV format (download_query):  max 1,000,000 blocks
+  - Parquet format (download_query): max 1,000,000 blocks
+
+Range specification (one required):
+  - block_start + block_end  (integer block numbers)
+  - since + until            (ISO 8601 timestamps or Unix seconds)
+  Cannot mix block range with time range.
+
+execute_query tool:
+  - Returns JSON, capped at the configured row limit (default 200).
+  - For larger result sets, narrow the block/time range or use download_query.
+
+download_query tool:
+  - Streams full result to a local file (CSV or Parquet).
+  - No row cap — limited only by block range.
+
+Quota:
+  - Each request costs Computation Units (CU).
+  - Cost depends on protocol, format, token, block range, and verbose flag.
+  - Response headers report remaining quota.
+
+Rate limiting:
+  - basic plan: 60 req/min
+  - pro plan: 300 req/min
+"""
+
+
+def register_resources(mcp):  # noqa: ANN001
+    """Register static resources on the FastMCP instance."""
+
+    @mcp.resource("defistream://protocols")
+    def protocols_resource() -> str:
+        """Overview of all DeFiStream protocols."""
+        return PROTOCOLS_TEXT
+
+    @mcp.resource("defistream://api-limits")
+    def api_limits_resource() -> str:
+        """API limits, block range caps, and quota information."""
+        return API_LIMITS_TEXT

defistream_mcp/server.py

@@ -0,0 +1,61 @@
+"""DeFiStream MCP Server — entry point."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+from mcp.server.fastmcp import FastMCP
+
+from .api_client import init_client
+from .config import ServerConfig
+from .resources import register_resources
+from .tools import register_tools
+
+# All logging goes to stderr so stdout stays clean for stdio transport.
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    stream=sys.stderr,
+)
+logger = logging.getLogger(__name__)
+
+
+def create_server(config: ServerConfig) -> FastMCP:
+    """Build and wire the FastMCP server instance."""
+    # Pass host/port to FastMCP constructor for SSE transport
+    mcp = FastMCP("defistream", host=config.host, port=config.port)
+    init_client(config)
+    register_resources(mcp)
+    register_tools(mcp, config)
+    return mcp
+
+
+def main() -> None:
+    """CLI entry point (``defistream-mcp``)."""
+    try:
+        config = ServerConfig.from_env()
+    except ValueError as exc:
+        logger.error("Configuration error: %s", exc)
+        sys.exit(1)
+
+    logger.info(
+        "Starting DeFiStream MCP server (transport=%s, base_url=%s)",
+        config.transport,
+        config.base_url,
+    )
+
+    server = create_server(config)
+
+    if config.transport == "http":
+        logger.info("HTTP server listening on %s:%d", config.host, config.port)
+        server.run(transport="streamable-http")
+    elif config.transport == "sse":
+        logger.info("SSE server listening on %s:%d", config.host, config.port)
+        server.run(transport="sse")
+    else:
+        server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()