@cyanheads/interpro-mcp-server 0.1.2 → 0.1.3

package/dist/mcp-server/tools/definitions/interpro-get-entry.tool.js

@@ -10,10 +10,45 @@ import { getInterproService } from '../../../services/interpro/interpro-service.
 import { resolveEntry } from '../../../services/interpro/routing.js';
 import { AccessionSchema, detailSchema, EntryDetailMetadataSchema, EntryMetadataSchema, optionalString, SourceDatabaseSchema, } from '../../../services/interpro/schemas.js';
 import { UPSTREAM_ERRORS } from '../../../services/interpro/upstream-errors.js';
+const SECTIONS = [
+    'description',
+    'hierarchy',
+    'member_databases',
+    'go_terms',
+    'literature',
+    'cross_references',
+    'wikipedia',
+    'counters',
+    'overlaps_with',
+];
+const SectionSchema = z.enum(SECTIONS);
+const OverlapsPageSchema = z.discriminatedUnion('available', [
+    z
+        .object({
+        available: z.literal(true).describe('Overlap array was supplied.'),
+        total: z.number().int().nonnegative().describe('Complete upstream overlap count.'),
+        offset: z.number().int().nonnegative().describe('Requested record offset.'),
+        returned: z.number().int().nonnegative().describe('Complete records returned.'),
+        hasMore: z.boolean().describe('More overlap records remain.'),
+        nextOffset: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe('Next offset when more records remain.'),
+    })
+        .describe('Page of complete upstream overlap records.'),
+    z
+        .object({
+        available: z.literal(false).describe('Overlap array was not supplied.'),
+        offset: z.number().int().nonnegative().describe('Requested record offset.'),
+    })
+        .describe('Overlap paging unavailable for a missing or null source section.'),
+]);
 /** Retrieve one complete entry with deterministic accession routing. */
 export const interproGetEntry = tool('interpro_get_entry', {
     title: 'InterPro entry metadata',
-    description: 'Retrieve one InterPro or member-database entry, including description, hierarchy, member signatures, GO terms, literature, cross-references, clan membership, and coverage counters.',
+    description: 'Retrieve one InterPro or member-database entry with full metadata by default. Select optional sections while retaining core and unknown metadata, or supply overlapLimit to page whole overlap records in upstream order; offsets are not a snapshot across calls.',
     annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     auth: ['tool:interpro_get_entry:read'],
     input: z.object({
@@ -23,21 +58,68 @@ export const interproGetEntry = tool('interpro_get_entry', {
             .boolean()
             .default(false)
             .describe('Include each Wikipedia thumbnail image, base64 data often hundreds of KB; defaults to false.'),
+        sections: z
+            .array(SectionSchema.describe('Optional metadata section to retain.'))
+            .optional()
+            .describe('Retain these named sections and all core or unknown metadata; omitted means full detail, and an empty array retains core metadata only.'),
+        overlapLimit: z
+            .number()
+            .int()
+            .positive()
+            .max(Number.MAX_SAFE_INTEGER)
+            .optional()
+            .describe('Positive safe integer number of whole overlap records; supplying it enables overlap paging.'),
+        overlapOffset: z
+            .number()
+            .int()
+            .nonnegative()
+            .max(Number.MAX_SAFE_INTEGER)
+            .optional()
+            .describe('Nonnegative safe integer overlap offset; requires overlapLimit, defaults to zero.'),
     }),
     output: z.object({
         accession: z.string().describe('Canonical requested accession.'),
         sourceDatabase: SourceDatabaseSchema,
-        entry: EntryDetailMetadataSchema.describe('Complete upstream metadata with readable descriptionText, preserving raw description shapes and sparse annotations; Wikipedia thumbnails are omitted unless includeThumbnail is true.'),
+        entry: EntryDetailMetadataSchema.describe('Upstream metadata after explicit section selection and overlap paging, with readable descriptionText when description is retained; raw description shapes and sparse annotations survive. Wikipedia thumbnails are omitted unless includeThumbnail is true.'),
         url: z.string().describe('Canonical InterPro website URL.'),
         sourceUrl: z.string().describe('Official API source URL.'),
+        sections: z
+            .array(SectionSchema.describe('Retained optional section.'))
+            .optional()
+            .describe('Canonical selected sections, when explicitly selected.'),
+        omittedSections: z
+            .array(SectionSchema.describe('Omitted source section.'))
+            .optional()
+            .describe('Named sections actually removed from upstream metadata.'),
+        overlapsPage: OverlapsPageSchema.optional().describe('Explicit overlap paging state; unavailable arrays have no fabricated total.'),
     }),
     enrichment: {
+        totalCount: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe('Total upstream overlap records when explicit paging has an available array.'),
         notice: z
             .string()
             .optional()
-            .describe('Omitted Wikipedia thumbnail size and how to include it.'),
+            .describe('Section selection, overlap page continuation or availability, and omitted Wikipedia thumbnail guidance.'),
     },
     errors: [
+        {
+            reason: 'overlap_limit_required',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'overlapOffset is supplied without overlapLimit.',
+            retryable: false,
+            recovery: 'Supply overlapLimit to enable paging, or omit overlapOffset for full overlaps.',
+        },
+        {
+            reason: 'overlaps_not_selected',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'Overlap paging is requested but sections excludes overlaps_with.',
+            retryable: false,
+            recovery: 'Include overlaps_with in sections or omit sections, then retry with overlapLimit.',
+        },
         {
             reason: 'database_mismatch',
             code: JsonRpcErrorCode.ValidationError,
@@ -81,14 +163,64 @@ export const interproGetEntry = tool('interpro_get_entry', {
         ...UPSTREAM_ERRORS,
     ],
     async handler(input, ctx) {
+        if (input.overlapOffset !== undefined && input.overlapLimit === undefined)
+            throw ctx.fail('overlap_limit_required');
+        if (input.overlapLimit !== undefined &&
+            input.sections &&
+            !input.sections.includes('overlaps_with'))
+            throw ctx.fail('overlaps_not_selected');
         const target = resolveEntry(input.accession, input.sourceDatabase);
         const service = getInterproService();
         const response = await service.request(service.begin(ctx), ['entry', target.sourceDatabase, target.accession], {}, detailSchema(EntryMetadataSchema), { missing: { reason: 'entry_not_found', ...target } });
         if (!response.data)
             throw ctx.fail('upstream_shape_invalid', 'Entry metadata response is missing.');
-        const { metadata, notice } = projectWikipediaThumbnails(response.data.metadata, input.includeThumbnail, 'interpro_get_entry');
+        const sourceMetadata = response.data.metadata;
+        const selected = input.sections === undefined
+            ? undefined
+            : SECTIONS.filter((section) => input.sections?.includes(section));
+        const omittedSections = selected === undefined
+            ? undefined
+            : SECTIONS.filter((section) => !selected.includes(section) && Object.hasOwn(sourceMetadata, section));
+        const projected = { ...sourceMetadata };
+        for (const section of omittedSections ?? [])
+            delete projected[section];
+        const notices = [];
+        if (selected)
+            notices.push(`Selected sections: ${JSON.stringify(selected)}; omitted source sections: ${JSON.stringify(omittedSections)}. Core and unknown metadata are retained.`);
+        let overlapsPage;
+        if (input.overlapLimit !== undefined) {
+            const offset = input.overlapOffset ?? 0;
+            const overlaps = projected.overlaps_with;
+            if (overlaps === undefined || overlaps === null) {
+                overlapsPage = { available: false, offset };
+                notices.push('Overlap paging is unavailable because upstream overlaps_with is missing or null; no total is known.');
+            }
+            else {
+                if (!Array.isArray(overlaps))
+                    throw ctx.fail('upstream_shape_invalid', 'Entry overlaps_with is not an array.');
+                const slice = overlaps.slice(offset, offset + Math.min(input.overlapLimit, overlaps.length));
+                projected.overlaps_with = slice;
+                const nextOffset = offset + slice.length;
+                const hasMore = nextOffset < overlaps.length;
+                ctx.enrich.total(overlaps.length);
+                overlapsPage = {
+                    available: true,
+                    total: overlaps.length,
+                    offset,
+                    returned: slice.length,
+                    hasMore,
+                    ...(hasMore ? { nextOffset } : {}),
+                };
+                notices.push(`Overlap page returned ${slice.length} of ${overlaps.length} records at offset ${offset}.`);
+                if (hasMore)
+                    notices.push(`Continue with interpro_get_entry ${JSON.stringify({ ...target, includeThumbnail: input.includeThumbnail, ...(selected ? { sections: selected } : {}), overlapLimit: input.overlapLimit, overlapOffset: nextOffset })}.`);
+            }
+        }
+        const { metadata, notice } = projectWikipediaThumbnails(projected, input.includeThumbnail, 'interpro_get_entry');
         if (notice)
-            ctx.enrich.notice(notice);
+            notices.push(notice);
+        if (notices.length)
+            ctx.enrich.notice(notices.join(' '));
         const readable = descriptionText(metadata.description);
         const entry = normalizeImages(metadata);
         if (readable)
@@ -98,6 +230,8 @@ export const interproGetEntry = tool('interpro_get_entry', {
             entry,
             url: `https://www.ebi.ac.uk/interpro/entry/${target.sourceDatabase}/${encodeURIComponent(target.accession)}/`,
             sourceUrl: response.sourceUrl,
+            ...(selected ? { sections: selected, omittedSections } : {}),
+            ...(overlapsPage ? { overlapsPage } : {}),
         };
     },
     format: formatInterpro,

package/dist/mcp-server/tools/definitions/interpro-get-entry.tool.js.map

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

package/dist/mcp-server/tools/definitions/interpro-get-protein-domains.tool.d.ts

@@ -9,6 +9,7 @@ export declare const interproGetProteinDomains: import("@cyanheads/mcp-ts-core")
     accession: z.ZodString;
     residuePosition: z.ZodOptional<z.ZodNumber>;
     includeExtraFeatures: z.ZodDefault<z.ZodBoolean>;
+    includeResidueAnnotations: z.ZodDefault<z.ZodBoolean>;
     cursor: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
 }, z.core.$strip>, z.ZodObject<{
     accession: z.ZodString;
@@ -69,9 +70,24 @@ export declare const interproGetProteinDomains: import("@cyanheads/mcp-ts-core")
             score: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         }, z.core.$catchall<z.ZodJSONSchema>>>;
     }, z.core.$catchall<z.ZodJSONSchema>>>>;
+    residueAnnotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        accession: z.ZodString;
+        source_database: z.ZodString;
+        locations: z.ZodArray<z.ZodObject<{
+            fragments: z.ZodArray<z.ZodObject<{
+                start: z.ZodNumber;
+                end: z.ZodNumber;
+                'dc-status': z.ZodOptional<z.ZodString>;
+            }, z.core.$catchall<z.ZodJSONSchema>>>;
+            representative: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+            model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            score: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$catchall<z.ZodJSONSchema>>>;
+    }, z.core.$catchall<z.ZodJSONSchema>>>>;
     selection: z.ZodObject<{
         residuePosition: z.ZodOptional<z.ZodNumber>;
         includeExtraFeatures: z.ZodBoolean;
+        includeResidueAnnotations: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strip>;
     coverage: z.ZodObject<{
         totalMatches: z.ZodNumber;
@@ -79,6 +95,8 @@ export declare const interproGetProteinDomains: import("@cyanheads/mcp-ts-core")
         returnedMatches: z.ZodNumber;
         totalFeatures: z.ZodOptional<z.ZodNumber>;
         returnedFeatures: z.ZodOptional<z.ZodNumber>;
+        totalResidueAnnotations: z.ZodOptional<z.ZodNumber>;
+        returnedResidueAnnotations: z.ZodOptional<z.ZodNumber>;
         complete: z.ZodBoolean;
         hasMore: z.ZodBoolean;
         nextCursor: z.ZodOptional<z.ZodString>;
@@ -88,9 +106,9 @@ export declare const interproGetProteinDomains: import("@cyanheads/mcp-ts-core")
 }, z.core.$strip>, readonly [{
     readonly reason: "retry_deadline_exceeded";
     readonly code: JsonRpcErrorCode.Timeout;
-    readonly when: "The shared fifty-second budget expires across protein metadata, match pages, and extra features.";
+    readonly when: "The shared fifty-second budget expires across metadata, match pages, extra features, and residue rules.";
     readonly retryable: true;
-    readonly recovery: "Retry interpro_get_protein_domains after waiting; omit extra features when they are not needed.";
+    readonly recovery: "Retry interpro_get_protein_domains after waiting; omit optional annotations when they are not needed.";
     readonly thrownBy: "service";
 }, {
     readonly reason: "invalid_cursor";

package/dist/mcp-server/tools/definitions/interpro-get-protein-domains.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interpro-get-protein-domains.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/interpro-get-protein-domains.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAsJjE,gGAAgG;AAChG,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsUpC,CAAC"}
+{"version":3,"file":"interpro-get-protein-domains.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/interpro-get-protein-domains.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAmLjE,gGAAgG;AAChG,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoYpC,CAAC"}

package/dist/mcp-server/tools/definitions/interpro-get-protein-domains.tool.js

@@ -8,7 +8,7 @@ import { BUDGET_LABEL, fitWithinBudget, jsonByteLength, RESPONSE_BYTE_BUDGET, }
 import { compareText, continuation, cursorScope, decodePositionCursor, encodePositionCursor, } from '../../../services/interpro/cursors.js';
 import { formatInterpro, normalizeImages } from '../../../services/interpro/format.js';
 import { getInterproService } from '../../../services/interpro/interpro-service.js';
-import { detailSchema, ExtraFeaturesSchema, isAccession, listSchema, MatchSchema, optionalString, ProteinAccessionSchema, ProteinMetadataSchema, } from '../../../services/interpro/schemas.js';
+import { detailSchema, ExtraFeaturesSchema, isAccession, listSchema, MatchSchema, optionalString, ProteinAccessionSchema, ProteinMetadataSchema, ResidueAnnotationsSchema, } from '../../../services/interpro/schemas.js';
 import { UPSTREAM_ERRORS } from '../../../services/interpro/upstream-errors.js';
 const OPERATION = 'interpro_get_protein_domains';
 const PAGE_SIZE = 200;
@@ -21,13 +21,17 @@ const SelectionSchema = z.object({
         .optional()
         .describe('Selected 1-based inclusive residue position.'),
     includeExtraFeatures: z.boolean().describe('Whether extra predicted features were requested.'),
+    includeResidueAnnotations: z
+        .literal(true)
+        .optional()
+        .describe('Present only when residue rules were requested.'),
 });
 const CoverageSchema = z.object({
     totalMatches: z
         .number()
         .int()
         .nonnegative()
-        .describe('Upstream unfiltered total match count; a segment holding only extra features repeats the count the match list reported.'),
+        .describe('Upstream unfiltered total match count; extra-feature-only and residue-rule-only segments repeat the count reported by the match list.'),
     scannedMatches: z
         .number()
         .int()
@@ -50,22 +54,34 @@ const CoverageSchema = z.object({
         .nonnegative()
         .optional()
         .describe('Extra features in this segment; present with extraFeatures.'),
+    totalResidueAnnotations: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe('Selected residue rules; present only when the residue stage is reached.'),
+    returnedResidueAnnotations: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe('Whole residue rules returned in this segment.'),
     complete: z
         .boolean()
-        .describe('True only when this call starts without a cursor and returns the whole map: every match and every requested extra feature.'),
+        .describe('True only when this call starts without a cursor and returns every match, requested extra feature, and requested residue rule.'),
     hasMore: z
         .boolean()
-        .describe('Whether another segment remains, holding more matches or requested extra features.'),
+        .describe('Whether another segment remains, holding matches, requested extras, or requested residue rules.'),
     nextCursor: z
         .string()
         .optional()
-        .describe('Opaque cursor resuming at the next whole match or extra feature, for the same protein and selection.'),
+        .describe('Opaque cursor resuming at the next whole match, extra feature, or residue rule for the same protein and selection.'),
 });
 /**
  * Where a continuation resumes: `skip` records into an upstream match page (`page` is that
  * page's upstream cursor, absent for the first page), or `features` selected extra features into
- * the feature list that follows the last match. `after` names the last record an earlier segment
- * covered, so a page or feature list that changed since the cursor was minted is rejected.
+ * the feature list that follows the last match, or `residues` selected rules after the extras.
+ * `after` names the last record an earlier segment covered, so changed lists are rejected.
  */
 const PositionSchema = z.union([
     z
@@ -85,6 +101,14 @@ const PositionSchema = z.union([
     })
         .strict()
         .refine((point) => point.features > 0 === (point.after !== undefined)),
+    z
+        .object({
+        residues: z.number().int().nonnegative(),
+        after: z.string().min(1).optional(),
+        totalMatches: z.number().int().nonnegative(),
+    })
+        .strict()
+        .refine((point) => point.residues > 0 === (point.after !== undefined)),
 ]);
 function contains(locations, position) {
     return locations.some((location) => location.fragments.some((fragment) => fragment.start <= position && position <= fragment.end));
@@ -101,7 +125,7 @@ function byCoordinate(left, right) {
 /** Map signatures to sequence coordinates in budget-bounded segments with explicit coverage. */
 export const interproGetProteinDomains = tool('interpro_get_protein_domains', {
     title: 'Map protein domains',
-    description: 'Retrieve InterPro and member-signature matches on a canonical UniProt protein, preserving every location and discontinuous fragment. Optionally retain matches covering a residue and include extra predicted features. Large maps arrive in segments of whole matches that fit the response budget: the first segment carries the protein metadata, requested extra features follow the last match, and coverage.nextCursor continues until hasMore is false.',
+    description: 'Retrieve InterPro and member-signature matches on a canonical UniProt protein, preserving every location and discontinuous fragment. Optionally select records covering a residue, include extra predicted features, and include functional residue rules with provenance. Budgeted segments hold whole records in order: matches, requested extras, then requested residue rules sorted by key. The first segment carries protein metadata; continue coverage.nextCursor until hasMore is false.',
     annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     auth: ['tool:interpro_get_protein_domains:read'],
     input: z.object({
@@ -116,7 +140,11 @@ export const interproGetProteinDomains = tool('interpro_get_protein_domains', {
             .boolean()
             .default(false)
             .describe('Include complete extra predicted features, returned after the last match; defaults to false.'),
-        cursor: optionalString(z.string().trim().max(4096)).describe('Opaque coverage.nextCursor with unchanged accession, residuePosition, and includeExtraFeatures.'),
+        includeResidueAnnotations: z
+            .boolean()
+            .default(false)
+            .describe('Include complete functional residue rules after matches and requested extras; defaults to false.'),
+        cursor: optionalString(z.string().trim().max(4096)).describe('Opaque coverage.nextCursor with unchanged accession, residuePosition, includeExtraFeatures, and includeResidueAnnotations.'),
     }),
     output: z.object({
         accession: z.string().describe('Canonical UniProt accession.'),
@@ -125,8 +153,9 @@ export const interproGetProteinDomains = tool('interpro_get_protein_domains', {
             .array(MatchSchema.describe('Complete entry match record.'))
             .describe('Whole selected match records in this segment, sorted by earliest coordinate then accession; a match is never split across segments.'),
         extraFeatures: ExtraFeaturesSchema.optional().describe('Whole selected extra features in this segment, in feature-key order; {} when none are selected. Omitted when not requested or when this segment ends before the features that follow the last match.'),
-        selection: SelectionSchema.describe('Applied residue and extra-feature selection.'),
-        coverage: CoverageSchema.describe('Where this segment sits in the protein map: every match, then requested extra features.'),
+        residueAnnotations: ResidueAnnotationsSchema.optional().describe('Whole selected residue rules sorted by key; {} means the stage was reached with no selected rules. Omitted when unrequested or unreached.'),
+        selection: SelectionSchema.describe('Applied residue, extra-feature, and residue-rule selection.'),
+        coverage: CoverageSchema.describe('Where this segment sits in the protein map: matches, requested extra features, then requested residue rules.'),
         url: z.string().describe('Canonical protein website URL.'),
         sourceUrl: z.string().describe('Official protein API source URL.'),
     }),
@@ -146,9 +175,9 @@ export const interproGetProteinDomains = tool('interpro_get_protein_domains', {
         {
             reason: 'retry_deadline_exceeded',
             code: JsonRpcErrorCode.Timeout,
-            when: 'The shared fifty-second budget expires across protein metadata, match pages, and extra features.',
+            when: 'The shared fifty-second budget expires across metadata, match pages, extra features, and residue rules.',
             retryable: true,
-            recovery: 'Retry interpro_get_protein_domains after waiting; omit extra features when they are not needed.',
+            recovery: 'Retry interpro_get_protein_domains after waiting; omit optional annotations when they are not needed.',
             thrownBy: 'service',
         },
         {
@@ -198,12 +227,15 @@ export const interproGetProteinDomains = tool('interpro_get_protein_domains', {
         const selection = {
             ...(residue !== undefined ? { residuePosition: residue } : {}),
             includeExtraFeatures: input.includeExtraFeatures,
+            ...(input.includeResidueAnnotations ? { includeResidueAnnotations: true } : {}),
         };
         const scope = { accession, ...selection };
         const start = decodePositionCursor(input.cursor, OPERATION, scope, PositionSchema);
         const stale = () => ctx.fail('invalid_cursor', 'Cursor no longer matches the InterPro records it resumes inside.');
         if (start && 'features' in start && !input.includeExtraFeatures)
             throw stale();
+        if (start && 'residues' in start && !input.includeResidueAnnotations)
+            throw stale();
         const resumed = start !== undefined;
         const covers = (locations) => residue === undefined || contains(locations, residue);
         const service = getInterproService();
@@ -214,11 +246,12 @@ export const interproGetProteinDomains = tool('interpro_get_protein_domains', {
         const protein = normalizeImages(detail.data.metadata);
         if (residue !== undefined && residue > protein.length)
             throw ctx.fail('residue_out_of_range', `Residue ${residue} exceeds the ${protein.length}-residue length of ${accession}.`, { accession, proteinLength: protein.length, residuePosition: residue });
-        /** Whole candidate items in walk order: every match, then every selected extra feature. */
+        /** Whole candidate items: matches, selected extra features, then selected residue rules. */
         const items = [];
         let scanned = 0;
-        let totalMatches = start && 'features' in start ? start.totalMatches : 0;
+        let totalMatches = start && !('skip' in start) ? start.totalMatches : 0;
         let totalFeatures;
+        let totalResidueAnnotations;
         /** Where the walk resumes after the last gathered item; undefined once the walk ends. */
         let end;
         const segment = (count) => {
@@ -226,18 +259,24 @@ export const interproGetProteinDomains = tool('interpro_get_protein_domains', {
             const resume = stop ? stop.at : end;
             const matches = [];
             const features = [];
+            const residues = [];
             for (const item of items.slice(0, count))
                 if (item.kind === 'match')
                     matches.push(item.match);
-                else
+                else if (item.kind === 'feature')
                     features.push([item.key, item.feature]);
+                else
+                    residues.push([item.key, item.rule]);
             const featureTotal = totalFeatures;
-            const reachedFeatures = featureTotal !== undefined && (features.length > 0 || resume === undefined);
+            const reachedFeatures = featureTotal !== undefined &&
+                (features.length > 0 || resume === undefined || 'residues' in resume);
+            const reachedResidues = totalResidueAnnotations !== undefined && (residues.length > 0 || resume === undefined);
             return {
                 accession,
                 ...(resumed ? {} : { protein }),
                 matches: matches.toSorted(byCoordinate),
                 ...(reachedFeatures ? { extraFeatures: Object.fromEntries(features) } : {}),
+                ...(reachedResidues ? { residueAnnotations: Object.fromEntries(residues) } : {}),
                 selection,
                 coverage: {
                     totalMatches,
@@ -246,6 +285,9 @@ export const interproGetProteinDomains = tool('interpro_get_protein_domains', {
                     ...(reachedFeatures
                         ? { totalFeatures: featureTotal, returnedFeatures: features.length }
                         : {}),
+                    ...(reachedResidues
+                        ? { totalResidueAnnotations, returnedResidueAnnotations: residues.length }
+                        : {}),
                     complete: !resumed && resume === undefined,
                     hasMore: resume !== undefined,
                     ...(resume ? { nextCursor: encodePositionCursor(OPERATION, scope, resume) } : {}),
@@ -293,7 +335,7 @@ export const interproGetProteinDomains = tool('interpro_get_protein_domains', {
                     break;
             }
         }
-        if (input.includeExtraFeatures && end === undefined) {
+        if (input.includeExtraFeatures && !(start && 'residues' in start) && end === undefined) {
             // Read extras only when the matches fit beside the cursor that would resume at them.
             end = { features: 0, totalMatches };
             if (!overflows()) {
@@ -325,20 +367,53 @@ export const interproGetProteinDomains = tool('interpro_get_protein_domains', {
                 }
             }
         }
+        if (input.includeResidueAnnotations && end === undefined) {
+            end = { residues: 0, totalMatches };
+            if (!overflows()) {
+                end = undefined;
+                const response = await service.request(call, ['protein', 'uniprot', accession], { residues: '' }, ResidueAnnotationsSchema);
+                if (!response.data)
+                    throw ctx.fail('upstream_shape_invalid', 'Residue annotation response is missing.');
+                const selected = Object.entries(normalizeImages(response.data))
+                    .filter(([, rule]) => covers(rule.locations))
+                    .toSorted(([a], [b]) => compareText(a, b));
+                const resumeAt = start && 'residues' in start ? start : undefined;
+                const skip = resumeAt?.residues ?? 0;
+                if (skip > 0 && (skip >= selected.length || selected[skip - 1]?.[0] !== resumeAt?.after))
+                    throw stale();
+                totalResidueAnnotations = selected.length;
+                for (let index = skip; index < selected.length; index++) {
+                    const [key, rule] = selected[index];
+                    items.push({
+                        kind: 'residue',
+                        key,
+                        rule,
+                        scannedBefore: scanned,
+                        at: {
+                            residues: index,
+                            ...(index ? { after: selected[index - 1][0] } : {}),
+                            totalMatches,
+                        },
+                    });
+                }
+            }
+        }
         const { count, output, oversized } = fitWithinBudget(items.length, segment);
         const { coverage } = output;
         const stop = items[count];
         const notices = [];
         if (oversized) {
             const only = items[0];
-            const [named, unnamed, id] = only.kind === 'feature'
-                ? ['Extra feature', 'This extra feature', only.key]
+            const [named, unnamed, id] = only.kind !== 'match'
+                ? only.kind === 'feature'
+                    ? ['Extra feature', 'This extra feature', only.key]
+                    : ['Residue rule', 'This residue rule', only.key]
                 : ['Match', 'This match', only.match.metadata.accession];
             notices.push(`${isAccession(id) ? `${named} ${id}` : unnamed} cannot be split, so this segment holds it alone and exceeds the ${BUDGET_LABEL}.`);
         }
         if (coverage.nextCursor) {
             const reason = stop
-                ? ` and stopped at the ${BUDGET_LABEL} before the next whole ${stop.kind === 'match' ? 'match' : 'extra feature'}`
+                ? ` and stopped at the ${BUDGET_LABEL} before the next whole ${stop.kind === 'match' ? 'match' : stop.kind === 'feature' ? 'extra feature' : 'residue rule'}`
                 : oversized
                     ? ''
                     : ` and reached the ${MAX_PAGES}-page read limit after ${coverage.scannedMatches} match records`;
@@ -346,13 +421,14 @@ export const interproGetProteinDomains = tool('interpro_get_protein_domains', {
                 accession,
                 ...(residue !== undefined ? { residuePosition: residue } : {}),
                 ...(input.includeExtraFeatures ? { includeExtraFeatures: true } : {}),
+                ...(input.includeResidueAnnotations ? { includeResidueAnnotations: true } : {}),
                 cursor: coverage.nextCursor,
             };
             notices.push(`This segment covers part of the protein map${reason}. Continue with interpro_get_protein_domains ${JSON.stringify(nextCall)} before concluding that a residue has no annotation.`);
         }
         else if (resumed)
             notices.push('This is the final resumed segment. Only the combined segments cover the traversal; upstream pagination is not a snapshot.' +
-                (coverage.returnedMatches || 'features' in start
+                (coverage.returnedMatches || !('skip' in start)
                     ? ''
                     : ' No match was selected in this segment.'));
         else if (!coverage.returnedMatches)