get_library_items

Instructions

Implementation Reference

• src/plex/tools.ts:75-119 (handler)

  The PlexTools.getLibraryItems() method - the actual handler that fetches items from a Plex library section with pagination, type filtering, and sorting. It makes a request to /library/sections/{libraryKey}/all and returns a JSON response with items (ratingKey, title, originalTitle, year, type, guid, editionTitle), totalSize, offset, and limit.

  async getLibraryItems(
    libraryKey: string,
    type?: string,
    limit: number = DEFAULT_LIMITS.libraryItems,
    offset: number = 0,
    sort?: string
  ): Promise<MCPResponse> {
    validatePlexId(libraryKey, "libraryKey");
  
    const safeLimit = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : DEFAULT_LIMITS.libraryItems;
    const safeOffset = Number.isFinite(offset) && offset >= 0 ? Math.floor(offset) : 0;
    const params: Record<string, string | number> = {
      "X-Plex-Container-Start": safeOffset,
      "X-Plex-Container-Size": safeLimit,
    };
  
    if (type) {
      params.type = this.client.getPlexTypeId(type);
    }
    if (sort) {
      params.sort = sort;
    }
  
    const data = await this.client.makeRequest(`/library/sections/${libraryKey}/all`, params);
    const container = data as {
      MediaContainer?: { Metadata?: Record<string, unknown>[]; totalSize?: number };
    };
    const items = container.MediaContainer?.Metadata || [];
  
    return jsonResponse({
      libraryKey,
      offset: safeOffset,
      limit: safeLimit,
      totalSize: container.MediaContainer?.totalSize,
      items: items.map((item) => ({
        ratingKey: item.ratingKey,
        title: item.title,
        originalTitle: item.originalTitle,
        year: item.year,
        type: item.type,
        guid: item.guid,
        editionTitle: item.editionTitle,
      })),
    });
  }

• src/plex/tool-schemas.ts:15-33 (schema)

  The GET_LIBRARY_ITEMS_SCHEMA object defining the tool name ('get_library_items'), description, and input schema with properties: libraryKey (required string), type (enum: movie/show/episode/artist/album/track), limit (number, default 1000), offset (number, default 0), and sort (string).

  const GET_LIBRARY_ITEMS_SCHEMA = {
    name: "get_library_items",
    description: "List items in a library with pagination (useful for large libraries)",
    inputSchema: {
      type: "object" as const,
      properties: {
        libraryKey: { type: "string", description: "Library section key" },
        type: {
          type: "string",
          description: "Media type (movie, show, episode, artist, album, track)",
          enum: ["movie", "show", "episode", "artist", "album", "track"],
        },
        limit: { type: "number", description: "Number of items to return (default: 1000)", default: 1000 },
        offset: { type: "number", description: "Zero-based offset for pagination (default: 0)", default: 0 },
        sort: { type: "string", description: "Sort order (optional, e.g., titleSort:asc)" },
      },
      required: ["libraryKey"],
    },
  };

• src/plex/tool-registry.ts:47-55 (registration)

  The tool registration in createPlexToolRegistry(), where 'get_library_items' is registered with a handler that calls tools.getLibraryItems() with extracted args (libraryKey, type, limit with default, offset with default, sort).

  registry.register("get_library_items", (args) =>
    tools.getLibraryItems(
      args.libraryKey as string,
      args.type as string | undefined,
      (args.limit as number) || DEFAULT_LIMITS.libraryItems,
      (args.offset as number) || 0,
      args.sort as string | undefined
    )
  );

• src/plex/tool-schemas.ts:445-459 (registration)

  The PLEX_CORE_TOOL_SCHEMAS array that exports GET_LIBRARY_ITEMS_SCHEMA along with other tool schemas for use by MCP servers.

  export const PLEX_CORE_TOOL_SCHEMAS = [
    GET_LIBRARIES_SCHEMA,
    GET_LIBRARY_ITEMS_SCHEMA,
    EXPORT_LIBRARY_SCHEMA,
    SEARCH_MEDIA_SCHEMA,
    GET_RECENTLY_ADDED_SCHEMA,
    GET_ON_DECK_SCHEMA,
    GET_MEDIA_DETAILS_SCHEMA,
    GET_EDITABLE_FIELDS_SCHEMA,
    GET_PLAYLIST_ITEMS_SCHEMA,
    GET_PLAYLISTS_SCHEMA,
    GET_WATCHLIST_SCHEMA,
    GET_RECENTLY_WATCHED_SCHEMA,
    GET_WATCH_HISTORY_SCHEMA,
  ];