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

spice_mcp/adapters/dune/extract.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import io
 import time
 from typing import TYPE_CHECKING, overload
+import os
 
 from ..http_client import HttpClient
 from . import cache as _cache
@@ -32,6 +33,10 @@ from .typing_utils import resolve_raw_sql_template_id
 
 ADAPTER_VERSION = "spice-mcp-adapter"
 
+# Runtime-configurable HTTP timeouts (helps avoid host-level timeouts)
+_GET_TIMEOUT: float = float(os.getenv("SPICE_DUNE_GET_TIMEOUT", os.getenv("SPICE_HTTP_TIMEOUT", "30")))
+_POST_TIMEOUT: float = float(os.getenv("SPICE_DUNE_POST_TIMEOUT", os.getenv("SPICE_HTTP_TIMEOUT", "30")))
+
 if TYPE_CHECKING:
     from collections.abc import Mapping, Sequence
     from typing import Any, Literal
@@ -749,7 +754,7 @@ def _execute(
         print('executing query, query_id = ' + str(query_id))
 
     # perform request
-    response = _transport_post(url, headers=headers, json=data, timeout=15.0)
+    response = _transport_post(url, headers=headers, json=data, timeout=_POST_TIMEOUT)
     result: Mapping[str, Any] = response.json()
 
     # check for errors
@@ -786,7 +791,7 @@ async def _async_execute(
         print('executing query, query_id = ' + str(query_id))
 
     # perform request
-    timeout = aiohttp.ClientTimeout(total=30)
+    timeout = aiohttp.ClientTimeout(total=_POST_TIMEOUT)
     async with aiohttp.ClientSession(timeout=timeout) as session:
         async with session.post(url, headers=headers, json=data) as response:
             result: Mapping[str, Any] = await response.json()
@@ -862,12 +867,12 @@ def _get_results(
     def _get_with_retries(u: str):
         client = current_http_client()
         if client is not None:
-            return client.request("GET", u, headers=headers, timeout=30.0)
+            return client.request("GET", u, headers=headers, timeout=_GET_TIMEOUT)
 
         attempts = 0
         backoff = 0.5
         while True:
-            resp = _transport_get(u, headers=headers, timeout=30.0)
+            resp = _transport_get(u, headers=headers, timeout=_GET_TIMEOUT)
             if resp.status_code in (429, 502):
                 attempts += 1
                 if attempts >= 3:
@@ -963,7 +968,7 @@ async def _async_get_results(
             print('getting results, execution_id = ' + str(execution['execution_id']))
 
     # perform request
-    timeout = aiohttp.ClientTimeout(total=30)
+    timeout = aiohttp.ClientTimeout(total=_GET_TIMEOUT)
     async with aiohttp.ClientSession(timeout=timeout) as session:
         # GET with simple retry/backoff for 429/502
         attempts = 0
@@ -1169,7 +1174,7 @@ def _poll_execution(
             )
 
         # poll
-        response = _http_get(url, headers=headers, timeout=15.0)
+        response = _http_get(url, headers=headers, timeout=_GET_TIMEOUT)
         result = response.json()
         if (
             'is_execution_finished' not in result
@@ -1243,7 +1248,7 @@ async def _async_poll_execution(
     t_start = time.time()
 
     # poll until completion
-    timeout = aiohttp.ClientTimeout(total=30)
+    timeout = aiohttp.ClientTimeout(total=_GET_TIMEOUT)
     async with aiohttp.ClientSession(timeout=timeout) as session:
         sleep_amount = poll_interval
         while True:

spice_mcp/adapters/dune/typing_utils.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import os
+
 
 def resolve_raw_sql_template_id() -> int:
     """Return a stable template ID used for executing raw SQL text.
@@ -7,4 +9,11 @@ def resolve_raw_sql_template_id() -> int:
     Tests stub HTTP boundaries and only require a consistent integer. This
     placeholder can be adjusted if upstream semantics change.
     """
-    return 0
+    env_value = os.getenv("SPICE_RAW_SQL_QUERY_ID")
+    if env_value:
+        try:
+            return int(env_value.strip())
+        except (ValueError, AttributeError):
+            # Invalid environment variable, fallback to default
+            pass
+    return 4060379

spice_mcp/mcp/server.py

@@ -229,26 +229,7 @@ async def dune_query(
     _ensure_initialized()
     assert EXECUTE_QUERY_TOOL is not None
     try:
-        # Limit concurrent executions to preserve API quota
-        if 'asyncio' not in globals():
-            pass  # type: ignore
-        if SEMAPHORE is not None:
-            async with SEMAPHORE:  # type: ignore
-                return await EXECUTE_QUERY_TOOL.execute(
-                    query=query,
-                    parameters=parameters,
-                    refresh=refresh,
-                    max_age=max_age,
-                    limit=limit,
-                    offset=offset,
-                    sample_count=sample_count,
-                    sort_by=sort_by,
-                    columns=columns,
-                    format=format,
-                    extras=extras,
-                    timeout_seconds=timeout_seconds,
-                )
-        # Fallback without semaphore
+        # Execute query directly without semaphore concurrency control
         return await EXECUTE_QUERY_TOOL.execute(
             query=query,
             parameters=parameters,

spice_mcp/mcp/tools/execute_query.py

@@ -313,6 +313,15 @@ class ExecuteQueryTool(MCPTool):
             if template_id_value is not None:
                 extra_fields["template_query_id"] = template_id_value
 
+            # Compute query SHA256 for better debugging
+            q_sha = None
+            try:
+                q_sha = self._persist_query_sql(q_use, q_type)
+                if q_sha:
+                    extra_fields["query_sha256"] = q_sha
+            except Exception:
+                pass
+
             self.query_history.record(
                 execution_id="unknown",
                 query_type=_categorize_query(query),
@@ -324,9 +333,22 @@ class ExecuteQueryTool(MCPTool):
             )
 
             enriched = self._enrich_error(exc)
-            context = {"tool": "dune_query", "query": q_use}
+            context = {"tool": "dune_query", "query": q_use, "query_type": _categorize_query(q_use)}
             if enriched:
                 context.update(enriched)
+            
+            # Add debugging information for raw SQL failures
+            if q_type == "raw_sql" and "could not determine execution" in str(exc):
+                context.update({
+                    "debug_info": "Raw SQL execution failed - this may be related to FastMCP async/concurrency handling",
+                    "template_query_id": template_id_value,
+                    "environment_vars": {
+                        "SPICE_RAW_SQL_QUERY_ID": os.getenv("SPICE_RAW_SQL_QUERY_ID"),
+                        "DUNE_API_KEY_present": bool(os.getenv("DUNE_API_KEY"))
+                    },
+                    "suggested_action": "Retry or check if the template query (4060379) is accessible"
+                })
+            
             return error_response(exc, context=context)
 
     def _persist_query_sql(self, query: str, q_type: str) -> str | None:

{spice_mcp-0.1.0.dist-info → spice_mcp-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spice-mcp
-Version: 0.1.0
+Version: 0.1.2
 Summary: MCP server for Dune Analytics data access
 Author-email: Evan-Kim2028 <ekcopersonal@gmail.com>
 License-File: LICENSE
@@ -21,27 +21,87 @@ Description-Content-Type: text/markdown
 
 # spice-mcp
 
-spice-mcp is an MCP server for Dune 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 and Sui package exploration. Results are Polars-first in Python and compact, token-efficient in MCP responses.
+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 and Sui package exploration. Results are Polars-first in Python and compact, token-efficient in MCP responses.
 
 Requirements: Python 3.13+
 
 This project uses FastMCP for typed, decorator-registered tools and resources.
 
-Highlights
+## Highlights
 - Polars LazyFrame-first pipeline: results stay lazy until explicitly materialized
-- Ports/adapters layering for maintainable integrations (`docs/architecture.md`)
+- Ports/adapters layering for maintainable integrations ([docs/architecture.md](docs/architecture.md))
 - Discovery utilities (find schemas/tables, describe columns)
 - Sui package workflows (events/transactions/objects) with safe defaults
 - JSONL query history + SQL artifacts (SHA-256) for reproducibility
 - Rich MCP surface: query info/run, discovery, health, Sui, and Dune admin (create/update/fork)
 
-Quick Start
+## 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 dependencies (`uv sync` or `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 dependencies and package
+   uv sync
+   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
+   - `sui_package_overview`: Analyze Sui packages
+   - `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.
@@ -114,16 +174,16 @@ Core Tools (with parameters)
   - Use: Verify API key presence and logging paths
   - Output: `api_key_present`, `query_history_path`, `logging_enabled`, `status`
 
-Docs
-- See `docs/index.md` for full documentation:
-  - Dune API structure and capabilities: `docs/dune_api.md`
-  - Discovery patterns and examples: `docs/discovery.md`
-  - Sui package workflows: `docs/sui_packages.md`
-  - Tool reference and schemas: `docs/tools.md`
-  - Codex CLI + tooling integration: `docs/codex_cli.md`, `docs/codex_cli_tools.md`
-  - Architecture overview: `docs/architecture.md`
-  - Installation and configuration: `docs/installation.md`, `docs/config.md`
-  - Development and linting: `docs/development.md`
+## 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)
+  - Sui package workflows: [docs/sui_packages.md](docs/sui_packages.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).

{spice_mcp-0.1.0.dist-info → spice_mcp-0.1.2.dist-info}/RECORD

@@ -8,11 +8,11 @@ spice_mcp/adapters/dune/__init__.py,sha256=8HRHPxkz0y2cyHSs4oCkHq_LQaUW5MBevbeNx
 spice_mcp/adapters/dune/admin.py,sha256=yxOueVz-rmgC-ZFbT06k59G24yRgYjiEkZlall5hXNQ,3157
 spice_mcp/adapters/dune/cache.py,sha256=7UmmxpBNeSGPH3KYBBSPHlVXCpiZUi4-X300U2FsSBs,5252
 spice_mcp/adapters/dune/client.py,sha256=JPrQZ_dtaPcGf6lYUguDxGweOtxG-8qMqOiXuhWL9QA,9122
-spice_mcp/adapters/dune/extract.py,sha256=MkPX8C5pLMB5oWjqEGwoVadYA4pOYt0MjdLBpru24G8,48154
+spice_mcp/adapters/dune/extract.py,sha256=frIFRUNJ99UlP26N9F-p1psX-e_TVq9vJTQxh0MBCr8,48510
 spice_mcp/adapters/dune/helpers.py,sha256=BgDKr_g-UqmU2hoMb0ejQZHta_NbKwR1eDJp33sJYNk,227
 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=izRaHUzt883KDAOA7rNgm6arZAovsGbMk2DBAn_Fdhs,306
+spice_mcp/adapters/dune/typing_utils.py,sha256=EpWneGDn-eQdo6lkLuESR09KXkDj9OqGz8bEF3JaFkM,574
 spice_mcp/adapters/dune/urls.py,sha256=bcuPERkFQduRTT2BrgzVhoFrMn-Lkvw9NmktcBZYEig,3902
 spice_mcp/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 spice_mcp/core/errors.py,sha256=jlfTuyRaAaA_oU07KUk-1pDAAa43KG0BbZc5CINXtoE,3256
@@ -20,10 +20,10 @@ spice_mcp/core/models.py,sha256=2AgAPcaDPEXLdka1E6-0cXN_QNsN2rnDoBnDTDDsO6I,2121
 spice_mcp/core/ports.py,sha256=-wtWjpYSjL-qugUtsm0MTngtJZWzr7QNDbAUCj4BTS0,2028
 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=km_gWerdoGTdbhHO2wp28AX28OJTwj3-tJA5EMoeFe4,18801
+spice_mcp/mcp/server.py,sha256=RtvK0u9Q3dp3JMALrVFL43Li1lKdaQwLvtZuoo0pkbY,18082
 spice_mcp/mcp/tools/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 spice_mcp/mcp/tools/base.py,sha256=Xw8k5WAXotCdZRd-cVJIFPH87JH8DH0sh1zKu-KmW3w,1047
-spice_mcp/mcp/tools/execute_query.py,sha256=VFy7x3-l1KbW5f02hByMDrejZE8eU_fn60d_fdUOgSc,16480
+spice_mcp/mcp/tools/execute_query.py,sha256=y2HU3Cv6T7QBXBDMea0TlXcf8_ERkq2sJeaexR6kBXE,17556
 spice_mcp/mcp/tools/sui_package_overview.py,sha256=a1CcpfBzEFzScjXgxLu9urxdtSbXjF98ugWPOX167rc,1736
 spice_mcp/observability/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 spice_mcp/observability/logging.py,sha256=ceJUEpKGpf5PAgPBmpB49zjqhdGCAESfLemFUhDSmI8,529
@@ -32,8 +32,8 @@ spice_mcp/service_layer/discovery_service.py,sha256=202O0SzCZGQukd9kb2JYfarLygZH
 spice_mcp/service_layer/query_admin_service.py,sha256=4q1NAAuTui7cm83Aq2rFDLIzKTHX17yzbSoSJyCmLbI,1356
 spice_mcp/service_layer/query_service.py,sha256=q0eAVW5I3sUxm29DgzPN_cH3rZEzmKwmdE3Xj4qP9lI,3878
 spice_mcp/service_layer/sui_service.py,sha256=G-LOsl-z-ldMxAYAetnG17IQlpVtLchGUjN6opU-PF0,4712
-spice_mcp-0.1.0.dist-info/METADATA,sha256=h4MsHI5EjkLfPWYxzC9N6Fe7ac7z3d9odv0WX1drF1A,7278
-spice_mcp-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-spice_mcp-0.1.0.dist-info/entry_points.txt,sha256=4XiXX13Vy-oiUJwlcO_82OltBaxFnEnkJ-76sZGm5os,56
-spice_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=r0GNDnDY1RSkVQp7kEEf6MQU21OrNGJkxUHIsv6eyLk,1079
-spice_mcp-0.1.0.dist-info/RECORD,,
+spice_mcp-0.1.2.dist-info/METADATA,sha256=TB63rlJQOinwNKj3XvevK0OLLF2Ic0xYmeLU_kaiuas,9316
+spice_mcp-0.1.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+spice_mcp-0.1.2.dist-info/entry_points.txt,sha256=4XiXX13Vy-oiUJwlcO_82OltBaxFnEnkJ-76sZGm5os,56
+spice_mcp-0.1.2.dist-info/licenses/LICENSE,sha256=r0GNDnDY1RSkVQp7kEEf6MQU21OrNGJkxUHIsv6eyLk,1079
+spice_mcp-0.1.2.dist-info/RECORD,,