spotify-analytics-mcp 0.1.0__tar.gz

spotify_analytics_mcp-0.1.0/.gitignore

@@ -0,0 +1,224 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Git worktrees
+.worktrees/
+.claude/worktrees/
+
+# Project specific
+# Vector database and user data
+data/vectordb/
+# sqlite databases and wal, shm files - ignore all but keep directory
+data/*.db*
+# Exclude user's actual Spotify data, but keep sample data
+data/spotify_history/*
+!data/spotify_history/sample_history.json
+# logs
+logs/
+# Internal planning docs (superpowers/Claude Code session artifacts)
+docs/superpowers/

spotify_analytics_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 WC Chang
+
+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.

spotify_analytics_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: spotify-analytics-mcp
+Version: 0.1.0
+Summary: MCP server and CLI installer for the Spotify AI Analytics project.
+Project-URL: Homepage, https://github.com/wcnoname5/spotify-ai-analytics
+Project-URL: Repository, https://github.com/wcnoname5/spotify-ai-analytics
+Project-URL: Issues, https://github.com/wcnoname5/spotify-ai-analytics/issues
+Author: WC Chang
+License: MIT
+License-File: LICENSE
+Keywords: analytics,claude,cli,listening-history,mcp,spotify
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: rich>=13.7
+Requires-Dist: spotify-analytics-core>=0.1.0
+Requires-Dist: spotify-analytics-dataloader>=0.1.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# spotify-analytics-mcp
+
+MCP server and `spotify-mcp` setup CLI for Spotify AI Analytics.

spotify_analytics_mcp-0.1.0/README.md

@@ -0,0 +1,3 @@
+# spotify-analytics-mcp
+
+MCP server and `spotify-mcp` setup CLI for Spotify AI Analytics.

spotify_analytics_mcp-0.1.0/SKILL.md

@@ -0,0 +1,91 @@
+# Spotify AI Analytics — Claude Skill
+
+> Add the contents of this file to your project's CLAUDE.md (or paste it into Claude Desktop's system prompt field) so Claude knows how to use this MCP server effectively.
+
+---
+
+## What this MCP server provides
+
+You are connected to a local Spotify AI Analytics MCP server with these capabilities:
+- **History analytics** — query local SQLite DB of listening history (no auth needed)
+- **Playback control** — control Spotify (requires auth + Spotify Premium)
+- **Long-term memory** — store and retrieve user preferences across conversations
+
+---
+
+## First interaction with a new user
+
+When the user first mentions Spotify or seems to be setting up the server:
+
+1. Call `setup_check()` immediately.
+2. Read the `actions_needed` list. Walk the user through each item in order — do not skip ahead.
+3. After the user completes an action, call `setup_check()` again to confirm before moving on.
+4. Once `ready: true`, confirm the server is fully configured and offer to show their listening stats.
+
+---
+
+## When analytics tools return a warning (empty DB)
+
+If `get_listening_summary`, `get_top_artists`, or `get_top_tracks` return a dict with a `warning` field:
+
+1. Tell the user: "Your local listening history database is empty."
+2. Ask: "Have you already downloaded your Spotify data from https://www.spotify.com/account/privacy/?"
+   - **If yes:** Guide them to run `uv run python scripts/import_json.py --dir data/spotify_history`
+   - **If no:** Explain that requesting the JSON export takes a few days. In the meantime, they can sync recent plays: `uv run python scripts/sync_api.py --user-id <their_user_id>` (last 50 tracks only).
+3. After they run one of these, call the analytics tool again to confirm data loaded.
+
+---
+
+## When a tool returns `requires_auth: true`
+
+The user's Spotify OAuth tokens are missing or expired. Guide them to:
+```bash
+uv run python scripts/init_db.py --auth --user-id <their_user_id>
+```
+This opens a browser tab. They approve access, browser shows "Authentication complete", done. Tokens are saved and auto-refresh going forward.
+
+---
+
+## Tool selection guide
+
+| User says… | Use this tool |
+|------------|---------------|
+| "What's playing?" / "Now playing?" | `get_now_playing` |
+| "Play [track]" / "Resume" | `play_track` (need URI first — ask or search) |
+| "Pause" / "Stop" | `pause_playback` |
+| "Skip" / "Next song" | `skip_track` |
+| "Volume up/down" / "Set volume to X" | `set_volume` |
+| "Add to queue" | `add_to_queue` |
+| "Top artists" / "Most played artists" | `get_top_artists` |
+| "Top tracks" / "Most played songs" | `get_top_tracks` |
+| "How much have I listened?" / "Overview" | `get_listening_summary` |
+| "Sync my plays" / "Update history" | `sync_history` |
+| "Remember that I like X" / "Note that…" | `remember_preference` |
+| "What do you know about my taste?" | `get_memory_summary` |
+| "Create a playlist" | `create_playlist` (generate URIs from analytics first) |
+| "Is everything set up?" / "Something isn't working" | `setup_check` |
+
+---
+
+## Date range filtering
+
+`get_top_artists` and `get_top_tracks` accept `start_date` and `end_date` in `"YYYY-MM-DD"` format.
+
+Examples:
+- "Last year" → `start_date="2024-01-01"`, `end_date="2024-12-31"`
+- "This month" → compute from today's date
+- "2023" → `start_date="2023-01-01"`, `end_date="2023-12-31"`
+
+---
+
+## Timestamps
+
+`get_listening_summary` returns `earliest_played_at` and `latest_played_at` in the user's **local timezone** ISO format. Display them as-is — no further conversion needed.
+
+---
+
+## Playback tool limitations
+
+- All playback tools (`play_track`, `pause_playback`, `skip_track`, `set_volume`, `add_to_queue`) require **Spotify Premium**.
+- If they return `{"error": "Spotify Premium required for playback control."}`, tell the user Premium is required — do not retry.
+- Track URIs follow the format `spotify:track:<22-char-id>`. You can get them from the analytics tools' `track_id` field or by asking the user to copy from Spotify.

spotify_analytics_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "spotify-analytics-mcp"
+version = "0.1.0"
+description = "MCP server and CLI installer for the Spotify AI Analytics project."
+readme = "README.md"
+license = { text = "MIT" }
+license-files = ["LICENSE"]
+authors = [{ name = "WC Chang" }]
+requires-python = ">=3.12"
+keywords = ["spotify", "mcp", "claude", "analytics", "cli", "listening-history"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+]
+dependencies = [
+    "fastmcp>=2.0",
+    "spotify-analytics-core>=0.1.0",
+    "spotify-analytics-dataloader>=0.1.0",
+    "typer>=0.12",
+    "rich>=13.7",
+    "platformdirs>=4.0",
+]
+
+[project.scripts]
+spotify-mcp = "spotify_mcp.cli:app"
+
+[project.entry-points."pipx.run"]
+spotify-analytics-mcp = "spotify_mcp.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/wcnoname5/spotify-ai-analytics"
+Repository = "https://github.com/wcnoname5/spotify-ai-analytics"
+Issues = "https://github.com/wcnoname5/spotify-ai-analytics/issues"
+
+[tool.uv.sources]
+spotify-analytics-core = { workspace = true }
+spotify-analytics-dataloader = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["spotify_mcp"]

spotify_analytics_mcp-0.1.0/server.py

@@ -0,0 +1,42 @@
+"""Spotify AI Analytics MCP Server — development entry point.
+
+For PyPI-installed users the server is launched via `spotify-mcp serve`.
+This file exists as a convenience for checkout-mode development:
+
+    uv run python apps/mcp/server.py
+
+Required environment variables:
+    SPOTIFY_CLIENT_ID   — Spotify app client ID
+    TOKEN_ENCRYPT_KEY   — Fernet key bytes (base64-encoded) for token encryption
+"""
+import logging
+import os
+
+from dotenv import load_dotenv
+
+from spotify_core import paths
+from spotify_core.logging import setup_mcp_logging
+from spotify_mcp.config import get_client_id, get_fernet_key
+
+# Load platformdirs .env first; cwd .env fills any gaps but never overrides.
+if paths.env_file().exists():
+    load_dotenv(paths.env_file())
+load_dotenv(override=False)
+
+_raw_level = os.getenv("LOG_LEVEL", "DEBUG").upper()
+_log_file = setup_mcp_logging(level=logging.getLevelNamesMapping().get(_raw_level, logging.DEBUG))
+logger = logging.getLogger(__name__)
+logger.info("Logging to %s", _log_file)
+
+if not get_client_id():
+    logger.warning("SPOTIFY_CLIENT_ID is not set. Set it in .env or as an environment variable.")
+if not get_fernet_key():
+    logger.warning(
+        "TOKEN_ENCRYPT_KEY is not set. "
+        'Generate one with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"'
+    )
+
+from spotify_mcp._mcp import main  # noqa: E402 — must come after env/logging setup
+
+if __name__ == "__main__":
+    main()

spotify_analytics_mcp-0.1.0/spotify_mcp/_mcp.py

@@ -0,0 +1,83 @@
+"""FastMCP application — mcp instance, tool registrations, and main().
+
+This module owns the FastMCP app object so it can be imported by both the
+development entry point (apps/mcp/server.py) and the `spotify-mcp serve`
+CLI command without duplicating server logic.
+"""
+import logging
+import sys
+from contextlib import asynccontextmanager
+
+from fastmcp import FastMCP
+
+from spotify_mcp import db_crud, spotify_control
+from spotify_mcp.config import get_client_id, get_fernet_key
+from spotify_mcp.prompts import register_prompts
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(server: FastMCP):
+    from spotify_mcp.wizard.state import collect_report
+
+    report = collect_report()
+    blocking = [a for a in report["actions_needed"] if "Load history" not in a]
+    if blocking:
+        msg = "spotify-mcp not configured. Run: spotify-mcp setup"
+
+        def _ascii_safe(s: str) -> str:
+            # Replace Unicode dashes with ASCII hyphen so Windows consoles
+            # (cp1252) don't produce un-decodable bytes in the stderr stream.
+            return s.replace("—", "-").replace("–", "-")
+
+        print(_ascii_safe(msg), file=sys.stderr, flush=True)
+        for action in blocking:
+            print(_ascii_safe(f"  - {action}"), file=sys.stderr, flush=True)
+        logger.error("%s\n%s", msg, "\n".join(f"  - {action}" for action in blocking))
+        raise SystemExit(1)
+
+    logger.info("MCP server ready: all checks passed.")
+    yield
+
+
+mcp = FastMCP("spotify_mcp", lifespan=lifespan)
+
+
+@mcp.tool(
+    name="setup_check",
+    annotations={
+        "title": "Check Server Setup",
+        "readOnlyHint": True,
+        "destructiveHint": False,
+        "idempotentHint": True,
+        "openWorldHint": False,
+    },
+)
+def setup_check() -> dict:
+    """Diagnose the MCP server configuration. Call this first if something isn't working.
+
+    Returns a structured report of what is configured and what actions are still needed,
+    in the order they must be completed.
+
+    Returns:
+        {
+            "ready": bool,
+            "checks": dict[str, bool],
+            "actions_needed": list[str],
+            "message": str,
+        }
+    """
+    logger.debug("[Tool] setup_check: running diagnostics on server configuration.")
+    from spotify_mcp.wizard.state import collect_report
+
+    return collect_report()
+
+
+register_prompts(mcp)
+db_crud.register(mcp)
+spotify_control.register(mcp)
+
+
+def main() -> None:
+    mcp.run(transport="stdio")