spice-mcp 0.1.3__py3-none-any.whl → 0.1.4__py3-none-any.whl

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

@@ -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.3.dist-info → spice_mcp-0.1.4.dist-info}/RECORD

@@ -7,13 +7,15 @@ spice_mcp/adapters/http_client.py,sha256=CYgSKAsx-5c-uxaNIBCBTgQdaoBe5J3dJvnw8iq
 spice_mcp/adapters/dune/__init__.py,sha256=nspEuDpVOktAxm8B066s-d0LwouCYGpvNEexi0mRMN8,386
 spice_mcp/adapters/dune/admin.py,sha256=yxOueVz-rmgC-ZFbT06k59G24yRgYjiEkZlall5hXNQ,3157
 spice_mcp/adapters/dune/cache.py,sha256=7ykT58WN1yHGIN2uV3t7fWOqGb1VJdCvf3I-xZwsv74,4304
-spice_mcp/adapters/dune/client.py,sha256=JPrQZ_dtaPcGf6lYUguDxGweOtxG-8qMqOiXuhWL9QA,9122
-spice_mcp/adapters/dune/extract.py,sha256=3jrXqlak4Kpl11y7C3L1AhFv09lQ-2pBqmrh-0Mwlm0,28836
+spice_mcp/adapters/dune/client.py,sha256=4-Ay2FQf_vo-eB6I9Kul3f1PgS78PPuUJ7zldebOtKU,9424
+spice_mcp/adapters/dune/extract.py,sha256=30D-5NyiOXDtMZoo1dU9pf5yAAFR_ALn6JWvhipPRG0,30405
 spice_mcp/adapters/dune/helpers.py,sha256=BgDKr_g-UqmU2hoMb0ejQZHta_NbKwR1eDJp33sJYNk,227
+spice_mcp/adapters/dune/query_wrapper.py,sha256=Km64otc00u9ieUhpZmL2aNYb9ETt6PoNb8czShIuPbY,2925
 spice_mcp/adapters/dune/transport.py,sha256=eRP-jPY2ZXxvTX9HSjIFqFUlbIzXspgH95jBFoTlpaQ,1436
 spice_mcp/adapters/dune/types.py,sha256=57TMX07u-Gq4BYwRAuZV0xI81nVXgtpp7KBID9YbKyQ,1195
 spice_mcp/adapters/dune/typing_utils.py,sha256=EpWneGDn-eQdo6lkLuESR09KXkDj9OqGz8bEF3JaFkM,574
 spice_mcp/adapters/dune/urls.py,sha256=bcuPERkFQduRTT2BrgzVhoFrMn-Lkvw9NmktcBZYEig,3902
+spice_mcp/adapters/dune/user_agent.py,sha256=c6Kt4zczbuT9mapDoh8-3sgm268MUtvyIRxDF9yJwXQ,218
 spice_mcp/adapters/spellbook/__init__.py,sha256=D2cdVtSUbmAJdbPRvAyKxYS4-wUQ3unXyX4ZFYxenuk,150
 spice_mcp/adapters/spellbook/explorer.py,sha256=Q3UfEGlALizCDeeW_ZZVRRedzwMXiknmxwSkeOnxxgc,11515
 spice_mcp/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -22,18 +24,18 @@ spice_mcp/core/models.py,sha256=i0C_-UE16OWyyZo_liooEJeYvbChE5lpK80aN2OF4lk,1795
 spice_mcp/core/ports.py,sha256=nEdeA3UH7v0kB_hbguMrpDljb9EhSxUAO0SdhjpoijQ,1618
 spice_mcp/logging/query_history.py,sha256=doE9lod64uzJxlA2XzHH2-VAmC6WstYAkQ0taEAxiIM,4315
 spice_mcp/mcp/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-spice_mcp/mcp/server.py,sha256=NNTjn5f_OLNd8zSnNsx73WhHzNGW_SBJoCrdzkgOGP4,26275
+spice_mcp/mcp/server.py,sha256=lHYEI76oQpPcpPT9pEoGXpUmAjDFXlOXuUrlOWV8s2c,28729
 spice_mcp/mcp/tools/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 spice_mcp/mcp/tools/base.py,sha256=zJkVxLgXR48iZcJeng8cZ2rXvbyicagoGlMN7BK7Img,1041
-spice_mcp/mcp/tools/execute_query.py,sha256=CucjxoBT22VUS-QJV1JrDjoywu2nd13fL3Lfs1qytUg,16093
+spice_mcp/mcp/tools/execute_query.py,sha256=CJtoNKpRY6pCkyqjwFy_cTYqTIg9-EsZA8GrH-2MFjk,16262
 spice_mcp/observability/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 spice_mcp/observability/logging.py,sha256=ceJUEpKGpf5PAgPBmpB49zjqhdGCAESfLemFUhDSmI8,529
 spice_mcp/service_layer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 spice_mcp/service_layer/discovery_service.py,sha256=202O0SzCZGQukd9kb2JYfarLygZHgiXlHqp_nTAdrWA,730
 spice_mcp/service_layer/query_admin_service.py,sha256=4q1NAAuTui7cm83Aq2rFDLIzKTHX17yzbSoSJyCmLbI,1356
 spice_mcp/service_layer/query_service.py,sha256=q0eAVW5I3sUxm29DgzPN_cH3rZEzmKwmdE3Xj4qP9lI,3878
-spice_mcp-0.1.3.dist-info/METADATA,sha256=a44b2EfhkPbQSS_PEoU1LF4Kkr2RfSD1gS6gGlEMmnQ,9343
-spice_mcp-0.1.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-spice_mcp-0.1.3.dist-info/entry_points.txt,sha256=4XiXX13Vy-oiUJwlcO_82OltBaxFnEnkJ-76sZGm5os,56
-spice_mcp-0.1.3.dist-info/licenses/LICENSE,sha256=r0GNDnDY1RSkVQp7kEEf6MQU21OrNGJkxUHIsv6eyLk,1079
-spice_mcp-0.1.3.dist-info/RECORD,,
+spice_mcp-0.1.4.dist-info/METADATA,sha256=MyGS87Cwkx0G5urib8a2JbqZVP4stYdGeVknRxzPw5A,5053
+spice_mcp-0.1.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+spice_mcp-0.1.4.dist-info/entry_points.txt,sha256=4XiXX13Vy-oiUJwlcO_82OltBaxFnEnkJ-76sZGm5os,56
+spice_mcp-0.1.4.dist-info/licenses/LICENSE,sha256=r0GNDnDY1RSkVQp7kEEf6MQU21OrNGJkxUHIsv6eyLk,1079
+spice_mcp-0.1.4.dist-info/RECORD,,

spice_mcp-0.1.3.dist-info/METADATA

@@ -1,198 +0,0 @@
-Metadata-Version: 2.4
-Name: spice-mcp
-Version: 0.1.3
-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
-
-spice-mcp is an MCP server for [Dune](https://dune.com/) Analytics. It wraps a curated subset of the original Spice client inside a clean architecture (`core` models/ports → `adapters.dune` → service layer → FastMCP tools) and adds agent-friendly workflows for discovery. Results are Polars-first in Python and compact, token-efficient in MCP responses.
-
-[![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>
-
-Requirements: Python 3.13+
-
-This project uses FastMCP for typed, decorator-registered tools and resources.
-
-## Highlights
-- Polars LazyFrame-first pipeline: results stay lazy until explicitly materialized
-- Ports/adapters layering for maintainable integrations ([docs/architecture.md](docs/architecture.md))
-- Discovery utilities (find schemas/tables, describe columns)
-- JSONL query history + SQL artifacts (SHA-256) for reproducibility
-- Rich MCP surface: query info/run, discovery, health, and Dune admin (create/update/fork)
-
-## What is Dune?
-[Dune](https://dune.com/) is a crypto data platform providing curated blockchain datasets and a public API to run and fetch query results. See the [Dune Docs](https://dune.com/docs) and [Dune API](https://dune.com/docs/api/) for full details.
-
-## Quick Start
-- Export `DUNE_API_KEY` in your shell (the server can also load a local `.env`; set `SPICE_MCP_SKIP_DOTENV=1` to skip during tests).
-- Install from PyPI: `uv pip install spice-mcp`
-- Or install from source:
-  - `uv sync` then `uv pip install -e .`
-- Start the FastMCP stdio server:
-  - `python -m spice_mcp.mcp.server --env PYTHONPATH=$(pwd)/src`
-  - or install the console script via `uv tool install .` and run `spice-mcp`.
-
-## Cursor IDE Setup
-
-To use spice-mcp with Cursor IDE:
-
-1. **Install the MCP Server**:
-   ```bash
-   # Install from PyPI (recommended)
-   uv pip install spice-mcp
-   
-   # Or install from source
-   uv sync
-   uv pip install -e .
-   
-   # Or install via uv tool (creates console script)
-   uv tool install .
-   ```
-
-2. **Configure Cursor**:
-   - Open Cursor Settings → MCP Servers
-   - Add new MCP server configuration:
-   ```json
-   {
-     "name": "spice-mcp",
-     "command": "spice-mcp",
-     "env": {
-       "DUNE_API_KEY": "your-dune-api-key-here"
-     },
-     "disabled": false
-   }
-   ```
-   Alternatively, if you prefer running from source:
-   ```json
-   {
-     "name": "spice-mcp", 
-     "command": "python",
-     "args": ["-m", "spice_mcp.mcp.server"],
-     "env": {
-       "PYTHONPATH": "/path/to/your/spice-mcp/src",
-       "DUNE_API_KEY": "your-dune-api-key-here"
-     },
-     "disabled": false
-   }
-   ```
-
-3. **Restart Cursor** to load the MCP server
-
-4. **Verify Connection**:
-   - Open Cursor and use the command palette (Cmd/Ctrl + Shift + P)
-   - Search for "MCP" or "spice" commands
-   - Test with `dune_health_check` to verify the connection
-
-5. **Available Tools in Cursor**:
-   - `dune_query`: Run Dune queries by ID, URL, or raw SQL
-   - `dune_find_tables`: Search schemas and list tables
-   - `dune_describe_table`: Get column metadata
-   - `dune_health_check`: Verify API connection
-
-**Tip**: Create a `.env` file in your project root with `DUNE_API_KEY=your-key-here` for easier configuration.
-
-## MCP Tools and Features
-
-All tools expose typed parameters, titles, and tags; failures return a consistent error envelope.
-
-- `dune_query_info` (Query Info, tags: dune, query)
-  - Fetch saved-query metadata by ID/URL (name, parameters, tags, SQL, version).
-
-- `dune_query` (Run Dune Query, tags: dune, query)
-  - Execute by ID/URL/raw SQL with parameters. Supports `refresh`, `max_age`, `limit/offset`, `sample_count`, `sort_by`, `columns`, and `format` = `preview|raw|metadata|poll`; accepts `timeout_seconds`.
-
-- `dune_health_check` (Health Check, tag: health)
-  - Checks API key presence, query-history path, logging enabled; best-effort template check when configured.
-
-- `dune_find_tables` (Find Tables, tags: dune, schema)
-  - Search schemas by keyword and/or list tables in a schema (`limit`).
-
-- `dune_describe_table` (Describe Table, tags: dune, schema)
-  - Column metadata for `schema.table` (Dune types + Polars inferred dtypes when available).
-
-- Dune Admin tools (tags: dune, admin)
-  - `dune_query_create(name, query_sql, description?, tags?, parameters?)`
-  - `dune_query_update(query_id, name?, query_sql?, description?, tags?, parameters?)`
-  - `dune_query_fork(source_query_id, name?)`
-
-### Resources
-- `spice:history/tail/{n}` — tail last N lines of query history (1..1000)
-- `spice:artifact/{sha}` — fetch stored SQL by 64-hex SHA-256
-- `spice:sui/events_preview/{hours}/{limit}/{packages}` — Sui events preview (JSON)
-- `spice:sui/package_overview/{hours}/{timeout_seconds}/{packages}` — Sui overview (JSON)
-
-## Resources
-
-- `spice:history/tail/{n}`
-  - Last `n` lines from the query-history JSONL, clamped to [1, 1000]
-
-- `spice:artifact/{sha}`
-  - Returns stored SQL for the SHA-256 (validated as 64 lowercase hex)
-
-Tests
-- Offline/unit tests (no network) live under `tests/offline/` and `tests/http_stubbed/`.
-- Live tests under `tests/live/` are skipped by default; enable with `SPICE_TEST_LIVE=1` and a valid `DUNE_API_KEY`.
-- Comprehensive scripted runner (tiered):
-  - Run all tiers: `python tests/scripts/comprehensive_test_runner.py`
-  - Select tiers: `python tests/scripts/comprehensive_test_runner.py -t 1 -t 3`
-  - Stop on first failure: `python tests/scripts/comprehensive_test_runner.py --stop`
-  - Optional JUnit export: `python tests/scripts/comprehensive_test_runner.py --junit tests/scripts/report.xml`
-- Pytest directly (offline/default): `uv run pytest -q -m "not live" --cov=src/spice_mcp --cov-report=term-missing`
-
-Core Tools (with parameters)
-- `dune_query`
-  - Use: Preview/query results by ID, URL, or raw SQL (Polars preview + Dune metadata/pagination).
-  - Params: `query` (string), `parameters?` (object), `performance?` ('medium'|'large'), `limit?` (int), `offset?` (int), `sort_by?` (string), `columns?` (string[]), `sample_count?` (int), `refresh?` (bool), `max_age?` (number), `timeout_seconds?` (number), `format?` ('preview'|'raw'|'metadata').
-  - Output: `type`, `rowcount`, `columns`, `data_preview`, `execution_id`, `duration_ms`, `metadata?`, `next_uri?`, `next_offset?`.
-- `dune_find_tables`
-  - Use: Search schemas by keyword and/or list tables for a schema.
-  - Params: `keyword?` (string), `schema?` (string), `limit?` (int)
-  - Output: `schemas?` (string[]), `tables?` (string[])
-- `dune_describe_table`
-  - Use: Column descriptions for `schema.table` via SHOW + fallback to 1-row sample inference.
-  - Params: `schema` (string), `table` (string)
-  - Output: `columns` ([{ name, dune_type?, polars_dtype?, extra?, comment? }])
-- `sui_package_overview`
-  - Use: Small-window overview for Sui packages (events/transactions/objects) with timeout handling.
-  - Params: `packages` (string[]), `hours?` (int, default 72), `timeout_seconds?` (number, default 30)
-  - Output: best-effort counts and previews; may include `*_timeout`/`*_error`
-- `dune_health_check`
-  - Use: Verify API key presence and logging paths
-  - Output: `api_key_present`, `query_history_path`, `logging_enabled`, `status`
-
-## Docs
-- See [docs/index.md](docs/index.md) for full documentation:
-  - Dune API structure and capabilities: [docs/dune_api.md](docs/dune_api.md)
-  - Discovery patterns and examples: [docs/discovery.md](docs/discovery.md)
-  
-  - Tool reference and schemas: [docs/tools.md](docs/tools.md)
-  - Codex CLI + tooling integration: [docs/codex_cli.md](docs/codex_cli.md), [docs/codex_cli_tools.md](docs/codex_cli_tools.md)
-  - Architecture overview: [docs/architecture.md](docs/architecture.md)
-  - Installation and configuration: [docs/installation.md](docs/installation.md), [docs/config.md](docs/config.md)
-  - Development and linting: [docs/development.md](docs/development.md)
-
-Notes
-- Legacy Spice code now lives under `src/spice_mcp/adapters/dune` (extract, cache, urls, types).
-- Ports and models live in `src/spice_mcp/core`; services consume ports and are exercised by FastMCP tools.
-- Query history and SQL artefacts are always-on (see `src/spice_mcp/logging/query_history.py`).
-- To bypass dot-env loading during tests/CI, export `SPICE_MCP_SKIP_DOTENV=1`.
-- LazyFrames everywhere: eager `.collect()` or `pl.DataFrame` usage outside dedicated helpers is blocked by `tests/style/test_polars_lazy.py`; materialization helpers live in `src/spice_mcp/polars_utils.py`.