v1.0

spotify-mcp-server/README.md

@@ -372,6 +372,14 @@ npm run auth
 **Note**: The `expiresAt` field is a Unix timestamp (in milliseconds) indicating when the access token expires.
 
 7. **Automatic Token Refresh**: The server will automatically refresh the access token when it expires (typically after 1 hour). The refresh happens transparently using the `refreshToken`, so you don't need to re-authenticate manually. If the refresh fails, you'll need to run `npm run auth` again to re-authenticate.
+   - Tokens are refreshed one minute before they expire, at most once even when several tool calls arrive together, and a rotated `refresh_token` returned by Spotify is saved.
+   - Spotify refresh tokens expire after **6 months**; the server then reports "refresh token expired or revoked — run `npm run auth`".
+   - `spotify-config.json` is rewritten atomically with owner-only permissions (0600 on Linux/macOS).
+
+**Errors:** failed tool calls are returned with `isError: true` (MCP tool error), so
+clients don't treat "Error …" texts as successful results. Every tool carries MCP
+annotations (`readOnlyHint` for lookups, `destructiveHint` for removals and
+playlist edits).
 
 ## Integrating with Claude Desktop, Cursor, and VsCode [Via Cline model extension](https://marketplace.visualstudio.com/items/?itemName=saoudrizwan.claude-dev)