spice-mcp 0.1.3__tar.gz → 0.1.4__tar.gz

spice_mcp-0.1.4/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: spice-mcp
+Version: 0.1.4
+Summary: MCP server for Dune Analytics data access
+Author-email: Evan-Kim2028 <ekcopersonal@gmail.com>
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: aiohttp>=3.9.5
+Requires-Dist: fastmcp>=0.3.0
+Requires-Dist: mcp>=0.9.0
+Requires-Dist: polars>=1.35.1
+Requires-Dist: requests>=2.31.0
+Requires-Dist: rich-argparse>=1.5.2
+Requires-Dist: rich>=13.3.3
+Description-Content-Type: text/markdown
+
+# spice-mcp
+
+[![PyPI version](https://img.shields.io/pypi/v/spice-mcp.svg)](https://pypi.org/project/spice-mcp/)
+<a href="https://glama.ai/mcp/servers/@Evan-Kim2028/spice-mcp">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@Evan-Kim2028/spice-mcp/badge" alt="Spice MCP server" />
+</a>
+
+An MCP server that provides AI agents with direct access to [Dune Analytics](https://dune.com/) data. Execute queries, discover schemas and tables, and manage saved queries—all through a clean, type-safe interface optimized for AI workflows.
+
+## Why spice-mcp?
+
+- **Agent-friendly**: Designed for AI agents using the Model Context Protocol (MCP)
+- **Efficient**: Polars-first pipeline keeps data lazy until needed, reducing memory usage
+- **Discovery**: Built-in tools to explore Dune's extensive blockchain datasets
+- **Type-safe**: Fully typed parameters and responses with FastMCP
+- **Reproducible**: Automatic query history logging and SQL artifact storage
+
+## Quick Start
+
+1. **Install**:
+   ```bash
+   uv pip install spice-mcp
+   ```
+
+2. **Set API key** (choose one method):
+   - **Option A**: Create a `.env` file in your project root:
+     ```bash
+     echo "DUNE_API_KEY=your-api-key-here" > .env
+     ```
+   - **Option B**: Export in your shell:
+     ```bash
+     export DUNE_API_KEY=your-api-key-here
+     ```
+
+3. **Use with Cursor IDE**:
+   Add to Cursor Settings → MCP Servers:
+   ```json
+   {
+     "name": "spice-mcp",
+     "command": "spice-mcp",
+     "env": {
+       "DUNE_API_KEY": "your-dune-api-key-here"
+     }
+   }
+   ```
+
+**Note**: Query history logging is enabled by default. Logs are saved to `logs/queries.jsonl` (or `~/.spice_mcp/logs/queries.jsonl` if not in a project directory). To customize paths, set `SPICE_QUERY_HISTORY` and `SPICE_ARTIFACT_ROOT` environment variables.
+
+## Core Tools
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `dune_query` | Execute queries by ID, URL, or raw SQL | `query` (str), `parameters` (object), `limit` (int), `offset` (int), `format` (`preview\|raw\|metadata\|poll`), `refresh` (bool), `timeout_seconds` (float) |
+| `dune_query_info` | Get metadata for a saved query | `query` (str - ID or URL) |
+| `dune_discover` | Unified discovery across Dune API and Spellbook | `keyword` (str\|list), `schema` (str), `limit` (int), `source` (`dune\|spellbook\|both`), `include_columns` (bool) |
+| `dune_find_tables` | Search schemas and list tables | `keyword` (str), `schema` (str), `limit` (int) |
+| `dune_describe_table` | Get column metadata for a table | `schema` (str), `table` (str) |
+| `spellbook_find_models` | Search Spellbook dbt models | `keyword` (str\|list), `schema` (str), `limit` (int), `include_columns` (bool) |
+| `dune_health_check` | Verify API key and configuration | (no parameters) |
+| `dune_query_create` | Create a new saved query | `name` (str), `query_sql` (str), `description` (str), `tags` (list), `parameters` (list) |
+| `dune_query_update` | Update an existing saved query | `query_id` (int), `name` (str), `query_sql` (str), `description` (str), `tags` (list), `parameters` (list) |
+| `dune_query_fork` | Fork an existing saved query | `source_query_id` (int), `name` (str) |
+
+## Resources
+
+- `spice:history/tail/{n}` — View last N lines of query history (1-1000)
+- `spice:artifact/{sha}` — Retrieve stored SQL by SHA-256 hash
+
+## What is Dune?
+
+[Dune](https://dune.com/) is a crypto data platform providing curated blockchain datasets and a public API. It aggregates on-chain data from Ethereum, Solana, Polygon, and other chains into queryable SQL tables. See the [Dune Docs](https://dune.com/docs) for more information.
+
+## Installation
+
+**From PyPI** (recommended):
+```bash
+uv pip install spice-mcp
+```
+
+**From source**:
+```bash
+git clone https://github.com/Evan-Kim2028/spice-mcp.git
+cd spice-mcp
+uv sync
+uv pip install -e .
+```
+
+**Requirements**: Python 3.13+
+
+## Documentation
+
+- [Tool Reference](docs/tools.md) — Complete tool documentation with parameters
+- [Architecture](docs/architecture.md) — Code structure and design patterns
+- [Discovery Guide](docs/discovery.md) — How to explore Dune schemas and tables
+- [Dune API Guide](docs/dune_api.md) — Understanding Dune's data structure
+- [Configuration](docs/config.md) — Environment variables and settings
+
+## License
+
+See [LICENSE](LICENSE) file for details.

spice_mcp-0.1.4/README.md

@@ -0,0 +1,100 @@
+# spice-mcp
+
+[![PyPI version](https://img.shields.io/pypi/v/spice-mcp.svg)](https://pypi.org/project/spice-mcp/)
+<a href="https://glama.ai/mcp/servers/@Evan-Kim2028/spice-mcp">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@Evan-Kim2028/spice-mcp/badge" alt="Spice MCP server" />
+</a>
+
+An MCP server that provides AI agents with direct access to [Dune Analytics](https://dune.com/) data. Execute queries, discover schemas and tables, and manage saved queries—all through a clean, type-safe interface optimized for AI workflows.
+
+## Why spice-mcp?
+
+- **Agent-friendly**: Designed for AI agents using the Model Context Protocol (MCP)
+- **Efficient**: Polars-first pipeline keeps data lazy until needed, reducing memory usage
+- **Discovery**: Built-in tools to explore Dune's extensive blockchain datasets
+- **Type-safe**: Fully typed parameters and responses with FastMCP
+- **Reproducible**: Automatic query history logging and SQL artifact storage
+
+## Quick Start
+
+1. **Install**:
+   ```bash
+   uv pip install spice-mcp
+   ```
+
+2. **Set API key** (choose one method):
+   - **Option A**: Create a `.env` file in your project root:
+     ```bash
+     echo "DUNE_API_KEY=your-api-key-here" > .env
+     ```
+   - **Option B**: Export in your shell:
+     ```bash
+     export DUNE_API_KEY=your-api-key-here
+     ```
+
+3. **Use with Cursor IDE**:
+   Add to Cursor Settings → MCP Servers:
+   ```json
+   {
+     "name": "spice-mcp",
+     "command": "spice-mcp",
+     "env": {
+       "DUNE_API_KEY": "your-dune-api-key-here"
+     }
+   }
+   ```
+
+**Note**: Query history logging is enabled by default. Logs are saved to `logs/queries.jsonl` (or `~/.spice_mcp/logs/queries.jsonl` if not in a project directory). To customize paths, set `SPICE_QUERY_HISTORY` and `SPICE_ARTIFACT_ROOT` environment variables.
+
+## Core Tools
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `dune_query` | Execute queries by ID, URL, or raw SQL | `query` (str), `parameters` (object), `limit` (int), `offset` (int), `format` (`preview\|raw\|metadata\|poll`), `refresh` (bool), `timeout_seconds` (float) |
+| `dune_query_info` | Get metadata for a saved query | `query` (str - ID or URL) |
+| `dune_discover` | Unified discovery across Dune API and Spellbook | `keyword` (str\|list), `schema` (str), `limit` (int), `source` (`dune\|spellbook\|both`), `include_columns` (bool) |
+| `dune_find_tables` | Search schemas and list tables | `keyword` (str), `schema` (str), `limit` (int) |
+| `dune_describe_table` | Get column metadata for a table | `schema` (str), `table` (str) |
+| `spellbook_find_models` | Search Spellbook dbt models | `keyword` (str\|list), `schema` (str), `limit` (int), `include_columns` (bool) |
+| `dune_health_check` | Verify API key and configuration | (no parameters) |
+| `dune_query_create` | Create a new saved query | `name` (str), `query_sql` (str), `description` (str), `tags` (list), `parameters` (list) |
+| `dune_query_update` | Update an existing saved query | `query_id` (int), `name` (str), `query_sql` (str), `description` (str), `tags` (list), `parameters` (list) |
+| `dune_query_fork` | Fork an existing saved query | `source_query_id` (int), `name` (str) |
+
+## Resources
+
+- `spice:history/tail/{n}` — View last N lines of query history (1-1000)
+- `spice:artifact/{sha}` — Retrieve stored SQL by SHA-256 hash
+
+## What is Dune?
+
+[Dune](https://dune.com/) is a crypto data platform providing curated blockchain datasets and a public API. It aggregates on-chain data from Ethereum, Solana, Polygon, and other chains into queryable SQL tables. See the [Dune Docs](https://dune.com/docs) for more information.
+
+## Installation
+
+**From PyPI** (recommended):
+```bash
+uv pip install spice-mcp
+```
+
+**From source**:
+```bash
+git clone https://github.com/Evan-Kim2028/spice-mcp.git
+cd spice-mcp
+uv sync
+uv pip install -e .
+```
+
+**Requirements**: Python 3.13+
+
+## Documentation
+
+- [Tool Reference](docs/tools.md) — Complete tool documentation with parameters
+- [Architecture](docs/architecture.md) — Code structure and design patterns
+- [Discovery Guide](docs/discovery.md) — How to explore Dune schemas and tables
+- [Dune API Guide](docs/dune_api.md) — Understanding Dune's data structure
+- [Configuration](docs/config.md) — Environment variables and settings
+
+## License
+
+See [LICENSE](LICENSE) file for details.

{spice_mcp-0.1.3 → spice_mcp-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spice-mcp"
-version = "0.1.3"
+version = "0.1.4"
 description = "MCP server for Dune Analytics data access"
 authors = [
     { name = "Evan-Kim2028", email = "ekcopersonal@gmail.com" }

{spice_mcp-0.1.3 → spice_mcp-0.1.4}/src/spice_mcp/adapters/dune/client.py

@@ -24,6 +24,10 @@ from ...polars_utils import collect_preview
 from ..http_client import HttpClient, HttpClientConfig
 from . import extract, urls
 
+# Use wrapper to avoid FastMCP detecting overloads in extract.query()
+# Note: We still import extract for _determine_input_type and other non-overloaded functions
+from .query_wrapper import execute_query as _execute_dune_query
+
 
 class DuneAdapter(QueryExecutor, CatalogExplorer):
     """Thin façade around the vendored extract module."""
@@ -47,7 +51,7 @@ class DuneAdapter(QueryExecutor, CatalogExplorer):
             q_rewritten = _maybe_rewrite_show_sql(q)
             if q_rewritten is not None:
                 q = q_rewritten
-        result = extract.query(
+        result = _execute_dune_query(
             query_or_execution=q,
             verbose=False,
             refresh=request.refresh,
@@ -123,9 +127,10 @@ class DuneAdapter(QueryExecutor, CatalogExplorer):
                     pass
 
             url = urls.get_query_results_url(query_id, parameters=params, csv=False)
+            from .user_agent import get_user_agent
             headers = {
                 "X-Dune-API-Key": self._api_key(),
-                "User-Agent": extract.get_user_agent(),
+                "User-Agent": get_user_agent(),
             }
             try:
                 resp = self._http.request("GET", url, headers=headers)
@@ -196,8 +201,8 @@ class DuneAdapter(QueryExecutor, CatalogExplorer):
     def _run_sql(self, sql: str, *, limit: int | None = None) -> pl.DataFrame:
         self._ensure_api_key()
         sql_eff = _maybe_rewrite_show_sql(sql) or sql
-        df = extract.query(
-            sql_eff,
+        df = _execute_dune_query(
+            query_or_execution=sql_eff,
             verbose=False,
             performance="medium",
             timeout_seconds=self.config.default_timeout_seconds,

{spice_mcp-0.1.3 → spice_mcp-0.1.4}/src/spice_mcp/adapters/dune/extract.py

@@ -289,6 +289,14 @@ def query(
 
         # execute or retrieve query
         if query_id:
+            # Check if this is a parameterized query (raw SQL via template or parameterized query)
+            # For parameterized queries, results don't exist until execution, so skip GET attempt
+            is_parameterized = (
+                parameters is not None 
+                and len(parameters) > 0 
+                and ('query' in parameters or any(k != 'query' for k in parameters))
+            )
+            
             if cache and load_from_cache and not refresh:
                 cache_result, cache_execution = _cache.load_from_cache(
                     execute_kwargs, result_kwargs, output_kwargs
@@ -301,7 +309,8 @@ def query(
                 age = get_query_latest_age(**execute_kwargs, verbose=verbose)  # type: ignore
                 if age is None or age > max_age:
                     refresh = True
-            if not refresh:
+            # Skip GET results attempt for parameterized queries - they need execution first
+            if not refresh and not is_parameterized:
                 df = get_results(**execute_kwargs, **result_kwargs)
                 if df is not None:
                     return process_result(df, execution, **output_kwargs)
@@ -334,9 +343,44 @@ def query(
             return execution
 
 
-@overload
-@overload
-@overload
+if TYPE_CHECKING:
+    @overload
+    def _process_result(
+        df: pl.DataFrame,
+        execution: Execution | None,
+        execute_kwargs: ExecuteKwargs,
+        result_kwargs: RetrievalKwargs,
+        cache: bool,
+        save_to_cache: bool,
+        cache_dir: str | None,
+        include_execution: Literal[False],
+    ) -> pl.DataFrame: ...
+
+    @overload
+    def _process_result(
+        df: pl.DataFrame,
+        execution: Execution | None,
+        execute_kwargs: ExecuteKwargs,
+        result_kwargs: RetrievalKwargs,
+        cache: bool,
+        save_to_cache: bool,
+        cache_dir: str | None,
+        include_execution: Literal[True],
+    ) -> tuple[pl.DataFrame, Execution]: ...
+
+    @overload
+    def _process_result(
+        df: pl.DataFrame,
+        execution: Execution | None,
+        execute_kwargs: ExecuteKwargs,
+        result_kwargs: RetrievalKwargs,
+        cache: bool,
+        save_to_cache: bool,
+        cache_dir: str | None,
+        include_execution: bool,
+    ) -> pl.DataFrame | tuple[pl.DataFrame, Execution]: ...
+
+
 def _process_result(
     df: pl.DataFrame,
     execution: Execution | None,

spice_mcp-0.1.4/src/spice_mcp/adapters/dune/query_wrapper.py

@@ -0,0 +1,86 @@
+"""Wrapper for extract.query() to avoid FastMCP overload detection.
+
+This module provides a clean interface to extract.query() without exposing
+the @overload decorators that FastMCP detects during runtime validation.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from collections.abc import Mapping, Sequence
+
+from ..http_client import HttpClient
+from .types import Execution, Performance, Query
+
+
+def execute_query(
+    query_or_execution: Query | Execution,
+    *,
+    verbose: bool = True,
+    refresh: bool = False,
+    max_age: float | None = None,
+    parameters: Mapping[str, Any] | None = None,
+    api_key: str | None = None,
+    performance: Performance = "medium",
+    poll: bool = True,
+    poll_interval: float = 1.0,
+    timeout_seconds: float | None = None,
+    limit: int | None = None,
+    offset: int | None = None,
+    sample_count: int | None = None,
+    sort_by: str | None = None,
+    columns: Sequence[str] | None = None,
+    extras: Mapping[str, Any] | None = None,
+    types: Sequence[type] | Mapping[str, type] | None = None,
+    all_types: Sequence[type] | Mapping[str, type] | None = None,
+    cache: bool = True,
+    cache_dir: str | None = None,
+    save_to_cache: bool = True,
+    load_from_cache: bool = True,
+    include_execution: bool = False,
+    http_client: HttpClient | None = None,
+) -> Any:
+    """
+    Execute a Dune query without exposing overloads to FastMCP.
+    
+    This is a wrapper around extract.query() that has a single, non-overloaded
+    signature. FastMCP won't detect overloads when inspecting this function.
+    """
+    # Import here to avoid FastMCP seeing overloads during module import
+    from . import extract
+    
+    # Call the actual query function - FastMCP won't trace through this wrapper
+    try:
+        return extract.query(
+            query_or_execution=query_or_execution,
+            verbose=verbose,
+            refresh=refresh,
+            max_age=max_age,
+            parameters=parameters,
+            api_key=api_key,
+            performance=performance,
+            poll=poll,
+            poll_interval=poll_interval,
+            timeout_seconds=timeout_seconds,
+            limit=limit,
+            offset=offset,
+            sample_count=sample_count,
+            sort_by=sort_by,
+            columns=columns,
+            extras=extras,
+            types=types,
+            all_types=all_types,
+            cache=cache,
+            cache_dir=cache_dir,
+            save_to_cache=save_to_cache,
+            load_from_cache=load_from_cache,
+            include_execution=include_execution,
+            http_client=http_client,
+        )
+    except NotImplementedError as exc:
+        # Provide additional context to help diagnose overload issues
+        raise RuntimeError(
+            "Underlying extract.query() raised NotImplementedError. "
+            "This suggests we're calling an overloaded stub."
+        ) from exc
+

spice_mcp-0.1.4/src/spice_mcp/adapters/dune/user_agent.py

@@ -0,0 +1,9 @@
+"""User agent utility to avoid importing overloaded functions."""
+
+ADAPTER_VERSION = "0.1.4"
+
+
+def get_user_agent() -> str:
+    """Get user agent string for HTTP requests."""
+    return f"spice-mcp/{ADAPTER_VERSION}"
+

{spice_mcp-0.1.3 → spice_mcp-0.1.4}/src/spice_mcp/mcp/server.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import logging
 import os
-from typing import Any, Literal
+from typing import Any, Literal, Optional
 
 os.environ.setdefault("FASTMCP_NO_BANNER", "1")
 os.environ.setdefault("FASTMCP_LOG_LEVEL", "ERROR")
@@ -22,7 +22,6 @@ try:
 except Exception:
     pass
 
-from ..adapters.dune import extract as dune_extract
 from ..adapters.dune import urls as dune_urls
 from ..adapters.dune.admin import DuneAdminAdapter
 from ..adapters.dune.client import DuneAdapter
@@ -144,9 +143,10 @@ def compute_health_status() -> dict[str, Any]:
         if tmpl:
             tid = dune_urls.get_query_id(tmpl)
             url = dune_urls.url_templates["query"].format(query_id=tid)
+            from ..adapters.dune.user_agent import get_user_agent as get_dune_user_agent
             headers = {
                 "X-Dune-API-Key": os.getenv("DUNE_API_KEY", ""),
-                "User-Agent": dune_extract.get_user_agent(),
+                "User-Agent": get_dune_user_agent(),
             }
             client = HTTP_CLIENT or HttpClient(Config.from_env().http)
             resp = client.request("GET", url, headers=headers, timeout=5.0)
@@ -169,9 +169,10 @@ def dune_query_info(query: str) -> dict[str, Any]:
     try:
         qid = dune_urls.get_query_id(query)
         url = dune_urls.url_templates["query"].format(query_id=qid)
+        from ..adapters.dune.user_agent import get_user_agent as get_dune_user_agent
         headers = {
             "X-Dune-API-Key": dune_urls.get_api_key(),
-            "User-Agent": dune_extract.get_user_agent(),
+            "User-Agent": get_dune_user_agent(),
         }
         client = HTTP_CLIENT or HttpClient(Config.from_env().http)
         resp = client.request("GET", url, headers=headers, timeout=10.0)
@@ -197,33 +198,55 @@ def dune_query_info(query: str) -> dict[str, Any]:
         })
 
 
-@app.tool(
-    name="dune_query",
-    title="Run Dune Query",
-    description="Execute Dune queries and return agent-optimized preview.",
-    tags={"dune", "query"},
-)
-def dune_query(
+def _dune_query_impl(
     query: str,
-    parameters: dict[str, Any] | None = None,
+    parameters: Optional[dict[str, Any]] = None,
     refresh: bool = False,
-    max_age: float | None = None,
-    limit: int | None = None,
-    offset: int | None = None,
-    sample_count: int | None = None,
-    sort_by: str | None = None,
-    columns: list[str] | None = None,
+    max_age: Optional[float] = None,
+    limit: Optional[int] = None,
+    offset: Optional[int] = None,
+    sample_count: Optional[int] = None,
+    sort_by: Optional[str] = None,
+    columns: Optional[list[str]] = None,
     format: Literal["preview", "raw", "metadata", "poll"] = "preview",
-    extras: dict[str, Any] | None = None,
-    timeout_seconds: float | None = None,
+    extras: Optional[dict[str, Any]] = None,
+    timeout_seconds: Optional[float] = None,
 ) -> dict[str, Any]:
+    """Internal implementation of dune_query to avoid FastMCP overload detection."""
     _ensure_initialized()
     assert EXECUTE_QUERY_TOOL is not None
+    
+    # Normalize parameters: handle case where MCP client passes JSON string
+    # This can happen if FastMCP's schema generation doesn't match client expectations
+    normalized_parameters = parameters
+    if isinstance(parameters, str):
+        try:
+            import json
+            normalized_parameters = json.loads(parameters)
+        except (json.JSONDecodeError, TypeError):
+            return error_response(
+                ValueError(f"parameters must be a dict or JSON string, got {type(parameters).__name__}"),
+                context={
+                    "tool": "dune_query",
+                    "query": query,
+                    "parameters_type": type(parameters).__name__,
+                }
+            )
+    
+    # Normalize extras similarly
+    normalized_extras = extras
+    if isinstance(extras, str):
+        try:
+            import json
+            normalized_extras = json.loads(extras)
+        except (json.JSONDecodeError, TypeError):
+            normalized_extras = None
+    
     try:
         # Execute query synchronously
         return EXECUTE_QUERY_TOOL.execute(
             query=query,
-            parameters=parameters,
+            parameters=normalized_parameters,
             refresh=refresh,
             max_age=max_age,
             limit=limit,
@@ -232,7 +255,7 @@ def dune_query(
             sort_by=sort_by,
             columns=columns,
             format=format,
-            extras=extras,
+            extras=normalized_extras,
             timeout_seconds=timeout_seconds,
         )
     except Exception as e:
@@ -244,6 +267,48 @@ def dune_query(
         })
 
 
+@app.tool(
+    name="dune_query",
+    title="Run Dune Query",
+    description="Execute Dune queries and return agent-optimized preview.",
+    tags={"dune", "query"},
+)
+def dune_query(
+    query: str,
+    parameters: Optional[dict[str, Any]] = None,
+    refresh: bool = False,
+    max_age: Optional[float] = None,
+    limit: Optional[int] = None,
+    offset: Optional[int] = None,
+    sample_count: Optional[int] = None,
+    sort_by: Optional[str] = None,
+    columns: Optional[list[str]] = None,
+    format: Literal["preview", "raw", "metadata", "poll"] = "preview",
+    extras: Optional[dict[str, Any]] = None,
+    timeout_seconds: Optional[float] = None,
+) -> dict[str, Any]:
+    """Execute Dune queries (by ID, URL, or raw SQL) and return agent-optimized preview.
+    
+    This wrapper ensures FastMCP doesn't detect overloads in imported functions.
+    """
+    # Always ensure parameters is explicitly passed (even if None) to avoid FastMCP
+    # overload detection when the keyword is omitted
+    return _dune_query_impl(
+        query=query,
+        parameters=parameters,
+        refresh=refresh,
+        max_age=max_age,
+        limit=limit,
+        offset=offset,
+        sample_count=sample_count,
+        sort_by=sort_by,
+        columns=columns,
+        format=format,
+        extras=extras,
+        timeout_seconds=timeout_seconds,
+    )
+
+
 @app.tool(
     name="dune_health_check",
     title="Health Check",

{spice_mcp-0.1.3 → spice_mcp-0.1.4}/src/spice_mcp/mcp/tools/execute_query.py

@@ -5,8 +5,10 @@ import re
 import time
 from typing import Any
 
-from ...adapters.dune import extract as dune_extract
 from ...adapters.dune import urls as dune_urls
+from ...adapters.dune.query_wrapper import execute_query as execute_dune_query
+# Import user_agent from separate module to avoid importing overloaded functions
+from ...adapters.dune.user_agent import get_user_agent as get_dune_user_agent
 from ...adapters.http_client import HttpClient
 from ...config import Config
 from ...core.errors import error_response
@@ -103,7 +105,7 @@ class ExecuteQueryTool(MCPTool):
             q_use = _maybe_rewrite_show_sql(query) or query
             # Poll-only: return execution handle without fetching results
             if format == "poll":
-                exec_obj = dune_extract.query(
+                exec_obj = execute_dune_query(
                     q_use,
                     parameters=parameters,
                     api_key=self.config.dune.api_key,
@@ -333,7 +335,7 @@ class ExecuteQueryTool(MCPTool):
             query_id = dune_urls.get_query_id(query)
             headers = {
                 "X-Dune-API-Key": dune_urls.get_api_key(),
-                "User-Agent": dune_extract.get_user_agent(),
+                "User-Agent": get_dune_user_agent(),
             }
             resp = self._http.request(
                 "GET",
@@ -362,7 +364,7 @@ class ExecuteQueryTool(MCPTool):
                 url = dune_urls.get_execution_status_url(execution_id)
                 headers = {
                     "X-Dune-API-Key": dune_urls.get_api_key(),
-                    "User-Agent": dune_extract.get_user_agent(),
+                    "User-Agent": get_dune_user_agent(),
                 }
                 resp = self._http.request("GET", url, headers=headers, timeout=10.0)
                 data = resp.json()

spice_mcp-0.1.4/test_mcp_cursor/.env.example

@@ -0,0 +1,9 @@
+# Dune API Key
+# Get your API key from https://dune.com/settings/api
+DUNE_API_KEY=your-api-key-here
+
+# Optional: Customize query history location
+# SPICE_QUERY_HISTORY=logs/queries.jsonl
+
+# Optional: Customize artifact storage location  
+# SPICE_ARTIFACT_ROOT=logs/artifacts