search_items
Search Internet Archive items using advanced filters for media type, collection, fields, sorting, and pagination to find specific archived content.
Instructions
Search Internet Archive items using Advanced Search (archive.org). Supports basic query, optional mediatype/collection filters, fields, sort, rows, and page.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| collection | No | ||
| fields | No | ||
| mediatype | No | ||
| page | No | ||
| query | Yes | ||
| rows | No | ||
| sort | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- wayback_mcp/server.py:194-246 (handler)The main handler function for the 'search_items' tool. It constructs a search query for archive.org's advanced search API, applies filters for mediatype and collection, sets default fields and sorting, fetches JSON results, and returns structured response with numFound and docs.
async def search_items( query: str, mediatype: Optional[str] = None, collection: Optional[str] = None, fields: Optional[List[str]] = None, sort: Optional[List[str]] = None, rows: int = 50, page: int = 1, ) -> Dict[str, Any]: """ Search archive.org items. Returns total, page info, and docs. - query: Lucene-like search string - mediatype: optional filter (e.g., texts, movies, audio, software, image) - collection: optional collection filter (e.g., web) - fields: list of field names to include (defaults to common ones) - sort: list like ["downloads desc", "publicdate desc"] """ q = query.strip() if query else "*:*" if mediatype: q += f" AND mediatype:{mediatype}" if collection: q += f" AND collection:{collection}" default_fields = [ "identifier", "title", "mediatype", "publicdate", "downloads", ] fl = fields if fields else default_fields default_sort = ["downloads desc"] srt = sort if sort else default_sort params: Dict[str, Any] = { "q": q, "fl[]": fl, "sort[]": srt, "rows": rows, "page": page, "output": "json", } data = await _fetch_json(ADVANCED_SEARCH_ENDPOINT, params) response = data.get("response", {}) if isinstance(data, dict) else {} return { "q": q, "rows": rows, "page": page, "numFound": response.get("numFound", 0), "docs": response.get("docs", []), } - wayback_mcp/server.py:187-193 (registration)Registers the 'search_items' tool with the FastMCP app using the @app.tool decorator, specifying the name and description.
@app.tool( name="search_items", description=( "Search Internet Archive items using Advanced Search (archive.org). " "Supports basic query, optional mediatype/collection filters, fields, sort, rows, and page." ), )