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

spice_mcp/adapters/dune/client.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import os
-import re
 import time
 from collections.abc import Mapping, Sequence
 from typing import Any
@@ -47,10 +46,9 @@ class DuneAdapter(QueryExecutor, CatalogExplorer):
         self._ensure_api_key()
         start = time.time()
         q = request.query
-        if isinstance(q, str):
-            q_rewritten = _maybe_rewrite_show_sql(q)
-            if q_rewritten is not None:
-                q = q_rewritten
+        # Use native SHOW statements directly - they're faster than information_schema queries
+        # See issue #10: https://github.com/Evan-Kim2028/spice-mcp/issues/10
+        # Removed rewrite to avoid performance issues with information_schema queries
         result = _execute_dune_query(
             query_or_execution=q,
             verbose=False,
@@ -200,7 +198,9 @@ class DuneAdapter(QueryExecutor, CatalogExplorer):
     # Internal helpers --------------------------------------------------------------
     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
+        # Use native SHOW statements directly - they're faster than information_schema queries
+        # See issue #10: https://github.com/Evan-Kim2028/spice-mcp/issues/10
+        sql_eff = sql
         df = _execute_dune_query(
             query_or_execution=sql_eff,
             verbose=False,
@@ -233,28 +233,12 @@ def _build_preview(lf: pl.LazyFrame, columns: list[str], rowcount: int) -> Resul
 
 
 def _maybe_rewrite_show_sql(sql: str) -> str | None:
-    """Rewrite certain SHOW statements to information_schema SELECTs for portability.
-
-    This allows running discovery-style commands through the parameterized raw SQL
-    template which expects SELECT statements.
+    """DEPRECATED: This function is no longer used.
+    
+    Native SHOW statements are now used directly as they're faster than
+    information_schema queries in Dune. See issue #10 for details.
+    
+    This function is kept for backward compatibility but is not called.
     """
-    s = sql.strip()
-    m = re.match(r"^SHOW\s+SCHEMAS\s+LIKE\s+'([^']+)'\s*;?$", s, flags=re.IGNORECASE)
-    if m:
-        pat = m.group(1)
-        return (
-            "SELECT schema_name AS Schema FROM information_schema.schemata "
-            f"WHERE schema_name LIKE '{pat}'"
-        )
-    if re.match(r"^SHOW\s+SCHEMAS\s*;?$", s, flags=re.IGNORECASE):
-        return "SELECT schema_name AS Schema FROM information_schema.schemata"
-
-    m = re.match(r"^SHOW\s+TABLES\s+FROM\s+([A-Za-z0-9_\.]+)\s*;?$", s, flags=re.IGNORECASE)
-    if m:
-        schema = m.group(1)
-        return (
-            "SELECT table_name AS Table FROM information_schema.tables "
-            f"WHERE table_schema = '{schema}'"
-        )
-
+    # Function body kept for reference but not executed
     return None

spice_mcp/adapters/dune/extract.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
 import io
+import os
 import time
 from typing import TYPE_CHECKING, overload
-import os
 
 from ..http_client import HttpClient
 from . import cache as _cache

spice_mcp/adapters/dune/query_wrapper.py

@@ -6,8 +6,8 @@ the @overload decorators that FastMCP detects during runtime validation.
 
 from __future__ import annotations
 
-from typing import Any
 from collections.abc import Mapping, Sequence
+from typing import Any
 
 from ..http_client import HttpClient
 from .types import Execution, Performance, Query

spice_mcp/adapters/spellbook/explorer.py

@@ -133,11 +133,43 @@ class SpellbookExplorer(CatalogExplorer):
                     if not schema_yml.exists():
                         schema_yml = sql_file.parent.parent / "schema.yml"
                     
+                    # Parse dbt config to get actual Dune table name
+                    config = self._parse_dbt_config(sql_file)
+
+                    # Ignore templated dbt config values like "{{ target.schema }}"
+                    def _is_templated(val: Any) -> bool:
+                        try:
+                            s = str(val)
+                        except Exception:
+                            return False
+                        return "{{" in s and "}}" in s
+
+                    raw_schema = config.get("schema")
+                    raw_alias = config.get("alias")
+
+                    dune_schema = (
+                        raw_schema.strip() if isinstance(raw_schema, str) else raw_schema
+                    )
+                    dune_alias = (
+                        raw_alias.strip() if isinstance(raw_alias, str) else raw_alias
+                    )
+
+                    # Fall back to original names when values are templated or empty
+                    if not dune_schema or _is_templated(dune_schema):
+                        dune_schema = schema_name
+                    if not dune_alias or _is_templated(dune_alias):
+                        dune_alias = model_name
+
+                    dune_table = f"{dune_schema}.{dune_alias}"
+                    
                     models[schema_name].append({
                         "name": model_name,
                         "file": sql_file,
                         "schema_yml": schema_yml if schema_yml.exists() else None,
                         "schema": schema_name,
+                        "dune_schema": dune_schema,
+                        "dune_alias": dune_alias,
+                        "dune_table": dune_table,
                     })
         
         self._models_cache = models
@@ -264,6 +296,58 @@ class SpellbookExplorer(CatalogExplorer):
         
         return []
 
+    def _parse_dbt_config(self, sql_file: Path) -> dict[str, str]:
+        """
+        Parse dbt config block from SQL file to extract schema and alias.
+        
+        Looks for patterns like:
+        {{ config(schema='sui_walrus', alias='base_table') }}
+        {{ config(schema="sui_walrus", alias="base_table") }}
+        
+        Returns dict with 'schema' and 'alias' keys, or empty dict if not found.
+        """
+        try:
+            with open(sql_file, encoding="utf-8") as f:
+                sql = f.read()
+            
+            # Match dbt config block: {{ config(...) }}
+            # Use non-greedy match to get first config block
+            config_match = re.search(
+                r"{{\s*config\s*\((.*?)\)\s*}}",
+                sql,
+                re.IGNORECASE | re.DOTALL,
+            )
+            
+            if not config_match:
+                return {}
+            
+            config_content = config_match.group(1)
+            result: dict[str, str] = {}
+            
+            # Extract schema parameter (supports single and double quotes)
+            schema_match = re.search(
+                r"schema\s*=\s*['\"]([^'\"]+)['\"]",
+                config_content,
+                re.IGNORECASE,
+            )
+            if schema_match:
+                result["schema"] = schema_match.group(1)
+            
+            # Extract alias parameter (supports single and double quotes)
+            alias_match = re.search(
+                r"alias\s*=\s*['\"]([^'\"]+)['\"]",
+                config_content,
+                re.IGNORECASE,
+            )
+            if alias_match:
+                result["alias"] = alias_match.group(1)
+            
+            return result
+        except Exception:
+            # On any error (file read, parsing, etc.), return empty dict
+            # This allows fallback to using schema_name and model_name
+            return {}
+
     def _parse_sql_columns(self, sql_file: Path) -> list[TableColumn]:
         """Parse SQL file to extract column names from SELECT statements."""
         try:
@@ -310,4 +394,3 @@ class SpellbookExplorer(CatalogExplorer):
             pass
         
         return []
-

spice_mcp/mcp/server.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import logging
 import os
-from typing import Any, Literal, Optional
+from typing import Any, Literal
 
 os.environ.setdefault("FASTMCP_NO_BANNER", "1")
 os.environ.setdefault("FASTMCP_LOG_LEVEL", "ERROR")
@@ -33,6 +33,7 @@ from ..logging.query_history import QueryHistory
 from ..service_layer.discovery_service import DiscoveryService
 from ..service_layer.query_admin_service import QueryAdminService
 from ..service_layer.query_service import QueryService
+from ..service_layer.verification_service import VerificationService
 from .tools.execute_query import ExecuteQueryTool
 
 logger = logging.getLogger(__name__)
@@ -47,6 +48,7 @@ QUERY_ADMIN_SERVICE: QueryAdminService | None = None
 DISCOVERY_SERVICE: DiscoveryService | None = None
 SPELLBOOK_EXPLORER: SpellbookExplorer | None = None
 HTTP_CLIENT: HttpClient | None = None
+VERIFICATION_SERVICE: VerificationService | None = None
 
 EXECUTE_QUERY_TOOL: ExecuteQueryTool | None = None
 
@@ -57,7 +59,7 @@ app = FastMCP("spice-mcp")
 def _ensure_initialized() -> None:
     """Initialize configuration and tool instances if not already initialized."""
     global CONFIG, QUERY_HISTORY, DUNE_ADAPTER, QUERY_SERVICE, DISCOVERY_SERVICE, QUERY_ADMIN_SERVICE
-    global EXECUTE_QUERY_TOOL, HTTP_CLIENT, SPELLBOOK_EXPLORER
+    global EXECUTE_QUERY_TOOL, HTTP_CLIENT, SPELLBOOK_EXPLORER, VERIFICATION_SERVICE
 
     if CONFIG is not None and EXECUTE_QUERY_TOOL is not None:
         return
@@ -95,6 +97,15 @@ def _ensure_initialized() -> None:
     
     # Initialize Spellbook explorer (lazy, clones repo on first use)
     SPELLBOOK_EXPLORER = SpellbookExplorer()
+    
+    # Initialize verification service with persistent cache
+    from pathlib import Path
+    cache_dir = Path.home() / ".spice_mcp"
+    cache_dir.mkdir(exist_ok=True)
+    VERIFICATION_SERVICE = VerificationService(
+        cache_path=cache_dir / "table_verification_cache.json",
+        dune_adapter=DUNE_ADAPTER,
+    )
 
     EXECUTE_QUERY_TOOL = ExecuteQueryTool(CONFIG, QUERY_SERVICE, QUERY_HISTORY)
 
@@ -200,17 +211,17 @@ def dune_query_info(query: str) -> dict[str, Any]:
 
 def _dune_query_impl(
     query: str,
-    parameters: Optional[dict[str, Any]] = None,
+    parameters: dict[str, Any] | None = 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,
+    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,
     format: Literal["preview", "raw", "metadata", "poll"] = "preview",
-    extras: Optional[dict[str, Any]] = None,
-    timeout_seconds: Optional[float] = None,
+    extras: dict[str, Any] | None = None,
+    timeout_seconds: float | None = None,
 ) -> dict[str, Any]:
     """Internal implementation of dune_query to avoid FastMCP overload detection."""
     _ensure_initialized()
@@ -275,20 +286,32 @@ def _dune_query_impl(
 )
 def dune_query(
     query: str,
-    parameters: Optional[dict[str, Any]] = None,
+    parameters: dict[str, Any] | None = 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,
+    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,
     format: Literal["preview", "raw", "metadata", "poll"] = "preview",
-    extras: Optional[dict[str, Any]] = None,
-    timeout_seconds: Optional[float] = None,
+    extras: dict[str, Any] | None = None,
+    timeout_seconds: float | None = None,
 ) -> dict[str, Any]:
     """Execute Dune queries (by ID, URL, or raw SQL) and return agent-optimized preview.
     
+    ⚠️ IMPORTANT: ALWAYS use dune_discover FIRST to find verified table names.
+    Do not guess table names or query information_schema directly.
+    
+    The query parameter accepts:
+    - Query IDs (e.g., "123456")
+    - Query URLs (e.g., "https://dune.com/queries/123456")
+    - Raw SQL using tables discovered via dune_discover
+    
+    For Spellbook models, use the 'dune_table' field returned by dune_discover.
+    Example: dune_discover(keyword="walrus") → returns dune_table="sui_walrus.base_table"
+             Then use: dune_query(query="SELECT * FROM sui_walrus.base_table LIMIT 10")
+    
     This wrapper ensures FastMCP doesn't detect overloads in imported functions.
     """
     # Always ensure parameters is explicitly passed (even if None) to avoid FastMCP
@@ -319,22 +342,6 @@ def dune_health_check() -> dict[str, Any]:
     return compute_health_status()
 
 
-def _dune_find_tables_impl(
-    keyword: str | None = None,
-    schema: str | None = None,
-    limit: int = 50,
-) -> dict[str, Any]:
-    _ensure_initialized()
-    assert DISCOVERY_SERVICE is not None
-    out: dict[str, Any] = {}
-    if keyword:
-        out["schemas"] = DISCOVERY_SERVICE.find_schemas(keyword)
-    if schema:
-        tables = DISCOVERY_SERVICE.list_tables(schema, limit=limit)
-        out["tables"] = [summary.table for summary in tables]
-    return out
-
-
 def _unified_discover_impl(
     keyword: str | list[str] | None = None,
     schema: str | None = None,
@@ -380,6 +387,8 @@ def _unified_discover_impl(
                     "table": summary.table,
                     "fully_qualified_name": f"{schema}.{summary.table}",
                     "source": "dune",
+                    "dune_table": f"{schema}.{summary.table}",
+                    "verified": True,
                 }
                 for summary in tables
             ]
@@ -415,11 +424,57 @@ def _unified_discover_impl(
                     "table": model["table"],
                     "fully_qualified_name": model["fully_qualified_name"],
                     "source": "spellbook",
+                    # Include resolved Dune table names
+                    "dune_schema": model.get("dune_schema"),
+                    "dune_alias": model.get("dune_alias"),
+                    "dune_table": model.get("dune_table"),
                 }
                 if "columns" in model:
                     table_info["columns"] = model["columns"]
                 out["tables"].append(table_info)
     
+    # Verify Spellbook tables exist in Dune before returning
+    if source in ("spellbook", "both") and out["tables"]:
+        assert VERIFICATION_SERVICE is not None
+        # Extract Spellbook tables that need verification
+        spellbook_tables = [
+            (t["dune_schema"], t["dune_alias"])
+            for t in out["tables"]
+            if t.get("source") == "spellbook" and t.get("dune_schema") and t.get("dune_alias")
+        ]
+        
+        if spellbook_tables:
+            # Verify tables exist (uses cache, queries Dune only if needed)
+            verification_results = VERIFICATION_SERVICE.verify_tables_batch(spellbook_tables)
+
+            # Filter: drop only tables explicitly verified as False.
+            # Keep tables when verification is True or inconclusive (missing).
+            verified_tables = []
+            for t in out["tables"]:
+                if t.get("source") != "spellbook":
+                    # Keep Dune tables as-is
+                    verified_tables.append(t)
+                    continue
+                dune_fqn = t.get("dune_table")
+                if not dune_fqn:
+                    # If we couldn't resolve dune_table, keep it (conservative)
+                    verified_tables.append(t)
+                    continue
+                vr = verification_results.get(dune_fqn)
+                if vr is False:
+                    # Explicitly known to be non-existent -> drop
+                    continue
+                if vr is True:
+                    t["verified"] = True
+                # If vr is None/missing (inconclusive), keep without setting verified
+                verified_tables.append(t)
+            
+            out["tables"] = verified_tables
+            
+            # Add helpful message if no tables found
+            if not out["tables"] and len(spellbook_tables) > 0:
+                out["message"] = "No verified tables found. Try different keywords or check schema names."
+    
     # Deduplicate and sort schemas
     out["schemas"] = sorted(list(set(out["schemas"])))
     
@@ -444,11 +499,19 @@ def dune_discover(
     include_columns: bool = True,
 ) -> dict[str, Any]:
     """
-    Unified discovery tool for Dune tables and Spellbook models.
+    PRIMARY discovery tool for finding tables in Dune.
+    
+    ⚠️ IMPORTANT: ALWAYS use this tool instead of querying information_schema directly.
+    Querying information_schema is slow and causes lag. This tool uses optimized
+    native SHOW statements for fast discovery.
     
-    This tool can search both Dune's live schemas (via SQL queries) and Spellbook's
-    dbt models (via GitHub repo parsing) in a single call. You don't need to decide
-    which source to use - it can search both automatically.
+    This tool automatically:
+    - Parses dbt configs from Spellbook models to resolve actual Dune table names
+    - Verifies tables exist in Dune before returning them
+    - Returns ONLY verified, queryable tables
+    
+    All returned tables are VERIFIED to exist - you can query them immediately using
+    the 'dune_table' field.
     
     Args:
         keyword: Search term(s) - can be a string or list of strings
@@ -463,16 +526,25 @@ def dune_discover(
         Dictionary with:
         - 'schemas': List of matching schema names
         - 'tables': List of table/model objects, each with:
-          - schema: Schema name
-          - table: Table/model name
-          - fully_qualified_name: schema.table
+          - schema: Schema name (Spellbook subproject name)
+          - table: Table/model name (Spellbook model name)
+          - fully_qualified_name: schema.table (Spellbook format)
           - source: "dune" or "spellbook"
+          - dune_schema: Actual Dune schema name (for Spellbook models)
+          - dune_alias: Actual Dune table alias (for Spellbook models)
+          - dune_table: Verified, queryable Dune table name (e.g., "sui_walrus.base_table")
+          - verified: True (all returned tables are verified to exist)
           - columns: Column details (for Spellbook models, if include_columns=True)
         - 'source': The source parameter used
+        - 'message': Helpful message if no tables found
     
     Examples:
-        # Search both sources for layerzero
-        dune_discover(keyword="layerzero")
+        # Search both sources for walrus - returns verified tables only
+        dune_discover(keyword="walrus")
+        # → Returns tables with dune_table field like "sui_walrus.base_table"
+        
+        # Use the dune_table field to query immediately
+        dune_query(query="SELECT * FROM sui_walrus.base_table LIMIT 10")
         
         # Search only Spellbook
         dune_discover(keyword=["layerzero", "bridge"], source="spellbook")
@@ -500,26 +572,6 @@ def dune_discover(
         })
 
 
-@app.tool(
-    name="dune_find_tables",
-    title="Find Tables",
-    description="Search schemas and optionally list tables.",
-    tags={"dune", "schema"},
-)
-def dune_find_tables(keyword: str | None = None, schema: str | None = None, limit: int = 50) -> dict[str, Any]:
-    """
-    Search schemas and optionally list tables in Dune.
-    """
-    try:
-        return _dune_find_tables_impl(keyword=keyword, schema=schema, limit=limit)
-    except Exception as e:
-        return error_response(e, context={
-            "tool": "dune_find_tables",
-            "keyword": keyword,
-            "schema": schema,
-        })
-
-
 def _dune_describe_table_impl(schema: str, table: str) -> dict[str, Any]:
     _ensure_initialized()
     assert DISCOVERY_SERVICE is not None
@@ -594,10 +646,22 @@ def _spellbook_find_models_impl(
                     matches_keyword = any(kw.lower() in table_name for kw in keywords)
                     
                     if matches_keyword:
+                        # Get model details including resolved Dune table names
+                        models_dict = SPELLBOOK_EXPLORER._load_models()
+                        model_details = None
+                        for m in models_dict.get(schema_name, []):
+                            if m["name"] == table_summary.table:
+                                model_details = m
+                                break
+                        
                         model_info: dict[str, Any] = {
                             "schema": schema_name,
                             "table": table_summary.table,
                             "fully_qualified_name": f"{schema_name}.{table_summary.table}",
+                            # Include resolved Dune table names if available
+                            "dune_schema": model_details.get("dune_schema") if model_details else None,
+                            "dune_alias": model_details.get("dune_alias") if model_details else None,
+                            "dune_table": model_details.get("dune_table") if model_details else None,
                         }
                         
                         # Include column details if requested
@@ -629,10 +693,22 @@ def _spellbook_find_models_impl(
             out["models"] = []
         
         for table_summary in tables:
+            # Get model details including resolved Dune table names
+            models_dict = SPELLBOOK_EXPLORER._load_models()
+            model_details = None
+            for m in models_dict.get(schema, []):
+                if m["name"] == table_summary.table:
+                    model_details = m
+                    break
+            
             model_info: dict[str, Any] = {
                 "schema": schema,
                 "table": table_summary.table,
                 "fully_qualified_name": f"{schema}.{table_summary.table}",
+                # Include resolved Dune table names if available
+                "dune_schema": model_details.get("dune_schema") if model_details else None,
+                "dune_alias": model_details.get("dune_alias") if model_details else None,
+                "dune_table": model_details.get("dune_table") if model_details else None,
             }
             
             # Include column details if requested
@@ -656,47 +732,6 @@ def _spellbook_find_models_impl(
     return out
 
 
-@app.tool(
-    name="spellbook_find_models",
-    title="Search Spellbook",
-    description="Search dbt models in Spellbook GitHub repository.",
-    tags={"spellbook", "dbt", "schema"},
-)
-def spellbook_find_models(
-    keyword: str | list[str] | None = None,
-    schema: str | None = None,
-    limit: int = 50,
-    include_columns: bool = True,
-) -> dict[str, Any]:
-    """
-    Search Spellbook dbt models from GitHub repository.
-    
-    Args:
-        keyword: Search term(s) to find models - can be a string or list of strings
-        schema: Schema/subproject name to list tables from
-        limit: Maximum number of models to return
-        include_columns: Whether to include column details in results (default: True)
-    
-    Returns:
-        Dictionary with 'schemas' and 'models' keys
-    """
-    try:
-        return _spellbook_find_models_impl(
-            keyword=keyword,
-            schema=schema,
-            limit=limit,
-            include_columns=include_columns,
-        )
-    except Exception as e:
-        return error_response(e, context={
-            "tool": "spellbook_find_models",
-            "keyword": keyword,
-            "schema": schema,
-        })
-
-
-
-
 # Resources
 @app.resource(uri="spice:history/tail/{n}", name="Query History Tail", description="Tail last N lines from query history")
 def history_tail(n: str) -> str:

spice_mcp/mcp/tools/execute_query.py

@@ -1,12 +1,12 @@
 from __future__ import annotations
 
 import os
-import re
 import time
 from typing import Any
 
 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
@@ -101,8 +101,10 @@ class ExecuteQueryTool(MCPTool):
     ) -> dict[str, Any]:
         t0 = time.time()
         try:
-            # Rewrite SHOW statements to portable information_schema SELECTs
-            q_use = _maybe_rewrite_show_sql(query) or query
+            # Use native SHOW statements directly - they're faster than information_schema queries
+            # See issue #10: https://github.com/Evan-Kim2028/spice-mcp/issues/10
+            # Removed rewrite to avoid performance issues with information_schema queries
+            q_use = query
             # Poll-only: return execution handle without fetching results
             if format == "poll":
                 exec_obj = execute_dune_query(
@@ -395,22 +397,12 @@ def _categorize_query(q: str) -> str:
 
 
 def _maybe_rewrite_show_sql(sql: str) -> str | None:
-    s = sql.strip()
-    m = re.match(r"^SHOW\s+SCHEMAS\s+LIKE\s+'([^']+)'\s*;?$", s, flags=re.IGNORECASE)
-    if m:
-        pat = m.group(1)
-        return (
-            "SELECT schema_name AS Schema FROM information_schema.schemata "
-            f"WHERE schema_name LIKE '{pat}'"
-        )
-    if re.match(r"^SHOW\s+SCHEMAS\s*;?$", s, flags=re.IGNORECASE):
-        return "SELECT schema_name AS Schema FROM information_schema.schemata"
-
-    m = re.match(r"^SHOW\s+TABLES\s+FROM\s+([A-Za-z0-9_\.]+)\s*;?$", s, flags=re.IGNORECASE)
-    if m:
-        schema = m.group(1)
-        return (
-            "SELECT table_name AS Table FROM information_schema.tables "
-            f"WHERE table_schema = '{schema}'"
-        )
+    """DEPRECATED: This function is no longer used.
+    
+    Native SHOW statements are now used directly as they're faster than
+    information_schema queries in Dune. See issue #10 for details.
+    
+    This function is kept for backward compatibility but is not called.
+    """
+    # Function body kept for reference but not executed
     return None

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.4.dist-info → spice_mcp-0.1.5.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: spice-mcp
-Version: 0.1.4
-Summary: MCP server for Dune Analytics data access
+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
@@ -28,11 +28,14 @@ Description-Content-Type: text/markdown
 
 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
+- **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
 
@@ -73,10 +76,8 @@ An MCP server that provides AI agents with direct access to [Dune Analytics](htt
 |------|-------------|----------------|
 | `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_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) |
-| `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) |
@@ -91,6 +92,17 @@ An MCP server that provides AI agents with direct access to [Dune Analytics](htt
 
 [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):

{spice_mcp-0.1.4.dist-info → spice_mcp-0.1.5.dist-info}/RECORD

@@ -7,35 +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=4-Ay2FQf_vo-eB6I9Kul3f1PgS78PPuUJ7zldebOtKU,9424
-spice_mcp/adapters/dune/extract.py,sha256=30D-5NyiOXDtMZoo1dU9pf5yAAFR_ALn6JWvhipPRG0,30405
+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=Km64otc00u9ieUhpZmL2aNYb9ETt6PoNb8czShIuPbY,2925
+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=lHYEI76oQpPcpPT9pEoGXpUmAjDFXlOXuUrlOWV8s2c,28729
+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=CJtoNKpRY6pCkyqjwFy_cTYqTIg9-EsZA8GrH-2MFjk,16262
+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.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/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,,