starred/spotify-mcp-varunneal

Fork 0

mirror of https://github.com/varunneal/spotify-mcp.git synced 2026-04-26 13:15:50 +03:00

[PR #34] [CLOSED] Comprehensive pagination support and tool modernization #39

New issue

Closed

opened 2026-02-28 15:42:57 +03:00 by kerem · 0 comments

kerem commented

2026-02-28 15:42:57 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/varunneal/spotify-mcp/pull/34
Author: @jamiew
Created: 8/13/2025
Status: ❌ Closed

Base: main ← Head: improve-pagination

📝 Commits (10+)

2f8a2ca Implement playlist API functions (and enhance type safety throughout)
1c02a97 Git-ignore common files and cache files
5bcc5ba Add additional logging so we can see what's going
1ad41c7 Add necessary playlist API scopes
9ecbc19 Add Dockerfile
d25a2ec Add Smithery configuration
8f0f0e7 Update README
cb742ba Merge pull request #1 from jamiew/smithery/config-jn1p
0e5630c Fix markdownlint issues in README (mostly newlines)
37093a5 Ignore cachefiles using .gitignore

📊 Changes

19 files changed (+3813 additions, -489 deletions)

View changed files

➕ .gitignore (+4 -0)
➕ CLAUDE.md (+739 -0)
➕ Dockerfile (+21 -0)
➕ LICENSE (+21 -0)
📝 README.md (+25 -9)
📝 pyproject.toml (+59 -2)
➕ smithery.yaml (+37 -0)
📝 src/spotify_mcp/__init__.py (+4 -5)
➕ src/spotify_mcp/errors.py (+275 -0)
➕ src/spotify_mcp/fastmcp_server.py (+678 -0)
➖ src/spotify_mcp/server.py (+0 -251)
📝 src/spotify_mcp/spotify_api.py (+342 -75)
📝 src/spotify_mcp/utils.py (+38 -11)
➕ tests/conftest.py (+122 -0)
➕ tests/test_errors.py (+193 -0)
➕ tests/test_fastmcp_tools.py (+385 -0)
➕ tests/test_spotify_api.py (+115 -0)
➕ tests/test_utils.py (+210 -0)
📝 uv.lock (+545 -136)

📄 Description

Summary

This PR implements comprehensive pagination support and modernizes the FastMCP server architecture, transforming it from a basic prototype into a production-ready MCP server.

🚀 Major Improvements

Comprehensive Pagination Support:

Added limit and offset parameters to search_tracks and get_user_playlists
New dedicated get_playlist_tracks tool with full pagination for large playlists (1000+ tracks)
Intelligent batching with safety limits (10,000 track maximum)
Structured pagination responses with items, total, limit, offset metadata

Tool Architecture Modernization:

Split multi-action tools: manage_queue(action) → add_to_queue() + get_queue()
Split generic tools: get_item_info(qtype) → get_track_info() + get_artist_info() + get_playlist_info()
Consistent return formats: All tools now return structured Dict[str, Any] instead of mixed types
Single responsibility: Each tool has a clear, focused purpose

Enhanced Documentation:

Added 3 new workflow prompts demonstrating pagination usage
Comprehensive tool descriptions with usage examples and performance tips
Clear parameter validation guidance for LLMs

🔧 Technical Details

API Efficiency:

Spotify API batch processing (100 items per request)
Progressive loading prevents memory issues with large datasets
Smart pagination loops with safety checks

Developer Experience:

Updated all 67 tests to match new tool signatures
Comprehensive test coverage for pagination scenarios
Type checking passes cleanly with new structured returns

📊 Tools Overview

Before (7 tools): Mixed patterns, limited pagination
After (13 tools): Focused, consistent, comprehensive pagination

New/Updated Tools:

get_playlist_tracks - Dedicated pagination for large playlists
add_to_queue / get_queue - Split from generic manage_queue
get_track_info / get_artist_info / get_playlist_info - Split from generic get_item_info
All search and user tools now support pagination

✅ Benefits

Handles real-world usage: Large playlists, extensive searches, bulk operations
Better LLM integration: Clear tool purposes, comprehensive documentation
Production ready: Robust pagination, error handling, type safety
Future proof: Extensible patterns for additional features

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/varunneal/spotify-mcp/pull/34 **Author:** [@jamiew](https://github.com/jamiew) **Created:** 8/13/2025 **Status:** ❌ Closed **Base:** `main` ← **Head:** `improve-pagination` --- ### 📝 Commits (10+) - [`2f8a2ca`](https://github.com/varunneal/spotify-mcp/commit/2f8a2cac78faf63b2455199db10faedd77737a1e) Implement playlist API functions (and enhance type safety throughout) - [`1c02a97`](https://github.com/varunneal/spotify-mcp/commit/1c02a9700dd24d0bf2e925ca59b8c7da9904c1cf) Git-ignore common files and cache files - [`5bcc5ba`](https://github.com/varunneal/spotify-mcp/commit/5bcc5baada2029b75607af3cfedac901081a724d) Add additional logging so we can see what's going - [`1ad41c7`](https://github.com/varunneal/spotify-mcp/commit/1ad41c74c97f80cd478acbbb31c9bb1cec146499) Add necessary playlist API scopes - [`9ecbc19`](https://github.com/varunneal/spotify-mcp/commit/9ecbc19fcca17b8edb8874dfb9ce269ecd1e4bc1) Add Dockerfile - [`d25a2ec`](https://github.com/varunneal/spotify-mcp/commit/d25a2ecd95aebc5c05c8556fc3b47ef32338067a) Add Smithery configuration - [`8f0f0e7`](https://github.com/varunneal/spotify-mcp/commit/8f0f0e79900210b49a33d3aa87ff69a3835484e8) Update README - [`cb742ba`](https://github.com/varunneal/spotify-mcp/commit/cb742ba2bb2f16bccacbcabaca751fd1f11469a6) Merge pull request #1 from jamiew/smithery/config-jn1p - [`0e5630c`](https://github.com/varunneal/spotify-mcp/commit/0e5630c6cddd0a87db09cb6f4bd3f4e5ece11126) Fix markdownlint issues in README (mostly newlines) - [`37093a5`](https://github.com/varunneal/spotify-mcp/commit/37093a5dfe13497f18232c3e0184f07b95509654) Ignore cachefiles using .gitignore ### 📊 Changes **19 files changed** (+3813 additions, -489 deletions) <details> <summary>View changed files</summary> ➕ `.gitignore` (+4 -0) ➕ `CLAUDE.md` (+739 -0) ➕ `Dockerfile` (+21 -0) ➕ `LICENSE` (+21 -0) 📝 `README.md` (+25 -9) 📝 `pyproject.toml` (+59 -2) ➕ `smithery.yaml` (+37 -0) 📝 `src/spotify_mcp/__init__.py` (+4 -5) ➕ `src/spotify_mcp/errors.py` (+275 -0) ➕ `src/spotify_mcp/fastmcp_server.py` (+678 -0) ➖ `src/spotify_mcp/server.py` (+0 -251) 📝 `src/spotify_mcp/spotify_api.py` (+342 -75) 📝 `src/spotify_mcp/utils.py` (+38 -11) ➕ `tests/conftest.py` (+122 -0) ➕ `tests/test_errors.py` (+193 -0) ➕ `tests/test_fastmcp_tools.py` (+385 -0) ➕ `tests/test_spotify_api.py` (+115 -0) ➕ `tests/test_utils.py` (+210 -0) 📝 `uv.lock` (+545 -136) </details> ### 📄 Description ## Summary This PR implements comprehensive pagination support and modernizes the FastMCP server architecture, transforming it from a basic prototype into a production-ready MCP server. ### 🚀 Major Improvements **Comprehensive Pagination Support:** - Added `limit` and `offset` parameters to `search_tracks` and `get_user_playlists` - New dedicated `get_playlist_tracks` tool with full pagination for large playlists (1000+ tracks) - Intelligent batching with safety limits (10,000 track maximum) - Structured pagination responses with `items`, `total`, `limit`, `offset` metadata **Tool Architecture Modernization:** - **Split multi-action tools**: `manage_queue(action)` → `add_to_queue()` + `get_queue()` - **Split generic tools**: `get_item_info(qtype)` → `get_track_info()` + `get_artist_info()` + `get_playlist_info()` - **Consistent return formats**: All tools now return structured `Dict[str, Any]` instead of mixed types - **Single responsibility**: Each tool has a clear, focused purpose **Enhanced Documentation:** - Added 3 new workflow prompts demonstrating pagination usage - Comprehensive tool descriptions with usage examples and performance tips - Clear parameter validation guidance for LLMs ### 🔧 Technical Details **API Efficiency:** - Spotify API batch processing (100 items per request) - Progressive loading prevents memory issues with large datasets - Smart pagination loops with safety checks **Developer Experience:** - Updated all 67 tests to match new tool signatures - Comprehensive test coverage for pagination scenarios - Type checking passes cleanly with new structured returns ### 📊 Tools Overview **Before (7 tools):** Mixed patterns, limited pagination **After (13 tools):** Focused, consistent, comprehensive pagination New/Updated Tools: - `get_playlist_tracks` - Dedicated pagination for large playlists - `add_to_queue` / `get_queue` - Split from generic manage_queue - `get_track_info` / `get_artist_info` / `get_playlist_info` - Split from generic get_item_info - All search and user tools now support pagination ### ✅ Benefits - **Handles real-world usage**: Large playlists, extensive searches, bulk operations - **Better LLM integration**: Clear tool purposes, comprehensive documentation - **Production ready**: Robust pagination, error handling, type safety - **Future proof**: Extensible patterns for additional features 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

kerem

2026-02-28 15:42:57 +03:00

closed this issue
added the
pull-request
label

No labels

pull-request

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/spotify-mcp-varunneal#39

No description provided.

Rows
Columns