spice-mcp 0.1.0__py3-none-any.whl

spice_mcp/adapters/dune/helpers.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+
+def get_dune_network_name(network: str) -> str:
+    if network == 'avalanche':
+        return 'avalanche_c'
+    elif network == 'bsc':
+        return 'bnb'
+    else:
+        return network
+

spice_mcp/adapters/dune/transport.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from contextlib import contextmanager
+from typing import Any
+
+from ..http_client import HttpClient
+
+_HTTP_CLIENT: HttpClient | None = None
+
+
+@contextmanager
+def use_http_client(client: HttpClient | None):
+    global _HTTP_CLIENT
+    previous = _HTTP_CLIENT
+    if client is not None:
+        _HTTP_CLIENT = client
+    try:
+        yield
+    finally:
+        _HTTP_CLIENT = previous
+
+
+def current_http_client() -> HttpClient | None:
+    return _HTTP_CLIENT
+
+
+def request(
+    method: str,
+    url: str,
+    *,
+    headers: Mapping[str, str],
+    timeout: float,
+    json: Any | None = None,
+    data: Any | None = None,
+) -> Any:
+    client = _HTTP_CLIENT
+    if client is not None:
+        return client.request(
+            method,
+            url,
+            headers=headers,
+            timeout=timeout,
+            json=json,
+            data=data,
+        )
+    import requests
+
+    return requests.request(
+        method,
+        url,
+        headers=headers,
+        timeout=timeout,
+        json=json,
+        data=data,
+    )
+
+
+def get(url: str, *, headers: Mapping[str, str], timeout: float):
+    return request("GET", url, headers=headers, timeout=timeout)
+
+
+def post(
+    url: str,
+    *,
+    headers: Mapping[str, str],
+    json: Any | None = None,
+    timeout: float,
+):
+    return request("POST", url, headers=headers, json=json, timeout=timeout)

spice_mcp/adapters/dune/types.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Literal, NotRequired, TypedDict
+
+import polars as pl
+
+Query = int | str
+
+Performance = Literal['medium', 'large']
+
+
+class Execution(TypedDict):
+    execution_id: str
+    timestamp: NotRequired[int | None]
+
+
+class ExecuteKwargs(TypedDict):
+    query_id: int | None
+    api_key: str | None
+    parameters: Mapping[str, Any] | None
+    performance: Performance
+
+
+class PollKwargs(TypedDict):
+    api_key: str | None
+    poll_interval: float
+    verbose: bool
+    timeout_seconds: float | None
+
+
+class RetrievalKwargs(TypedDict):
+    limit: int | None
+    offset: int | None
+    sample_count: int | None
+    sort_by: str | None
+    columns: Sequence[str] | None
+    extras: Mapping[str, Any] | None
+    types: Sequence[type[pl.DataType]] | Mapping[str, type[pl.DataType]] | None
+    all_types: (
+        Sequence[type[pl.DataType]] | Mapping[str, type[pl.DataType]] | None
+    )
+    verbose: bool
+
+
+class OutputKwargs(TypedDict):
+    execute_kwargs: ExecuteKwargs
+    result_kwargs: RetrievalKwargs
+    cache: bool
+    save_to_cache: bool
+    cache_dir: str | None
+    include_execution: bool

spice_mcp/adapters/dune/typing_utils.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+
+def resolve_raw_sql_template_id() -> int:
+    """Return a stable template ID used for executing raw SQL text.
+
+    Tests stub HTTP boundaries and only require a consistent integer. This
+    placeholder can be adjusted if upstream semantics change.
+    """
+    return 0

spice_mcp/adapters/dune/urls.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Mapping
+from typing import Any
+
+
+def _base_url() -> str:
+    base = os.getenv('DUNE_API_URL', 'https://api.dune.com/api/v1').rstrip('/')
+    return base
+
+
+url_templates = {
+    'execution_status': _base_url() + '/execution/{execution_id}/status',
+    'execution_results': _base_url() + '/execution/{execution_id}/results/csv',
+    'query_execution': _base_url() + '/query/{query_id}/execute',
+    'query_results': _base_url() + '/query/{query_id}/results/csv',
+    'query_results_json': _base_url() + '/query/{query_id}/results',
+    'query_create': _base_url() + '/query/',
+    'query': _base_url() + '/query/{query_id}',
+    'query_fork': _base_url() + '/query/{query_id}/fork',
+}
+
+
+def get_query_execute_url(query: int | str) -> str:
+    if isinstance(query, str):
+        return query
+    elif isinstance(query, int):
+        return url_templates['query_execution'].format(query_id=query)
+    else:
+        raise Exception('unknown query format: ' + str(type(query)))
+
+
+def get_query_results_url(
+    query: int | str, parameters: dict[str, Any], csv: bool = True
+) -> str:
+    query_id = get_query_id(query)
+    if csv:
+        template = url_templates['query_results']
+    else:
+        template = url_templates['query_results_json']
+    url = template.format(query_id=query_id)
+
+    parameters = dict(parameters.items())
+    if 'query_parameters' in parameters:
+        parameters['params'] = parameters.pop('query_parameters')
+    for key, value in list(parameters.items()):
+        if isinstance(value, dict):
+            del parameters[key]
+            for subkey, subvalue in value.items():
+                parameters[key + '.' + subkey] = subvalue
+
+    return add_args_to_url(url, parameters=parameters)
+
+
+def get_execution_status_url(execution_id: str) -> str:
+    return url_templates['execution_status'].format(execution_id=execution_id)
+
+
+def get_execution_results_url(
+    execution_id: str, parameters: Mapping[str, Any]
+) -> str:
+    url = url_templates['execution_results'].format(execution_id=execution_id)
+    return add_args_to_url(url, parameters=parameters)
+
+
+def add_args_to_url(url: str, parameters: Mapping[str, Any]) -> str:
+    """Append query params to a base URL.
+
+    - Flattens nested dicts like {"a": {"b": 1}} -> "a.b=1"
+    - Joins lists via commas
+    - Skips None values
+    """
+    # Flatten nested dicts once (shallow nesting like key: {sub: val})
+    flat: dict[str, Any] = {}
+    for key, value in parameters.items():
+        if value is None:
+            continue
+        if isinstance(value, dict):
+            for subkey, subvalue in value.items():
+                flat[f"{key}.{subkey}"] = subvalue
+        else:
+            flat[key] = value
+
+    # Build query string
+    parts: list[str] = []
+    for key, value in flat.items():
+        if value is None:
+            continue
+        if isinstance(value, list):
+            value = ','.join(str(item) for item in value)
+        parts.append(f"{key}={value}")
+
+    sep = '&' if '?' in url else '?'
+    return url + (sep if parts else '') + '&'.join(parts)
+
+
+def get_api_key() -> str:
+    """get dune api key"""
+    return os.environ['DUNE_API_KEY']
+
+
+def get_query_id(query: str | int) -> int:
+    """get id of a query"""
+    if isinstance(query, int):
+        return query
+    elif isinstance(query, str):
+        m = re.search(r"/api/v1/query/(\d+)", query)
+        if m:
+            query = m.group(1)
+        else:
+            m2 = re.search(r"dune\.com/queries/(\d+)", query)
+            if m2:
+                query = m2.group(1)
+
+    try:
+        return int(query)
+    except ValueError:
+        raise Exception('invalid query id: ' + str(query))
+
+
+def get_headers(*, api_key: str | None = None) -> Mapping[str, str]:
+    if api_key is None:
+        api_key = get_api_key()
+    return {'X-Dune-API-Key': api_key}

spice_mcp/adapters/http_client.py

@@ -0,0 +1,156 @@
+"""HTTP client utilities shared across adapters.
+
+This module centralises retry/backoff behaviour, timeout defaults, and structured
+logging so that transport concerns stay consistent between adapters and higher
+level services.  It is intentionally lightweight (requests-based) to avoid
+imposing additional dependencies on downstream environments.
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+import time
+from collections.abc import Iterable, Mapping, MutableMapping
+from dataclasses import dataclass
+
+import requests
+
+logger = logging.getLogger("spice_mcp.http")
+
+
+@dataclass(frozen=True)
+class HttpClientConfig:
+    """Configuration knobs for :class:`HttpClient`."""
+
+    timeout_seconds: float = 15.0
+    max_retries: int = 3
+    backoff_initial: float = 0.35
+    backoff_max: float = 5.0
+    jitter_range: tuple[float, float] = (1.25, 2.25)
+    retry_statuses: tuple[int, ...] = (408, 409, 425, 429, 500, 502, 503, 504)
+
+
+class HttpClient:
+    """Tiny wrapper over :mod:`requests` with consistent retry semantics."""
+
+    def __init__(
+        self,
+        config: HttpClientConfig,
+        *,
+        session: requests.Session | None = None,
+    ) -> None:
+        self._config = config
+        self._session = session or requests.Session()
+
+    # ------------------------------------------------------------------ public
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        params: Mapping[str, object] | None = None,
+        json: object | None = None,
+        data: object | None = None,
+        timeout: float | None = None,
+        ok_statuses: Iterable[int] | None = None,
+    ) -> requests.Response:
+        """Perform an HTTP request with exponential backoff.
+
+        ``ok_statuses`` may be provided to allow responses that would otherwise
+        raise for status.  Any HTTP exception that is not recoverable (non
+        retryable status or retries exhausted) is re-raised to the caller.
+        """
+
+        attempt = 0
+        backoff = self._config.backoff_initial
+        timeout_value = timeout or self._config.timeout_seconds
+
+        while True:
+            start = time.perf_counter()
+            try:
+                response = self._session.request(
+                    method,
+                    url,
+                    headers=_clone_mapping(headers),
+                    params=params,
+                    json=json,
+                    data=data,
+                    timeout=timeout_value,
+                )
+            except requests.RequestException as exc:  # network/timeout failure
+                logger.warning(
+                    "http_request_error",
+                    extra={
+                        "method": method,
+                        "url": url,
+                        "attempt": attempt,
+                        "error": str(exc),
+                    },
+                )
+                if attempt >= self._config.max_retries:
+                    raise
+                _sleep(backoff, self._config)
+                backoff = min(self._config.backoff_max, backoff * 2)
+                attempt += 1
+                continue
+
+            duration_ms = int((time.perf_counter() - start) * 1000)
+            status = response.status_code
+
+            logger.debug(
+                "http_request",
+                extra={
+                    "method": method,
+                    "url": url,
+                    "status": status,
+                    "attempt": attempt,
+                    "duration_ms": duration_ms,
+                },
+            )
+
+            if _should_retry(status, attempt, self._config):
+                _sleep(backoff, self._config)
+                backoff = min(self._config.backoff_max, backoff * 2)
+                attempt += 1
+                continue
+
+            if ok_statuses and status in ok_statuses:
+                return response
+
+            try:
+                response.raise_for_status()
+            except requests.HTTPError as exc:  # Non-OK terminal status
+                logger.error(
+                    "http_request_failed",
+                    extra={
+                        "method": method,
+                        "url": url,
+                        "status": status,
+                        "attempt": attempt,
+                        "error": str(exc),
+                    },
+                )
+                raise
+
+            return response
+
+
+# ---------------------------------------------------------------------------
+def _should_retry(status: int, attempt: int, config: HttpClientConfig) -> bool:
+    return (
+        status in config.retry_statuses
+        and attempt < config.max_retries
+    )
+
+
+def _sleep(backoff: float, config: HttpClientConfig) -> None:
+    jitter = random.uniform(*config.jitter_range)
+    time.sleep(backoff * jitter)
+
+
+def _clone_mapping(mapping: Mapping[str, str] | None) -> MutableMapping[str, str] | None:
+    if mapping is None:
+        return None
+    return dict(mapping)

spice_mcp/config.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Literal
+
+from .adapters.http_client import HttpClientConfig
+
+
+@dataclass(frozen=True)
+class DuneConfig:
+    """Dune Analytics API configuration."""
+
+    api_key: str  # Required
+    api_url: str = "https://api.dune.com/api/v1"
+
+
+@dataclass(frozen=True)
+class CacheConfig:
+    """Cache configuration."""
+
+    mode: Literal["enabled", "read_only", "refresh", "disabled"] = "enabled"
+    cache_dir: str | None = None
+    max_size_mb: int = 500
+
+
+@dataclass(frozen=True)
+class LoggingConfig:
+    """Logging configuration."""
+
+    query_history_path: str | None = None
+    artifact_root: str | None = None
+    enabled: bool = True
+
+
+@dataclass(frozen=True)
+class Config:
+    """Main application configuration."""
+
+    dune: DuneConfig
+    cache: CacheConfig = field(default_factory=CacheConfig)
+    logging: LoggingConfig = field(default_factory=LoggingConfig)
+    http: HttpClientConfig = field(default_factory=HttpClientConfig)
+    max_concurrent_queries: int = 5
+    default_timeout_seconds: int = 30
+
+    @classmethod
+    def from_env(cls) -> Config:
+        """Load configuration from environment variables."""
+        api_key = os.getenv("DUNE_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "DUNE_API_KEY environment variable is required. "
+                "Get your API key from https://dune.com/settings/api"
+            )
+
+        return cls(
+            dune=DuneConfig(
+                api_key=api_key,
+                api_url=os.getenv("DUNE_API_URL", "https://api.dune.com/api/v1"),
+            ),
+            cache=CacheConfig(
+                mode=os.getenv("SPICE_CACHE_MODE", "enabled"),
+                cache_dir=os.getenv("SPICE_CACHE_DIR"),
+                max_size_mb=int(os.getenv("SPICE_CACHE_MAX_SIZE_MB", "500")),
+            ),
+            logging=LoggingConfig(
+                query_history_path=os.getenv("SPICE_QUERY_HISTORY"),
+                artifact_root=os.getenv("SPICE_ARTIFACT_ROOT"),
+                enabled=os.getenv("SPICE_LOGGING_ENABLED", "true").lower()
+                == "true",
+            ),
+            http=HttpClientConfig(
+                timeout_seconds=float(os.getenv("SPICE_HTTP_TIMEOUT", "15")),
+                max_retries=int(os.getenv("SPICE_HTTP_RETRIES", "3")),
+                backoff_initial=float(os.getenv("SPICE_HTTP_BACKOFF", "0.35")),
+                backoff_max=float(os.getenv("SPICE_HTTP_BACKOFF_MAX", "5.0")),
+            ),
+            default_timeout_seconds=int(os.getenv("SPICE_TIMEOUT_SECONDS", "30")),
+            max_concurrent_queries=int(os.getenv("SPICE_MAX_CONCURRENT_QUERIES", "5")),
+        )

spice_mcp/core/errors.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True)
+class MCPError:
+    code: str
+    message: str
+    suggestions: tuple[str, ...] = ()
+    context: dict[str, Any] | None = None
+
+    def to_payload(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "code": self.code,
+            "message": self.message,
+            "data": {"suggestions": list(self.suggestions)},
+        }
+        if self.context:
+            payload["context"] = _redact_context(self.context)
+        return payload
+
+
+def categorize_error(error: Exception) -> MCPError:
+    """Return a structured MCPError with actionable suggestions."""
+    msg = str(error) if error is not None else ""
+    low = msg.lower()
+
+    if isinstance(error, TimeoutError) or "timeout" in low or "timed out" in low:
+        return MCPError(
+            code="QUERY_TIMEOUT",
+            message=msg or "Query timed out",
+            suggestions=(
+                "Increase timeout_seconds (e.g., 60 or 120).",
+                "Reduce the scan window or LIMIT.",
+                "Add WHERE filters to narrow the dataset.",
+            ),
+        )
+
+    if "429" in low or "rate limit" in low:
+        return MCPError(
+            code="RATE_LIMIT",
+            message=msg or "Dune API rate limit hit.",
+            suggestions=(
+                "Retry shortly; the client already applies exponential backoff.",
+                "Use cached results or smaller LIMIT windows.",
+            ),
+        )
+
+    if "401" in low or "unauthorized" in low or "api key" in low:
+        return MCPError(
+            code="AUTH_ERROR",
+            message=msg or "Authentication failed.",
+            suggestions=(
+                "Ensure DUNE_API_KEY is exported before launching Codex.",
+                "Rotate or verify the API key in Dune settings.",
+            ),
+        )
+
+    if "query failed" in low or "sql" in low or "syntax" in low:
+        return MCPError(
+            code="QUERY_ERROR",
+            message=msg or "Query execution failed.",
+            suggestions=(
+                "Validate SQL and parameters in the Dune UI.",
+                "Check schema/table/column names.",
+                "Ensure parameter names and types match the query definition.",
+            ),
+        )
+
+    return MCPError(
+        code="UNKNOWN_ERROR",
+        message=msg or type(error).__name__,
+        suggestions=(
+            "Retry the request.",
+            "Inspect error details for additional context.",
+        ),
+    )
+
+
+def error_response(error: Exception, *, context: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Serialize an error into the standard MCP envelope."""
+    cat = categorize_error(error)
+    if context:
+        cat.context = context
+    payload: dict[str, Any] = {
+        "ok": False,
+        "error": cat.to_payload(),
+    }
+    return payload
+
+
+def _redact_context(ctx: dict[str, Any]) -> dict[str, Any]:
+    redacted: dict[str, Any] = {}
+    for key, value in ctx.items():
+        if isinstance(value, str) and any(token in key.lower() for token in ("api_key", "token", "secret")):
+            redacted[key] = "****"
+        else:
+            redacted[key] = value
+    return redacted

spice_mcp/core/models.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class QueryRequest:
+    """Normalized representation of a Dune query request."""
+
+    query: int | str
+    parameters: Mapping[str, Any] | None = None
+    refresh: bool = False
+    max_age: float | None = None
+    poll: bool = True
+    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
+    performance: str | None = None
+    include_execution: bool = True
+
+
+@dataclass(slots=True)
+class ResultPreview:
+    rowcount: int
+    columns: list[str]
+    data_preview: list[dict[str, Any]]
+
+
+@dataclass(slots=True)
+class ResultMetadata:
+    """Subset of Dune execution metadata surfaced to MCP clients."""
+
+    execution: dict[str, Any]
+    duration_ms: int
+    metadata: dict[str, Any] | None = None
+    next_offset: int | None = None
+    next_uri: str | None = None
+
+
+@dataclass(slots=True)
+class QueryResult:
+    """Normalized result returned by QueryExecutor implementations."""
+
+    preview: ResultPreview
+    info: ResultMetadata
+    lazyframe: Any | None = None
+
+
+@dataclass(slots=True)
+class SchemaMatch:
+    schema: str
+
+
+@dataclass(slots=True)
+class TableSummary:
+    schema: str
+    table: str
+
+
+@dataclass(slots=True)
+class TableColumn:
+    name: str
+    dune_type: str | None = None
+    polars_dtype: str | None = None
+    comment: str | None = None
+    extra: str | None = None
+
+
+@dataclass(slots=True)
+class TableDescription:
+    fully_qualified_name: str
+    columns: list[TableColumn] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class SuiPackageOverview:
+    package_ids: list[str]
+    window_hours: int
+    events_preview: list[dict[str, Any]] | None = None
+    transactions_preview: list[dict[str, Any]] | None = None
+    objects_preview: list[dict[str, Any]] | None = None
+    stats: dict[str, Any] = field(default_factory=dict)