defistream-mcp 0.2.0__py3-none-any.whl

defistream_mcp-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+defistream_mcp/__init__.py,sha256=yOeKNMa4Vamk7c_E1i5hh8T5e_PHeWsyF8uSmiRH7zk,109
+defistream_mcp/api_client.py,sha256=jhr4Mm8gHwPldpJdWwxx2xDZR4lI-Z8DYplciWtGBcU,3306
+defistream_mcp/config.py,sha256=fY_PX6_OUcZHFdfsG8jfdw_iFqhlyZLSpjIvfqCzfXw,3708
+defistream_mcp/formatters.py,sha256=XUMPCw7f0I7EPToq3-IdEmxbfdIDXuLyZn78NOInmGE,6793
+defistream_mcp/resources.py,sha256=A0XTXPFhYn2X0dI1SzCngmSSkoTVLWCuMo-Az0ySwDQ,2608
+defistream_mcp/server.py,sha256=Dw5XDbCq8W5-OZPaW8okrAMu9OolfYQUZPLMvVO4MDw,1682
+defistream_mcp/tools.py,sha256=FkHwTfwWBEK4PSOfGehJU_9zOmewdxtmul4Yga1iSGQ,30222
+defistream_mcp-0.2.0.dist-info/METADATA,sha256=FR-4nPc6YIHQataXIYGFpj8C-JDU1Z1RUTobGKWNV7w,6522
+defistream_mcp-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+defistream_mcp-0.2.0.dist-info/entry_points.txt,sha256=b8vx7j6914vBBpqa5X2TUgmppjNGQCpBMcpP6yEZhNk,62
+defistream_mcp-0.2.0.dist-info/RECORD,,

defistream_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

defistream_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+defistream-mcp = defistream_mcp.server:main