spice-mcp 0.1.0__tar.gz

spice_mcp-0.1.0/.factory/droids/agentic-documentation-systems-droid.md

@@ -0,0 +1,16 @@
+---
+name: agentic-documentation-systems-droid
+description: Documentation reviewer focused on agent-ready knowledge systems.
+model: inherit
+tools: ["Read", "LS", "Grep", "Glob"]
+---
+
+You are a documentation specialist. Analyze README and docs with read-only tools and propose minimal, focused updates.
+Keep suggestions path-specific and concise; do not write full docs unless asked.
+
+Output:
+Summary: <one line>
+Findings:
+- <path>: <gap/issue>
+Suggestions:
+- <small change>

spice_mcp-0.1.0/.factory/droids/development-workflow-optimization-droid.md

@@ -0,0 +1,16 @@
+---
+name: development-workflow-optimization-droid
+description: Reviews engineering workflows and automation practices.
+model: inherit
+tools: ["Read", "LS", "Grep", "Glob"]
+---
+
+You are a workflow strategist. Inspect CI/workflows and repo automation using read-only tools.
+Respond with a concise, path-referenced assessment and concrete changes to apply.
+
+Output:
+Summary: <one line>
+Observations:
+- <path>: <issue/opportunity>
+Recommendations:
+- <change>

spice_mcp-0.1.0/.factory/droids/production-python-development-droid.md

@@ -0,0 +1,18 @@
+---
+name: production-python-development-droid
+description: Python reviewer focused on maintainability, testing, and ergonomics.
+model: inherit
+tools: ["Read", "LS", "Grep", "Glob"]
+---
+
+You are a senior Python engineer. Do research-only analysis using the allowed tools.
+Requirements:
+- Keep outputs concise; cite concrete file paths for all findings.
+- No edits or shell commands; summarize config/state and recommend minimal diffs.
+
+Respond with:
+Summary: <one line>
+Findings:
+- <path>: <note>
+Recommendations:
+- <action>

spice_mcp-0.1.0/.factory/droids/temp-smoke-droid.md

@@ -0,0 +1,8 @@
+---
+name: temp-smoke-droid
+description: Minimal read-only droid for troubleshooting Task tool.
+model: inherit
+tools: ["Read", "LS"]
+---
+
+Return the list of files you inspected and a one-line summary.

spice_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,144 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: ruff (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13"]
+
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache uv
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-${{ matrix.python-version }}-
+
+      - name: Cache ruff cache
+        uses: actions/cache@v4
+        with:
+          path: .ruff_cache
+          key: ${{ runner.os }}-ruff-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-ruff-${{ matrix.python-version }}-
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies (uv)
+        run: |
+          uv --version
+          uv sync --frozen --dev
+
+      - name: Ruff lint
+        run: uv run ruff check --output-format=github --color always .
+
+  typecheck:
+    name: mypy (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13"]
+
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache uv
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-${{ matrix.python-version }}-
+
+      - name: Cache mypy cache
+        uses: actions/cache@v4
+        with:
+          path: .mypy_cache
+          key: ${{ runner.os }}-mypy-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-mypy-${{ matrix.python-version }}-
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies (uv)
+        run: |
+          uv --version
+          uv sync --frozen --dev
+
+      - name: mypy
+        env:
+          MYPY_CACHE_DIR: .mypy_cache
+        run: uv run mypy --pretty --color-output --show-error-codes .
+
+  test:
+    name: pytest (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13"]
+
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache uv
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-${{ matrix.python-version }}-
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies (uv)
+        run: |
+          uv --version
+          uv sync --frozen --dev
+
+      - name: Run tests (skip live) with coverage
+        env:
+          PYTHONUNBUFFERED: "1"
+          SPICE_MCP_SKIP_DOTENV: "1"
+        run: |
+          uv run pytest -m "not live" -ra --color=yes \
+            --durations=10 \
+            --cov=src/spice_mcp --cov-report=term-missing:skip-covered --cov-report=xml

spice_mcp-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# python generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# venv
+.venv
+.env
+logs/*
+notes/*
+.claude/*
+.pytest_cache/*
+tests/scripts/test_report.txt
+coverage*

spice_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13.1

spice_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+## Contributing to spice-mcp
+
+Thanks for your interest in contributing! This is a lightweight guide to get you productive quickly.
+
+### Setup
+- Python 3.13+
+- Install dependencies:
+  - Using uv: `uv sync`
+  - Or pip: `pip install -e . && pip install -r <(python - <<'PY'\nimport tomllib,sys;print('\n'.join(tomllib.load(open('pyproject.toml','rb'))['tool']['rye']['dev-dependencies']))\nPY\n)`
+
+### Running the server
+- `python -m spice_mcp.mcp.server --env PYTHONPATH=$(pwd)/src`
+- Or `spice-mcp` if installed as a console script
+
+### Tests
+- Tiered runner: `python tests/scripts/comprehensive_test_runner.py [-t 1 -t 3] [--stop] [--junit out.xml]`
+- Pytest quick run (offline): `uv run pytest -q -m "not live"`
+- Live tests: `export SPICE_TEST_LIVE=1 DUNE_API_KEY=...` then run as above
+
+### Linting / Type checks
+- Ruff: `uv run ruff check . && uv run ruff format .`
+- MyPy (optional relaxed config): `uv run mypy`
+
+### Pull requests
+- Keep changes focused, add/adjust tests when possible
+- Ensure no secrets are committed (`.env` is ignored and required for keys)
+- Follow existing code style and patterns; avoid gratuitous new deps

spice_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Spice MCP contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spice_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: spice-mcp
+Version: 0.1.0
+Summary: MCP server for Dune Analytics data access
+Author-email: Evan-Kim2028 <ekcopersonal@gmail.com>
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: aiohttp>=3.9.5
+Requires-Dist: fastmcp>=0.3.0
+Requires-Dist: mcp>=0.9.0
+Requires-Dist: polars>=1.35.1
+Requires-Dist: requests>=2.31.0
+Requires-Dist: rich-argparse>=1.5.2
+Requires-Dist: rich>=13.3.3
+Description-Content-Type: text/markdown
+
+# spice-mcp
+
+spice-mcp is an MCP server for Dune 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
+- Polars LazyFrame-first pipeline: results stay lazy until explicitly materialized
+- Ports/adapters layering for maintainable integrations (`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
+- 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`.
+
+## MCP Tools and Features
+
+All tools expose typed parameters, titles, and tags; failures return a consistent error envelope.
+
+- `dune_query_info` (Query Info, tags: dune, query)
+  - Fetch saved-query metadata by ID/URL (name, parameters, tags, SQL, version).
+
+- `dune_query` (Run Dune Query, tags: dune, query)
+  - Execute by ID/URL/raw SQL with parameters. Supports `refresh`, `max_age`, `limit/offset`, `sample_count`, `sort_by`, `columns`, and `format` = `preview|raw|metadata|poll`; accepts `timeout_seconds`.
+
+- `dune_health_check` (Health Check, tag: health)
+  - Checks API key presence, query-history path, logging enabled; best-effort template check when configured.
+
+- `dune_find_tables` (Find Tables, tags: dune, schema)
+  - Search schemas by keyword and/or list tables in a schema (`limit`).
+
+- `dune_describe_table` (Describe Table, tags: dune, schema)
+  - Column metadata for `schema.table` (Dune types + Polars inferred dtypes when available).
+
+- `sui_package_overview` (Sui Package Overview, tag: sui)
+  - Compact Sui activity overview for `packages[]` with `hours` (default 72) and `timeout_seconds`.
+
+- Dune Admin tools (tags: dune, admin)
+  - `dune_query_create(name, query_sql, description?, tags?, parameters?)`
+  - `dune_query_update(query_id, name?, query_sql?, description?, tags?, parameters?)`
+  - `dune_query_fork(source_query_id, name?)`
+
+### Resources
+- `spice:history/tail/{n}` — tail last N lines of query history (1..1000)
+- `spice:artifact/{sha}` — fetch stored SQL by 64-hex SHA-256
+- `spice:sui/events_preview/{hours}/{limit}/{packages}` — Sui events preview (JSON)
+- `spice:sui/package_overview/{hours}/{timeout_seconds}/{packages}` — Sui overview (JSON)
+
+## Resources
+
+- `spice:history/tail/{n}`
+  - Last `n` lines from the query-history JSONL, clamped to [1, 1000]
+
+- `spice:artifact/{sha}`
+  - Returns stored SQL for the SHA-256 (validated as 64 lowercase hex)
+
+Tests
+- Offline/unit tests (no network) live under `tests/offline/` and `tests/http_stubbed/`.
+- Live tests under `tests/live/` are skipped by default; enable with `SPICE_TEST_LIVE=1` and a valid `DUNE_API_KEY`.
+- Comprehensive scripted runner (tiered):
+  - Run all tiers: `python tests/scripts/comprehensive_test_runner.py`
+  - Select tiers: `python tests/scripts/comprehensive_test_runner.py -t 1 -t 3`
+  - Stop on first failure: `python tests/scripts/comprehensive_test_runner.py --stop`
+  - Optional JUnit export: `python tests/scripts/comprehensive_test_runner.py --junit tests/scripts/report.xml`
+- Pytest directly (offline/default): `uv run pytest -q -m "not live" --cov=src/spice_mcp --cov-report=term-missing`
+
+Core Tools (with parameters)
+- `dune_query`
+  - Use: Preview/query results by ID, URL, or raw SQL (Polars preview + Dune metadata/pagination).
+  - Params: `query` (string), `parameters?` (object), `performance?` ('medium'|'large'), `limit?` (int), `offset?` (int), `sort_by?` (string), `columns?` (string[]), `sample_count?` (int), `refresh?` (bool), `max_age?` (number), `timeout_seconds?` (number), `format?` ('preview'|'raw'|'metadata').
+  - Output: `type`, `rowcount`, `columns`, `data_preview`, `execution_id`, `duration_ms`, `metadata?`, `next_uri?`, `next_offset?`.
+- `dune_find_tables`
+  - Use: Search schemas by keyword and/or list tables for a schema.
+  - Params: `keyword?` (string), `schema?` (string), `limit?` (int)
+  - Output: `schemas?` (string[]), `tables?` (string[])
+- `dune_describe_table`
+  - Use: Column descriptions for `schema.table` via SHOW + fallback to 1-row sample inference.
+  - Params: `schema` (string), `table` (string)
+  - Output: `columns` ([{ name, dune_type?, polars_dtype?, extra?, comment? }])
+- `sui_package_overview`
+  - Use: Small-window overview for Sui packages (events/transactions/objects) with timeout handling.
+  - Params: `packages` (string[]), `hours?` (int, default 72), `timeout_seconds?` (number, default 30)
+  - Output: best-effort counts and previews; may include `*_timeout`/`*_error`
+- `dune_health_check`
+  - Use: Verify API key presence and logging paths
+  - Output: `api_key_present`, `query_history_path`, `logging_enabled`, `status`
+
+Docs
+- See `docs/index.md` 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`
+
+Notes
+- Legacy Spice code now lives under `src/spice_mcp/adapters/dune` (extract, cache, urls, types).
+- Ports and models live in `src/spice_mcp/core`; services consume ports and are exercised by FastMCP tools.
+- Query history and SQL artefacts are always-on (see `src/spice_mcp/logging/query_history.py`).
+- To bypass dot-env loading during tests/CI, export `SPICE_MCP_SKIP_DOTENV=1`.
+- LazyFrames everywhere: eager `.collect()` or `pl.DataFrame` usage outside dedicated helpers is blocked by `tests/style/test_polars_lazy.py`; materialization helpers live in `src/spice_mcp/polars_utils.py`.

spice_mcp-0.1.0/README.md

@@ -0,0 +1,112 @@
+# 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.
+
+Requirements: Python 3.13+
+
+This project uses FastMCP for typed, decorator-registered tools and resources.
+
+Highlights
+- Polars LazyFrame-first pipeline: results stay lazy until explicitly materialized
+- Ports/adapters layering for maintainable integrations (`docs/architecture.md`)
+- 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
+- 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`.
+
+## MCP Tools and Features
+
+All tools expose typed parameters, titles, and tags; failures return a consistent error envelope.
+
+- `dune_query_info` (Query Info, tags: dune, query)
+  - Fetch saved-query metadata by ID/URL (name, parameters, tags, SQL, version).
+
+- `dune_query` (Run Dune Query, tags: dune, query)
+  - Execute by ID/URL/raw SQL with parameters. Supports `refresh`, `max_age`, `limit/offset`, `sample_count`, `sort_by`, `columns`, and `format` = `preview|raw|metadata|poll`; accepts `timeout_seconds`.
+
+- `dune_health_check` (Health Check, tag: health)
+  - Checks API key presence, query-history path, logging enabled; best-effort template check when configured.
+
+- `dune_find_tables` (Find Tables, tags: dune, schema)
+  - Search schemas by keyword and/or list tables in a schema (`limit`).
+
+- `dune_describe_table` (Describe Table, tags: dune, schema)
+  - Column metadata for `schema.table` (Dune types + Polars inferred dtypes when available).
+
+- `sui_package_overview` (Sui Package Overview, tag: sui)
+  - Compact Sui activity overview for `packages[]` with `hours` (default 72) and `timeout_seconds`.
+
+- Dune Admin tools (tags: dune, admin)
+  - `dune_query_create(name, query_sql, description?, tags?, parameters?)`
+  - `dune_query_update(query_id, name?, query_sql?, description?, tags?, parameters?)`
+  - `dune_query_fork(source_query_id, name?)`
+
+### Resources
+- `spice:history/tail/{n}` — tail last N lines of query history (1..1000)
+- `spice:artifact/{sha}` — fetch stored SQL by 64-hex SHA-256
+- `spice:sui/events_preview/{hours}/{limit}/{packages}` — Sui events preview (JSON)
+- `spice:sui/package_overview/{hours}/{timeout_seconds}/{packages}` — Sui overview (JSON)
+
+## Resources
+
+- `spice:history/tail/{n}`
+  - Last `n` lines from the query-history JSONL, clamped to [1, 1000]
+
+- `spice:artifact/{sha}`
+  - Returns stored SQL for the SHA-256 (validated as 64 lowercase hex)
+
+Tests
+- Offline/unit tests (no network) live under `tests/offline/` and `tests/http_stubbed/`.
+- Live tests under `tests/live/` are skipped by default; enable with `SPICE_TEST_LIVE=1` and a valid `DUNE_API_KEY`.
+- Comprehensive scripted runner (tiered):
+  - Run all tiers: `python tests/scripts/comprehensive_test_runner.py`
+  - Select tiers: `python tests/scripts/comprehensive_test_runner.py -t 1 -t 3`
+  - Stop on first failure: `python tests/scripts/comprehensive_test_runner.py --stop`
+  - Optional JUnit export: `python tests/scripts/comprehensive_test_runner.py --junit tests/scripts/report.xml`
+- Pytest directly (offline/default): `uv run pytest -q -m "not live" --cov=src/spice_mcp --cov-report=term-missing`
+
+Core Tools (with parameters)
+- `dune_query`
+  - Use: Preview/query results by ID, URL, or raw SQL (Polars preview + Dune metadata/pagination).
+  - Params: `query` (string), `parameters?` (object), `performance?` ('medium'|'large'), `limit?` (int), `offset?` (int), `sort_by?` (string), `columns?` (string[]), `sample_count?` (int), `refresh?` (bool), `max_age?` (number), `timeout_seconds?` (number), `format?` ('preview'|'raw'|'metadata').
+  - Output: `type`, `rowcount`, `columns`, `data_preview`, `execution_id`, `duration_ms`, `metadata?`, `next_uri?`, `next_offset?`.
+- `dune_find_tables`
+  - Use: Search schemas by keyword and/or list tables for a schema.
+  - Params: `keyword?` (string), `schema?` (string), `limit?` (int)
+  - Output: `schemas?` (string[]), `tables?` (string[])
+- `dune_describe_table`
+  - Use: Column descriptions for `schema.table` via SHOW + fallback to 1-row sample inference.
+  - Params: `schema` (string), `table` (string)
+  - Output: `columns` ([{ name, dune_type?, polars_dtype?, extra?, comment? }])
+- `sui_package_overview`
+  - Use: Small-window overview for Sui packages (events/transactions/objects) with timeout handling.
+  - Params: `packages` (string[]), `hours?` (int, default 72), `timeout_seconds?` (number, default 30)
+  - Output: best-effort counts and previews; may include `*_timeout`/`*_error`
+- `dune_health_check`
+  - Use: Verify API key presence and logging paths
+  - Output: `api_key_present`, `query_history_path`, `logging_enabled`, `status`
+
+Docs
+- See `docs/index.md` 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`
+
+Notes
+- Legacy Spice code now lives under `src/spice_mcp/adapters/dune` (extract, cache, urls, types).
+- Ports and models live in `src/spice_mcp/core`; services consume ports and are exercised by FastMCP tools.
+- Query history and SQL artefacts are always-on (see `src/spice_mcp/logging/query_history.py`).
+- To bypass dot-env loading during tests/CI, export `SPICE_MCP_SKIP_DOTENV=1`.
+- LazyFrames everywhere: eager `.collect()` or `pl.DataFrame` usage outside dedicated helpers is blocked by `tests/style/test_polars_lazy.py`; materialization helpers live in `src/spice_mcp/polars_utils.py`.

spice_mcp-0.1.0/bin/bat

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Wrapper to provide a consistent `bat` command across distros.
+# On Debian/Ubuntu the binary may be `batcat`.
+set -euo pipefail
+
+if command -v bat >/dev/null 2>&1; then
+  exec bat "$@"
+elif command -v batcat >/dev/null 2>&1; then
+  exec batcat "$@"
+else
+  echo "bat (or batcat) is not installed. Suggested installs:" >&2
+  echo "  macOS:   brew install bat" >&2
+  echo "  Ubuntu:  sudo apt install bat && sudo update-alternatives --set bat \$(command -v batcat) || echo 'Use batcat instead'" >&2
+  echo "  Arch:    sudo pacman -S bat" >&2
+  echo "  Fedora:  sudo dnf install bat" >&2
+  exit 127
+fi
+

spice_mcp-0.1.0/bin/fd

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Wrapper to provide a consistent `fd` command across distros.
+# On Debian/Ubuntu the binary may be `fdfind`.
+set -euo pipefail
+
+if command -v fd >/dev/null 2>&1; then
+  exec fd "$@"
+elif command -v fdfind >/dev/null 2>&1; then
+  exec fdfind "$@"
+else
+  echo "fd (or fdfind) is not installed. Suggested installs:" >&2
+  echo "  macOS:   brew install fd" >&2
+  echo "  Ubuntu:  sudo apt install fd-find && sudo ln -s \$(command -v fdfind) /usr/local/bin/fd" >&2
+  echo "  Arch:    sudo pacman -S fd" >&2
+  echo "  Fedora:  sudo dnf install fd-find" >&2
+  exit 127
+fi
+

spice_mcp-0.1.0/debug_api.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+Debug script to figure out what's happening with the Dune API calls.
+"""
+import os
+import sys
+from pathlib import Path
+
+# Add src to path  
+src_path = Path('src')
+sys.path.insert(0, str(src_path))
+
+from spice_mcp.adapters.dune import urls, transport
+
+def test_dune_connection():
+    """Test API connectivity directly."""
+    print("🔧 Debugging Dune API connection...")
+    
+    api_key = os.getenv("DUNE_API_KEY")
+    print(f"API key: {api_key[:8] if api_key else 'None'}...")
+    
+    try:
+        # Test1: Check headers
+        headers = urls.get_headers(api_key=api_key)
+        print(f"Headers: {headers}")
+        
+        # Test2: Simple URL construction
+        url = urls.get_query_execute_url("SELECT 1 as test")
+        print(f"URL for raw SQL: {url}")
+        
+        # Test3: Try a direct API call
+        print("\n📡 Testing direct API call...")
+        test_url = urls.url_templates['query_create']
+        print(f"Test URL: {test_url}")
+        
+        response = transport.post(
+            test_url,
+            headers=headers,
+            json={
+                "query_sql": "SELECT 1 as test_col",
+                "name": "debug_test",
+                "dataset": "preview",
+                "is_private": True
+            },
+            timeout=10.0
+        )
+        
+        print(f"Response status: {response.status_code}")
+        print(f"Response: {response.text[:200]}...")
+        
+        if response.status_code == 200:
+            data = response.json()
+            query_id = data.get('query_id')
+            print(f"✓ Created query with ID: {query_id}")
+            
+            # Now try to execute it
+            execute_url = urls.get_query_execute_url(query_id)
+            execute_response = transport.post(
+                execute_url,
+                headers=headers,
+                json={
+                    "performance": "medium",
+                    "query_parameters": {}
+                },
+                timeout=10.0
+            )
+            
+            print(f"Execute response status: {execute_response.status_code}")
+            print(f"Execute response: {execute_response.text[:200]}...")
+            
+            if execute_response.status_code == 200:
+                exec_data = execute_response.json()
+                execution_id = exec_data.get('execution_id')
+                print(f"✓ Created execution with ID: {execution_id}")
+                return True
+        
+        return False
+        
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+if __name__ == "__main__":
+    # Load env
+    env_file = Path('.env')
+    if env_file.exists():
+        with open(env_file) as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith("#") and "=" in line:
+                    key, value = line.split("=", 1)
+                    os.environ[key] = value
+    
+    success = test_dune_connection()
+    sys.exit(0 if success else 1)