get_user_collection_items

Retrieve items from a user's Discogs music collection with options to filter by folder, sort by criteria like artist or year, and paginate results for efficient browsing.

Instructions

Retrieve a list of items in a user's collection

Input Schema

TableJSON Schema

Name	Required	Description	Default
`username`	Yes
`folder_id`	Yes
`page`	No
`per_page`	No
`sort`	No
`sort_order`	No

Implementation Reference

src/tools/userCollection.ts:238-255 (handler)

MCP tool definition and handler (execute function) for get_user_collection_items, which delegates to UserService.collection.getItems and returns JSON stringified result.

export const getUserCollectionItemsTool: Tool<
  FastMCPSessionAuth,
  typeof UserCollectionItemsParamsSchema
> = {
  name: 'get_user_collection_items',
  description: `Retrieve a list of items in a user's collection`,
  parameters: UserCollectionItemsParamsSchema,
  execute: async (args) => {
    try {
      const userService = new UserService();
      const items = await userService.collection.getItems(args);

      return JSON.stringify(items);
    } catch (error) {
      throw formatDiscogsError(error);
    }
  },
};

src/types/user/collection.ts:88-101 (schema)

Input parameters Zod schema (UserCollectionItemsParamsSchema) for the get_user_collection_items tool.

export const UserCollectionItemsParamsSchema = UsernameInputSchema.merge(
  FolderIdParamSchema().merge(
    QueryParamsSchema([
      'added',
      'artist',
      'catno',
      'format',
      'label',
      'rating',
      'title',
      'year',
    ] as const),
  ),
);

src/tools/userCollection.ts:327-327 (registration)
Direct registration of the tool in registerUserCollectionTools function.
```
server.addTool(getUserCollectionItemsTool);
```
src/tools/index.ts:20-20 (registration)
Registration of the user collection tools module (including this tool) in the main tools registry.
```
registerUserCollectionTools(server);
```

src/services/user/collection.ts:360-382 (helper)

Supporting UserCollectionService.getItems method that performs the HTTP request to Discogs API endpoint for fetching user collection items and validates the response.

async getItems({
  username,
  folder_id,
  ...options
}: UserCollectionItemsParams): Promise<UserCollectionItemsByRelease> {
  try {
    const response = await this.request<UserCollectionItemsByRelease>(
      `/${username}/collection/folders/${folder_id}/releases`,
      {
        params: options,
      },
    );

    const validatedResponse = UserCollectionItemsByReleaseSchema.parse(response);
    return validatedResponse;
  } catch (error) {
    if (isDiscogsError(error)) {
      throw error;
    }

    throw new Error(`Failed to get collection items: ${String(error)}`);
  }
}

Discogs MCP Server