spotify-mcp-jamiew 0.3.0__tar.gz

spotify_mcp_jamiew-0.3.0/.dockerignore

@@ -0,0 +1,57 @@
+# Git and version control
+.git/
+.gitignore
+.gitattributes
+
+# System files
+/proc/
+/sys/
+/dev/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+.venv/
+.env
+.env.*
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Testing and development
+.pytest_cache/
+.coverage
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+*.log
+
+# IDE and editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Documentation
+docs/
+*.md
+!README.md
+
+# CI/CD
+.github/
+.gitlab-ci.yml
+
+# Other
+*.tmp
+*.bak
+node_modules/

spotify_mcp_jamiew-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,158 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    needs: [lint]  # Don't test broken code
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        # Install a specific uv version
+        version: "latest"
+        # Install uv globally
+        enable-cache: true
+
+    - name: Set up project
+      run: uv sync --dev
+
+    - name: Run type checking
+      run: uv run mypy src/
+
+    - name: Run tests
+      run: uv run pytest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+        enable-cache: true
+
+    - name: Set up project
+      run: uv sync --dev
+
+    - name: Run ruff linter
+      run: uv run ruff check src/ tests/
+
+    - name: Run ruff formatter check
+      run: uv run ruff format --check src/ tests/
+
+  security:
+    runs-on: ubuntu-latest
+    needs: [lint]  # Don't scan broken code
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+        enable-cache: true
+
+    - name: Set up project
+      run: uv sync --dev
+
+    - name: Run bandit security linter
+      run: uv run bandit -r src/
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [test, lint, security]  # Require all quality gates
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+        enable-cache: true
+
+    - name: Set up project
+      run: uv sync --dev
+
+    - name: Build package
+      run: uv build
+
+    - name: Store build artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+  docker:
+    runs-on: ubuntu-latest
+    needs: [test, lint, security]
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Build Docker image
+      uses: docker/build-push-action@v6
+      with:
+        context: .
+        file: ./Dockerfile
+        push: false
+        load: true  # Load image into Docker daemon for testing
+        tags: spotify-mcp:test
+        cache-from: type=gha
+        cache-to: type=gha,mode=max
+
+    - name: Test Docker image
+      run: |
+        # Test that image was built and can run basic commands
+        docker run --rm spotify-mcp:test python --version
+        
+        # Test that entry point is installed and accessible
+        docker run --rm spotify-mcp:test which spotify-mcp
+        
+        # Test that application starts without errors (with proper env vars)
+        docker run --rm -e SPOTIFY_CLIENT_ID=test -e SPOTIFY_CLIENT_SECRET=test -e SPOTIFY_REDIRECT_URI=http://localhost:8888 spotify-mcp:test python -c "print('✅ Docker image works correctly')"
+        
+        # Test security: ensure running as non-root user
+        docker run --rm spotify-mcp:test sh -c 'whoami | grep -v root'

spotify_mcp_jamiew-0.3.0/.github/workflows/claude-code-review.yml

@@ -0,0 +1,57 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Please review this pull request and provide feedback on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Performance considerations
+            - Security concerns
+            - Test coverage
+
+            Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
+
+            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
+
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
+

spotify_mcp_jamiew-0.3.0/.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'
+

spotify_mcp_jamiew-0.3.0/.github/workflows/deploy-pages.yml

@@ -0,0 +1,40 @@
+name: Deploy GitHub Pages
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './docs'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

spotify_mcp_jamiew-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish to PyPI & MCP Registry
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run type checking
+        run: uv run mypy src/
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz" | tar xz mcp-publisher
+
+      - name: Authenticate to MCP Registry
+        run: ./mcp-publisher login github-oidc
+
+      - name: Set version in server.json
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          jq --arg v "$VERSION" '.version = $v | .packages[0].version = $v' server.json > server.tmp && mv server.tmp server.json
+
+      - name: Publish to MCP Registry
+        run: ./mcp-publisher publish

spotify_mcp_jamiew-0.3.0/.gitignore

@@ -0,0 +1,6 @@
+.env*
+.cache
+.coverage
+.DS_Store
+**/__pycache__
+dist/

spotify_mcp_jamiew-0.3.0/.python-version

@@ -0,0 +1 @@
+3.12

spotify_mcp_jamiew-0.3.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## 2026-05-29
+
+### Packaging & distribution
+- published to PyPI as `spotify-mcp-jamiew` and to the MCP Registry as
+  `io.github.jamiew/spotify-mcp` (`spotify-mcp` is taken by upstream)
+- one-command install via `uvx spotify-mcp-jamiew`; README now has copy-paste
+  setup for Claude Code, Claude Desktop, and Codex CLI
+- automated release: a GitHub Actions workflow publishes to PyPI + the MCP
+  Registry on GitHub release via OIDC trusted publishing (no stored tokens)
+- added packaging tests that keep `server.json` in sync with `pyproject.toml`
+  and the env vars the server reads
+
+## 2026-05-28
+
+### Modern MCP protocol features
+- structured output: every tool returns a typed Pydantic model (real output
+  schemas) instead of bare dicts
+- tool annotations (readOnly/destructive/idempotent/openWorld hints) + titles,
+  plus a Spotify icon on every tool, resource, and prompt
+- progress + log notifications while paginating large playlists
+- elicitation: `remove_tracks_from_playlist` confirms before deleting on clients
+  that support it, and proceeds without prompting on clients that don't
+- new resources: track / playlist / artist / album by id
+
+### Fixes
+- playback now reads from `current_playback()`, so device/volume/shuffle/repeat
+  are populated instead of always null
+- a destructive removal no longer slips through when an elicitation prompt errors
+  on a capable client — only genuinely unsupported clients skip confirmation
+- playlist add/remove now surface the returned `snapshot_id`
+- search tolerates null entries in result items
+- dropped unused error codes left over from the deleted error helpers
+
+### Dependencies updated to current majors
+- bumped the runtime + dev stack to latest: mcp 1.27, spotipy 2.26, pytest 9,
+  mypy 2.0, ruff 0.15, pytest-cov 7 (pydantic 2.13 pulled in transitively)
+
+### Audio-features and recommendations tools removed
+- dropped both tools — Spotify deprecated those endpoints in nov 2024 and they
+  return 403 for apps created after that (tool count 13 → 11)
+
+### Dead code removed
+- removed the unused Client wrapper, utils parsers, and error/logging helpers
+  left over from the FastMCP rewrite (~1400 lines)
+
+### Test coverage raised to 95%
+- every tool now has a success and a failure test; the resources and prompts
+  are covered too (was 55%)
+
+### Typed Spotify response shapes
+- added TypedDicts for the Spotify objects the server consumes, applied at the
+  parse and model-building boundaries
+
+## 2025-12-08 — 0.2.0
+- batch support for tracks/audio features plus new tools
+- added the release.sh helper script

spotify_mcp_jamiew-0.3.0/CLAUDE.md

@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+This file provides essential guidance for working with the Spotify MCP server codebase.
+
+## Essential Commands
+
+### Development
+- `uv run spotify-mcp` - Start the MCP server (local alias; the package publishes as `spotify-mcp-jamiew`, so end users run `uvx spotify-mcp-jamiew`)
+- `uv sync` - Sync dependencies 
+- `uv run pytest` - Run all tests (must pass before commits)
+- `uv run mypy src/` - Type checking (must pass before commits)
+  - Optional speedup on mypy 2.x: `uv run mypy src/ --num-workers 4` (parallel checking)
+
+### Environment Setup
+Required environment variables:
+- `SPOTIFY_CLIENT_ID` - Spotify API Client ID
+- `SPOTIFY_CLIENT_SECRET` - Spotify API Client Secret
+
+Three-tier configuration (highest priority first):
+1. Environment variables (for production/MCP usage)
+2. `.env` file (for local development)
+3. `pyproject.toml` defaults (fallback - edit `[tool.spotify-mcp.env]` section)
+
+### Git Workflow
+**Quality Gates**: Before any commit, ALWAYS run:
+- `uv run mypy src/` - Type checking must pass
+- `uv run pytest` - All tests must pass
+
+**Commit Message Format:**
+```
+Brief description of change
+
+Detailed explanation of what and why.
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+### Releasing
+Publishing is fully automated via OIDC trusted publishing — no tokens stored anywhere.
+
+1. Bump `version` in `pyproject.toml`, commit, and create a GitHub release for tag `vX.Y.Z`
+   (the `/release` skill or `release.sh` does the tag + `gh release create`).
+2. The `release: published` event triggers `.github/workflows/publish.yml`, which tests → builds →
+   publishes to **PyPI** (`pypa/gh-action-pypi-publish`, OIDC) → publishes to the **MCP Registry**
+   (`mcp-publisher login github-oidc`), injecting the tag version into `server.json` at publish time.
+
+The package publishes to PyPI as `spotify-mcp-jamiew` and to the registry as `io.github.jamiew/spotify-mcp`.
+
+One-time setup (already required before the first successful run):
+- PyPI: register a trusted publisher for project `spotify-mcp-jamiew` → owner `jamiew`, repo
+  `spotify-mcp`, workflow `publish.yml`.
+- MCP Registry: the `io.github.jamiew/*` namespace is authenticated automatically via GitHub OIDC.
+
+## Architecture
+
+FastMCP-based MCP server for Spotify Web API integration using Python/`uv`.
+
+### Core Files
+- **`src/spotify_mcp/fastmcp_server.py`** - Main MCP server: tools, resources, and prompts using `@mcp.tool()`/`@mcp.resource()`/`@mcp.prompt()` decorators, with typed Pydantic output models
+- **`src/spotify_mcp/spotify_api.py`** - OAuth client wrapper (auth/token management only); tools talk to `self.sp` directly
+- **`src/spotify_mcp/spotify_types.py`** - TypedDicts for the Spotify response shapes the server consumes
+- **`src/spotify_mcp/utils.py`** - Redirect-URI normalization
+
+### Key Features
+- **MCP Tools**: Playback control, search, queue management, playlist operations, track/artist info
+- **Structured Output**: Every tool returns a typed Pydantic model (real output schema)
+- **Tool Annotations & Icons**: read-only/destructive hints, titles, and a Spotify glyph on tools/resources/prompts
+- **Progress & Elicitation**: progress notifications for large paginations; confirmation prompts before destructive playlist removals (when the client supports it)
+- **Pagination Support**: Handles large datasets (10k+ tracks) with `limit`/`offset` parameters
+- **OAuth Flow**: Automatic token management via spotipy
+- **Type Safety**: Full Pydantic validation and MyPy compliance
+- **Performance Logging**: Comprehensive timing and debug logging for tools and API calls
+
+## Development Guidelines
+
+### Tool Design Principles
+- **Single Responsibility**: One focused purpose per tool (avoid `action` parameters)
+- **Structured Returns**: Return a typed Pydantic model so the tool has a real output schema
+- **Pagination-First**: Add `limit`/`offset` to tools that can return >20 items
+- **Type Safety**: Use strict type hints and Pydantic validation
+
+### Code Quality Standards
+- Run `mypy` and `pytest` before every commit
+- Convert Spotify exceptions to MCP-compliant errors
+- Include Args/Returns in all tool docstrings
+- Mock external API calls in tests
+

spotify_mcp_jamiew-0.3.0/Dockerfile

@@ -0,0 +1,39 @@
+# Multi-stage build for Spotify MCP server
+FROM python:3.12-alpine AS builder
+
+# Install build dependencies
+RUN apk add --no-cache build-base
+
+# Install uv
+RUN pip install --no-cache-dir uv
+
+# Set working directory
+WORKDIR /app
+
+# Copy dependency files first for better caching
+COPY pyproject.toml uv.lock ./
+COPY src/ ./src/
+COPY README.md ./
+
+# Sync dependencies and build
+RUN uv sync --frozen --no-dev
+RUN uv build
+
+# Production stage
+FROM python:3.12-alpine AS runtime
+
+# Install uv for runtime
+RUN pip install --no-cache-dir uv
+
+# Copy the built wheel and install it
+COPY --from=builder /app/dist/*.whl /tmp/
+RUN pip install --no-cache-dir /tmp/*.whl && rm /tmp/*.whl
+
+# Create non-root user for security
+RUN addgroup -g 1001 -S spotify && \
+    adduser -S -D -H -u 1001 -s /sbin/nologin -G spotify spotify
+
+USER spotify
+
+# Command to run the MCP server
+CMD ["spotify-mcp"]

spotify_mcp_jamiew-0.3.0/LICENSE

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