spice-mcp 0.1.8__tar.gz

spice_mcp-0.1.8/.git

@@ -0,0 +1 @@
+gitdir: /Users/evandekim/Documents/spice_mcp/.git/worktrees/fbR9c

spice_mcp-0.1.8/.gitignore

@@ -0,0 +1,28 @@
+# 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*
+
+# Development tools and directories
+bin/
+.github/
+.factory/
+debug_api.py
+
+# Local testing environment
+test_spice_mcp/
+scripts/
+test_mcp_cursor/

spice_mcp-0.1.8/.python-version

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

spice_mcp-0.1.8/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.8/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.8/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: spice-mcp
+Version: 0.1.8
+Summary: mcp server built ontop of dune api endpoint
+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
+
+[![PyPI version](https://img.shields.io/pypi/v/spice-mcp.svg)](https://pypi.org/project/spice-mcp/)
+<a href="https://glama.ai/mcp/servers/@Evan-Kim2028/spice-mcp">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@Evan-Kim2028/spice-mcp/badge" alt="Spice MCP server" />
+</a>
+
+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 from both Dune API and Spellbook
+- **Type-safe**: Fully typed parameters and responses with FastMCP
+- **Reproducible**: Automatic query history logging and SQL artifact storage
+
+## Quick Start
+
+1. **Install**:
+   ```bash
+   uv pip install spice-mcp
+   ```
+
+2. **Set API key** (choose one method):
+   - **Option A**: Create a `.env` file in your project root:
+     ```bash
+     echo "DUNE_API_KEY=your-api-key-here" > .env
+     ```
+   - **Option B**: Export in your shell:
+     ```bash
+     export DUNE_API_KEY=your-api-key-here
+     ```
+
+3. **Use with Cursor IDE**:
+   Add to Cursor Settings → MCP Servers:
+   ```json
+   {
+     "name": "spice-mcp",
+     "command": "spice-mcp",
+     "env": {
+       "DUNE_API_KEY": "your-dune-api-key-here"
+     }
+   }
+   ```
+
+**Note**: Query history logging is enabled by default. Logs are saved to `logs/queries.jsonl` (or `~/.spice_mcp/logs/queries.jsonl` if not in a project directory). To customize paths, set `SPICE_QUERY_HISTORY` and `SPICE_ARTIFACT_ROOT` environment variables.
+Admin operations (create/update/fork/archive/unarchive) are logged with `action_type="admin_action"` and include `query_id` for traceability.
+
+## Core Tools
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `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 (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) |
+| `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) |
+| `dune_query_fork` | Fork an existing saved query | `source_query_id` (int), `name` (str) |
+| `dune_query_archive` | Archive a saved query | `query_id` (int) |
+| `dune_query_unarchive` | Unarchive a saved query | `query_id` (int) |
+
+## Resources
+
+- `spice:history/tail/{n}` — View last N lines of query history (1-1000)
+- `spice:artifact/{sha}` — Retrieve stored SQL by SHA-256 hash
+
+## What is Dune?
+
+[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):
+```bash
+uv pip install spice-mcp
+```
+
+**From source**:
+```bash
+git clone https://github.com/Evan-Kim2028/spice-mcp.git
+cd spice-mcp
+uv sync
+uv pip install -e .
+```
+
+**Requirements**: Python 3.13+
+
+## Documentation
+
+- [Tool Reference](docs/tools.md) — Complete tool documentation with parameters
+- [Architecture](docs/architecture.md) — Code structure and design patterns
+- [Discovery Guide](docs/discovery.md) — How to explore Dune schemas and tables
+- [Dune API Guide](docs/dune_api.md) — Understanding Dune's data structure
+- [Configuration](docs/config.md) — Environment variables and settings
+
+## License
+
+See [LICENSE](LICENSE) file for details.

spice_mcp-0.1.8/README.md

@@ -0,0 +1,115 @@
+# spice-mcp
+
+[![PyPI version](https://img.shields.io/pypi/v/spice-mcp.svg)](https://pypi.org/project/spice-mcp/)
+<a href="https://glama.ai/mcp/servers/@Evan-Kim2028/spice-mcp">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@Evan-Kim2028/spice-mcp/badge" alt="Spice MCP server" />
+</a>
+
+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 from both Dune API and Spellbook
+- **Type-safe**: Fully typed parameters and responses with FastMCP
+- **Reproducible**: Automatic query history logging and SQL artifact storage
+
+## Quick Start
+
+1. **Install**:
+   ```bash
+   uv pip install spice-mcp
+   ```
+
+2. **Set API key** (choose one method):
+   - **Option A**: Create a `.env` file in your project root:
+     ```bash
+     echo "DUNE_API_KEY=your-api-key-here" > .env
+     ```
+   - **Option B**: Export in your shell:
+     ```bash
+     export DUNE_API_KEY=your-api-key-here
+     ```
+
+3. **Use with Cursor IDE**:
+   Add to Cursor Settings → MCP Servers:
+   ```json
+   {
+     "name": "spice-mcp",
+     "command": "spice-mcp",
+     "env": {
+       "DUNE_API_KEY": "your-dune-api-key-here"
+     }
+   }
+   ```
+
+**Note**: Query history logging is enabled by default. Logs are saved to `logs/queries.jsonl` (or `~/.spice_mcp/logs/queries.jsonl` if not in a project directory). To customize paths, set `SPICE_QUERY_HISTORY` and `SPICE_ARTIFACT_ROOT` environment variables.
+Admin operations (create/update/fork/archive/unarchive) are logged with `action_type="admin_action"` and include `query_id` for traceability.
+
+## Core Tools
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `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 (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) |
+| `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) |
+| `dune_query_fork` | Fork an existing saved query | `source_query_id` (int), `name` (str) |
+| `dune_query_archive` | Archive a saved query | `query_id` (int) |
+| `dune_query_unarchive` | Unarchive a saved query | `query_id` (int) |
+
+## Resources
+
+- `spice:history/tail/{n}` — View last N lines of query history (1-1000)
+- `spice:artifact/{sha}` — Retrieve stored SQL by SHA-256 hash
+
+## What is Dune?
+
+[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):
+```bash
+uv pip install spice-mcp
+```
+
+**From source**:
+```bash
+git clone https://github.com/Evan-Kim2028/spice-mcp.git
+cd spice-mcp
+uv sync
+uv pip install -e .
+```
+
+**Requirements**: Python 3.13+
+
+## Documentation
+
+- [Tool Reference](docs/tools.md) — Complete tool documentation with parameters
+- [Architecture](docs/architecture.md) — Code structure and design patterns
+- [Discovery Guide](docs/discovery.md) — How to explore Dune schemas and tables
+- [Dune API Guide](docs/dune_api.md) — Understanding Dune's data structure
+- [Configuration](docs/config.md) — Environment variables and settings
+
+## License
+
+See [LICENSE](LICENSE) file for details.