@cyanheads/zenodo-mcp-server 0.1.1

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

@@ -0,0 +1,268 @@
+/**
+ * @fileoverview zenodo_list_versions — lists a Zenodo deposit's version series,
+ * newest first. Accepts every identifier form zenodo_get_record accepts; a miss
+ * (unknown id, deleted record, restricted metadata, DOI not on Zenodo) is a result.
+ * @module mcp-server/tools/definitions/list-versions
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { parseRecordRef } from '../../../services/zenodo/identifiers.js';
+import { getZenodoService } from '../../../services/zenodo/zenodo-service.js';
+import { notOnZenodoMiss, recordMiss, TombstoneSchema } from '../record-miss.js';
+import { inline, quoteBlock } from '../render.js';
+/** Zenodo answers HTTP 400 when page × size passes this window. */
+const RESULT_WINDOW = 10_000;
+export const listVersions = tool('zenodo_list_versions', {
+    title: 'List Zenodo record versions',
+    description: "List every version of a Zenodo deposit's version series, newest first, with each version's record id, DOI, version label, publication date, file totals, and usage counts. Accepts any identifier zenodo_get_record accepts; a concept DOI and any single version's DOI list the same series. Use it to find the version a paper cited or the current release. A miss (an unknown id, a deleted record with its removal tombstone, restricted metadata, or a DOI not registered on Zenodo) returns found: false with guidance instead of an error.",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        id: z
+            .string()
+            .trim()
+            .min(1)
+            .max(500)
+            .describe('Any version or concept identifier of the deposit: a record id (22705923), a Zenodo DOI (10.5281/zenodo.22705923) or concept DOI (10.5281/zenodo.591564), another DOI registered to a Zenodo record, or a zenodo.org/records or doi.org URL.'),
+        page: z
+            .number()
+            .int()
+            .min(1)
+            .default(1)
+            .describe('Result page, starting at 1. page × size may not exceed 10,000.'),
+        size: z.number().int().min(1).max(25).default(25).describe('Versions per page (1–25).'),
+    }),
+    output: z.object({
+        found: z.boolean().describe('True when the version series resolved.'),
+        input_kind: z
+            .enum(['record_id', 'zenodo_doi', 'external_doi', 'url'])
+            .describe('How id was parsed: record_id (digits), zenodo_doi (10.5281/zenodo.N or zenodo.N), external_doi (another DOI), or url (a zenodo.org or doi.org link).'),
+        miss_kind: z
+            .enum(['not_found', 'deleted', 'restricted', 'not_on_zenodo'])
+            .optional()
+            .describe('Why nothing resolved. Present when not found.'),
+        guidance: z.string().optional().describe('What to do next. Present when not found.'),
+        tombstone: TombstoneSchema.optional().describe('Removal tombstone. Present when miss_kind is deleted.'),
+        concept_recid: z
+            .string()
+            .optional()
+            .describe('Concept record id naming the whole series; absent when not found or on a page past the end.'),
+        concept_doi: z
+            .string()
+            .optional()
+            .describe('Concept DOI of the series, when minted; absent when not found or on a page past the end.'),
+        total_versions: z
+            .number()
+            .optional()
+            .describe('Number of versions in the series. Present when found.'),
+        latest_recid: z
+            .string()
+            .optional()
+            .describe('Record id of the newest version. Present when found, unless Zenodo cannot name it for a page past the end.'),
+        page: z.number().describe('Page returned.'),
+        size: z.number().describe('Page size applied.'),
+        has_more: z.boolean().describe('True when another page of versions follows.'),
+        next_page: z.number().optional().describe('The next page number, when has_more.'),
+        versions: z
+            .array(z
+            .object({
+            recid: z.string().describe('Record id of this version — feeds zenodo_get_record id.'),
+            doi: z.string().optional().describe('DOI of this version; absent on some old records.'),
+            version: z
+                .string()
+                .optional()
+                .describe('Version label as deposited; absent when the depositor set none.'),
+            title: z.string().describe('Title of this version.'),
+            publication_date: z
+                .string()
+                .optional()
+                .describe('Publication date (EDTF as given); absent when not recorded.'),
+            index: z
+                .number()
+                .optional()
+                .describe('Position in the series (1 = first version); absent if Zenodo omits version data.'),
+            is_latest: z
+                .boolean()
+                .optional()
+                .describe('True for the newest version; absent if Zenodo omits version data.'),
+            file_count: z
+                .number()
+                .optional()
+                .describe('Number of files; absent when files are restricted or embargoed.'),
+            total_bytes: z
+                .number()
+                .optional()
+                .describe('Total file size in bytes; absent when files are restricted or embargoed.'),
+            views: z
+                .number()
+                .optional()
+                .describe('Unique views of this version; absent when not reported.'),
+            downloads: z
+                .number()
+                .optional()
+                .describe('Unique downloads of this version; absent when not reported.'),
+        })
+            .describe('One version.'))
+            .describe('Versions on this page, newest first; empty when not found.'),
+    }),
+    enrichment: {
+        truncated: z.boolean().describe('True when more versions follow this page.'),
+        shown: z.number().describe('Versions returned on this page.'),
+        cap: z.number().describe('Page size applied.'),
+        totalCount: z.number().describe('Number of versions in the series.'),
+        notice: z.string().optional().describe('Guidance on paging or a page past the end.'),
+    },
+    errors: [
+        {
+            reason: 'invalid_identifier',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'id matches no accepted form, or is a GitHub-badge latestdoi id or a non-zenodo.org host',
+            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.',
+        },
+        {
+            reason: 'result_window_exceeded',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'page × size exceeds 10,000',
+            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).',
+        },
+        {
+            reason: 'record_unavailable',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'Zenodo could not serve this record or its versions page: HTTP 500 after one retry, HTTP 500 while resolving a non-Zenodo DOI, or no complete record response within the time budget (its gateway cuts off near 30 s, which deposits with about 10,000 or more files hit)',
+            thrownBy: 'service',
+            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.',
+        },
+        {
+            reason: 'upstream_timeout',
+            code: JsonRpcErrorCode.Timeout,
+            when: 'The versions page got no complete response within its time budget',
+            retryable: false,
+            thrownBy: 'service',
+            recovery: 'Call zenodo_list_versions again with a smaller size (5); this series holds large file manifests.',
+        },
+        {
+            reason: 'rate_limited',
+            code: JsonRpcErrorCode.RateLimited,
+            when: "Zenodo answered HTTP 429, or this server's shared Zenodo request budget is spent for the current window",
+            retryable: true,
+            thrownBy: 'service',
+            recovery: 'Wait for the retryAfter seconds in the error data, then call zenodo_list_versions again with the same arguments.',
+        },
+    ],
+    async handler(input, ctx) {
+        ctx.enrich({ truncated: false, shown: 0, cap: input.size, totalCount: 0 });
+        if (input.page * input.size > RESULT_WINDOW) {
+            throw ctx.fail('result_window_exceeded', `page ${input.page} × size ${input.size} is past the first ${RESULT_WINDOW.toLocaleString('en-US')} versions Zenodo pages through.`, ctx.recoveryFor('result_window_exceeded'));
+        }
+        const ref = parseRecordRef(input.id);
+        if (ref.kind === 'invalid') {
+            throw ctx.fail('invalid_identifier', ref.message, ctx.recoveryFor('invalid_identifier'));
+        }
+        const service = getZenodoService();
+        const inputKind = ref.inputKind;
+        const miss = { found: false, input_kind: inputKind, page: input.page, size: input.size };
+        let recid;
+        if (ref.kind === 'external_doi') {
+            const resolution = await service.resolveDoi(ref.doi, ref.strippedDoi, ctx);
+            if (resolution.status === 'not_on_zenodo') {
+                return {
+                    ...miss,
+                    ...notOnZenodoMiss(ref.strippedDoi ?? ref.doi),
+                    has_more: false,
+                    versions: [],
+                };
+            }
+            recid = resolution.record.recid;
+        }
+        else {
+            recid = ref.recid;
+        }
+        let lookup = await service.listVersions(recid, input.page, input.size, ctx);
+        if (lookup.status === 'not_found' || lookup.total === 0) {
+            // A concept id 404s on /versions and a deleted recid answers 200 with no hits; the record GET classifies every miss.
+            const record = await service.getRecord(recid, ctx);
+            if (record.status !== 'found') {
+                return { ...miss, ...recordMiss(recid, record), has_more: false, versions: [] };
+            }
+            if (record.record.recid !== recid) {
+                recid = record.record.recid;
+                lookup = await service.listVersions(recid, input.page, input.size, ctx);
+            }
+            if (lookup.status === 'not_found')
+                lookup = { status: 'ok', total: 0, hits: [] };
+            lookup = {
+                ...lookup,
+                ...(lookup.concept_recid || !record.record.concept_recid
+                    ? {}
+                    : { concept_recid: record.record.concept_recid }),
+                ...(lookup.concept_doi || !record.record.concept_doi
+                    ? {}
+                    : { concept_doi: record.record.concept_doi }),
+            };
+        }
+        const { hits, total } = lookup;
+        const latestRecid = hits.find((h) => h.is_latest)?.recid ??
+            (input.page === 1 ? hits[0]?.recid : await service.latestRecid(recid, ctx));
+        const hasMore = input.page * input.size < total;
+        ctx.enrich({ shown: hits.length });
+        ctx.enrich.total(total);
+        if (hasMore) {
+            ctx.enrich.truncated({
+                shown: hits.length,
+                cap: input.size,
+                guidance: `Showing ${hits.length} of ${total} versions; call again with page ${input.page + 1}.`,
+            });
+        }
+        else if (total > 0 && hits.length === 0) {
+            ctx.enrich.notice(`Page ${input.page} is past the last page (${Math.max(1, Math.ceil(total / input.size))}).`);
+        }
+        return {
+            found: true,
+            input_kind: inputKind,
+            ...(lookup.concept_recid ? { concept_recid: lookup.concept_recid } : {}),
+            ...(lookup.concept_doi ? { concept_doi: lookup.concept_doi } : {}),
+            total_versions: total,
+            ...(latestRecid ? { latest_recid: latestRecid } : {}),
+            page: input.page,
+            size: input.size,
+            has_more: hasMore,
+            ...(hasMore ? { next_page: input.page + 1 } : {}),
+            versions: hits,
+        };
+    },
+    format: (result) => {
+        const lines = [`**Found:** ${result.found} | **Input kind:** ${result.input_kind}`];
+        if (result.miss_kind)
+            lines.push(`**Miss kind:** ${result.miss_kind}`);
+        if (result.guidance)
+            lines.push(`**Guidance:** ${inline(result.guidance)}`);
+        const t = result.tombstone;
+        if (t) {
+            lines.push(`**Tombstone:** removed ${inline(t.removal_date ?? 'on an unrecorded date')}; reason: ${t.removal_reason ? inline(t.removal_reason) : 'not given'}`);
+            if (t.note)
+                lines.push(quoteBlock(t.note, 'Removal note (untrusted):'));
+            if (t.citation_text)
+                lines.push(quoteBlock(t.citation_text, 'Tombstone citation (untrusted):'));
+        }
+        const series = [
+            result.concept_recid ? `**Concept record:** ${result.concept_recid}` : undefined,
+            result.concept_doi ? `**Concept DOI:** ${inline(result.concept_doi)}` : undefined,
+            result.total_versions !== undefined ? `**Versions:** ${result.total_versions}` : undefined,
+            result.latest_recid ? `**Latest record:** ${result.latest_recid}` : undefined,
+        ].filter(Boolean);
+        if (series.length)
+            lines.push(series.join(' | '));
+        lines.push(`**Page:** ${result.page} | **Size:** ${result.size} | **Has more:** ${result.has_more}${result.next_page !== undefined ? ` | **Next page:** ${result.next_page}` : ''}`);
+        for (const v of result.versions) {
+            lines.push('', `### ${v.version ? `${inline(v.version)} — ` : ''}record ${v.recid}${v.is_latest ? ' (latest)' : ''}`, `**Title:** ${inline(v.title)}`, [
+                v.doi ? `**DOI:** ${inline(v.doi)}` : undefined,
+                v.publication_date ? `**Published:** ${inline(v.publication_date)}` : undefined,
+                v.index !== undefined ? `**Index:** ${v.index}` : undefined,
+                v.is_latest !== undefined ? `**Latest:** ${v.is_latest}` : undefined,
+            ]
+                .filter(Boolean)
+                .join(' | '), `**Files:** ${v.file_count ?? 'not disclosed'} (${v.total_bytes ?? 'not disclosed'} bytes) | **Views:** ${v.views ?? 'not available'} | **Downloads:** ${v.downloads ?? 'not available'}`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=list-versions.tool.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list-versions.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/list-versions.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/lookup-vocabulary.tool.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview zenodo_lookup_vocabulary — resolves community, funder, award,
+ * license, and resource-type names to the ids zenodo_search_records filters on.
+ * The routing target for every unknown-value and zero-hit path.
+ * @module mcp-server/tools/definitions/lookup-vocabulary
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const lookupVocabulary: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    vocabulary: z.ZodPreprocess<z.ZodEnum<{
+        awards: "awards";
+        communities: "communities";
+        funders: "funders";
+        licenses: "licenses";
+        resource_types: "resource_types";
+    }>, unknown>;
+    query: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    funder: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    page: z.ZodDefault<z.ZodNumber>;
+    size: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    vocabulary: z.ZodEnum<{
+        awards: "awards";
+        communities: "communities";
+        funders: "funders";
+        licenses: "licenses";
+        resource_types: "resource_types";
+    }>;
+    query: z.ZodOptional<z.ZodString>;
+    total: z.ZodNumber;
+    page: z.ZodNumber;
+    size: z.ZodNumber;
+    has_more: z.ZodBoolean;
+    next_page: z.ZodOptional<z.ZodNumber>;
+    entries: z.ZodArray<z.ZodObject<{
+        filter_param: z.ZodEnum<{
+            award: "award";
+            community: "community";
+            funder: "funder";
+            license: "license";
+            resource_type: "resource_type";
+        }>;
+        filter_value: z.ZodString;
+        label: z.ZodString;
+        slug: z.ZodOptional<z.ZodString>;
+        uuid: z.ZodOptional<z.ZodString>;
+        community_type: z.ZodOptional<z.ZodString>;
+        website: z.ZodOptional<z.ZodString>;
+        organizations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ror_id: z.ZodOptional<z.ZodString>;
+        funder_doi: z.ZodOptional<z.ZodString>;
+        acronym: z.ZodOptional<z.ZodString>;
+        country: z.ZodOptional<z.ZodString>;
+        country_name: z.ZodOptional<z.ZodString>;
+        number: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        program: z.ZodOptional<z.ZodString>;
+        funder_id: z.ZodOptional<z.ZodString>;
+        funder_name: z.ZodOptional<z.ZodString>;
+        award_doi: z.ZodOptional<z.ZodString>;
+        award_url: z.ZodOptional<z.ZodString>;
+        start_date: z.ZodOptional<z.ZodString>;
+        end_date: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        osi_approved: z.ZodOptional<z.ZodBoolean>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        parent_type: z.ZodOptional<z.ZodString>;
+        search_value: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "funder_only_for_awards";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "funder is set with a vocabulary other than awards";
+    readonly recovery: "Call zenodo_lookup_vocabulary again without funder, or set vocabulary to awards to scope grants by funder.";
+}, {
+    readonly reason: "unknown_funder";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "funder (awards) resolves to no Zenodo funder";
+    readonly recovery: "Resolve the funder first with zenodo_lookup_vocabulary (vocabulary: funders) and pass its ROR id as funder.";
+}, {
+    readonly reason: "result_window_exceeded";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "page × size exceeds 10,000";
+    readonly recovery: "Narrow the query and call zenodo_lookup_vocabulary again instead of paging past 10,000 entries.";
+}, {
+    readonly reason: "rate_limited";
+    readonly code: 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_lookup_vocabulary again with the same arguments.";
+}], {
+    readonly truncated: z.ZodBoolean;
+    readonly shown: z.ZodNumber;
+    readonly cap: z.ZodNumber;
+    readonly totalCount: z.ZodNumber;
+    readonly notice: z.ZodOptional<z.ZodString>;
+}>;
+//# sourceMappingURL=lookup-vocabulary.tool.d.ts.map

package/dist/mcp-server/tools/definitions/lookup-vocabulary.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup-vocabulary.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/lookup-vocabulary.tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAmJjE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsO3B,CAAC"}