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

spice_mcp/mcp/server.py

@@ -27,15 +27,14 @@ from ..adapters.dune import urls as dune_urls
 from ..adapters.dune.admin import DuneAdminAdapter
 from ..adapters.dune.client import DuneAdapter
 from ..adapters.http_client import HttpClient
+from ..adapters.spellbook.explorer import SpellbookExplorer
 from ..config import Config
 from ..core.errors import error_response
 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.sui_service import SuiService
 from .tools.execute_query import ExecuteQueryTool
-from .tools.sui_package_overview import SuiPackageOverviewTool
 
 logger = logging.getLogger(__name__)
 
@@ -46,13 +45,11 @@ QUERY_HISTORY: QueryHistory | None = None
 DUNE_ADAPTER: DuneAdapter | None = None
 QUERY_SERVICE: QueryService | None = None
 QUERY_ADMIN_SERVICE: QueryAdminService | None = None
-SEMAPHORE = None
 DISCOVERY_SERVICE: DiscoveryService | None = None
-SUI_SERVICE: SuiService | None = None
+SPELLBOOK_EXPLORER: SpellbookExplorer | None = None
 HTTP_CLIENT: HttpClient | None = None
 
 EXECUTE_QUERY_TOOL: ExecuteQueryTool | None = None
-SUI_OVERVIEW_TOOL: SuiPackageOverviewTool | None = None
 
 
 app = FastMCP("spice-mcp")
@@ -60,8 +57,8 @@ 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, SUI_SERVICE, QUERY_ADMIN_SERVICE
-    global EXECUTE_QUERY_TOOL, SUI_OVERVIEW_TOOL, HTTP_CLIENT
+    global CONFIG, QUERY_HISTORY, DUNE_ADAPTER, QUERY_SERVICE, DISCOVERY_SERVICE, QUERY_ADMIN_SERVICE
+    global EXECUTE_QUERY_TOOL, HTTP_CLIENT, SPELLBOOK_EXPLORER
 
     if CONFIG is not None and EXECUTE_QUERY_TOOL is not None:
         return
@@ -96,17 +93,11 @@ def _ensure_initialized() -> None:
             http_config=CONFIG.http,
         )
     )
-    SUI_SERVICE = SuiService(QUERY_SERVICE)
+    
+    # Initialize Spellbook explorer (lazy, clones repo on first use)
+    SPELLBOOK_EXPLORER = SpellbookExplorer()
 
     EXECUTE_QUERY_TOOL = ExecuteQueryTool(CONFIG, QUERY_SERVICE, QUERY_HISTORY)
-    SUI_OVERVIEW_TOOL = SuiPackageOverviewTool(SUI_SERVICE)
-    # Concurrency gate for heavy query executions
-    try:
-        import asyncio
-        global SEMAPHORE
-        SEMAPHORE = asyncio.Semaphore(CONFIG.max_concurrent_queries)
-    except Exception:
-        pass
 
     logger.info("spice-mcp server ready (fastmcp)!")
 
@@ -173,7 +164,7 @@ def compute_health_status() -> dict[str, Any]:
     description="Fetch Dune query metadata (name, parameters, tags, SQL).",
     tags={"dune", "query"},
 )
-async def dune_query_info(query: str) -> dict[str, Any]:
+def dune_query_info(query: str) -> dict[str, Any]:
     _ensure_initialized()
     try:
         qid = dune_urls.get_query_id(query)
@@ -212,7 +203,7 @@ async def dune_query_info(query: str) -> dict[str, Any]:
     description="Execute Dune queries and return agent-optimized preview.",
     tags={"dune", "query"},
 )
-async def dune_query(
+def dune_query(
     query: str,
     parameters: dict[str, Any] | None = None,
     refresh: bool = False,
@@ -229,8 +220,8 @@ async def dune_query(
     _ensure_initialized()
     assert EXECUTE_QUERY_TOOL is not None
     try:
-        # Execute query directly without semaphore concurrency control
-        return await EXECUTE_QUERY_TOOL.execute(
+        # Execute query synchronously
+        return EXECUTE_QUERY_TOOL.execute(
             query=query,
             parameters=parameters,
             refresh=refresh,
@@ -259,11 +250,11 @@ async def dune_query(
     description="Validate Dune API key presence and logging setup.",
     tags={"health"},
 )
-async def dune_health_check() -> dict[str, Any]:
+def dune_health_check() -> dict[str, Any]:
     return compute_health_status()
 
 
-async def _dune_find_tables_impl(
+def _dune_find_tables_impl(
     keyword: str | None = None,
     schema: str | None = None,
     limit: int = 50,
@@ -279,15 +270,183 @@ async def _dune_find_tables_impl(
     return out
 
 
+def _unified_discover_impl(
+    keyword: str | list[str] | None = None,
+    schema: str | None = None,
+    limit: int = 50,
+    source: Literal["dune", "spellbook", "both"] = "both",
+    include_columns: bool = True,
+) -> dict[str, Any]:
+    """
+    Unified discovery implementation that can search Dune API, Spellbook repo, or both.
+    
+    Returns a consistent format with 'schemas' and 'tables' keys.
+    """
+    _ensure_initialized()
+    out: dict[str, Any] = {
+        "schemas": [],
+        "tables": [],
+        "source": source,
+    }
+    
+    # Normalize keyword to list
+    keywords = keyword if isinstance(keyword, list) else ([keyword] if keyword else [])
+    
+    # Search Dune API if requested
+    if source in ("dune", "both"):
+        dune_result: dict[str, Any] = {}
+        if keyword:
+            assert DISCOVERY_SERVICE is not None
+            # Search each keyword and combine results
+            # DISCOVERY_SERVICE.find_schemas returns list[str], not SchemaMatch objects
+            all_schemas: set[str] = set()
+            for kw in keywords:
+                schemas = DISCOVERY_SERVICE.find_schemas(kw)
+                # schemas is already a list of strings from DiscoveryService
+                all_schemas.update(schemas)
+            dune_result["schemas"] = sorted(list(all_schemas))
+        
+        if schema:
+            assert DISCOVERY_SERVICE is not None
+            tables = DISCOVERY_SERVICE.list_tables(schema, limit=limit)
+            dune_result["tables"] = [
+                {
+                    "schema": schema,
+                    "table": summary.table,
+                    "fully_qualified_name": f"{schema}.{summary.table}",
+                    "source": "dune",
+                }
+                for summary in tables
+            ]
+        
+        # Merge Dune results
+        if "schemas" in dune_result:
+            out["schemas"].extend(dune_result["schemas"])
+        if "tables" in dune_result:
+            out["tables"].extend(dune_result["tables"])
+    
+    # Search Spellbook if requested
+    if source in ("spellbook", "both"):
+        spellbook_result = _spellbook_find_models_impl(
+            keyword=keyword,
+            schema=schema,
+            limit=limit,
+            include_columns=include_columns,
+        )
+        
+        # Convert spellbook models to unified format
+        if "schemas" in spellbook_result:
+            spellbook_schemas = spellbook_result["schemas"]
+            # Merge schemas (avoid duplicates)
+            existing_schemas = set(out["schemas"])
+            for s in spellbook_schemas:
+                if s not in existing_schemas:
+                    out["schemas"].append(s)
+        
+        if "models" in spellbook_result:
+            for model in spellbook_result["models"]:
+                table_info = {
+                    "schema": model["schema"],
+                    "table": model["table"],
+                    "fully_qualified_name": model["fully_qualified_name"],
+                    "source": "spellbook",
+                }
+                if "columns" in model:
+                    table_info["columns"] = model["columns"]
+                out["tables"].append(table_info)
+    
+    # Deduplicate and sort schemas
+    out["schemas"] = sorted(list(set(out["schemas"])))
+    
+    # Limit total tables
+    if limit and len(out["tables"]) > limit:
+        out["tables"] = out["tables"][:limit]
+    
+    return out
+
+
+@app.tool(
+    name="dune_discover",
+    title="Discover Tables",
+    description="Unified tool to discover tables/models from Dune API and/or Spellbook repository. Search by keyword(s) or list tables in a schema.",
+    tags={"dune", "spellbook", "schema", "discovery"},
+)
+def dune_discover(
+    keyword: str | list[str] | None = None,
+    schema: str | None = None,
+    limit: int = 50,
+    source: Literal["dune", "spellbook", "both"] = "both",
+    include_columns: bool = True,
+) -> dict[str, Any]:
+    """
+    Unified discovery tool for Dune tables and Spellbook models.
+    
+    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.
+    
+    Args:
+        keyword: Search term(s) - can be a string or list of strings
+                 (e.g., "layerzero", ["layerzero", "dex"], "nft")
+        schema: Schema name to list tables from (e.g., "dex", "spellbook", "layerzero")
+        limit: Maximum number of tables to return
+        source: Where to search - "dune" (Dune API only), "spellbook" (GitHub repo only),
+                or "both" (default: searches both and merges results)
+        include_columns: Whether to include column details for Spellbook models (default: True)
+    
+    Returns:
+        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
+          - source: "dune" or "spellbook"
+          - columns: Column details (for Spellbook models, if include_columns=True)
+        - 'source': The source parameter used
+    
+    Examples:
+        # Search both sources for layerzero
+        dune_discover(keyword="layerzero")
+        
+        # Search only Spellbook
+        dune_discover(keyword=["layerzero", "bridge"], source="spellbook")
+        
+        # Search only Dune API
+        dune_discover(keyword="sui", source="dune")
+        
+        # List all tables in a schema (searches both sources)
+        dune_discover(schema="dex")
+    """
+    try:
+        return _unified_discover_impl(
+            keyword=keyword,
+            schema=schema,
+            limit=limit,
+            source=source,
+            include_columns=include_columns,
+        )
+    except Exception as e:
+        return error_response(e, context={
+            "tool": "dune_discover",
+            "keyword": keyword,
+            "schema": schema,
+            "source": source,
+        })
+
+
 @app.tool(
     name="dune_find_tables",
     title="Find Tables",
     description="Search schemas and optionally list tables.",
     tags={"dune", "schema"},
 )
-async def dune_find_tables(keyword: str | None = None, schema: str | None = None, limit: int = 50) -> dict[str, Any]:
+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 await _dune_find_tables_impl(keyword=keyword, schema=schema, limit=limit)
+        return _dune_find_tables_impl(keyword=keyword, schema=schema, limit=limit)
     except Exception as e:
         return error_response(e, context={
             "tool": "dune_find_tables",
@@ -296,7 +455,7 @@ async def dune_find_tables(keyword: str | None = None, schema: str | None = None
         })
 
 
-async def _dune_describe_table_impl(schema: str, table: str) -> dict[str, Any]:
+def _dune_describe_table_impl(schema: str, table: str) -> dict[str, Any]:
     _ensure_initialized()
     assert DISCOVERY_SERVICE is not None
     desc = DISCOVERY_SERVICE.describe_table(schema, table)
@@ -320,9 +479,9 @@ async def _dune_describe_table_impl(schema: str, table: str) -> dict[str, Any]:
     description="Describe columns for a schema.table on Dune.",
     tags={"dune", "schema"},
 )
-async def dune_describe_table(schema: str, table: str) -> dict[str, Any]:
+def dune_describe_table(schema: str, table: str) -> dict[str, Any]:
     try:
-        return await _dune_describe_table_impl(schema=schema, table=table)
+        return _dune_describe_table_impl(schema=schema, table=table)
     except Exception as e:
         return error_response(e, context={
             "tool": "dune_describe_table",
@@ -331,68 +490,151 @@ async def dune_describe_table(schema: str, table: str) -> dict[str, Any]:
         })
 
 
+def _spellbook_find_models_impl(
+    keyword: str | list[str] | None = None,
+    schema: str | None = None,
+    limit: int = 50,
+    include_columns: bool = True,
+) -> dict[str, Any]:
+    """
+    Implementation for spellbook model discovery.
+    
+    Supports searching by keyword(s) and optionally includes column details.
+    """
+    _ensure_initialized()
+    assert SPELLBOOK_EXPLORER is not None
+    out: dict[str, Any] = {}
+    
+    # Handle keyword search (string or list)
+    if keyword:
+        # Normalize to list
+        keywords = keyword if isinstance(keyword, list) else [keyword]
+        
+        # Find schemas matching any keyword
+        all_schemas: set[str] = set()
+        for kw in keywords:
+            schemas = SPELLBOOK_EXPLORER.find_schemas(kw)
+            all_schemas.update(match.schema for match in schemas)
+        
+        out["schemas"] = sorted(list(all_schemas))
+        
+        # If schema not specified but we found schemas, search models in those schemas
+        if not schema and all_schemas:
+            out["models"] = []
+            for schema_name in sorted(all_schemas):
+                tables = SPELLBOOK_EXPLORER.list_tables(schema_name, limit=limit)
+                for table_summary in tables:
+                    # Check if table name matches any keyword
+                    table_name = table_summary.table.lower()
+                    matches_keyword = any(kw.lower() in table_name for kw in keywords)
+                    
+                    if matches_keyword:
+                        model_info: dict[str, Any] = {
+                            "schema": schema_name,
+                            "table": table_summary.table,
+                            "fully_qualified_name": f"{schema_name}.{table_summary.table}",
+                        }
+                        
+                        # Include column details if requested
+                        if include_columns:
+                            try:
+                                desc = SPELLBOOK_EXPLORER.describe_table(schema_name, table_summary.table)
+                                model_info["columns"] = [
+                                    {
+                                        "name": col.name,
+                                        "dune_type": col.dune_type,
+                                        "polars_dtype": col.polars_dtype,
+                                        "comment": col.comment,
+                                    }
+                                    for col in desc.columns
+                                ]
+                            except Exception:
+                                model_info["columns"] = []
+                        
+                        out["models"].append(model_info)
+            
+            # Limit total models returned
+            if limit and len(out["models"]) > limit:
+                out["models"] = out["models"][:limit]
+    
+    # If schema specified, list all tables in that schema
+    if schema:
+        tables = SPELLBOOK_EXPLORER.list_tables(schema, limit=limit)
+        if "models" not in out:
+            out["models"] = []
+        
+        for table_summary in tables:
+            model_info: dict[str, Any] = {
+                "schema": schema,
+                "table": table_summary.table,
+                "fully_qualified_name": f"{schema}.{table_summary.table}",
+            }
+            
+            # Include column details if requested
+            if include_columns:
+                try:
+                    desc = SPELLBOOK_EXPLORER.describe_table(schema, table_summary.table)
+                    model_info["columns"] = [
+                        {
+                            "name": col.name,
+                            "dune_type": col.dune_type,
+                            "polars_dtype": col.polars_dtype,
+                            "comment": col.comment,
+                        }
+                        for col in desc.columns
+                    ]
+                except Exception:
+                    model_info["columns"] = []
+            
+            out["models"].append(model_info)
+    
+    return out
+
+
 @app.tool(
-    name="sui_package_overview",
-    title="Sui Package Overview",
-    description="Compact overview for Sui package activity.",
-    tags={"sui"},
+    name="spellbook_find_models",
+    title="Search Spellbook",
+    description="Search dbt models in Spellbook GitHub repository.",
+    tags={"spellbook", "dbt", "schema"},
 )
-async def sui_package_overview(
-    packages: list[str],
-    hours: int = 72,
-    timeout_seconds: float | None = 30,
+def spellbook_find_models(
+    keyword: str | list[str] | None = None,
+    schema: str | None = None,
+    limit: int = 50,
+    include_columns: bool = True,
 ) -> dict[str, Any]:
-    _ensure_initialized()
-    assert SUI_OVERVIEW_TOOL is not None
+    """
+    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 await SUI_OVERVIEW_TOOL.execute(
-            packages=packages, hours=hours, timeout_seconds=timeout_seconds
+        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": "sui_package_overview",
-            "packages": packages,
-            "hours": hours,
+            "tool": "spellbook_find_models",
+            "keyword": keyword,
+            "schema": schema,
         })
 
 
-@app.resource(uri="spice:sui/events_preview/{hours}/{limit}/{packages}", name="Sui Events Preview", description="Preview Sui events (3-day default) for comma-separated packages; returns JSON.")
-async def sui_events_preview_resource(hours: str, limit: str, packages: str) -> str:
-    import json
-
-    try:
-        hh = int(hours)
-    except Exception:
-        hh = 72
-    try:
-        ll = int(limit)
-    except Exception:
-        ll = 50
-    pkgs = []
-    if packages and packages != "_":
-        pkgs = [p.strip() for p in packages.split(",") if p.strip()]
-
-    _ensure_initialized()
-    assert SUI_SERVICE is not None
-    try:
-        result = SUI_SERVICE.events_preview(pkgs, hours=hh, limit=ll)
-        payload = {"ok": True, **result}
-    except Exception as exc:
-        payload = error_response(
-            exc,
-            context={
-                "resource": "sui_events_preview",
-                "packages": pkgs,
-                "hours": hh,
-                "limit": ll,
-            },
-        )
-    return json.dumps(payload)
 
 
 # Resources
 @app.resource(uri="spice:history/tail/{n}", name="Query History Tail", description="Tail last N lines from query history")
-async def history_tail(n: str) -> str:
+def history_tail(n: str) -> str:
     from collections import deque
     try:
         nn = int(n)
@@ -418,7 +660,7 @@ async def history_tail(n: str) -> str:
 
 
 @app.resource(uri="spice:artifact/{sha}", name="SQL Artifact", description="SQL artifact by SHA-256")
-async def sql_artifact(sha: str) -> str:
+def sql_artifact(sha: str) -> str:
     import os
     import re
 
@@ -437,43 +679,6 @@ async def sql_artifact(sha: str) -> str:
         return ""
 
 
-@app.resource(
-    uri="spice:sui/package_overview/{hours}/{timeout_seconds}/{packages}",
-    name="Sui Package Overview (cmd)",
-    description="Compact overview for Sui package activity as a command-style resource."
-)
-async def sui_package_overview_cmd(hours: str, timeout_seconds: str, packages: str) -> str:
-    import json
-
-    try:
-        hh = int(hours)
-    except Exception:
-        hh = 72
-    try:
-        tt = float(timeout_seconds)
-    except Exception:
-        tt = 30.0
-    pkgs = []
-    if packages and packages != "_":
-        pkgs = [p.strip() for p in packages.split(",") if p.strip()]
-
-    _ensure_initialized()
-    assert SUI_SERVICE is not None
-    try:
-        result = SUI_SERVICE.package_overview(pkgs, hours=hh, timeout_seconds=tt)
-    except Exception as exc:
-        result = error_response(
-            exc,
-            context={
-                "resource": "sui_package_overview",
-                "packages": pkgs,
-                "hours": hh,
-                "timeout_seconds": tt,
-            },
-        )
-    return json.dumps(result)
-
-
 def main() -> None:
     # Do not initialize at startup; defer until first tool call so env issues
     # don't break MCP handshake. Disable banner to keep stdio clean.
@@ -488,7 +693,7 @@ if __name__ == "__main__":
     description="Create a new saved Dune query (name + SQL).",
     tags={"dune", "admin"},
 )
-async def dune_query_create(name: str, query_sql: str, description: str | None = None, tags: list[str] | None = None, parameters: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+def dune_query_create(name: str, query_sql: str, description: str | None = None, tags: list[str] | None = None, parameters: list[dict[str, Any]] | None = None) -> dict[str, Any]:
     _ensure_initialized()
     assert QUERY_ADMIN_SERVICE is not None
     try:
@@ -503,7 +708,7 @@ async def dune_query_create(name: str, query_sql: str, description: str | None =
     description="Update fields of a saved Dune query (name/SQL/description/tags/parameters).",
     tags={"dune", "admin"},
 )
-async def dune_query_update(query_id: int, name: str | None = None, query_sql: str | None = None, description: str | None = None, tags: list[str] | None = None, parameters: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+def dune_query_update(query_id: int, name: str | None = None, query_sql: str | None = None, description: str | None = None, tags: list[str] | None = None, parameters: list[dict[str, Any]] | None = None) -> dict[str, Any]:
     _ensure_initialized()
     assert QUERY_ADMIN_SERVICE is not None
     try:
@@ -518,7 +723,7 @@ async def dune_query_update(query_id: int, name: str | None = None, query_sql: s
     description="Fork an existing saved Dune query.",
     tags={"dune", "admin"},
 )
-async def dune_query_fork(source_query_id: int, name: str | None = None) -> dict[str, Any]:
+def dune_query_fork(source_query_id: int, name: str | None = None) -> dict[str, Any]:
     _ensure_initialized()
     assert QUERY_ADMIN_SERVICE is not None
     try:

spice_mcp/mcp/tools/base.py

@@ -20,7 +20,7 @@ class MCPTool(ABC):
         raise NotImplementedError
 
     @abstractmethod
-    async def execute(self, **kwargs) -> dict[str, Any]:
+    def execute(self, **kwargs) -> dict[str, Any]:
         """Execute tool logic and return result dictionary."""
         raise NotImplementedError