spotted-ts-mcp 0.1.0

package/src/tools/playlists/tracks/add-playlists-tracks.ts

@@ -0,0 +1,62 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { maybeFilter } from 'spotted-ts-mcp/filtering';
+import { Metadata, asTextContentResult } from 'spotted-ts-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import Spotted from 'spotted-ts';
+
+export const metadata: Metadata = {
+  resource: 'playlists.tracks',
+  operation: 'write',
+  tags: [],
+  httpMethod: 'post',
+  httpPath: '/playlists/{playlist_id}/tracks',
+  operationId: 'add-tracks-to-playlist',
+};
+
+export const tool: Tool = {
+  name: 'add_playlists_tracks',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nAdd one or more items to a user's playlist.\n\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/track_add_response',\n  $defs: {\n    track_add_response: {\n      type: 'object',\n      properties: {\n        snapshot_id: {\n          type: 'string'\n        }\n      }\n    }\n  }\n}\n```",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      playlist_id: {
+        type: 'string',
+        title: 'Playlist ID',
+        description: 'The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the playlist.\n',
+      },
+      position: {
+        type: 'integer',
+        description:
+          'The position to insert the items, a zero-based index. For example, to insert the items in the first position: `position=0` ; to insert the items in the third position: `position=2`. If omitted, the items will be appended to the playlist. Items are added in the order they appear in the uris array. For example: `{"uris": ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh","spotify:track:1301WleyT98MSxVHPZCA6M"], "position": 3}`\n',
+      },
+      uris: {
+        type: 'array',
+        description:
+          'A JSON array of the [Spotify URIs](/documentation/web-api/concepts/spotify-uris-ids) to add. For example: `{"uris": ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh","spotify:track:1301WleyT98MSxVHPZCA6M", "spotify:episode:512ojhOuo1ktJprKbVcKyQ"]}`<br/>A maximum of 100 items can be added in one request. _**Note**: if the `uris` parameter is present in the query string, any URIs listed here in the body will be ignored._\n',
+        items: {
+          type: 'string',
+        },
+      },
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
+    },
+    required: ['playlist_id'],
+  },
+  annotations: {},
+};
+
+export const handler = async (client: Spotted, args: Record<string, unknown> | undefined) => {
+  const { playlist_id, jq_filter, ...body } = args as any;
+  return asTextContentResult(
+    await maybeFilter(jq_filter, await client.playlists.tracks.add(playlist_id, body)),
+  );
+};
+
+export default { metadata, tool, handler };

package/src/tools/playlists/tracks/list-playlists-tracks.ts

@@ -0,0 +1,71 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Metadata, asTextContentResult } from 'spotted-ts-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import Spotted from 'spotted-ts';
+
+export const metadata: Metadata = {
+  resource: 'playlists.tracks',
+  operation: 'read',
+  tags: [],
+  httpMethod: 'get',
+  httpPath: '/playlists/{playlist_id}/tracks',
+  operationId: 'get-playlists-tracks',
+};
+
+export const tool: Tool = {
+  name: 'list_playlists_tracks',
+  description: 'Get full details of the items of a playlist owned by a Spotify user.\n',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      playlist_id: {
+        type: 'string',
+        title: 'Playlist ID',
+        description: 'The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the playlist.\n',
+      },
+      additional_types: {
+        type: 'string',
+        title: 'Additional Types',
+        description:
+          'A comma-separated list of item types that your client supports besides the default `track` type. Valid types are: `track` and `episode`.<br/>\n_**Note**: This parameter was introduced to allow existing clients to maintain their current behaviour and might be deprecated in the future._<br/>\nIn addition to providing this parameter, make sure that your client properly handles cases of new types in the future by checking against the `type` field of each object.\n',
+      },
+      fields: {
+        type: 'string',
+        title: 'Fields',
+        description:
+          'Filters for the query: a comma-separated list of the\nfields to return. If omitted, all fields are returned. For example, to get\njust the total number of items and the request limit:<br/>`fields=total,limit`<br/>A\ndot separator can be used to specify non-reoccurring fields, while parentheses\ncan be used to specify reoccurring fields within objects. For example, to\nget just the added date and user ID of the adder:<br/>`fields=items(added_at,added_by.id)`<br/>Use\nmultiple parentheses to drill down into nested objects, for example:<br/>`fields=items(track(name,href,album(name,href)))`<br/>Fields\ncan be excluded by prefixing them with an exclamation mark, for example:<br/>`fields=items.track.album(!external_urls,images)`\n',
+      },
+      limit: {
+        type: 'integer',
+        title: 'Limit',
+        description: 'The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 100.\n',
+      },
+      market: {
+        type: 'string',
+        title: 'Market',
+        description:
+          'An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n  If a country code is specified, only content that is available in that market will be returned.<br/>\n  If a valid user access token is specified in the request header, the country associated with\n  the user account will take priority over this parameter.<br/>\n  _**Note**: If neither market or user country are provided, the content is considered unavailable for the client._<br/>\n  Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/).\n',
+      },
+      offset: {
+        type: 'integer',
+        title: 'Offset',
+        description:
+          'The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items.\n',
+      },
+    },
+    required: ['playlist_id'],
+  },
+  annotations: {
+    readOnlyHint: true,
+  },
+};
+
+export const handler = async (client: Spotted, args: Record<string, unknown> | undefined) => {
+  const { playlist_id, ...body } = args as any;
+  const response = await client.playlists.tracks.list(playlist_id, body).asResponse();
+  return asTextContentResult(await response.json());
+};
+
+export default { metadata, tool, handler };

package/src/tools/playlists/tracks/remove-playlists-tracks.ts

@@ -0,0 +1,70 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { maybeFilter } from 'spotted-ts-mcp/filtering';
+import { Metadata, asTextContentResult } from 'spotted-ts-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import Spotted from 'spotted-ts';
+
+export const metadata: Metadata = {
+  resource: 'playlists.tracks',
+  operation: 'write',
+  tags: [],
+  httpMethod: 'delete',
+  httpPath: '/playlists/{playlist_id}/tracks',
+  operationId: 'remove-tracks-playlist',
+};
+
+export const tool: Tool = {
+  name: 'remove_playlists_tracks',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nRemove one or more items from a user's playlist.\n\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/track_remove_response',\n  $defs: {\n    track_remove_response: {\n      type: 'object',\n      properties: {\n        snapshot_id: {\n          type: 'string'\n        }\n      }\n    }\n  }\n}\n```",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      playlist_id: {
+        type: 'string',
+        title: 'Playlist ID',
+        description: 'The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the playlist.\n',
+      },
+      tracks: {
+        type: 'array',
+        description:
+          'An array of objects containing [Spotify URIs](/documentation/web-api/concepts/spotify-uris-ids) of the tracks or episodes to remove.\nFor example: `{ "tracks": [{ "uri": "spotify:track:4iV5W9uYEdYUVa79Axb7Rh" },{ "uri": "spotify:track:1301WleyT98MSxVHPZCA6M" }] }`. A maximum of 100 objects can be sent at once.\n',
+        items: {
+          type: 'object',
+          properties: {
+            uri: {
+              type: 'string',
+              description: 'Spotify URI',
+            },
+          },
+        },
+      },
+      snapshot_id: {
+        type: 'string',
+        description:
+          "The playlist's snapshot ID against which you want to make the changes.\nThe API will validate that the specified items exist and in the specified positions and make the changes,\neven if more recent changes have been made to the playlist.\n",
+      },
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
+    },
+    required: ['playlist_id', 'tracks'],
+  },
+  annotations: {
+    idempotentHint: true,
+  },
+};
+
+export const handler = async (client: Spotted, args: Record<string, unknown> | undefined) => {
+  const { playlist_id, jq_filter, ...body } = args as any;
+  return asTextContentResult(
+    await maybeFilter(jq_filter, await client.playlists.tracks.remove(playlist_id, body)),
+  );
+};
+
+export default { metadata, tool, handler };

package/src/tools/playlists/tracks/update-playlists-tracks.ts

@@ -0,0 +1,75 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { maybeFilter } from 'spotted-ts-mcp/filtering';
+import { Metadata, asTextContentResult } from 'spotted-ts-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import Spotted from 'spotted-ts';
+
+export const metadata: Metadata = {
+  resource: 'playlists.tracks',
+  operation: 'write',
+  tags: [],
+  httpMethod: 'put',
+  httpPath: '/playlists/{playlist_id}/tracks',
+  operationId: 'reorder-or-replace-playlists-tracks',
+};
+
+export const tool: Tool = {
+  name: 'update_playlists_tracks',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nEither reorder or replace items in a playlist depending on the request's parameters.\nTo reorder items, include `range_start`, `insert_before`, `range_length` and `snapshot_id` in the request's body.\nTo replace items, include `uris` as either a query parameter or in the request's body.\nReplacing items in a playlist will overwrite its existing items. This operation can be used for replacing or clearing items in a playlist.\n<br/>\n**Note**: Replace and reorder are mutually exclusive operations which share the same endpoint, but have different parameters.\nThese operations can't be applied together in a single request.\n\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/track_update_response',\n  $defs: {\n    track_update_response: {\n      type: 'object',\n      properties: {\n        snapshot_id: {\n          type: 'string'\n        }\n      }\n    }\n  }\n}\n```",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      playlist_id: {
+        type: 'string',
+        title: 'Playlist ID',
+        description: 'The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the playlist.\n',
+      },
+      insert_before: {
+        type: 'integer',
+        description:
+          'The position where the items should be inserted.<br/>To reorder the items to the end of the playlist, simply set _insert_before_ to the position after the last item.<br/>Examples:<br/>To reorder the first item to the last position in a playlist with 10 items, set _range_start_ to 0, and _insert_before_ to 10.<br/>To reorder the last item in a playlist with 10 items to the start of the playlist, set _range_start_ to 9, and _insert_before_ to 0.\n',
+      },
+      range_length: {
+        type: 'integer',
+        description:
+          'The amount of items to be reordered. Defaults to 1 if not set.<br/>The range of items to be reordered begins from the _range_start_ position, and includes the _range_length_ subsequent items.<br/>Example:<br/>To move the items at index 9-10 to the start of the playlist, _range_start_ is set to 9, and _range_length_ is set to 2.\n',
+      },
+      range_start: {
+        type: 'integer',
+        description: 'The position of the first item to be reordered.\n',
+      },
+      snapshot_id: {
+        type: 'string',
+        description: "The playlist's snapshot ID against which you want to make the changes.\n",
+      },
+      uris: {
+        type: 'array',
+        items: {
+          type: 'string',
+        },
+      },
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
+    },
+    required: ['playlist_id'],
+  },
+  annotations: {
+    idempotentHint: true,
+  },
+};
+
+export const handler = async (client: Spotted, args: Record<string, unknown> | undefined) => {
+  const { playlist_id, jq_filter, ...body } = args as any;
+  return asTextContentResult(
+    await maybeFilter(jq_filter, await client.playlists.tracks.update(playlist_id, body)),
+  );
+};
+
+export default { metadata, tool, handler };

package/src/tools/playlists/update-playlists.ts

@@ -0,0 +1,61 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Metadata, asTextContentResult } from 'spotted-ts-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import Spotted from 'spotted-ts';
+
+export const metadata: Metadata = {
+  resource: 'playlists',
+  operation: 'write',
+  tags: [],
+  httpMethod: 'put',
+  httpPath: '/playlists/{playlist_id}',
+  operationId: 'change-playlist-details',
+};
+
+export const tool: Tool = {
+  name: 'update_playlists',
+  description:
+    "Change a playlist's name and public/private state. (The user must, of\ncourse, own the playlist.)\n",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      playlist_id: {
+        type: 'string',
+        title: 'Playlist ID',
+        description: 'The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the playlist.\n',
+      },
+      collaborative: {
+        type: 'boolean',
+        description:
+          'If `true`, the playlist will become collaborative and other users will be able to modify the playlist in their Spotify client. <br/>\n_**Note**: You can only set `collaborative` to `true` on non-public playlists._\n',
+      },
+      description: {
+        type: 'string',
+        description: 'Value for playlist description as displayed in Spotify Clients and in the Web API.\n',
+      },
+      name: {
+        type: 'string',
+        description: 'The new name for the playlist, for example `"My New Playlist Title"`\n',
+      },
+      public: {
+        type: 'boolean',
+        description:
+          "The playlist's public/private status (if it should be added to the user's profile or not): `true` the playlist will be public, `false` the playlist will be private, `null` the playlist status is not relevant. For more about public/private status, see [Working with Playlists](/documentation/web-api/concepts/playlists)\n",
+      },
+    },
+    required: ['playlist_id'],
+  },
+  annotations: {
+    idempotentHint: true,
+  },
+};
+
+export const handler = async (client: Spotted, args: Record<string, unknown> | undefined) => {
+  const { playlist_id, ...body } = args as any;
+  const response = await client.playlists.update(playlist_id, body).asResponse();
+  return asTextContentResult(await response.text());
+};
+
+export default { metadata, tool, handler };