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

spice_mcp/service_layer/verification_service.py

@@ -0,0 +1,185 @@
+"""
+Verification Service - Verifies tables exist in Dune with persistent caching.
+
+This service provides lazy verification of table existence, caching results
+to avoid repeated queries. Cache persists across server restarts.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import time
+from pathlib import Path
+from typing import Any
+
+from ..adapters.dune.client import DuneAdapter
+
+logger = logging.getLogger(__name__)
+
+# Cache entry expires after 1 week (604800 seconds)
+CACHE_TTL_SECONDS = 604800
+
+
+class VerificationService:
+    """
+    Service for verifying table existence in Dune with persistent caching.
+    
+    Verifies tables exist before returning them to users, ensuring only
+    queryable tables are surfaced. Uses persistent cache to avoid repeated
+    verification queries.
+    """
+
+    def __init__(self, cache_path: Path, dune_adapter: DuneAdapter):
+        """
+        Initialize verification service.
+        
+        Args:
+            cache_path: Path to JSON file for persistent cache storage
+            dune_adapter: DuneAdapter instance for querying table existence
+        """
+        self.cache_path = cache_path
+        self.dune_adapter = dune_adapter
+        self._cache: dict[str, dict[str, Any]] = self._load_cache()
+
+    def verify_tables_batch(
+        self, tables: list[tuple[str, str]]
+    ) -> dict[str, bool]:
+        """
+        Verify multiple tables exist in Dune.
+        
+        Uses cache for fast lookups, queries Dune only for uncached tables.
+        Results are cached for future use.
+        
+        Args:
+            tables: List of (schema, table) tuples to verify
+            
+        Returns:
+            Dict mapping "schema.table" -> bool (exists or not)
+        """
+        results: dict[str, bool] = {}
+        to_check: list[tuple[str, str]] = []
+
+        # Check cache first
+        for schema, table in tables:
+            fqn = f"{schema}.{table}"
+            cached = self._get_cached(fqn)
+            if cached is not None:
+                results[fqn] = cached
+            else:
+                to_check.append((schema, table))
+
+        # Verify uncached tables
+        if to_check:
+            logger.info(f"Verifying {len(to_check)} uncached tables")
+            for schema, table in to_check:
+                try:
+                    exists = self._verify_single(schema, table)
+                    fqn = f"{schema}.{table}"
+                    results[fqn] = exists
+                    self._cache_result(fqn, exists)
+                except Exception as e:
+                    # Do not hard-cache transient failures as negative results.
+                    # Leave the table unverified so callers can choose to keep it.
+                    logger.warning(
+                        f"Failed to verify {schema}.{table}: {e}. Skipping cache and leaving unverified."
+                    )
+                    # Intentionally omit from results and cache on failure
+
+        return results
+
+    def _verify_single(self, schema: str, table: str) -> bool:
+        """
+        Verify a single table exists using lightweight DESCRIBE query.
+        
+        Uses SHOW COLUMNS which is fast and doesn't require full table scan.
+        
+        Args:
+            schema: Schema name
+            table: Table name
+            
+        Returns:
+            True if table exists, False otherwise
+        """
+        try:
+            # Use describe_table which internally uses SHOW COLUMNS
+            # This is lightweight and fast
+            self.dune_adapter.describe_table(schema, table)
+            return True
+        except Exception:
+            # If describe fails, table doesn't exist
+            return False
+
+    def _get_cached(self, table: str) -> bool | None:
+        """
+        Get verification result from cache if fresh.
+        
+        Args:
+            table: Fully qualified table name (schema.table)
+            
+        Returns:
+            bool if cached and fresh, None if cache miss or stale
+        """
+        if table not in self._cache:
+            return None
+
+        entry = self._cache[table]
+        timestamp = entry.get("timestamp", 0)
+        age = time.time() - timestamp
+
+        if age < CACHE_TTL_SECONDS:
+            return entry.get("exists", False)
+        else:
+            # Cache entry is stale, remove it
+            del self._cache[table]
+            self._save_cache()
+            return None
+
+    def _cache_result(self, table: str, exists: bool) -> None:
+        """
+        Cache verification result with current timestamp.
+        
+        Args:
+            table: Fully qualified table name
+            exists: Whether table exists
+        """
+        self._cache[table] = {
+            "exists": exists,
+            "timestamp": time.time(),
+        }
+        self._save_cache()
+
+    def _load_cache(self) -> dict[str, dict[str, Any]]:
+        """
+        Load verification cache from disk.
+        
+        Returns:
+            Dict mapping table -> cache entry
+        """
+        if not self.cache_path.exists():
+            return {}
+
+        try:
+            with open(self.cache_path, encoding="utf-8") as f:
+                cache = json.load(f)
+                # Validate cache structure
+                if isinstance(cache, dict):
+                    return cache
+                return {}
+        except Exception as e:
+            logger.warning(f"Failed to load verification cache: {e}")
+            return {}
+
+    def _save_cache(self) -> None:
+        """Persist verification cache to disk."""
+        try:
+            self.cache_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(self.cache_path, "w", encoding="utf-8") as f:
+                json.dump(self._cache, f, indent=2)
+        except Exception as e:
+            logger.warning(f"Failed to save verification cache: {e}")
+
+    def clear_cache(self) -> None:
+        """Clear verification cache (useful for testing or forced refresh)."""
+        self._cache = {}
+        if self.cache_path.exists():
+            self.cache_path.unlink()

spice_mcp-0.1.5.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: spice-mcp
+Version: 0.1.5
+Summary: mcp server built ontop of dune api endpoint
+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.
+
+**Discover High-Quality Tables**: Leverages [Dune Spellbook](https://github.com/duneanalytics/spellbook), Dune's official GitHub repository of curated dbt models, to surface verified, production-ready tables with rich metadata.
+
+## Why spice-mcp?
+
+- **Agent-friendly**: Designed for AI agents using the Model Context Protocol (MCP)
+- **High-Quality Discovery**: Leverages Dune Spellbook's GitHub repository to find verified, production-ready tables with rich metadata
+- **Efficient**: Polars-first pipeline keeps data lazy until needed, reducing memory usage
+- **Discovery**: Built-in tools to explore Dune's extensive blockchain datasets from both Dune API and Spellbook
+- **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 (returns verified tables only). **Leverages Dune Spellbook GitHub repository** for high-quality, curated tables. | `keyword` (str\|list), `schema` (str), `limit` (int), `source` (`dune\|spellbook\|both`), `include_columns` (bool) |
+| `dune_describe_table` | Get column metadata for a table | `schema` (str), `table` (str) |
+| `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.
+
+## What is Dune Spellbook?
+
+[Dune Spellbook](https://github.com/duneanalytics/spellbook) is Dune's official GitHub repository containing thousands of curated dbt models. These models represent high-quality, production-ready tables that are:
+
+- **Verified**: All tables are verified to exist in Dune before being returned
+- **Well-documented**: Rich metadata including column descriptions and types
+- **Maintained**: Regularly updated by the Dune community and team
+- **Production-ready**: Used by analysts and dashboards across the ecosystem
+
+spice-mcp automatically clones and parses the Spellbook repository to discover these high-quality tables, parsing dbt config blocks to resolve actual Dune table names and verifying their existence before returning them to you.
+
+## 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.5.dist-info}/RECORD

@@ -7,33 +7,36 @@ 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=zle19bU-I3AzpOF1cp_hEaZUFNQV1RWhtl1LAxObk0g,9052
+spice_mcp/adapters/dune/extract.py,sha256=67x-WCaP13vbMsTKnqNSOVbMs6Dsf0QHi2fLHduYTBI,30405
 spice_mcp/adapters/dune/helpers.py,sha256=BgDKr_g-UqmU2hoMb0ejQZHta_NbKwR1eDJp33sJYNk,227
+spice_mcp/adapters/dune/query_wrapper.py,sha256=4dk8D8KJKWoBhuMLzDGupRrXGlG-N0cbM6HCs8wMFvE,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/adapters/spellbook/explorer.py,sha256=nfecYztzxfBXp9b9IKcP4dVICCnPzhHvPfNJKFhaKxA,14856
 spice_mcp/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 spice_mcp/core/errors.py,sha256=jlfTuyRaAaA_oU07KUk-1pDAAa43KG0BbZc5CINXtoE,3256
 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=oi0RRaSithCgUt0Qt6Tb3gks32LN0dOOwN7kX-BrN7s,32263
 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=K1YpuQGwvVM20A4_h9zNlkeG37J7jbY7BPzLm6vPAsY,16033
 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/service_layer/verification_service.py,sha256=dPA88p9zKqg62bNjN_4c5QFEUBHCWjZph8pn2a5zrUI,6057
+spice_mcp-0.1.5.dist-info/METADATA,sha256=ag4hjEMz-qxvImxJPxpsQN_0F9BOUdbk6TF8zAXW5I4,6093
+spice_mcp-0.1.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+spice_mcp-0.1.5.dist-info/entry_points.txt,sha256=4XiXX13Vy-oiUJwlcO_82OltBaxFnEnkJ-76sZGm5os,56
+spice_mcp-0.1.5.dist-info/licenses/LICENSE,sha256=r0GNDnDY1RSkVQp7kEEf6MQU21OrNGJkxUHIsv6eyLk,1079
+spice_mcp-0.1.5.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`.