@cyanheads/protein-mcp-server 0.1.0

package/dist/mcp-server/tools/definitions/search-structures.tool.js

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview protein_search_structures — federated search across experimental
+ * (PDB) and predicted (computed model) structures via RCSB Search v2, with
+ * optional metadata enrichment of the experimental page and an optional facet
+ * breakdown for instant corpus orientation.
+ * @module mcp-server/tools/definitions/search-structures.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getServerConfig } from '../../../config/server-config.js';
+import { buildFacetSpec, FACET_DIMENSION_NAMES } from '../../../services/rcsb/facets.js';
+import { getRcsbService } from '../../../services/rcsb/rcsb-service.js';
+import { entryIdOf } from '../../../services/shared/identifiers.js';
+import { facetDimensionSchema, renderFacets, toFacetOutput } from './_schemas.js';
+const CONTENT_TYPE_MAP = {
+    experimental: ['experimental'],
+    predicted: ['computational'],
+    all: ['experimental', 'computational'],
+};
+/** A computed-model identifier (AlphaFold / ModelArchive) vs an experimental PDB entry. */
+function isPredictedId(id) {
+    return /^(AF|MA)_/i.test(id);
+}
+/** Pull a UniProt accession out of a computed-model identifier when present (`AF_AFP69905F1` → `P69905`). */
+function accessionFromCsm(id) {
+    return /AF_AF([A-Z0-9]+?)F\d+$/i.exec(id)?.[1]?.toUpperCase();
+}
+export const searchStructures = tool('protein_search_structures', {
+    title: 'protein-mcp-server: search structures',
+    description: 'Search experimental (PDB) and predicted (computed-model) protein structures by free text, ' +
+        'protein sequence (triggers an mmseqs2 similarity search), and/or organism, method, and ' +
+        'resolution filters. Returns ranked hits; the experimental page is enriched with title, method, ' +
+        'resolution, and organism. Chain hit IDs into protein_get_structure. Optionally returns a facet ' +
+        'breakdown (counts by method / organism / release year / …) alongside the hits at no extra call.',
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    errors: [
+        {
+            reason: 'no_criteria',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'No query, sequence, or organism was provided — nothing to search on.',
+            recovery: 'Provide a free-text query, a protein sequence, or an organism name (filters alone are not enough).',
+        },
+    ],
+    input: z.object({
+        query: z
+            .string()
+            .optional()
+            .describe('Free-text query (protein name, gene, keyword, PDB title terms).'),
+        sequence: z
+            .string()
+            .optional()
+            .describe('One-letter amino-acid sequence; triggers an RCSB mmseqs2 sequence-similarity search.'),
+        organism: z
+            .string()
+            .optional()
+            .describe('Filter by source organism scientific name (e.g. "Homo sapiens").'),
+        method: z
+            .string()
+            .optional()
+            .describe('Filter by experimental method (e.g. "X-RAY DIFFRACTION", "ELECTRON MICROSCOPY").'),
+        max_resolution: z
+            .number()
+            .positive()
+            .optional()
+            .describe('Maximum resolution in Å (lower is sharper); applies to experimental structures.'),
+        min_identity: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe('Minimum sequence identity (0–1) for a sequence search. Default 0.'),
+        max_evalue: z
+            .number()
+            .positive()
+            .optional()
+            .describe('Maximum E-value for a sequence search. Default 1.'),
+        content_type: z
+            .enum(['experimental', 'predicted', 'all'])
+            .default('all')
+            .describe('Which structure universe to search: experimental (PDB), predicted (computed models), or all.'),
+        facets: z
+            .array(z.enum(FACET_DIMENSION_NAMES))
+            .optional()
+            .describe('Optional dimensions to summarize as a facet breakdown alongside the hits.'),
+        limit: z.number().int().min(1).max(100).default(25).describe('Maximum hits to return (1–100).'),
+    }),
+    output: z.object({
+        hits: z
+            .array(z
+            .object({
+            id: z.string().describe('Structure identifier (PDB entry ID or computed-model ID).'),
+            source: z
+                .enum(['experimental', 'predicted'])
+                .describe('Which universe the hit came from.'),
+            score: z.number().optional().describe('RCSB relevance score.'),
+            uniprotAccession: z
+                .string()
+                .optional()
+                .describe('UniProt accession parsed from a computed-model ID, when available.'),
+            title: z.string().optional().describe('Structure title (enriched experimental hits).'),
+            method: z
+                .string()
+                .optional()
+                .describe('Experimental method(s) (enriched experimental hits).'),
+            resolution: z
+                .number()
+                .optional()
+                .describe('Resolution in Å (enriched experimental hits).'),
+            organism: z
+                .string()
+                .optional()
+                .describe('Primary source organism (enriched experimental hits).'),
+        })
+            .describe('A ranked structure hit with optional enrichment metadata.'))
+            .describe('Ranked structure hits.'),
+        facets: z
+            .array(facetDimensionSchema)
+            .optional()
+            .describe('Optional facet breakdown when requested.'),
+    }),
+    enrichment: {
+        totalCount: z.number().describe('Total matches upstream before pagination.'),
+        effectiveQuery: z.string().optional().describe('Echoed text query for follow-up calls.'),
+        notice: z
+            .string()
+            .optional()
+            .describe('Advisory note (empty results, predicted-search caveats, truncation).'),
+    },
+    async handler(input, ctx) {
+        if (!input.query && !input.sequence && !input.organism) {
+            throw ctx.fail('no_criteria', 'Provide a query, sequence, or organism to search on.');
+        }
+        const cfg = getServerConfig();
+        const rcsb = getRcsbService();
+        const contentTypes = CONTENT_TYPE_MAP[input.content_type];
+        const facetSpecs = input.facets?.map((d) => buildFacetSpec(d));
+        const result = await rcsb.search({
+            ...(input.query ? { text: input.query } : {}),
+            ...(input.sequence ? { sequence: input.sequence } : {}),
+            ...(input.organism ? { organism: input.organism } : {}),
+            ...(input.method ? { method: input.method } : {}),
+            ...(typeof input.max_resolution === 'number'
+                ? { maxResolution: input.max_resolution }
+                : {}),
+            ...(typeof input.min_identity === 'number' ? { minIdentity: input.min_identity } : {}),
+            ...(typeof input.max_evalue === 'number' ? { maxEvalue: input.max_evalue } : {}),
+            // RCSB scopes by content type; multi-content searches just union both halves.
+            ...(contentTypes.length === 1 ? { contentType: contentTypes[0] } : {}),
+            limit: input.limit,
+        }, ctx, facetSpecs);
+        const experimentalIds = [
+            ...new Set(result.hits.filter((h) => !isPredictedId(h.id)).map((h) => entryIdOf(h.id))),
+        ];
+        const metaById = new Map();
+        if (experimentalIds.length > 0) {
+            for (const meta of await rcsb.getEntries(experimentalIds, ctx))
+                metaById.set(meta.id, meta);
+        }
+        const hits = result.hits.map((h) => toHit(h, metaById));
+        const facets = result.facets?.map((f) => toFacetOutput(f, cfg.facetBucketCap));
+        ctx.enrich.total(result.total);
+        if (input.query)
+            ctx.enrich.echo(input.query);
+        if (hits.length === 0) {
+            ctx.enrich.notice(input.content_type === 'predicted'
+                ? 'No predicted models matched. Predicted search covers computed models indexed by RCSB; try content_type "all".'
+                : 'No structures matched. Broaden the query, drop filters, or switch content_type.');
+        }
+        return { hits, ...(facets ? { facets } : {}) };
+    },
+    format: (result) => {
+        const lines = [`## Structure search — ${result.hits.length} hits`];
+        for (const h of result.hits) {
+            lines.push(`\n### ${h.id} _(${h.source})_`);
+            if (h.title)
+                lines.push(h.title);
+            const meta = [
+                h.method ? `**Method:** ${h.method}` : null,
+                typeof h.resolution === 'number' ? `**Resolution:** ${h.resolution} Å` : null,
+                h.organism ? `**Organism:** ${h.organism}` : null,
+                h.uniprotAccession ? `**UniProt:** ${h.uniprotAccession}` : null,
+                typeof h.score === 'number' ? `**Score:** ${h.score.toFixed(3)}` : null,
+            ].filter(Boolean);
+            if (meta.length > 0)
+                lines.push(meta.join(' | '));
+        }
+        if (result.facets && result.facets.length > 0) {
+            lines.push('\n## Facets');
+            lines.push(...renderFacets(result.facets));
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+/** Build one output hit, folding in enrichment metadata when available. */
+function toHit(hit, metaById) {
+    if (isPredictedId(hit.id)) {
+        const accession = accessionFromCsm(hit.id);
+        return {
+            id: hit.id,
+            source: 'predicted',
+            score: hit.score,
+            ...(accession ? { uniprotAccession: accession } : {}),
+        };
+    }
+    const meta = metaById.get(entryIdOf(hit.id));
+    return {
+        id: hit.id,
+        source: 'experimental',
+        score: hit.score,
+        ...(meta?.title ? { title: meta.title } : {}),
+        ...(meta?.methods && meta.methods.length > 0 ? { method: meta.methods.join(', ') } : {}),
+        ...(typeof meta?.resolution === 'number' ? { resolution: meta.resolution } : {}),
+        ...(meta?.organisms && meta.organisms.length > 0 ? { organism: meta.organisms[0] } : {}),
+    };
+}
+//# sourceMappingURL=search-structures.tool.js.map

package/dist/mcp-server/tools/definitions/search-structures.tool.js.map

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

package/dist/mcp-server/tools/definitions/track-ligands.tool.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview protein_track_ligands — ligand discovery and binding-site
+ * analysis. Resolves a ligand name/formula to chemical component IDs, finds PDB
+ * entries bound to a ligand, or returns the protein residues lining a ligand's
+ * pocket in a structure (via RCSB `rcsb_target_neighbors`).
+ * @module mcp-server/tools/definitions/track-ligands.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const trackLigands: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    mode: z.ZodEnum<{
+        find_ligand: "find_ligand";
+        structures_with_ligand: "structures_with_ligand";
+        binding_site: "binding_site";
+    }>;
+    query: z.ZodOptional<z.ZodString>;
+    comp_id: z.ZodOptional<z.ZodString>;
+    pdb_id: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    mode: z.ZodEnum<{
+        find_ligand: "find_ligand";
+        structures_with_ligand: "structures_with_ligand";
+        binding_site: "binding_site";
+    }>;
+    ligands: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        compId: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        formula: z.ZodOptional<z.ZodString>;
+        formulaWeight: z.ZodOptional<z.ZodNumber>;
+        smiles: z.ZodOptional<z.ZodString>;
+        inchikey: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    structures: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        score: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    bindingSites: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        ligandCompId: z.ZodString;
+        ligandAsymId: z.ZodOptional<z.ZodString>;
+        residues: z.ZodArray<z.ZodObject<{
+            residueCompId: z.ZodString;
+            asymId: z.ZodString;
+            seqId: z.ZodOptional<z.ZodNumber>;
+            distance: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No chemical component matched the name/formula, no structures contain the component, or the structure has no instance of the ligand.";
+    readonly recovery: "Use mode \"find_ligand\" to resolve a name to a component ID first, then confirm the ligand is present in the structure via protein_get_structure.";
+}], {
+    readonly totalCount: z.ZodOptional<z.ZodNumber>;
+    readonly resolvedCompId: z.ZodOptional<z.ZodString>;
+    readonly notice: z.ZodOptional<z.ZodString>;
+}>;
+//# sourceMappingURL=track-ligands.tool.d.ts.map

package/dist/mcp-server/tools/definitions/track-ligands.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-ligands.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/track-ligands.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAqCjE,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0KvB,CAAC"}

package/dist/mcp-server/tools/definitions/track-ligands.tool.js

@@ -0,0 +1,195 @@
+/**
+ * @fileoverview protein_track_ligands — ligand discovery and binding-site
+ * analysis. Resolves a ligand name/formula to chemical component IDs, finds PDB
+ * entries bound to a ligand, or returns the protein residues lining a ligand's
+ * pocket in a structure (via RCSB `rcsb_target_neighbors`).
+ * @module mcp-server/tools/definitions/track-ligands.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getServerConfig } from '../../../config/server-config.js';
+import { getRcsbService } from '../../../services/rcsb/rcsb-service.js';
+import { mapWithConcurrency } from '../../../services/shared/async.js';
+const chemCompSchema = z
+    .object({
+    compId: z.string().describe('Chemical component ID (e.g. STI, HEM).'),
+    name: z.string().optional().describe('Chemical name.'),
+    formula: z.string().optional().describe('Molecular formula.'),
+    formulaWeight: z.number().optional().describe('Formula weight in Da.'),
+    smiles: z.string().optional().describe('Isomeric SMILES.'),
+    inchikey: z.string().optional().describe('InChIKey.'),
+    type: z.string().optional().describe('Component type (e.g. non-polymer).'),
+})
+    .describe('A resolved chemical component (ligand) and its identifiers.');
+const bindingSiteSchema = z
+    .object({
+    ligandCompId: z.string().describe('Bound ligand chemical component ID.'),
+    ligandAsymId: z.string().optional().describe('Ligand instance chain (asym) ID.'),
+    residues: z
+        .array(z
+        .object({
+        residueCompId: z.string().describe('Interacting residue type (e.g. ASP).'),
+        asymId: z.string().describe('Chain ID the residue belongs to.'),
+        seqId: z.number().optional().describe('Residue sequence position.'),
+        distance: z.number().optional().describe('Contact distance to the ligand in Å.'),
+    })
+        .describe('A pocket residue in contact with the ligand.'))
+        .describe('Protein residues lining the pocket, nearest first.'),
+})
+    .describe('A ligand instance and the protein residues lining its pocket.');
+export const trackLigands = tool('protein_track_ligands', {
+    title: 'protein-mcp-server: track ligands',
+    description: 'Ligand discovery and binding-site analysis across the PDB. mode "find_ligand" resolves a name or ' +
+        'formula to chemical component IDs with metadata (formula, weight, SMILES). mode ' +
+        '"structures_with_ligand" returns PDB entries containing a ligand (by exact component ID — get the ' +
+        'ID from find_ligand first). mode "binding_site" returns the protein residues lining a ligand\'s ' +
+        'pocket in a given structure, with contact distances. Binding sites are experimental-only ' +
+        '(computed from deposited coordinates; predicted models carry no bound ligands).',
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    errors: [
+        {
+            reason: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No chemical component matched the name/formula, no structures contain the component, or the structure has no instance of the ligand.',
+            recovery: 'Use mode "find_ligand" to resolve a name to a component ID first, then confirm the ligand is present in the structure via protein_get_structure.',
+        },
+    ],
+    input: z.object({
+        mode: z
+            .enum(['find_ligand', 'structures_with_ligand', 'binding_site'])
+            .describe('Operation: resolve a ligand, find structures containing it, or analyze its binding site.'),
+        query: z.string().optional().describe('Ligand name or formula (mode find_ligand).'),
+        comp_id: z
+            .string()
+            .optional()
+            .describe('Exact chemical component ID (modes structures_with_ligand and binding_site).'),
+        pdb_id: z.string().optional().describe('PDB entry ID (mode binding_site).'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(25)
+            .describe('Maximum results to return (1–100).'),
+    }),
+    output: z.object({
+        mode: z
+            .enum(['find_ligand', 'structures_with_ligand', 'binding_site'])
+            .describe('Echoed mode.'),
+        ligands: z
+            .array(chemCompSchema)
+            .optional()
+            .describe('Resolved chemical components (find_ligand).'),
+        structures: z
+            .array(z
+            .object({
+            id: z.string().describe('PDB entry ID containing the ligand.'),
+            score: z.number().optional().describe('RCSB relevance score.'),
+        })
+            .describe('A PDB entry containing the ligand.'))
+            .optional()
+            .describe('PDB entries containing the ligand (structures_with_ligand).'),
+        bindingSites: z
+            .array(bindingSiteSchema)
+            .optional()
+            .describe('Binding-site residues (binding_site).'),
+    }),
+    enrichment: {
+        totalCount: z
+            .number()
+            .optional()
+            .describe('Total upstream matches before pagination (structures_with_ligand).'),
+        resolvedCompId: z.string().optional().describe('The chemical component ID used to query.'),
+        notice: z
+            .string()
+            .optional()
+            .describe('Advisory note when a mode-specific input is missing or absent.'),
+    },
+    async handler(input, ctx) {
+        const rcsb = getRcsbService();
+        const cfg = getServerConfig();
+        if (input.mode === 'find_ligand') {
+            if (!input.query)
+                throw ctx.fail('not_found', 'mode find_ligand requires a name or formula in "query".');
+            const ids = await rcsb.findChemComps(input.query, input.limit, ctx);
+            const ligands = (await mapWithConcurrency(ids, cfg.fanoutConcurrency, (id) => rcsb.getChemComp(id, ctx))).filter((c) => c != null);
+            if (ligands.length === 0) {
+                throw ctx.fail('not_found', `No chemical component matched "${input.query}".`, {
+                    recovery: {
+                        hint: `No ligand matched "${input.query}". Try the exact name, a synonym, or a formula.`,
+                    },
+                });
+            }
+            return { mode: input.mode, ligands };
+        }
+        if (input.mode === 'structures_with_ligand') {
+            const compId = input.comp_id?.toUpperCase();
+            if (!compId)
+                throw ctx.fail('not_found', 'mode structures_with_ligand requires a "comp_id".');
+            const result = await rcsb.searchByLigand(compId, { limit: input.limit }, ctx);
+            if (result.hits.length === 0) {
+                throw ctx.fail('not_found', `No structures contain ligand ${compId}.`, {
+                    recovery: {
+                        hint: `No PDB entries contain ${compId}. Verify the component ID via mode find_ligand.`,
+                    },
+                });
+            }
+            ctx.enrich.total(result.total);
+            ctx.enrich({ resolvedCompId: compId });
+            return {
+                mode: input.mode,
+                structures: result.hits.map((h) => ({ id: h.id, score: h.score })),
+            };
+        }
+        // binding_site
+        const compId = input.comp_id?.toUpperCase();
+        if (!input.pdb_id)
+            throw ctx.fail('not_found', 'mode binding_site requires a "pdb_id".');
+        const sites = await rcsb.getBindingSites(input.pdb_id, compId, ctx);
+        if (sites.length === 0) {
+            throw ctx.fail('not_found', `No binding-site contacts found in ${input.pdb_id.toUpperCase()}${compId ? ` for ligand ${compId}` : ''}.`, {
+                recovery: {
+                    hint: `Confirm ${input.pdb_id.toUpperCase()} contains${compId ? ` ${compId}` : ' a ligand'} via protein_get_structure; binding sites are experimental-only.`,
+                },
+            });
+        }
+        if (compId)
+            ctx.enrich({ resolvedCompId: compId });
+        return { mode: input.mode, bindingSites: sites };
+    },
+    format: (result) => {
+        const lines = [`## protein_track_ligands — ${result.mode}`];
+        for (const l of result.ligands ?? []) {
+            lines.push(`\n### ${l.compId}${l.name ? ` — ${l.name}` : ''}`);
+            const parts = [
+                l.formula ? `**Formula:** ${l.formula}` : null,
+                typeof l.formulaWeight === 'number' ? `**Weight:** ${l.formulaWeight} Da` : null,
+                l.type ? `**Type:** ${l.type}` : null,
+            ].filter(Boolean);
+            if (parts.length > 0)
+                lines.push(parts.join(' | '));
+            if (l.smiles)
+                lines.push(`**SMILES:** ${l.smiles}`);
+            if (l.inchikey)
+                lines.push(`**InChIKey:** ${l.inchikey}`);
+        }
+        if (result.structures) {
+            lines.push(`\n**${result.structures.length} structures:**`);
+            lines.push(result.structures.map((s) => s.id).join(', '));
+            for (const s of result.structures) {
+                if (typeof s.score === 'number')
+                    lines.push(`- ${s.id} (score ${s.score.toFixed(2)})`);
+            }
+        }
+        for (const site of result.bindingSites ?? []) {
+            lines.push(`\n### Ligand ${site.ligandCompId}${site.ligandAsymId ? ` (chain ${site.ligandAsymId})` : ''}`);
+            for (const r of site.residues) {
+                const pos = r.seqId != null ? `${r.residueCompId}${r.seqId}` : r.residueCompId;
+                const dist = r.distance != null ? ` — ${r.distance.toFixed(2)} Å` : '';
+                lines.push(`- ${pos} (chain ${r.asymId})${dist}`);
+            }
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=track-ligands.tool.js.map

package/dist/mcp-server/tools/definitions/track-ligands.tool.js.map

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

package/dist/services/alignment/alignment-service.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview RCSB Structural Comparison (alignment) service — wraps the hosted
+ * async pairwise alignment API (`/api/v1/structures/submit` → `/results?uuid=`).
+ * Native mode is `pairwise`; multi-structure comparison fans these out. Submit
+ * returns a bare UUID; the results poll returns 404 until the job is computed.
+ * Backs `protein_compare_structures`. No in-process alignment — edge-deployable.
+ * @module services/alignment/alignment-service
+ */
+import type { Context } from '@cyanheads/mcp-ts-core';
+import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
+import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
+import type { ServerConfig } from '../../config/server-config.js';
+/** Alignment method name accepted by the RCSB Structural Comparison API. */
+export type AlignmentMethod = 'tm-align' | 'fatcat-rigid' | 'fatcat-flexible';
+/** One structure (+ optional chain) in a comparison. */
+export interface CompareStructure {
+    asymId?: string;
+    entryId: string;
+}
+/** Scores for one aligned pair. */
+export interface PairScores {
+    alignedResidues?: number;
+    rmsd?: number;
+    sequenceIdentity?: number;
+    tmScore?: number;
+}
+/** Outcome of one pairwise alignment. */
+export type PairOutcome = {
+    status: 'complete';
+    uuid: string;
+    scores: PairScores;
+} | {
+    status: 'computing';
+    uuid: string;
+} | {
+    status: 'failed';
+    error: string;
+};
+export declare class AlignmentService {
+    private readonly submitUrl;
+    private readonly resultsUrl;
+    constructor(_config: AppConfig, _storage: StorageService, serverConfig: ServerConfig);
+    /** Submit a pairwise alignment job; returns the job UUID. */
+    submit(a: CompareStructure, b: CompareStructure, method: AlignmentMethod, ctx: Context): Promise<string>;
+    /**
+     * Run one pairwise alignment end-to-end: submit, then bounded-poll the result.
+     * Never throws — a submit/poll failure degrades to `{ status: 'failed' }` so
+     * one bad pair doesn't sink the whole comparison.
+     */
+    comparePair(a: CompareStructure, b: CompareStructure, method: AlignmentMethod, timeoutMs: number, ctx: Context): Promise<PairOutcome>;
+    /** Single poll of a job's results. 404 = still computing; a result body = ready. */
+    private pollResult;
+}
+export declare function initAlignmentService(config: AppConfig, storage: StorageService, serverConfig: ServerConfig): void;
+export declare function getAlignmentService(): AlignmentService;
+//# sourceMappingURL=alignment-service.d.ts.map

package/dist/services/alignment/alignment-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignment-service.d.ts","sourceRoot":"","sources":["../../../src/services/alignment/alignment-service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAI9D,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,cAAc,GAAG,iBAAiB,CAAC;AAE9E,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mCAAmC;AACnC,MAAM,WAAW,UAAU;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,yCAAyC;AACzC,MAAM,MAAM,WAAW,GACnB;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GACxD;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY;IAKpF,6DAA6D;IACvD,MAAM,CACV,CAAC,EAAE,gBAAgB,EACnB,CAAC,EAAE,gBAAgB,EACnB,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,MAAM,CAAC;IAsBlB;;;;OAIG;IACG,WAAW,CACf,CAAC,EAAE,gBAAgB,EACnB,CAAC,EAAE,gBAAgB,EACnB,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,WAAW,CAAC;IAuBvB,oFAAoF;YACtE,UAAU;CAazB;AAmDD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,YAAY,GACzB,IAAI,CAEN;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,CAItD"}