@cyanheads/interpro-mcp-server 0.0.0-stage → 0.1.1

package/dist/services/interpro/interpro-service.js

@@ -0,0 +1,284 @@
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode, McpError, notFound, serviceUnavailable, timeout, validationError, } from '@cyanheads/mcp-ts-core/errors';
+import { createPacer, defaultIsTransient, httpErrorFromResponse, withRetry, } from '@cyanheads/mcp-ts-core/utils';
+import { interproHttpFetch, MAX_RESPONSE_BYTES } from './http-adapter.js';
+import { apiUrl } from './routing.js';
+import { isAccession, JsonObjectSchema, JsonValueSchema } from './schemas.js';
+const pacer = createPacer({
+    name: 'interpro',
+    minStartGapMs: 1000,
+    maxConcurrent: 1,
+    maxQueueDepth: 20,
+});
+/** Upstream fields of a 410 body that are echoed in the withdrawal error. */
+const WITHDRAWAL_FIELDS = new Set([
+    'accession',
+    'source_database',
+    'deletion_date',
+    'short_name',
+    'history',
+]);
+/**
+ * Single-line forms a withdrawal date or short name must match whole before the message names it;
+ * any other upstream value stays in error data only.
+ */
+const WITHDRAWAL_DATE = /^\d{4}-\d{2}-\d{2}(?:T[\d:.]+Z?)?$/;
+const SHORT_NAME = /^[A-Za-z0-9_.:+-]{1,100}$/;
+const RECORD_NOUNS = {
+    entry_not_found: 'entry',
+    clan_not_found: 'set',
+    protein_not_found: 'protein',
+};
+/** Name a record in a caller-facing message, e.g. `entry PF00870 in pfam`. */
+const describeRecord = ({ reason, accession, sourceDatabase }) => `${RECORD_NOUNS[reason]} ${accession} in ${sourceDatabase}`;
+/** InterPro service; inject only the network seam, retaining the real domain behavior. */
+export class InterproService {
+    fetch;
+    constructor(fetch = interproHttpFetch) {
+        this.fetch = fetch;
+    }
+    /** Start a 50-second call budget, once per handler invocation. */
+    begin(ctx) {
+        return { ctx, deadline: performance.now() + 50_000 };
+    }
+    /** Fetch, classify, parse and validate one fixed-origin operation within a shared call. */
+    async request(call, segments, query, schema, options = {}) {
+        call.ctx.signal.throwIfAborted();
+        const remaining = call.deadline - performance.now();
+        if (remaining <= 0)
+            throw timeout('InterPro call exhausted its 50-second budget.', {
+                reason: 'retry_deadline_exceeded',
+                retryable: true,
+                deadlineMs: 50_000,
+            });
+        const sourceUrl = apiUrl(segments, query);
+        return await withRetry(async ({ signal }) => pacer.run(async () => {
+            const attemptMs = Math.min(15_000, call.deadline - performance.now());
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(timeout('InterPro attempt deadline elapsed.', {
+                reason: 'upstream_timeout',
+                retryable: true,
+            })), Math.max(0, attemptMs));
+            const attemptSignal = AbortSignal.any([signal, controller.signal, call.ctx.signal]);
+            try {
+                const response = await this.fetch(sourceUrl, {
+                    signal: attemptSignal,
+                    headers: { Accept: 'application/json', 'Accept-Encoding': 'identity' },
+                    redirect: 'manual',
+                });
+                attemptSignal.throwIfAborted();
+                if ((response.status === 400 || response.status === 404) && options.continuation)
+                    throw validationError('InterPro rejected the continuation cursor.', {
+                        reason: 'invalid_cursor',
+                        retryable: false,
+                        status: response.status,
+                    });
+                const { missing } = options;
+                if (missing &&
+                    (response.status === 404 || (response.status === 204 && !missing.list)))
+                    throw notFound(`InterPro could not find ${describeRecord(missing)}.`, {
+                        reason: missing.reason,
+                        retryable: false,
+                        status: response.status,
+                        accession: missing.accession,
+                        sourceDatabase: missing.sourceDatabase,
+                    });
+                if (response.status === 204)
+                    return { data: null, sourceUrl, headers: response.headers };
+                if (response.status === 410) {
+                    const body = await readBody(response, attemptSignal);
+                    let withdrawal = {};
+                    try {
+                        const parsed = JsonObjectSchema.parse(JSON.parse(body));
+                        withdrawal = Object.fromEntries(Object.entries(parsed).filter(([key, value]) => WITHDRAWAL_FIELDS.has(key) && JSON.stringify(value).length <= 4096));
+                    }
+                    catch {
+                        /* A withdrawn record need not include valid metadata. */
+                    }
+                    const { accession, deletion_date: deleted, short_name: shortName } = withdrawal;
+                    const subject = missing
+                        ? describeRecord(missing)
+                        : isAccession(accession)
+                            ? `record ${accession}`
+                            : 'the requested record';
+                    const on = typeof deleted === 'string' && WITHDRAWAL_DATE.test(deleted)
+                        ? ` on ${deleted}`
+                        : '';
+                    const named = typeof shortName === 'string' && SHORT_NAME.test(shortName)
+                        ? ` (short name ${shortName})`
+                        : '';
+                    throw notFound(`InterPro reports that ${subject} was withdrawn${on}${named}.`, {
+                        reason: 'entry_withdrawn',
+                        retryable: false,
+                        status: 410,
+                        ...withdrawal,
+                        // The canonical accession the message names wins over upstream's spelling.
+                        ...(missing ? { accession: missing.accession } : {}),
+                    });
+                }
+                if (!response.ok) {
+                    const status = response.status;
+                    const reason = status === 408 || status === 504
+                        ? 'upstream_timeout'
+                        : status === 429
+                            ? 'upstream_rate_limited'
+                            : status >= 500
+                                ? 'upstream_unavailable'
+                                : 'upstream_rejected';
+                    throw await httpErrorFromResponse(response, {
+                        service: 'InterPro',
+                        captureBody: false,
+                        codeOverride: (value) => value < 500 && value !== 408 && value !== 429
+                            ? JsonRpcErrorCode.ServiceUnavailable
+                            : undefined,
+                        data: {
+                            reason,
+                            retryable: (status >= 500 && status !== 501) || status === 408 || status === 429,
+                        },
+                    });
+                }
+                const encoding = response.headers.get('content-encoding');
+                if (encoding && encoding.toLowerCase() !== 'identity')
+                    throw serviceUnavailable('InterPro returned an unexpected content encoding.', {
+                        reason: 'upstream_shape_invalid',
+                        retryable: false,
+                    });
+                const body = await readBody(response, attemptSignal);
+                if (/^\s*<(?:!doctype\s+html|html[\s>])/i.test(body))
+                    throw serviceUnavailable('InterPro returned HTML instead of JSON.', {
+                        reason: 'upstream_unavailable',
+                        retryable: true,
+                    });
+                let json;
+                try {
+                    json = JSON.parse(body);
+                }
+                catch (cause) {
+                    throw serviceUnavailable('InterPro returned malformed JSON.', { reason: 'upstream_shape_invalid', retryable: false }, { cause });
+                }
+                const parsed = schema.safeParse(json);
+                if (!parsed.success)
+                    throw serviceUnavailable('InterPro JSON does not match the required response structure.', { reason: 'upstream_shape_invalid', retryable: false });
+                attemptSignal.throwIfAborted();
+                if (performance.now() > call.deadline)
+                    throw timeout('InterPro call exhausted its total budget.', {
+                        reason: 'retry_deadline_exceeded',
+                        retryable: true,
+                    });
+                return { data: parsed.data, sourceUrl, headers: response.headers };
+            }
+            catch (cause) {
+                if (call.ctx.signal.aborted)
+                    throw call.ctx.signal.reason;
+                if (signal.aborted)
+                    throw signal.reason;
+                if (controller.signal.aborted)
+                    throw controller.signal.reason;
+                if (cause instanceof McpError)
+                    throw cause;
+                throw serviceUnavailable('InterPro network request failed.', { reason: 'upstream_unavailable', retryable: true }, { cause });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }, { signal, maxWaitMs: Math.max(0, Math.min(5000, call.deadline - performance.now())) }), {
+            signal: call.ctx.signal,
+            context: call.ctx,
+            operation: 'interpro.request',
+            deadlineMs: remaining,
+            maxRetries: 1,
+            baseDelayMs: 1000,
+            maxDelayMs: 3000,
+            isTransient: defaultIsTransient,
+        });
+    }
+    /** Retrieve a coherent current release and its complete database-count object. */
+    async release(ctx) {
+        const call = this.begin(ctx);
+        const releases = await this.request(call, ['utils', 'release'], {}, z.record(z.string().regex(/^\d+(?:\.\d+)*$/), z.string()));
+        const counts = await this.request(call, ['entry'], {}, z.object({ entries: JsonObjectSchema }).catchall(JsonValueSchema));
+        if (!releases.data || !counts.data || !Object.keys(releases.data).length)
+            throw serviceUnavailable('InterPro release metadata is missing.', {
+                reason: 'upstream_shape_invalid',
+                retryable: false,
+            });
+        const firstVersion = releases.headers.get('interpro-version');
+        const secondVersion = counts.headers.get('interpro-version');
+        if (firstVersion && secondVersion && firstVersion !== secondVersion)
+            throw serviceUnavailable('InterPro release changed between metadata responses.', {
+                reason: 'release_changed',
+                retryable: true,
+            });
+        const version = Object.keys(releases.data).sort((a, b) => {
+            const left = a.split('.').map(Number);
+            const right = b.split('.').map(Number);
+            for (let index = 0; index < Math.max(left.length, right.length); index++) {
+                const difference = (right[index] ?? 0) - (left[index] ?? 0);
+                if (difference)
+                    return difference;
+            }
+            return 0;
+        })[0];
+        if (!version)
+            throw serviceUnavailable('InterPro release map has no version.', {
+                reason: 'upstream_shape_invalid',
+                retryable: false,
+            });
+        return {
+            version,
+            date: releases.data[version],
+            databaseCounts: counts.data,
+            sourceUrls: [releases.sourceUrl, counts.sourceUrl],
+        };
+    }
+}
+async function readBody(response, signal) {
+    if (!response.body)
+        return '';
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytes = 0;
+    const abort = () => {
+        void reader.cancel(signal.reason).catch(() => { });
+    };
+    signal.addEventListener('abort', abort, { once: true });
+    try {
+        while (true) {
+            signal.throwIfAborted();
+            const { done, value } = await reader.read();
+            signal.throwIfAborted();
+            if (done)
+                break;
+            bytes += value.byteLength;
+            if (bytes > MAX_RESPONSE_BYTES) {
+                await reader.cancel();
+                throw serviceUnavailable('InterPro response exceeds 4 MiB.', {
+                    reason: 'upstream_response_too_large',
+                    retryable: false,
+                });
+            }
+            chunks.push(value);
+        }
+        return Buffer.concat(chunks).toString('utf8');
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+        reader.releaseLock();
+    }
+}
+let service;
+/** Initialize the process service in createApp.setup. */
+export function initInterproService(fetch = interproHttpFetch) {
+    service = new InterproService(fetch);
+}
+/** Obtain the initialized process service. */
+export function getInterproService() {
+    if (!service)
+        throw new Error('InterPro service is not initialized.');
+    return service;
+}
+/** Dispose queued pacing work during application teardown. */
+export function disposeInterproService() {
+    pacer.dispose();
+}
+//# sourceMappingURL=interpro-service.js.map

package/dist/services/interpro/interpro-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpro-service.js","sourceRoot":"","sources":["../../../src/services/interpro/interpro-service.ts"],"names":[],"mappings":"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"}

package/dist/services/interpro/reference.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Static API vocabulary and common taxonomy examples.
+ * @module services/interpro/reference
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+/** Available reference topics; only release performs network operations. */
+export declare const ReferenceTopicSchema: z.ZodEnum<{
+    accession_patterns: "accession_patterns";
+    databases: "databases";
+    entry_types: "entry_types";
+    release: "release";
+    taxa: "taxa";
+}>;
+/** Applicable reference fields, without fabricated empty annotations. */
+export declare const ReferenceItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    sourceDatabase: z.ZodOptional<z.ZodString>;
+    accessionPattern: z.ZodOptional<z.ZodString>;
+    example: z.ZodOptional<z.ZodString>;
+    taxonId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** A reference vocabulary row. */
+export type ReferenceItem = z.infer<typeof ReferenceItemSchema>;
+/** Return bounded local reference data without making upstream requests. */
+export declare function staticReference(topic: Exclude<z.infer<typeof ReferenceTopicSchema>, 'release'>): {
+    items: ReferenceItem[];
+    sourceUrls: string[];
+};
+//# sourceMappingURL=reference.d.ts.map

package/dist/services/interpro/reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../../../src/services/interpro/reference.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAI3C,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB;;;;;;EAE2C,CAAC;AAC7E,yEAAyE;AACzE,eAAO,MAAM,mBAAmB;;;;;;;;iBAaa,CAAC;AAC9C,kCAAkC;AAClC,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AA0DhE,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,EAAE,SAAS,CAAC,GAAG;IAChG,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAsCA"}

package/dist/services/interpro/reference.js

@@ -0,0 +1,122 @@
+/**
+ * @fileoverview Static API vocabulary and common taxonomy examples.
+ * @module services/interpro/reference
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { DOCUMENTATION_URL, ENTRY_ROUTES } from './routing.js';
+/** Available reference topics; only release performs network operations. */
+export const ReferenceTopicSchema = z
+    .enum(['databases', 'entry_types', 'accession_patterns', 'taxa', 'release'])
+    .describe('Reference topic; release retrieves current upstream metadata.');
+/** Applicable reference fields, without fabricated empty annotations. */
+export const ReferenceItemSchema = z
+    .object({
+    id: z.string().describe('Reference identifier.'),
+    label: z.string().describe('Human-readable label.'),
+    description: z.string().optional().describe('Meaning and coverage.'),
+    sourceDatabase: z.string().optional().describe('Entry API database slug.'),
+    accessionPattern: z.string().optional().describe('Case-insensitive accession routing pattern.'),
+    example: z
+        .string()
+        .optional()
+        .describe('Example accession spelling; assignment is not guaranteed.'),
+    taxonId: z.string().optional().describe('NCBI taxonomy identifier.'),
+})
+    .describe('One reference vocabulary item.');
+const databaseLabels = {
+    interpro: 'InterPro',
+    pfam: 'Pfam',
+    prosite: 'PROSITE patterns',
+    profile: 'PROSITE profiles',
+    smart: 'SMART',
+    cdd: 'CDD',
+    panther: 'PANTHER',
+    cathgene3d: 'CATH-Gene3D',
+    ssf: 'SUPERFAMILY',
+    ncbifam: 'NCBIFAM',
+    hamap: 'HAMAP',
+    prints: 'PRINTS',
+    pirsf: 'PIRSF',
+    sfld: 'SFLD',
+    antifam: 'AntiFam',
+};
+const types = [
+    ['domain', 'Domain', 'A distinct structural or functional protein unit.'],
+    ['family', 'Family', 'A group of evolutionarily related proteins.'],
+    ['repeat', 'Repeat', 'A repeated sequence or structural unit.'],
+    [
+        'homologous_superfamily',
+        'Homologous superfamily',
+        'Proteins or domains with a shared evolutionary origin.',
+    ],
+    ['active_site', 'Active site', 'Residues involved in catalysis.'],
+    ['binding_site', 'Binding site', 'Residues involved in binding.'],
+    ['conserved_site', 'Conserved site', 'A conserved functional sequence site.'],
+    ['ptm', 'Post-translational modification', 'A post-translational modification site.'],
+    [
+        'region',
+        'Region',
+        'A sequence region; AntiFam signatures of spurious protein predictions use this type.',
+    ],
+    [
+        'coiled_coil',
+        'Coiled coil',
+        'A coiled-coil region, where alpha-helices wind around each other.',
+    ],
+    [
+        'disordered',
+        'Disordered region',
+        'An intrinsically disordered region without a fixed three-dimensional structure.',
+    ],
+];
+const taxa = [
+    ['9606', 'Human'],
+    ['10090', 'Mouse'],
+    ['10116', 'Rat'],
+    ['7955', 'Zebrafish'],
+    ['7227', 'Fruit fly'],
+    ['6239', 'Nematode'],
+    ['559292', 'Budding yeast'],
+    ['3702', 'Arabidopsis'],
+    ['562', 'Escherichia coli'],
+];
+/** Return bounded local reference data without making upstream requests. */
+export function staticReference(topic) {
+    if (topic === 'entry_types')
+        return {
+            items: types.map(([id, label, description]) => ({ id, label, description })),
+            sourceUrls: [DOCUMENTATION_URL],
+        };
+    if (topic === 'taxa')
+        return {
+            items: taxa.map(([taxonId, label]) => ({
+                id: taxonId,
+                label,
+                taxonId,
+                description: 'Common taxonomy example; this is not an exhaustive taxonomy.',
+            })),
+            sourceUrls: [DOCUMENTATION_URL, 'https://www.ncbi.nlm.nih.gov/taxonomy'],
+        };
+    return {
+        items: ENTRY_ROUTES.map(({ source, pattern, example }) => ({
+            id: source,
+            label: databaseLabels[source],
+            sourceDatabase: source,
+            accessionPattern: pattern.source,
+            example,
+            description: topic === 'accession_patterns'
+                ? 'Routing syntax does not guarantee that an accession is assigned.'
+                : source === 'interpro'
+                    ? 'Integrating database combining member signatures.'
+                    : source === 'antifam'
+                        ? 'Additional API source for spurious protein predictions.'
+                        : source === 'prosite'
+                            ? 'PROSITE pattern signatures; profiles use the profile route.'
+                            : source === 'profile'
+                                ? 'PROSITE profile signatures; patterns use the prosite route.'
+                                : 'Member-database signatures exposed through the InterPro entry API.',
+        })),
+        sourceUrls: [DOCUMENTATION_URL],
+    };
+}
+//# sourceMappingURL=reference.js.map

package/dist/services/interpro/reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.js","sourceRoot":"","sources":["../../../src/services/interpro/reference.ts"],"names":[],"mappings":"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"}

package/dist/services/interpro/relationships.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Deterministic, whole-record slices of a clan relationship graph.
+ * @module services/interpro/relationships
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+/** The graph InterPro attaches to set metadata: node and link records plus any additional fields. */
+export declare const RelationshipGraphSchema: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+    nodes: z.ZodArray<z.ZodJSONSchema>;
+    links: z.ZodArray<z.ZodJSONSchema>;
+}, z.core.$catchall<z.ZodJSONSchema>>>>;
+/** A relationship graph as supplied, or null/absent when InterPro supplied none. */
+type RelationshipGraph = z.infer<typeof RelationshipGraphSchema>;
+/**
+ * Order nodes by accession and links by source, target, and method, so an offset addresses the
+ * same record on every call whatever order the upstream arrays arrive in.
+ */
+export declare function orderRelationships(graph: RelationshipGraph): RelationshipGraph;
+/**
+ * The `count` whole records starting at `offset` in the sequence of every node followed by every
+ * link, as a graph of the upstream shape, with the page block that locates it.
+ */
+export declare function sliceRelationships(graph: RelationshipGraph, offset: number, count: number): {
+    relationships: {
+        nodes: z.JSONType[];
+        links: z.JSONType[];
+    } | null | undefined;
+    page: {
+        totalNodes: number;
+        totalLinks: number;
+        offset: number;
+        returnedNodes: number;
+        returnedLinks: number;
+        hasMore: boolean;
+        nextOffset?: number;
+    };
+};
+export {};
+//# sourceMappingURL=relationships.d.ts.map

package/dist/services/interpro/relationships.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../../src/services/interpro/relationships.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAM3C,qGAAqG;AACrG,eAAO,MAAM,uBAAuB;;;uCAIvB,CAAC;AACd,oFAAoF;AACpF,KAAK,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAmBjE;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,iBAAiB,CAQ9E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;;;;;;;;;;;;;;EAuBzF"}

package/dist/services/interpro/relationships.js

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Deterministic, whole-record slices of a clan relationship graph.
+ * @module services/interpro/relationships
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { compareText, cursorScope } from './cursors.js';
+import { JsonValueSchema } from './schemas.js';
+/** The graph InterPro attaches to set metadata: node and link records plus any additional fields. */
+export const RelationshipGraphSchema = z
+    .object({ nodes: z.array(JsonValueSchema), links: z.array(JsonValueSchema) })
+    .catchall(JsonValueSchema)
+    .nullable()
+    .optional();
+const field = (record, key) => {
+    if (!record || typeof record !== 'object' || Array.isArray(record))
+        return '';
+    const value = record[key];
+    return typeof value === 'string' ? value : '';
+};
+/** Sort by the named string fields in turn; canonical JSON breaks any remaining tie. */
+function ordered(records, keys) {
+    return records.toSorted((a, b) => {
+        for (const key of keys) {
+            const difference = compareText(field(a, key), field(b, key));
+            if (difference)
+                return difference;
+        }
+        return compareText(cursorScope(a), cursorScope(b));
+    });
+}
+/**
+ * Order nodes by accession and links by source, target, and method, so an offset addresses the
+ * same record on every call whatever order the upstream arrays arrive in.
+ */
+export function orderRelationships(graph) {
+    return (graph && {
+        ...graph,
+        nodes: ordered(graph.nodes, ['accession']),
+        links: ordered(graph.links, ['source', 'target', 'method']),
+    });
+}
+/**
+ * The `count` whole records starting at `offset` in the sequence of every node followed by every
+ * link, as a graph of the upstream shape, with the page block that locates it.
+ */
+export function sliceRelationships(graph, offset, count) {
+    const nodes = graph?.nodes ?? [];
+    const links = graph?.links ?? [];
+    const total = nodes.length + links.length;
+    const start = Math.min(offset, total);
+    const end = Math.min(start + count, total);
+    const slice = {
+        nodes: nodes.slice(Math.min(start, nodes.length), Math.min(end, nodes.length)),
+        links: links.slice(Math.max(0, start - nodes.length), Math.max(0, end - nodes.length)),
+    };
+    const hasMore = end < total;
+    return {
+        relationships: graph && { ...graph, ...slice },
+        page: {
+            totalNodes: nodes.length,
+            totalLinks: links.length,
+            offset,
+            returnedNodes: slice.nodes.length,
+            returnedLinks: slice.links.length,
+            hasMore,
+            ...(hasMore ? { nextOffset: end } : {}),
+        },
+    };
+}
+//# sourceMappingURL=relationships.js.map

package/dist/services/interpro/relationships.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationships.js","sourceRoot":"","sources":["../../../src/services/interpro/relationships.ts"],"names":[],"mappings":"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"}

package/dist/services/interpro/routing.d.ts

@@ -0,0 +1,24 @@
+import { type SourceDatabase } from './schemas.js';
+/** Canonical API origin; no upstream continuation URL is fetched directly. */
+export declare const API_BASE = "https://www.ebi.ac.uk/interpro/api/";
+/** Official reference documentation. */
+export declare const DOCUMENTATION_URL = "https://interpro-documentation.readthedocs.io/en/latest/api.html";
+/** Routing patterns and examples are shared with the reference vocabulary. */
+export declare const ENTRY_ROUTES: readonly {
+    source: SourceDatabase;
+    pattern: RegExp;
+    example: string;
+}[];
+/** Resolve one entry accession without guessing alternate databases after a miss. */
+export declare function resolveEntry(accession: string, sourceDatabase?: SourceDatabase): {
+    accession: string;
+    sourceDatabase: SourceDatabase;
+};
+/** Resolve case-sensitive CL clan prefixes, with explicit source disambiguation. */
+export declare function resolveClan(accession: string, sourceDatabase?: 'pfam' | 'cdd' | 'pirsf'): {
+    accession: string;
+    sourceDatabase: 'pfam' | 'cdd' | 'pirsf';
+};
+/** Build fixed-origin requests from independently validated, encoded path segments. */
+export declare function apiUrl(segments: readonly string[], query?: Readonly<Record<string, string | number | boolean | undefined>>): string;
+//# sourceMappingURL=routing.d.ts.map

package/dist/services/interpro/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../../src/services/interpro/routing.ts"],"names":[],"mappings":"AAKA,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAEpE,8EAA8E;AAC9E,eAAO,MAAM,QAAQ,wCAAwC,CAAC;AAC9D,wCAAwC;AACxC,eAAO,MAAM,iBAAiB,qEAAqE,CAAC;AACpG,8EAA8E;AAC9E,eAAO,MAAM,YAAY,EAAE,SAAS;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAiB7F,CAAC;AAGJ,qFAAqF;AACrF,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,cAAc,GAC9B;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,cAAc,CAAA;CAAE,CAiCvD;AACD,oFAAoF;AACpF,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,OAAO,GACxC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,GAAG,KAAK,GAAG,OAAO,CAAA;CAAE,CA2CjE;AACD,uFAAuF;AACvF,wBAAgB,MAAM,CACpB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,KAAK,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAM,GAC1E,MAAM,CAMR"}