defistream-mcp 0.2.0__tar.gz

defistream_mcp-0.2.0/.dockerignore

@@ -0,0 +1,14 @@
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+.env
+.pytest_cache/
+.mypy_cache/
+tests/
+*.egg
+.git/

defistream_mcp-0.2.0/.env.example

@@ -0,0 +1,38 @@
+# DeFiStream MCP Server Configuration
+
+# API Key (optional for remote SSE mode - users provide their own)
+# For stdio mode or if you want utility tools to work without user key
+# Get your API key from https://defistream.dev
+# DEFISTREAM_API_KEY=dsk_your_api_key_here
+
+# API Base URL (optional)
+# Default: https://api.defistream.dev/v1
+# DEFISTREAM_BASE_URL=https://api.defistream.dev/v1
+
+# Use local gateway instead of production API (optional)
+# Set to true/1/yes to use local development server
+# DEFISTREAM_LOCAL=false
+
+# MCP Transport (optional)
+# Options: stdio (default), http, sse
+# Use "http" for remote server mode (recommended)
+# Use "sse" for legacy SSE transport (deprecated)
+# DEFISTREAM_MCP_TRANSPORT=stdio
+
+# SSE Server Host (optional, only used with transport=sse)
+# Default: 0.0.0.0 (all interfaces)
+# DEFISTREAM_MCP_HOST=0.0.0.0
+
+# SSE Server Port (optional, only used with transport=sse)
+# Default: 8000
+# DEFISTREAM_MCP_PORT=8000
+
+# Query row limit (optional)
+# Maximum rows returned for query results
+# Default: 10000
+# DEFISTREAM_QUERY_ROW_LIMIT=10000
+
+# Download directory (optional)
+# Directory for downloaded files (only used with stdio transport)
+# Default: current directory
+# DEFISTREAM_DOWNLOAD_DIR=.

defistream_mcp-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/

defistream_mcp-0.2.0/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "defistream": {
+      "type": "stdio",
+      "command": "defistream-mcp",
+      "args": [],
+      "env": {}
+    }
+  }
+}

defistream_mcp-0.2.0/Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY src/ src/
+
+RUN pip install --no-cache-dir . && rm -rf /app/*
+
+# Default SSE port
+EXPOSE 8000
+
+ENTRYPOINT ["defistream-mcp"]

defistream_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: defistream-mcp
+Version: 0.2.0
+Summary: MCP server for the DeFiStream API
+Project-URL: Homepage, https://defistream.dev
+Project-URL: Documentation, https://docs.defistream.dev
+Project-URL: Repository, https://github.com/Eren-Nevin/DeFiStream_MCPServer
+Author-email: DeFiStream <support@defistream.dev>
+License-Expression: MIT
+Keywords: blockchain,defi,llm,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: mcp>=1.7.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.5.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# DeFiStream MCP Server
+
+Model Context Protocol (MCP) server that wraps the [DeFiStream](https://defistream.dev) REST API, giving LLMs (Claude Desktop, Claude Code, etc.) direct access to on-chain DeFi event data. Make sure to get an api key from app.defistream.deveasily.
+
+## Quick Start
+
+```bash
+# Install
+cd mcp-server
+pip install -e .
+
+# Set your API key
+export DEFISTREAM_API_KEY="dsk_your_key_here"
+
+# Run (stdio transport)
+defistream-mcp
+```
+
+## Docker
+
+No Python installation required — run the MCP server directly from Docker Hub:
+
+```bash
+docker run -i -e DEFISTREAM_API_KEY=dsk_your_key_here defistream/mcp-server
+```
+
+### Claude Code
+
+```bash
+claude mcp add --transport stdio defistream \
+  -- docker run -i -e DEFISTREAM_API_KEY=dsk_your_key_here defistream/mcp-server
+```
+
+### Claude Desktop (Docker)
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "defistream": {
+      "command": "docker",
+      "args": [
+        "run", "-i",
+        "-e", "DEFISTREAM_API_KEY=dsk_your_key_here",
+        "defistream/mcp-server"
+      ]
+    }
+  }
+}
+```
+
+> **Note:** Claude Desktop passes `env` to the spawned process, but `docker run` requires explicit `-e` flags. Put the API key in `args` as shown above, or set it in your shell before launching Claude Desktop.
+
+### Build from Source
+
+```bash
+cd mcp-server
+docker build -t defistream/mcp-server .
+docker run -i -e DEFISTREAM_API_KEY=dsk_your_key_here defistream/mcp-server
+```
+
+### Publish to Docker Hub
+
+```bash
+docker login
+docker build -t defistream/mcp-server:latest -t defistream/mcp-server:0.1.0 .
+docker push defistream/mcp-server:latest
+docker push defistream/mcp-server:0.1.0
+```
+
+## Claude Desktop Configuration
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "defistream": {
+      "command": "defistream-mcp",
+      "env": {
+        "DEFISTREAM_API_KEY": "dsk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `DEFISTREAM_API_KEY` | Yes | — | API key (`dsk_xxx`) |
+| `DEFISTREAM_LOCAL` | No | `false` | Set to `true` to use local gateway (`http://localhost:8081/v1`) |
+| `DEFISTREAM_BASE_URL` | No | `https://api.defistream.dev/v1` | API base URL (overrides `DEFISTREAM_LOCAL`) |
+| `DEFISTREAM_MCP_TRANSPORT` | No | `stdio` | `stdio` or `sse` |
+| `DEFISTREAM_DOWNLOAD_DIR` | No | `.` (cwd) | Default dir for downloaded files |
+| `DEFISTREAM_QUERY_ROW_LIMIT` | No | `200` | Max rows returned by execute_query |
+
+### Local Development
+
+To test against the local API gateway (port 8081):
+
+```bash
+export DEFISTREAM_API_KEY="dsk_your_key"
+export DEFISTREAM_LOCAL=true
+defistream-mcp
+```
+
+Or in Claude Desktop / Claude Code config:
+
+```json
+{
+  "mcpServers": {
+    "defistream": {
+      "command": "defistream-mcp",
+      "env": {
+        "DEFISTREAM_API_KEY": "dsk_your_key",
+        "DEFISTREAM_LOCAL": "true"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### Utility
+
+| Tool | Description |
+|---|---|
+| `supported_networks(protocol)` | List supported networks for a protocol |
+| `supported_events(protocol)` | List supported event types for a protocol |
+| `base_url()` | Get the API base URL |
+| `execute_query(query, limit?)` | Execute a query path and return JSON results |
+| `download_query(query, file_format?, output_dir?)` | Download query results as CSV/Parquet |
+
+### Protocol Query Builders
+
+Each builder returns a query path string to pass to `execute_query()` or `download_query()`.
+
+| Tool | Protocol | Required Params |
+|---|---|---|
+| `erc20_query_builder` | ERC-20 tokens | `event_type`, `network`, `token` |
+| `native_token_query_builder` | Native tokens (ETH, BNB, …) | `event_type`, `network` |
+| `aave_v3_query_builder` | AAVE V3 lending | `event_type`, `network` |
+| `uniswap_v3_query_builder` | Uniswap V3 DEX | `event_type`, `network`, `symbol0`, `symbol1`, `fee` |
+| `lido_query_builder` | Lido staking | `event_type`, `network` |
+| `stader_query_builder` | Stader ETHx | `event_type`, `network` |
+| `threshold_query_builder` | Threshold tBTC | `event_type`, `network` |
+
+All builders also accept: `block_start/block_end` or `since/until` for range, `verbose`, `with_value`, `aggregate`, `group_by`, `period`, and protocol-specific filter params.
+
+- **`with_value`** — Set `true` to enrich events with USD value data. Adds `value_usd` column to individual events, and `agg_value_usd` to aggregate results.
+
+### Workflow
+
+```
+1. supported_networks("erc20")          → check network is valid
+2. erc20_query_builder(                 → build query path
+     event_type="transfer",
+     network="ETH",
+     token="USDT",
+     since="2025-01-01",
+     until="2025-01-02"
+   )
+3. execute_query(query)                 → get JSON results
+   — or —
+   download_query(query, "csv")         → save CSV file
+```
+
+**Multi-token queries:** Pass comma-separated known symbol names to query multiple tokens at once (contract addresses not supported for multi-token):
+
+```
+erc20_query_builder(
+  event_type="transfer",
+  network="ETH",
+  token="USDT,USDC,DAI",
+  since="2025-01-01",
+  until="2025-01-02"
+)
+```
+
+## Resources
+
+| URI | Description |
+|---|---|
+| `defistream://protocols` | Protocol descriptions and builder tool mapping |
+| `defistream://api-limits` | Block limits, row caps, quota info |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

defistream_mcp-0.2.0/README.md

@@ -0,0 +1,196 @@
+# DeFiStream MCP Server
+
+Model Context Protocol (MCP) server that wraps the [DeFiStream](https://defistream.dev) REST API, giving LLMs (Claude Desktop, Claude Code, etc.) direct access to on-chain DeFi event data. Make sure to get an api key from app.defistream.deveasily.
+
+## Quick Start
+
+```bash
+# Install
+cd mcp-server
+pip install -e .
+
+# Set your API key
+export DEFISTREAM_API_KEY="dsk_your_key_here"
+
+# Run (stdio transport)
+defistream-mcp
+```
+
+## Docker
+
+No Python installation required — run the MCP server directly from Docker Hub:
+
+```bash
+docker run -i -e DEFISTREAM_API_KEY=dsk_your_key_here defistream/mcp-server
+```
+
+### Claude Code
+
+```bash
+claude mcp add --transport stdio defistream \
+  -- docker run -i -e DEFISTREAM_API_KEY=dsk_your_key_here defistream/mcp-server
+```
+
+### Claude Desktop (Docker)
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "defistream": {
+      "command": "docker",
+      "args": [
+        "run", "-i",
+        "-e", "DEFISTREAM_API_KEY=dsk_your_key_here",
+        "defistream/mcp-server"
+      ]
+    }
+  }
+}
+```
+
+> **Note:** Claude Desktop passes `env` to the spawned process, but `docker run` requires explicit `-e` flags. Put the API key in `args` as shown above, or set it in your shell before launching Claude Desktop.
+
+### Build from Source
+
+```bash
+cd mcp-server
+docker build -t defistream/mcp-server .
+docker run -i -e DEFISTREAM_API_KEY=dsk_your_key_here defistream/mcp-server
+```
+
+### Publish to Docker Hub
+
+```bash
+docker login
+docker build -t defistream/mcp-server:latest -t defistream/mcp-server:0.1.0 .
+docker push defistream/mcp-server:latest
+docker push defistream/mcp-server:0.1.0
+```
+
+## Claude Desktop Configuration
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "defistream": {
+      "command": "defistream-mcp",
+      "env": {
+        "DEFISTREAM_API_KEY": "dsk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `DEFISTREAM_API_KEY` | Yes | — | API key (`dsk_xxx`) |
+| `DEFISTREAM_LOCAL` | No | `false` | Set to `true` to use local gateway (`http://localhost:8081/v1`) |
+| `DEFISTREAM_BASE_URL` | No | `https://api.defistream.dev/v1` | API base URL (overrides `DEFISTREAM_LOCAL`) |
+| `DEFISTREAM_MCP_TRANSPORT` | No | `stdio` | `stdio` or `sse` |
+| `DEFISTREAM_DOWNLOAD_DIR` | No | `.` (cwd) | Default dir for downloaded files |
+| `DEFISTREAM_QUERY_ROW_LIMIT` | No | `200` | Max rows returned by execute_query |
+
+### Local Development
+
+To test against the local API gateway (port 8081):
+
+```bash
+export DEFISTREAM_API_KEY="dsk_your_key"
+export DEFISTREAM_LOCAL=true
+defistream-mcp
+```
+
+Or in Claude Desktop / Claude Code config:
+
+```json
+{
+  "mcpServers": {
+    "defistream": {
+      "command": "defistream-mcp",
+      "env": {
+        "DEFISTREAM_API_KEY": "dsk_your_key",
+        "DEFISTREAM_LOCAL": "true"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### Utility
+
+| Tool | Description |
+|---|---|
+| `supported_networks(protocol)` | List supported networks for a protocol |
+| `supported_events(protocol)` | List supported event types for a protocol |
+| `base_url()` | Get the API base URL |
+| `execute_query(query, limit?)` | Execute a query path and return JSON results |
+| `download_query(query, file_format?, output_dir?)` | Download query results as CSV/Parquet |
+
+### Protocol Query Builders
+
+Each builder returns a query path string to pass to `execute_query()` or `download_query()`.
+
+| Tool | Protocol | Required Params |
+|---|---|---|
+| `erc20_query_builder` | ERC-20 tokens | `event_type`, `network`, `token` |
+| `native_token_query_builder` | Native tokens (ETH, BNB, …) | `event_type`, `network` |
+| `aave_v3_query_builder` | AAVE V3 lending | `event_type`, `network` |
+| `uniswap_v3_query_builder` | Uniswap V3 DEX | `event_type`, `network`, `symbol0`, `symbol1`, `fee` |
+| `lido_query_builder` | Lido staking | `event_type`, `network` |
+| `stader_query_builder` | Stader ETHx | `event_type`, `network` |
+| `threshold_query_builder` | Threshold tBTC | `event_type`, `network` |
+
+All builders also accept: `block_start/block_end` or `since/until` for range, `verbose`, `with_value`, `aggregate`, `group_by`, `period`, and protocol-specific filter params.
+
+- **`with_value`** — Set `true` to enrich events with USD value data. Adds `value_usd` column to individual events, and `agg_value_usd` to aggregate results.
+
+### Workflow
+
+```
+1. supported_networks("erc20")          → check network is valid
+2. erc20_query_builder(                 → build query path
+     event_type="transfer",
+     network="ETH",
+     token="USDT",
+     since="2025-01-01",
+     until="2025-01-02"
+   )
+3. execute_query(query)                 → get JSON results
+   — or —
+   download_query(query, "csv")         → save CSV file
+```
+
+**Multi-token queries:** Pass comma-separated known symbol names to query multiple tokens at once (contract addresses not supported for multi-token):
+
+```
+erc20_query_builder(
+  event_type="transfer",
+  network="ETH",
+  token="USDT,USDC,DAI",
+  since="2025-01-01",
+  until="2025-01-02"
+)
+```
+
+## Resources
+
+| URI | Description |
+|---|---|
+| `defistream://protocols` | Protocol descriptions and builder tool mapping |
+| `defistream://api-limits` | Block limits, row caps, quota info |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

defistream_mcp-0.2.0/docker-compose.yml

@@ -0,0 +1,21 @@
+services:
+  mcp-server:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8912:8912"
+    environment:
+      - DEFISTREAM_MCP_TRANSPORT=http
+      - DEFISTREAM_MCP_HOST=0.0.0.0
+      - DEFISTREAM_MCP_PORT=8912
+      - DEFISTREAM_BASE_URL=${DEFISTREAM_BASE_URL:-https://api.defistream.dev/v1}
+      # API key optional - only needed if you want utility tools to work without user key
+      - DEFISTREAM_API_KEY=${DEFISTREAM_API_KEY:-}
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8912/mcp"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s

defistream_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "defistream-mcp"
+version = "0.2.0"
+description = "MCP server for the DeFiStream API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "DeFiStream", email = "support@defistream.dev" }
+]
+keywords = ["defi", "blockchain", "mcp", "model-context-protocol", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "mcp>=1.7.0",
+    "httpx>=0.25.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-xdist>=3.5.0",
+]
+
+[project.scripts]
+defistream-mcp = "defistream_mcp.server:main"
+
+[project.urls]
+Homepage = "https://defistream.dev"
+Documentation = "https://docs.defistream.dev"
+Repository = "https://github.com/Eren-Nevin/DeFiStream_MCPServer"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/defistream_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

defistream_mcp-0.2.0/src/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-0.2.0/src/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()