@cyanheads/zenodo-mcp-server 0.1.2 → 0.1.3

package/dist/mcp-server/tools/definitions/index.d.ts

@@ -11,6 +11,283 @@ import { searchRecords } from './search-records.tool.js';
 export { getRecord, listFiles, listVersions, lookupVocabulary, readFile, searchRecords };
 /** All tool definitions, in registration order. */
 export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+    id: import("zod").ZodString;
+    citation_style: import("zod").ZodPreprocess<import("zod").ZodOptional<import("zod").ZodEnum<{
+        apa: "apa";
+        bibtex: "bibtex";
+        "chicago-author-date": "chicago-author-date";
+        "csl-json": "csl-json";
+        "harvard-cite-them-right": "harvard-cite-them-right";
+        ieee: "ieee";
+        "modern-language-association": "modern-language-association";
+        nature: "nature";
+    }>>, unknown>;
+    cursor: import("zod").ZodPreprocess<import("zod").ZodOptional<import("zod").ZodString>, unknown>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    found: import("zod").ZodBoolean;
+    input_kind: import("zod").ZodEnum<{
+        external_doi: "external_doi";
+        record_id: "record_id";
+        url: "url";
+        zenodo_doi: "zenodo_doi";
+    }>;
+    resolved_from: import("zod").ZodOptional<import("zod").ZodEnum<{
+        concept_to_latest: "concept_to_latest";
+        external_doi: "external_doi";
+        version: "version";
+    }>>;
+    miss_kind: import("zod").ZodOptional<import("zod").ZodEnum<{
+        deleted: "deleted";
+        not_found: "not_found";
+        not_on_zenodo: "not_on_zenodo";
+        restricted: "restricted";
+    }>>;
+    guidance: import("zod").ZodOptional<import("zod").ZodString>;
+    tombstone: import("zod").ZodOptional<import("zod").ZodObject<{
+        removal_date: import("zod").ZodOptional<import("zod").ZodString>;
+        removal_reason: import("zod").ZodOptional<import("zod").ZodString>;
+        note: import("zod").ZodOptional<import("zod").ZodString>;
+        citation_text: import("zod").ZodOptional<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>>;
+    record: import("zod").ZodOptional<import("zod").ZodObject<{
+        recid: import("zod").ZodString;
+        concept_recid: import("zod").ZodOptional<import("zod").ZodString>;
+        doi: import("zod").ZodOptional<import("zod").ZodString>;
+        doi_provider: import("zod").ZodOptional<import("zod").ZodString>;
+        concept_doi: import("zod").ZodOptional<import("zod").ZodString>;
+        oai_id: import("zod").ZodOptional<import("zod").ZodString>;
+        title: import("zod").ZodString;
+        publication_date: import("zod").ZodOptional<import("zod").ZodString>;
+        version: import("zod").ZodOptional<import("zod").ZodString>;
+        publisher: import("zod").ZodOptional<import("zod").ZodString>;
+        resource_type: import("zod").ZodOptional<import("zod").ZodObject<{
+            id: import("zod").ZodString;
+            title: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>>;
+        description: import("zod").ZodOptional<import("zod").ZodString>;
+        description_truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        description_length: import("zod").ZodOptional<import("zod").ZodNumber>;
+        additional_descriptions: import("zod").ZodArray<import("zod").ZodObject<{
+            type: import("zod").ZodOptional<import("zod").ZodString>;
+            text: import("zod").ZodString;
+            length: import("zod").ZodNumber;
+            truncated: import("zod").ZodBoolean;
+        }, import("zod/v4/core").$strip>>;
+        additional_description_count: import("zod").ZodNumber;
+        creators: import("zod").ZodArray<import("zod").ZodObject<{
+            name: import("zod").ZodString;
+            type: import("zod").ZodOptional<import("zod").ZodString>;
+            orcid: import("zod").ZodOptional<import("zod").ZodString>;
+            role: import("zod").ZodOptional<import("zod").ZodString>;
+            affiliations: import("zod").ZodArray<import("zod").ZodObject<{
+                name: import("zod").ZodOptional<import("zod").ZodString>;
+                ror: import("zod").ZodOptional<import("zod").ZodString>;
+            }, import("zod/v4/core").$strip>>;
+        }, import("zod/v4/core").$strip>>;
+        creator_count: import("zod").ZodNumber;
+        contributors: import("zod").ZodArray<import("zod").ZodObject<{
+            name: import("zod").ZodString;
+            type: import("zod").ZodOptional<import("zod").ZodString>;
+            orcid: import("zod").ZodOptional<import("zod").ZodString>;
+            role: import("zod").ZodOptional<import("zod").ZodString>;
+            affiliations: import("zod").ZodArray<import("zod").ZodObject<{
+                name: import("zod").ZodOptional<import("zod").ZodString>;
+                ror: import("zod").ZodOptional<import("zod").ZodString>;
+            }, import("zod/v4/core").$strip>>;
+        }, import("zod/v4/core").$strip>>;
+        contributor_count: import("zod").ZodNumber;
+        keywords: import("zod").ZodArray<import("zod").ZodString>;
+        keyword_count: import("zod").ZodNumber;
+        rights: import("zod").ZodArray<import("zod").ZodObject<{
+            id: import("zod").ZodOptional<import("zod").ZodString>;
+            title: import("zod").ZodString;
+            url: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>>;
+        access: import("zod").ZodObject<{
+            status: import("zod").ZodString;
+            record: import("zod").ZodOptional<import("zod").ZodString>;
+            files: import("zod").ZodOptional<import("zod").ZodString>;
+            embargo_active: import("zod").ZodBoolean;
+            embargo_until: import("zod").ZodOptional<import("zod").ZodString>;
+            embargo_reason: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>;
+        funding: import("zod").ZodArray<import("zod").ZodObject<{
+            funder_id: import("zod").ZodOptional<import("zod").ZodString>;
+            funder_name: import("zod").ZodOptional<import("zod").ZodString>;
+            award_id: import("zod").ZodOptional<import("zod").ZodString>;
+            award_number: import("zod").ZodOptional<import("zod").ZodString>;
+            award_acronym: import("zod").ZodOptional<import("zod").ZodString>;
+            award_title: import("zod").ZodOptional<import("zod").ZodString>;
+            award_program: import("zod").ZodOptional<import("zod").ZodString>;
+            award_doi: import("zod").ZodOptional<import("zod").ZodString>;
+            award_url: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>>;
+        funding_count: import("zod").ZodNumber;
+        related_identifiers: import("zod").ZodArray<import("zod").ZodObject<{
+            identifier: import("zod").ZodString;
+            scheme: import("zod").ZodOptional<import("zod").ZodString>;
+            relation: import("zod").ZodOptional<import("zod").ZodString>;
+            resource_type: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>>;
+        related_identifier_count: import("zod").ZodNumber;
+        code_repository: import("zod").ZodOptional<import("zod").ZodString>;
+        communities: import("zod").ZodArray<import("zod").ZodObject<{
+            slug: import("zod").ZodString;
+            title: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>>;
+        community_count: import("zod").ZodNumber;
+        versions: import("zod").ZodObject<{
+            index: import("zod").ZodOptional<import("zod").ZodNumber>;
+            is_latest: import("zod").ZodOptional<import("zod").ZodBoolean>;
+            latest_recid: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>;
+        stats: import("zod").ZodOptional<import("zod").ZodObject<{
+            this_version: import("zod").ZodObject<{
+                views: import("zod").ZodOptional<import("zod").ZodNumber>;
+                downloads: import("zod").ZodOptional<import("zod").ZodNumber>;
+            }, import("zod/v4/core").$strip>;
+            all_versions: import("zod").ZodObject<{
+                views: import("zod").ZodOptional<import("zod").ZodNumber>;
+                downloads: import("zod").ZodOptional<import("zod").ZodNumber>;
+            }, import("zod/v4/core").$strip>;
+        }, import("zod/v4/core").$strip>>;
+        files: import("zod").ZodObject<{
+            enabled: import("zod").ZodBoolean;
+            count: import("zod").ZodOptional<import("zod").ZodNumber>;
+            total_bytes: import("zod").ZodOptional<import("zod").ZodNumber>;
+            shown: import("zod").ZodNumber;
+            entries: import("zod").ZodArray<import("zod").ZodObject<{
+                key: import("zod").ZodString;
+                size: import("zod").ZodOptional<import("zod").ZodNumber>;
+                mimetype: import("zod").ZodOptional<import("zod").ZodString>;
+                md5: import("zod").ZodOptional<import("zod").ZodString>;
+                download_url: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>>;
+        }, import("zod/v4/core").$strip>;
+        revision: import("zod").ZodOptional<import("zod").ZodNumber>;
+        zenodo_url: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+    window: import("zod").ZodOptional<import("zod").ZodObject<{
+        field: import("zod").ZodEnum<{
+            additional_descriptions: "additional_descriptions";
+            communities: "communities";
+            contributors: "contributors";
+            creators: "creators";
+            description: "description";
+            funding: "funding";
+            keywords: "keywords";
+            related_identifiers: "related_identifiers";
+        }>;
+        index: import("zod").ZodOptional<import("zod").ZodNumber>;
+        unit: import("zod").ZodEnum<{
+            characters: "characters";
+            entries: "entries";
+        }>;
+        offset: import("zod").ZodNumber;
+        shown: import("zod").ZodNumber;
+        total: import("zod").ZodNumber;
+        text: import("zod").ZodOptional<import("zod").ZodString>;
+        additional_descriptions: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+            type: import("zod").ZodOptional<import("zod").ZodString>;
+            text: import("zod").ZodString;
+            length: import("zod").ZodNumber;
+            truncated: import("zod").ZodBoolean;
+        }, import("zod/v4/core").$strip>>>;
+        creators: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+            name: import("zod").ZodString;
+            type: import("zod").ZodOptional<import("zod").ZodString>;
+            orcid: import("zod").ZodOptional<import("zod").ZodString>;
+            role: import("zod").ZodOptional<import("zod").ZodString>;
+            affiliations: import("zod").ZodArray<import("zod").ZodObject<{
+                name: import("zod").ZodOptional<import("zod").ZodString>;
+                ror: import("zod").ZodOptional<import("zod").ZodString>;
+            }, import("zod/v4/core").$strip>>;
+        }, import("zod/v4/core").$strip>>>;
+        contributors: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+            name: import("zod").ZodString;
+            type: import("zod").ZodOptional<import("zod").ZodString>;
+            orcid: import("zod").ZodOptional<import("zod").ZodString>;
+            role: import("zod").ZodOptional<import("zod").ZodString>;
+            affiliations: import("zod").ZodArray<import("zod").ZodObject<{
+                name: import("zod").ZodOptional<import("zod").ZodString>;
+                ror: import("zod").ZodOptional<import("zod").ZodString>;
+            }, import("zod/v4/core").$strip>>;
+        }, import("zod/v4/core").$strip>>>;
+        keywords: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+        funding: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+            funder_id: import("zod").ZodOptional<import("zod").ZodString>;
+            funder_name: import("zod").ZodOptional<import("zod").ZodString>;
+            award_id: import("zod").ZodOptional<import("zod").ZodString>;
+            award_number: import("zod").ZodOptional<import("zod").ZodString>;
+            award_acronym: import("zod").ZodOptional<import("zod").ZodString>;
+            award_title: import("zod").ZodOptional<import("zod").ZodString>;
+            award_program: import("zod").ZodOptional<import("zod").ZodString>;
+            award_doi: import("zod").ZodOptional<import("zod").ZodString>;
+            award_url: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>>>;
+        related_identifiers: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+            identifier: import("zod").ZodString;
+            scheme: import("zod").ZodOptional<import("zod").ZodString>;
+            relation: import("zod").ZodOptional<import("zod").ZodString>;
+            resource_type: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>>>;
+        communities: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+            slug: import("zod").ZodString;
+            title: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>>>;
+    }, import("zod/v4/core").$strip>>;
+    continuations: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+        field: import("zod").ZodEnum<{
+            additional_descriptions: "additional_descriptions";
+            communities: "communities";
+            contributors: "contributors";
+            creators: "creators";
+            description: "description";
+            funding: "funding";
+            keywords: "keywords";
+            related_identifiers: "related_identifiers";
+        }>;
+        index: import("zod").ZodOptional<import("zod").ZodNumber>;
+        unit: import("zod").ZodEnum<{
+            characters: "characters";
+            entries: "entries";
+        }>;
+        shown: import("zod").ZodNumber;
+        total: import("zod").ZodNumber;
+        id: import("zod").ZodString;
+        cursor: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>>;
+    citation: import("zod").ZodOptional<import("zod").ZodString>;
+    citation_style: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "invalid_identifier";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "id matches no accepted form, or is a GitHub-badge latestdoi id or a non-zenodo.org host";
+    readonly recovery: "Pass a Zenodo record id (22705923), a DOI (10.5281/zenodo.22705923), or a zenodo.org/records URL as id; for a title or keyword, use zenodo_search_records.";
+}, {
+    readonly reason: "invalid_cursor";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "cursor is not one this tool returned in continuations, belongs to another record, or the record was edited after the cursor was issued";
+    readonly recovery: "Pass the cursor with the record id the message names as id to continue that record; otherwise call zenodo_get_record with this id and no cursor for this record’s own continuations, and pass one of those cursors unchanged with the id it lists.";
+}, {
+    readonly reason: "record_unavailable";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "Zenodo could not serve this record: HTTP 500 after one retry, HTTP 500 while resolving a non-Zenodo DOI, or no complete response within the time budget (its gateway cuts off near 30 s, which deposits with about 10,000 or more files hit)";
+    readonly thrownBy: "service";
+    readonly recovery: "Look the record up with zenodo_search_records using query doi:\"<its DOI>\" (all_versions true) or its title; withdrawn legacy records and deposits with more than about 10,000 files fail on the record endpoint, and if a keyword search also fails, Zenodo is degraded.";
+}, {
+    readonly reason: "rate_limited";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
+    readonly when: "Zenodo answered HTTP 429, or this server's shared Zenodo request budget is spent for the current window";
+    readonly retryable: true;
+    readonly thrownBy: "service";
+    readonly recovery: "Wait for the retryAfter seconds in the error data, then call zenodo_get_record again with the same arguments.";
+}], {
+    readonly truncated: import("zod").ZodBoolean;
+    readonly shown: import("zod").ZodNumber;
+    readonly cap: import("zod").ZodNumber;
+    readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
+}> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     id: import("zod").ZodString;
     page: import("zod").ZodDefault<import("zod").ZodNumber>;
     size: import("zod").ZodDefault<import("zod").ZodNumber>;
@@ -64,7 +341,7 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
 }, {
     readonly reason: "result_window_exceeded";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
-    readonly when: "page × size exceeds 10,000";
+    readonly when: "The page starts past the first 10,000 versions: (page − 1) × size is 10,000 or more, counting a size above 25 as 25";
     readonly recovery: "Zenodo pages only the first 10,000 versions of a series, and no series comes near that; call zenodo_list_versions with page 1 (total_versions and has_more show how far the series goes).";
 }, {
     readonly reason: "record_unavailable";
@@ -202,8 +479,8 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
 }, {
     readonly reason: "query_syntax";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
-    readonly when: "The query has an unpaired unescaped / outside quotes";
-    readonly recovery: "Escape the slash as \\/ or wrap that term in double quotes, then call zenodo_search_records again.";
+    readonly when: "The query holds something Zenodo cannot run: a regular expression with no closing / (an unescaped / outside double quotes) or with a \" inside /…/ left open; a \" inside a word whose phrase never closes (with a filter other than community and all_versions set, only when the query still fails once that phrase is closed at its end) or closes past a bracket the query needs; a range bound ending in a backslash, as one holding an escaped space, ] or } does; an unescaped ! with nothing after it; or a boost, fuzziness, or proximity value it cannot convert. Or a filter other than community and all_versions is set and the query is not valid search syntax, which Zenodo would match as plain text with every filter dropped";
+    readonly recovery: "Fix the syntax the message names, then call zenodo_search_records again: double-quote or backslash-escape any / [ ] { } ~ ^ : or ! meant as plain text (\"[CMIP6]\", \\[CMIP6\\], 10.5281\\/zenodo.1, climate\\!) and any \" inside a regular expression or a word (12\\\" vinyl), write phrases in double quotes rather than single, drop a doubled or dangling operator (AND AND, or one with nothing after it inside parentheses, as in (climate AND)), give a field: prefix a value, close a range as [a TO b] and double-quote a bound that holds a space, ] or } ([a TO \"b]\"]), and give a boost or fuzziness one decimal number and a phrase proximity a whole number (^2, ~0.5, \"x y\"~2).";
 }, {
     readonly reason: "query_failed";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
@@ -236,7 +513,7 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
 }, {
     readonly reason: "result_window_exceeded";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
-    readonly when: "page × size exceeds 10,000";
+    readonly when: "The page starts past the first 10,000 matches: (page − 1) × size is 10,000 or more, counting a size above 25 as 25";
     readonly recovery: "Zenodo serves only the first 10,000 matches; add filters or a published_from/published_to range to zenodo_search_records instead of paging deeper.";
 }, {
     readonly reason: "rate_limited";
@@ -262,181 +539,6 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
     }>;
     readonly allVersions: import("zod").ZodBoolean;
     readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
-}> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
-    id: import("zod").ZodString;
-    citation_style: import("zod").ZodPreprocess<import("zod").ZodOptional<import("zod").ZodEnum<{
-        apa: "apa";
-        bibtex: "bibtex";
-        "chicago-author-date": "chicago-author-date";
-        "csl-json": "csl-json";
-        "harvard-cite-them-right": "harvard-cite-them-right";
-        ieee: "ieee";
-        "modern-language-association": "modern-language-association";
-        nature: "nature";
-    }>>, unknown>;
-}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
-    found: import("zod").ZodBoolean;
-    input_kind: import("zod").ZodEnum<{
-        external_doi: "external_doi";
-        record_id: "record_id";
-        url: "url";
-        zenodo_doi: "zenodo_doi";
-    }>;
-    resolved_from: import("zod").ZodOptional<import("zod").ZodEnum<{
-        concept_to_latest: "concept_to_latest";
-        external_doi: "external_doi";
-        version: "version";
-    }>>;
-    miss_kind: import("zod").ZodOptional<import("zod").ZodEnum<{
-        deleted: "deleted";
-        not_found: "not_found";
-        not_on_zenodo: "not_on_zenodo";
-        restricted: "restricted";
-    }>>;
-    guidance: import("zod").ZodOptional<import("zod").ZodString>;
-    tombstone: import("zod").ZodOptional<import("zod").ZodObject<{
-        removal_date: import("zod").ZodOptional<import("zod").ZodString>;
-        removal_reason: import("zod").ZodOptional<import("zod").ZodString>;
-        note: import("zod").ZodOptional<import("zod").ZodString>;
-        citation_text: import("zod").ZodOptional<import("zod").ZodString>;
-    }, import("zod/v4/core").$strip>>;
-    record: import("zod").ZodOptional<import("zod").ZodObject<{
-        recid: import("zod").ZodString;
-        concept_recid: import("zod").ZodOptional<import("zod").ZodString>;
-        doi: import("zod").ZodOptional<import("zod").ZodString>;
-        doi_provider: import("zod").ZodOptional<import("zod").ZodString>;
-        concept_doi: import("zod").ZodOptional<import("zod").ZodString>;
-        oai_id: import("zod").ZodOptional<import("zod").ZodString>;
-        title: import("zod").ZodString;
-        publication_date: import("zod").ZodOptional<import("zod").ZodString>;
-        version: import("zod").ZodOptional<import("zod").ZodString>;
-        publisher: import("zod").ZodOptional<import("zod").ZodString>;
-        resource_type: import("zod").ZodOptional<import("zod").ZodObject<{
-            id: import("zod").ZodString;
-            title: import("zod").ZodOptional<import("zod").ZodString>;
-        }, import("zod/v4/core").$strip>>;
-        description: import("zod").ZodOptional<import("zod").ZodString>;
-        description_truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
-        description_length: import("zod").ZodOptional<import("zod").ZodNumber>;
-        additional_descriptions: import("zod").ZodArray<import("zod").ZodObject<{
-            type: import("zod").ZodOptional<import("zod").ZodString>;
-            text: import("zod").ZodString;
-        }, import("zod/v4/core").$strip>>;
-        creators: import("zod").ZodArray<import("zod").ZodObject<{
-            name: import("zod").ZodString;
-            type: import("zod").ZodOptional<import("zod").ZodString>;
-            orcid: import("zod").ZodOptional<import("zod").ZodString>;
-            role: import("zod").ZodOptional<import("zod").ZodString>;
-            affiliations: import("zod").ZodArray<import("zod").ZodObject<{
-                name: import("zod").ZodOptional<import("zod").ZodString>;
-                ror: import("zod").ZodOptional<import("zod").ZodString>;
-            }, import("zod/v4/core").$strip>>;
-        }, import("zod/v4/core").$strip>>;
-        creator_count: import("zod").ZodNumber;
-        contributors: import("zod").ZodArray<import("zod").ZodObject<{
-            name: import("zod").ZodString;
-            type: import("zod").ZodOptional<import("zod").ZodString>;
-            orcid: import("zod").ZodOptional<import("zod").ZodString>;
-            role: import("zod").ZodOptional<import("zod").ZodString>;
-            affiliations: import("zod").ZodArray<import("zod").ZodObject<{
-                name: import("zod").ZodOptional<import("zod").ZodString>;
-                ror: import("zod").ZodOptional<import("zod").ZodString>;
-            }, import("zod/v4/core").$strip>>;
-        }, import("zod/v4/core").$strip>>;
-        contributor_count: import("zod").ZodNumber;
-        keywords: import("zod").ZodArray<import("zod").ZodString>;
-        rights: import("zod").ZodArray<import("zod").ZodObject<{
-            id: import("zod").ZodOptional<import("zod").ZodString>;
-            title: import("zod").ZodString;
-            url: import("zod").ZodOptional<import("zod").ZodString>;
-        }, import("zod/v4/core").$strip>>;
-        access: import("zod").ZodObject<{
-            status: import("zod").ZodString;
-            record: import("zod").ZodOptional<import("zod").ZodString>;
-            files: import("zod").ZodOptional<import("zod").ZodString>;
-            embargo_active: import("zod").ZodBoolean;
-            embargo_until: import("zod").ZodOptional<import("zod").ZodString>;
-            embargo_reason: import("zod").ZodOptional<import("zod").ZodString>;
-        }, import("zod/v4/core").$strip>;
-        funding: import("zod").ZodArray<import("zod").ZodObject<{
-            funder_id: import("zod").ZodOptional<import("zod").ZodString>;
-            funder_name: import("zod").ZodOptional<import("zod").ZodString>;
-            award_id: import("zod").ZodOptional<import("zod").ZodString>;
-            award_number: import("zod").ZodOptional<import("zod").ZodString>;
-            award_acronym: import("zod").ZodOptional<import("zod").ZodString>;
-            award_title: import("zod").ZodOptional<import("zod").ZodString>;
-            award_program: import("zod").ZodOptional<import("zod").ZodString>;
-            award_doi: import("zod").ZodOptional<import("zod").ZodString>;
-            award_url: import("zod").ZodOptional<import("zod").ZodString>;
-        }, import("zod/v4/core").$strip>>;
-        related_identifiers: import("zod").ZodArray<import("zod").ZodObject<{
-            identifier: import("zod").ZodString;
-            scheme: import("zod").ZodOptional<import("zod").ZodString>;
-            relation: import("zod").ZodOptional<import("zod").ZodString>;
-            resource_type: import("zod").ZodOptional<import("zod").ZodString>;
-        }, import("zod/v4/core").$strip>>;
-        related_identifier_count: import("zod").ZodNumber;
-        code_repository: import("zod").ZodOptional<import("zod").ZodString>;
-        communities: import("zod").ZodArray<import("zod").ZodObject<{
-            slug: import("zod").ZodString;
-            title: import("zod").ZodOptional<import("zod").ZodString>;
-        }, import("zod/v4/core").$strip>>;
-        versions: import("zod").ZodObject<{
-            index: import("zod").ZodOptional<import("zod").ZodNumber>;
-            is_latest: import("zod").ZodOptional<import("zod").ZodBoolean>;
-            latest_recid: import("zod").ZodOptional<import("zod").ZodString>;
-        }, import("zod/v4/core").$strip>;
-        stats: import("zod").ZodOptional<import("zod").ZodObject<{
-            this_version: import("zod").ZodObject<{
-                views: import("zod").ZodOptional<import("zod").ZodNumber>;
-                downloads: import("zod").ZodOptional<import("zod").ZodNumber>;
-            }, import("zod/v4/core").$strip>;
-            all_versions: import("zod").ZodObject<{
-                views: import("zod").ZodOptional<import("zod").ZodNumber>;
-                downloads: import("zod").ZodOptional<import("zod").ZodNumber>;
-            }, import("zod/v4/core").$strip>;
-        }, import("zod/v4/core").$strip>>;
-        files: import("zod").ZodObject<{
-            enabled: import("zod").ZodBoolean;
-            count: import("zod").ZodOptional<import("zod").ZodNumber>;
-            total_bytes: import("zod").ZodOptional<import("zod").ZodNumber>;
-            shown: import("zod").ZodNumber;
-            entries: import("zod").ZodArray<import("zod").ZodObject<{
-                key: import("zod").ZodString;
-                size: import("zod").ZodOptional<import("zod").ZodNumber>;
-                mimetype: import("zod").ZodOptional<import("zod").ZodString>;
-                md5: import("zod").ZodOptional<import("zod").ZodString>;
-                download_url: import("zod").ZodString;
-            }, import("zod/v4/core").$strip>>;
-        }, import("zod/v4/core").$strip>;
-        revision: import("zod").ZodOptional<import("zod").ZodNumber>;
-        zenodo_url: import("zod").ZodString;
-    }, import("zod/v4/core").$strip>>;
-    citation: import("zod").ZodOptional<import("zod").ZodString>;
-    citation_style: import("zod").ZodOptional<import("zod").ZodString>;
-}, import("zod/v4/core").$strip>, readonly [{
-    readonly reason: "invalid_identifier";
-    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
-    readonly when: "id matches no accepted form, or is a GitHub-badge latestdoi id or a non-zenodo.org host";
-    readonly recovery: "Pass a Zenodo record id (22705923), a DOI (10.5281/zenodo.22705923), or a zenodo.org/records URL as id; for a title or keyword, use zenodo_search_records.";
-}, {
-    readonly reason: "record_unavailable";
-    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
-    readonly when: "Zenodo could not serve this record: HTTP 500 after one retry, HTTP 500 while resolving a non-Zenodo DOI, or no complete response within the time budget (its gateway cuts off near 30 s, which deposits with about 10,000 or more files hit)";
-    readonly thrownBy: "service";
-    readonly recovery: "Look the record up with zenodo_search_records using query doi:\"<its DOI>\" (all_versions true) or its title; withdrawn legacy records and deposits with more than about 10,000 files fail on the record endpoint, and if a keyword search also fails, Zenodo is degraded.";
-}, {
-    readonly reason: "rate_limited";
-    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
-    readonly when: "Zenodo answered HTTP 429, or this server's shared Zenodo request budget is spent for the current window";
-    readonly retryable: true;
-    readonly thrownBy: "service";
-    readonly recovery: "Wait for the retryAfter seconds in the error data, then call zenodo_get_record again with the same arguments.";
-}], {
-    readonly truncated: import("zod").ZodBoolean;
-    readonly shown: import("zod").ZodNumber;
-    readonly cap: import("zod").ZodNumber;
-    readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
 }> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     id: import("zod").ZodString;
     archive_key: import("zod").ZodPreprocess<import("zod").ZodOptional<import("zod").ZodString>, unknown>;
@@ -650,6 +752,7 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
     }>;
     query: import("zod").ZodOptional<import("zod").ZodString>;
     total: import("zod").ZodNumber;
+    reachable: import("zod").ZodNumber;
     page: import("zod").ZodNumber;
     size: import("zod").ZodNumber;
     has_more: import("zod").ZodBoolean;
@@ -702,7 +805,7 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
 }, {
     readonly reason: "result_window_exceeded";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
-    readonly when: "page × size exceeds 10,000";
+    readonly when: "The page starts past the first 10,000 entries: (page − 1) × size is 10,000 or more, counting a size above 25 as 25";
     readonly recovery: "Narrow the query and call zenodo_lookup_vocabulary again instead of paging past 10,000 entries.";
 }, {
     readonly reason: "rate_limited";

package/dist/mcp-server/tools/definitions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,gBAAgB,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC;AAEzF,mDAAmD;AACnD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAO9B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,gBAAgB,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC;AAEzF,mDAAmD;AACnD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAO9B,CAAC"}

package/dist/mcp-server/tools/definitions/list-files.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-files.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/list-files.tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAsBjE,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6YpB,CAAC"}
+{"version":3,"file":"list-files.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/list-files.tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA0BjE,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkZpB,CAAC"}

package/dist/mcp-server/tools/definitions/list-files.tool.js

@@ -9,8 +9,11 @@ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { parseRecordRef } from '../../../services/zenodo/identifiers.js';
 import { isZip, previewMode } from '../../../services/zenodo/text-preview.js';
 import { getZenodoService } from '../../../services/zenodo/zenodo-service.js';
+import { applyCap } from '../paging.js';
 import { inline } from '../render.js';
 import { blankToUndefined } from '../schema-helpers.js';
+/** Entries per page: a larger `limit` is served at this many. */
+const LIMIT_CAP = 200;
 /** True when zenodo_read_file reads the file rather than refusing it unread. */
 const readsAsText = (key, mimetype) => previewMode(key, mimetype) !== 'binary';
 const PREVIEWABLE_DESCRIPTION = 'True when zenodo_read_file reads this as text: a text MIME type or extension, or an extensionless application/octet-stream file (LICENSE, Makefile) whose content is checked on read and returned only if it is UTF-8 text.';
@@ -38,7 +41,13 @@ export const listFiles = tool('zenodo_list_files', {
             .preprocess(blankToUndefined, z.string().max(200).optional())
             .describe('Case-insensitive substring filter on file keys (manifest) or member paths (archive), applied before paging.'),
         offset: z.number().int().min(0).default(0).describe('Entries to skip before this page.'),
-        limit: z.number().int().min(1).max(200).default(50).describe('Entries per page (1–200).'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(10_000)
+            .default(50)
+            .describe('Entries per page, at most 200 per call; larger values return 200.'),
     }),
     output: z.object({
         recid: z
@@ -58,7 +67,7 @@ export const listFiles = tool('zenodo_list_files', {
         files_enabled: z.boolean().describe('False for a metadata-only deposit.'),
         key_contains: z.string().optional().describe('The key filter applied, when set.'),
         offset: z.number().describe('Entries skipped before this page.'),
-        limit: z.number().describe('Page size applied.'),
+        limit: z.number().describe('Page size applied: limit, or 200 when limit asked for more.'),
         matched: z.number().describe('Entries matching the filter, before paging.'),
         has_more: z.boolean().describe('True when more matching entries follow this page.'),
         next_offset: z.number().optional().describe('Offset of the next page, when has_more.'),
@@ -122,12 +131,12 @@ export const listFiles = tool('zenodo_list_files', {
     enrichment: {
         truncated: z.boolean().describe('True when more matching entries follow this page.'),
         shown: z.number().describe('Entries returned on this page.'),
-        cap: z.number().describe('Page size applied.'),
+        cap: z.number().describe('Page size applied (at most 200).'),
         totalCount: z.number().describe('Entries matching the filter, before paging.'),
         notice: z
             .string()
             .optional()
-            .describe('File access notes, empty-filter guidance, listing caps, or paging guidance.'),
+            .describe('File access notes, empty-filter guidance, listing caps, the 200-per-call limit cap, or paging guidance.'),
     },
     errors: [
         {
@@ -184,7 +193,8 @@ export const listFiles = tool('zenodo_list_files', {
         },
     ],
     async handler(input, ctx) {
-        ctx.enrich({ truncated: false, shown: 0, cap: input.limit, totalCount: 0 });
+        const { applied: limit, capNote } = applyCap('limit', input.limit, LIMIT_CAP);
+        ctx.enrich({ truncated: false, shown: 0, cap: limit, totalCount: 0 });
         const ref = parseRecordRef(input.id);
         if (ref.kind === 'invalid') {
             throw ctx.fail('invalid_identifier', ref.message);
@@ -221,7 +231,7 @@ export const listFiles = tool('zenodo_list_files', {
             files_enabled: files.enabled,
             ...(input.key_contains ? { key_contains: input.key_contains } : {}),
             offset: input.offset,
-            limit: input.limit,
+            limit,
         };
         const needle = input.key_contains?.toLowerCase();
         if (files.enabled && access.files === 'restricted') {
@@ -245,15 +255,11 @@ export const listFiles = tool('zenodo_list_files', {
                     : `No ${noun} contain "${filter}"; call zenodo_list_files again without key_contains.`);
             }
             else if (page.matched > 0 && input.offset >= page.matched) {
-                notice.push(`Offset ${input.offset} is past the last of ${page.matched} ${noun}; call again with a lower offset.`);
+                notice.push(`Offset ${input.offset} is past the last of ${page.matched.toLocaleString('en-US')} ${noun}; call again with a lower offset.`);
             }
             if (page.hasMore) {
-                notice.push(`Showing ${page.slice.length} of ${page.matched}; call again with offset ${page.nextOffset}.`);
-                ctx.enrich.truncated({
-                    shown: page.slice.length,
-                    cap: input.limit,
-                    guidance: notice.join(' '),
-                });
+                notice.push(`Showing ${page.slice.length} of ${page.matched.toLocaleString('en-US')}${capNote ? ` (${capNote})` : ''}; call again with offset ${page.nextOffset}.`);
+                ctx.enrich.truncated({ shown: page.slice.length, cap: limit, guidance: notice.join(' ') });
             }
             else if (notice.length) {
                 ctx.enrich.notice(notice.join(' '));
@@ -270,7 +276,7 @@ export const listFiles = tool('zenodo_list_files', {
             const matching = needle
                 ? files.entries.filter((e) => e.key.toLowerCase().includes(needle))
                 : files.entries;
-            const page = pageOf(matching, input.offset, input.limit);
+            const page = pageOf(matching, input.offset, limit);
             const paging = finish(page, 'files');
             return {
                 ...common,
@@ -304,7 +310,7 @@ export const listFiles = tool('zenodo_list_files', {
         const matching = needle
             ? listing.members.filter((m) => m.path.toLowerCase().includes(needle))
             : listing.members;
-        const page = pageOf(matching, input.offset, input.limit);
+        const page = pageOf(matching, input.offset, limit);
         const paging = finish(page, 'members', listing.upstream_truncated);
         return {
             ...common,