@cyanheads/protein-mcp-server 0.1.0

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

@@ -0,0 +1,129 @@
+/**
+ * @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 { withAsyncPoll } from '../shared/async.js';
+import { fetchResponse, fetchText, parseJson } from '../shared/http.js';
+export class AlignmentService {
+    submitUrl;
+    resultsUrl;
+    constructor(_config, _storage, serverConfig) {
+        this.submitUrl = `${serverConfig.rcsbAlignmentBaseUrl}/api/v1/structures/submit`;
+        this.resultsUrl = `${serverConfig.rcsbAlignmentBaseUrl}/api/v1/structures/results`;
+    }
+    /** Submit a pairwise alignment job; returns the job UUID. */
+    async submit(a, b, method, ctx) {
+        const query = {
+            context: {
+                mode: 'pairwise',
+                // The API's method schema is additionalProperties:false with only `name`
+                // for tm-align — sending an (even empty) `parameters` object fails
+                // validation. Methods that accept parameters all default sensibly.
+                method: { name: method },
+                structures: [toQueryStructure(a), toQueryStructure(b)],
+            },
+        };
+        const url = `${this.submitUrl}?query=${encodeURIComponent(JSON.stringify(query))}`;
+        const text = await fetchText(url, ctx, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            operation: 'AlignmentService.submit',
+            label: 'RCSB Alignment API',
+            baseDelayMs: 500,
+        });
+        return text.trim().replace(/^"|"$/g, '');
+    }
+    /**
+     * 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.
+     */
+    async comparePair(a, b, method, timeoutMs, ctx) {
+        let uuid;
+        try {
+            uuid = await this.submit(a, b, method, ctx);
+        }
+        catch (err) {
+            return { status: 'failed', error: err instanceof Error ? err.message : String(err) };
+        }
+        try {
+            const outcome = await withAsyncPoll({
+                step: () => this.pollResult(uuid, ctx),
+                timeoutMs,
+                ctx,
+                intervalMs: 1500,
+                maxIntervalMs: 2500,
+            });
+            return outcome.status === 'complete'
+                ? { status: 'complete', uuid, scores: outcome.value }
+                : { status: 'computing', uuid };
+        }
+        catch (err) {
+            return { status: 'failed', error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    /** Single poll of a job's results. 404 = still computing; a result body = ready. */
+    async pollResult(uuid, ctx) {
+        const res = await fetchResponse(`${this.resultsUrl}?uuid=${encodeURIComponent(uuid)}`, ctx, {
+            operation: 'AlignmentService.pollResult',
+            timeoutMs: 15_000,
+            baseDelayMs: 400,
+        });
+        if (res.status === 404)
+            return { ready: false };
+        if (!res.ok)
+            throw new Error(`RCSB Alignment results returned HTTP ${res.status}`);
+        const raw = parseJson(await res.text(), 'RCSB Alignment API');
+        const first = raw.results?.[0];
+        if (!first)
+            return { ready: false };
+        return { ready: true, value: normalizeScores(first) };
+    }
+}
+function toQueryStructure(s) {
+    return {
+        entry_id: s.entryId.toUpperCase(),
+        ...(s.asymId ? { selection: { asym_id: s.asymId } } : {}),
+    };
+}
+/**
+ * Extract TM-score / RMSD / aligned-residue count from a result row. The summary
+ * carries a heterogeneous `scores` array (`{ type, value }`); match by type name
+ * so a field rename upstream degrades a single metric rather than the whole row.
+ */
+function normalizeScores(result) {
+    const summary = result.summary ?? {};
+    const scores = summary.scores ?? [];
+    const byType = (re) => scores.find((s) => s.type && re.test(s.type))?.value;
+    const out = {};
+    const tm = byType(/tm[\s_-]?score/i);
+    const rmsd = byType(/rmsd/i);
+    const seqId = byType(/seq.*id|identity/i);
+    const aligned = summary.n_aln_residue_pairs ??
+        summary.aligned_residues ??
+        summary.n_aligned_residues ??
+        byType(/aligned/i);
+    if (typeof tm === 'number')
+        out.tmScore = tm;
+    if (typeof rmsd === 'number')
+        out.rmsd = rmsd;
+    if (typeof seqId === 'number')
+        out.sequenceIdentity = seqId;
+    if (typeof aligned === 'number')
+        out.alignedResidues = aligned;
+    return out;
+}
+let _service;
+export function initAlignmentService(config, storage, serverConfig) {
+    _service = new AlignmentService(config, storage, serverConfig);
+}
+export function getAlignmentService() {
+    if (!_service)
+        throw new Error('AlignmentService not initialized — call initAlignmentService() in setup()');
+    return _service;
+}
+//# sourceMappingURL=alignment-service.js.map

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

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

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

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview AlphaFold service — wraps the AlphaFold Protein Structure
+ * Database API (`/api/prediction/{accession}`). Kept as a direct provider (not
+ * only via 3D-Beacons) because it carries confidence detail the Beacons summary
+ * abbreviates: mean pLDDT, the four confidence-bucket fractions, and the PAE
+ * documentation URL. Backs `protein_get_structure` (predicted) and the `af://`
+ * resource.
+ * @module services/alphafold/alphafold-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';
+/** Fractions of residues in each pLDDT confidence band (0–1). */
+export interface ConfidenceBuckets {
+    confident: number;
+    low: number;
+    veryHigh: number;
+    veryLow: number;
+}
+/** A normalized AlphaFold prediction. */
+export interface AlphaFoldModel {
+    bcifUrl?: string;
+    /** Coordinate / metadata URLs. */
+    cifUrl?: string;
+    /** Residue fractions in each confidence band. */
+    confidenceBuckets?: ConfidenceBuckets;
+    /** AlphaFold model entry ID (e.g. `AF-P69905-F1`). */
+    entryId?: string;
+    /** Mean pLDDT across the model (0–100). */
+    meanPlddt?: number;
+    /** Model version (latest). */
+    modelVersion?: number;
+    /** Source organism scientific name. */
+    organism?: string;
+    paeDocUrl?: string;
+    paeImageUrl?: string;
+    pdbUrl?: string;
+    /** Predicted sequence length. */
+    sequenceLength?: number;
+    /** UniProt accession the model predicts. */
+    uniprotAccession: string;
+    /** UniProt protein description. */
+    uniprotDescription?: string;
+}
+export declare class AlphaFoldService {
+    private readonly baseUrl;
+    constructor(_config: AppConfig, _storage: StorageService, serverConfig: ServerConfig);
+    /**
+     * Fetch the AlphaFold prediction for a UniProt accession. Returns `null` when
+     * no model exists (404); a malformed accession (400) bubbles as `InvalidParams`.
+     */
+    getPrediction(accession: string, ctx: Context): Promise<AlphaFoldModel | null>;
+}
+export declare function initAlphaFoldService(config: AppConfig, storage: StorageService, serverConfig: ServerConfig): void;
+export declare function getAlphaFoldService(): AlphaFoldService;
+//# sourceMappingURL=alphafold-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"alphafold-service.d.ts","sourceRoot":"","sources":["../../../src/services/alphafold/alphafold-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAG9D,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,gBAAgB,EAAE,MAAM,CAAC;IACzB,mCAAmC;IACnC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAqBD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY;IAIpF;;;OAGG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;CAiBrF;AA0CD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,YAAY,GACzB,IAAI,CAEN;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,CAItD"}

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

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview AlphaFold service — wraps the AlphaFold Protein Structure
+ * Database API (`/api/prediction/{accession}`). Kept as a direct provider (not
+ * only via 3D-Beacons) because it carries confidence detail the Beacons summary
+ * abbreviates: mean pLDDT, the four confidence-bucket fractions, and the PAE
+ * documentation URL. Backs `protein_get_structure` (predicted) and the `af://`
+ * resource.
+ * @module services/alphafold/alphafold-service
+ */
+import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
+import { fetchJson } from '../shared/http.js';
+export class AlphaFoldService {
+    baseUrl;
+    constructor(_config, _storage, serverConfig) {
+        this.baseUrl = serverConfig.alphafoldBaseUrl;
+    }
+    /**
+     * Fetch the AlphaFold prediction for a UniProt accession. Returns `null` when
+     * no model exists (404); a malformed accession (400) bubbles as `InvalidParams`.
+     */
+    async getPrediction(accession, ctx) {
+        const url = `${this.baseUrl}/api/prediction/${encodeURIComponent(accession.toUpperCase())}`;
+        let raw;
+        try {
+            raw = await fetchJson(url, ctx, {
+                operation: 'AlphaFoldService.getPrediction',
+                label: 'AlphaFold DB',
+                baseDelayMs: 300,
+            });
+        }
+        catch (err) {
+            if (err instanceof McpError && err.code === JsonRpcErrorCode.NotFound)
+                return null;
+            throw err;
+        }
+        const first = raw[0];
+        if (!first)
+            return null;
+        return normalizePrediction(accession.toUpperCase(), first);
+    }
+}
+function normalizePrediction(accession, raw) {
+    const buckets = confidenceBuckets(raw);
+    return {
+        uniprotAccession: raw.uniprotAccession ?? accession,
+        ...(raw.entryId ? { entryId: raw.entryId } : {}),
+        ...(typeof raw.globalMetricValue === 'number' ? { meanPlddt: raw.globalMetricValue } : {}),
+        ...(buckets ? { confidenceBuckets: buckets } : {}),
+        ...(raw.cifUrl ? { cifUrl: raw.cifUrl } : {}),
+        ...(raw.pdbUrl ? { pdbUrl: raw.pdbUrl } : {}),
+        ...(raw.bcifUrl ? { bcifUrl: raw.bcifUrl } : {}),
+        ...(raw.paeImageUrl ? { paeImageUrl: raw.paeImageUrl } : {}),
+        ...(raw.paeDocUrl ? { paeDocUrl: raw.paeDocUrl } : {}),
+        ...(typeof raw.latestVersion === 'number' ? { modelVersion: raw.latestVersion } : {}),
+        ...(raw.organismScientificName ? { organism: raw.organismScientificName } : {}),
+        ...(raw.uniprotDescription ? { uniprotDescription: raw.uniprotDescription } : {}),
+        ...(raw.uniprotSequence ? { sequenceLength: raw.uniprotSequence.length } : {}),
+    };
+}
+function confidenceBuckets(raw) {
+    const { fractionPlddtVeryLow, fractionPlddtLow, fractionPlddtConfident, fractionPlddtVeryHigh } = raw;
+    if (typeof fractionPlddtVeryLow !== 'number' &&
+        typeof fractionPlddtLow !== 'number' &&
+        typeof fractionPlddtConfident !== 'number' &&
+        typeof fractionPlddtVeryHigh !== 'number') {
+        return;
+    }
+    return {
+        veryLow: fractionPlddtVeryLow ?? 0,
+        low: fractionPlddtLow ?? 0,
+        confident: fractionPlddtConfident ?? 0,
+        veryHigh: fractionPlddtVeryHigh ?? 0,
+    };
+}
+let _service;
+export function initAlphaFoldService(config, storage, serverConfig) {
+    _service = new AlphaFoldService(config, storage, serverConfig);
+}
+export function getAlphaFoldService() {
+    if (!_service)
+        throw new Error('AlphaFoldService not initialized — call initAlphaFoldService() in setup()');
+    return _service;
+}
+//# sourceMappingURL=alphafold-service.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"alphafold-service.js","sourceRoot":"","sources":["../../../src/services/alphafold/alphafold-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAG3E,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAuD9C,MAAM,OAAO,gBAAgB;IACV,OAAO,CAAS;IAEjC,YAAY,OAAkB,EAAE,QAAwB,EAAE,YAA0B;QAClF,IAAI,CAAC,OAAO,GAAG,YAAY,CAAC,gBAAgB,CAAC;IAC/C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,aAAa,CAAC,SAAiB,EAAE,GAAY;QACjD,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,mBAAmB,kBAAkB,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;QAC5F,IAAI,GAAoB,CAAC;QACzB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,SAAS,CAAkB,GAAG,EAAE,GAAG,EAAE;gBAC/C,SAAS,EAAE,gCAAgC;gBAC3C,KAAK,EAAE,cAAc;gBACrB,WAAW,EAAE,GAAG;aACjB,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,QAAQ,IAAI,GAAG,CAAC,IAAI,KAAK,gBAAgB,CAAC,QAAQ;gBAAE,OAAO,IAAI,CAAC;YACnF,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,MAAM,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACrB,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,OAAO,mBAAmB,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,KAAK,CAAC,CAAC;IAC7D,CAAC;CACF;AAED,SAAS,mBAAmB,CAAC,SAAiB,EAAE,GAAkB;IAChE,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACvC,OAAO;QACL,gBAAgB,EAAE,GAAG,CAAC,gBAAgB,IAAI,SAAS;QACnD,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChD,GAAG,CAAC,OAAO,GAAG,CAAC,iBAAiB,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1F,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChD,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,GAAG,CAAC,OAAO,GAAG,CAAC,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrF,GAAG,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,sBAAsB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/E,GAAG,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,GAAG,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjF,GAAG,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,GAAG,CAAC,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/E,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAkB;IAC3C,MAAM,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,GAC7F,GAAG,CAAC;IACN,IACE,OAAO,oBAAoB,KAAK,QAAQ;QACxC,OAAO,gBAAgB,KAAK,QAAQ;QACpC,OAAO,sBAAsB,KAAK,QAAQ;QAC1C,OAAO,qBAAqB,KAAK,QAAQ,EACzC,CAAC;QACD,OAAO;IACT,CAAC;IACD,OAAO;QACL,OAAO,EAAE,oBAAoB,IAAI,CAAC;QAClC,GAAG,EAAE,gBAAgB,IAAI,CAAC;QAC1B,SAAS,EAAE,sBAAsB,IAAI,CAAC;QACtC,QAAQ,EAAE,qBAAqB,IAAI,CAAC;KACrC,CAAC;AACJ,CAAC;AAED,IAAI,QAAsC,CAAC;AAE3C,MAAM,UAAU,oBAAoB,CAClC,MAAiB,EACjB,OAAuB,EACvB,YAA0B;IAE1B,QAAQ,GAAG,IAAI,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,IAAI,CAAC,QAAQ;QACX,MAAM,IAAI,KAAK,CAAC,2EAA2E,CAAC,CAAC;IAC/F,OAAO,QAAQ,CAAC;AAClB,CAAC"}

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

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview 3D-Beacons service — wraps the EMBL-EBI federated structure API
+ * (`/uniprot/summary/{accession}.json`), which fronts experimental (PDBe) and
+ * predicted (AlphaFold DB, AlphaFill, SWISS-MODEL, BFVD, …) models behind one
+ * UniProt-keyed interface. Backs the predicted half of `protein_search_structures`
+ * and `best_available` resolution in `protein_get_structure`. A 404 returns an
+ * empty object upstream — treated as "no models", distinct from a transport error.
+ * @module services/beacons/beacons-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';
+/** A single federated model summary. */
+export interface BeaconModel {
+    /** Average local confidence score (predicted models only). */
+    confidenceAvgLocalScore?: number;
+    /** Confidence metric type (e.g. "pLDDT", "QMEANDisCo") when present. */
+    confidenceType?: string;
+    /** UniProt residue coverage fraction (0–1) the model spans. */
+    coverage?: number;
+    /** Experimental method (experimental models only). */
+    experimentalMethod?: string;
+    /** `EXPERIMENTALLY DETERMINED`, `AB-INITIO`, `TEMPLATE-BASED`, … */
+    modelCategory?: string;
+    /** Provider model identifier. */
+    modelIdentifier: string;
+    /** Coordinate file URL. */
+    modelUrl?: string;
+    /** Originating provider (e.g. "AlphaFold DB", "PDBe", "SWISS-MODEL"). */
+    provider?: string;
+    /** Resolution in Å (experimental models only). */
+    resolution?: number;
+}
+/** A UniProt accession's federated model set. */
+export interface BeaconSummary {
+    /** The queried UniProt accession. */
+    accession: string;
+    /** Whether the upstream returned any entry at all. */
+    found: boolean;
+    /** Federated models, experimental and predicted. */
+    models: BeaconModel[];
+}
+export declare class BeaconsService {
+    private readonly baseUrl;
+    constructor(_config: AppConfig, _storage: StorageService, serverConfig: ServerConfig);
+    /** Fetch the federated model summary for a UniProt accession. */
+    getSummary(accession: string, ctx: Context): Promise<BeaconSummary>;
+}
+export declare function initBeaconsService(config: AppConfig, storage: StorageService, serverConfig: ServerConfig): void;
+export declare function getBeaconsService(): BeaconsService;
+//# sourceMappingURL=beacons-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"beacons-service.d.ts","sourceRoot":"","sources":["../../../src/services/beacons/beacons-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;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;AAG9D,wCAAwC;AACxC,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,iDAAiD;AACjD,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,KAAK,EAAE,OAAO,CAAC;IACf,oDAAoD;IACpD,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAmBD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY;IAIpF,iEAAiE;IAC3D,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC;CAoB1E;AAoBD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,YAAY,GACzB,IAAI,CAEN;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAIlD"}

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

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview 3D-Beacons service — wraps the EMBL-EBI federated structure API
+ * (`/uniprot/summary/{accession}.json`), which fronts experimental (PDBe) and
+ * predicted (AlphaFold DB, AlphaFill, SWISS-MODEL, BFVD, …) models behind one
+ * UniProt-keyed interface. Backs the predicted half of `protein_search_structures`
+ * and `best_available` resolution in `protein_get_structure`. A 404 returns an
+ * empty object upstream — treated as "no models", distinct from a transport error.
+ * @module services/beacons/beacons-service
+ */
+import { fetchResponse, parseJson } from '../shared/http.js';
+export class BeaconsService {
+    baseUrl;
+    constructor(_config, _storage, serverConfig) {
+        this.baseUrl = serverConfig.beaconsBaseUrl;
+    }
+    /** Fetch the federated model summary for a UniProt accession. */
+    async getSummary(accession, ctx) {
+        const acc = accession.toUpperCase();
+        const url = `${this.baseUrl}/uniprot/summary/${encodeURIComponent(acc)}.json`;
+        const res = await fetchResponse(url, ctx, {
+            operation: 'BeaconsService.getSummary',
+            baseDelayMs: 500,
+        });
+        if (res.status === 404)
+            return { accession: acc, found: false, models: [] };
+        if (!res.ok) {
+            // Surface non-404 failures via the framework's status mapping by re-reading the body.
+            throw new Error(`3D-Beacons returned HTTP ${res.status} for ${acc}`);
+        }
+        const text = await res.text();
+        const raw = parseJson(text, '3D-Beacons');
+        const models = (raw.structures ?? [])
+            .map((s) => s.summary)
+            .filter((s) => s != null && !!s.model_identifier)
+            .map(normalizeModel);
+        return { accession: raw.uniprot_entry?.ac ?? acc, found: models.length > 0, models };
+    }
+}
+function normalizeModel(raw) {
+    return {
+        modelIdentifier: raw.model_identifier,
+        ...(raw.model_category ? { modelCategory: raw.model_category } : {}),
+        ...(raw.provider ? { provider: raw.provider } : {}),
+        ...(raw.model_url ? { modelUrl: raw.model_url } : {}),
+        ...(typeof raw.coverage === 'number' ? { coverage: raw.coverage } : {}),
+        ...(typeof raw.resolution === 'number' ? { resolution: raw.resolution } : {}),
+        ...(raw.experimental_method ? { experimentalMethod: raw.experimental_method } : {}),
+        ...(raw.confidence_type ? { confidenceType: raw.confidence_type } : {}),
+        ...(typeof raw.confidence_avg_local_score === 'number'
+            ? { confidenceAvgLocalScore: raw.confidence_avg_local_score }
+            : {}),
+    };
+}
+let _service;
+export function initBeaconsService(config, storage, serverConfig) {
+    _service = new BeaconsService(config, storage, serverConfig);
+}
+export function getBeaconsService() {
+    if (!_service)
+        throw new Error('BeaconsService not initialized — call initBeaconsService() in setup()');
+    return _service;
+}
+//# sourceMappingURL=beacons-service.js.map

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

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

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

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Foldseek service — wraps the public Foldseek structural-search
+ * ticket API (`/api/ticket` → poll `/api/ticket/{id}` → `/api/result/{id}/{n}`).
+ * Submits a query coordinate file against experimental + predicted databases and
+ * returns fold-similarity hits. Backs `protein_find_similar` (`by: structure`).
+ * Async: the ticket status field drives completion, not the HTTP code.
+ * @module services/foldseek/foldseek-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';
+/** A single fold-similarity hit. */
+export interface FoldseekHit {
+    /** Aligned length. */
+    alignmentLength?: number;
+    /** Chain ID (pdb targets). */
+    chain?: string;
+    /** Source database the hit came from. */
+    database: string;
+    /** Alignment E-value. */
+    evalue?: number;
+    /** PDB entry ID (pdb targets). */
+    pdbId?: string;
+    /** Match probability (0–1). */
+    probability?: number;
+    /** Alignment bit score. */
+    score?: number;
+    /** Sequence identity (0–1) over the alignment. */
+    sequenceIdentity?: number;
+    /** Raw target identifier as returned by Foldseek. */
+    target: string;
+    /** Resolved target kind. */
+    targetType: 'pdb' | 'alphafold' | 'other';
+    /** UniProt accession (AlphaFold targets). */
+    uniprotAccession?: string;
+}
+/** Outcome of a structural search. */
+export type FoldseekOutcome = {
+    status: 'complete';
+    ticketId: string;
+    hits: FoldseekHit[];
+} | {
+    status: 'computing';
+    ticketId: string;
+} | {
+    status: 'failed';
+    error: string;
+};
+export declare class FoldseekService {
+    private readonly baseUrl;
+    constructor(_config: AppConfig, _storage: StorageService, serverConfig: ServerConfig);
+    /**
+     * Submit a structure and bounded-poll for fold-similarity hits. Never throws —
+     * a submit/poll failure degrades to `{ status: 'failed' }`.
+     */
+    search(params: {
+        fileContent: string;
+        fileName: string;
+        databases: string[];
+        mode: string;
+        limit: number;
+        timeoutMs: number;
+    }, ctx: Context): Promise<FoldseekOutcome>;
+    private submit;
+    private pollTicket;
+    private fetchResults;
+}
+export declare function initFoldseekService(config: AppConfig, storage: StorageService, serverConfig: ServerConfig): void;
+export declare function getFoldseekService(): FoldseekService;
+//# sourceMappingURL=foldseek-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"foldseek-service.d.ts","sourceRoot":"","sources":["../../../src/services/foldseek/foldseek-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,oCAAoC;AACpC,MAAM,WAAW,WAAW;IAC1B,sBAAsB;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,UAAU,EAAE,KAAK,GAAG,WAAW,GAAG,OAAO,CAAC;IAC1C,6CAA6C;IAC7C,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,sCAAsC;AACtC,MAAM,MAAM,eAAe,GACvB;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,EAAE,CAAA;CAAE,GAC7D;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY;IAIpF;;;OAGG;IACG,MAAM,CACV,MAAM,EAAE;QACN,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;KACnB,EACD,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,eAAe,CAAC;YA8Bb,MAAM;YA4BN,UAAU;YAsBV,YAAY;CAuB3B;AA0CD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,YAAY,GACzB,IAAI,CAEN;AAED,wBAAgB,kBAAkB,IAAI,eAAe,CAIpD"}

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

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview Foldseek service — wraps the public Foldseek structural-search
+ * ticket API (`/api/ticket` → poll `/api/ticket/{id}` → `/api/result/{id}/{n}`).
+ * Submits a query coordinate file against experimental + predicted databases and
+ * returns fold-similarity hits. Backs `protein_find_similar` (`by: structure`).
+ * Async: the ticket status field drives completion, not the HTTP code.
+ * @module services/foldseek/foldseek-service
+ */
+import { withAsyncPoll } from '../shared/async.js';
+import { fetchJson } from '../shared/http.js';
+export class FoldseekService {
+    baseUrl;
+    constructor(_config, _storage, serverConfig) {
+        this.baseUrl = serverConfig.foldseekBaseUrl;
+    }
+    /**
+     * Submit a structure and bounded-poll for fold-similarity hits. Never throws —
+     * a submit/poll failure degrades to `{ status: 'failed' }`.
+     */
+    async search(params, ctx) {
+        let ticketId;
+        try {
+            ticketId = await this.submit(params.fileContent, params.fileName, params.databases, params.mode, ctx);
+        }
+        catch (err) {
+            return { status: 'failed', error: err instanceof Error ? err.message : String(err) };
+        }
+        try {
+            const outcome = await withAsyncPoll({
+                step: () => this.pollTicket(ticketId, params.limit, ctx),
+                timeoutMs: params.timeoutMs,
+                ctx,
+                intervalMs: 1500,
+                maxIntervalMs: 2500,
+            });
+            return outcome.status === 'complete'
+                ? { status: 'complete', ticketId, hits: outcome.value }
+                : { status: 'computing', ticketId };
+        }
+        catch (err) {
+            return { status: 'failed', error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    async submit(fileContent, fileName, databases, mode, ctx) {
+        const form = new FormData();
+        form.append('q', new Blob([fileContent], { type: 'chemical/x-pdb' }), fileName);
+        for (const db of databases)
+            form.append('database[]', db);
+        form.append('mode', mode);
+        // fetchWithTimeout sets the multipart boundary header from the FormData body.
+        const raw = await fetchJson(`${this.baseUrl}/api/ticket`, ctx, {
+            method: 'POST',
+            body: form,
+            operation: 'FoldseekService.submit',
+            label: 'Foldseek',
+            baseDelayMs: 1000,
+            maxRetries: 1,
+        });
+        if (!raw.id)
+            throw new Error('Foldseek did not return a ticket ID');
+        return raw.id;
+    }
+    async pollTicket(ticketId, limit, ctx) {
+        const ticket = await fetchJson(`${this.baseUrl}/api/ticket/${encodeURIComponent(ticketId)}`, ctx, {
+            operation: 'FoldseekService.pollTicket',
+            label: 'Foldseek',
+            timeoutMs: 15_000,
+            baseDelayMs: 400,
+        });
+        const status = (ticket.status ?? '').toUpperCase();
+        if (status === 'ERROR')
+            throw new Error('Foldseek reported an error processing the structure');
+        if (status !== 'COMPLETE')
+            return { ready: false };
+        const hits = await this.fetchResults(ticketId, limit, ctx);
+        return { ready: true, value: hits };
+    }
+    async fetchResults(ticketId, limit, ctx) {
+        const raw = await fetchJson(`${this.baseUrl}/api/result/${encodeURIComponent(ticketId)}/0`, ctx, { operation: 'FoldseekService.fetchResults', label: 'Foldseek', baseDelayMs: 400 });
+        const hits = [];
+        for (const dbResult of raw.results ?? []) {
+            const db = dbResult.db ?? 'unknown';
+            for (const group of dbResult.alignments ?? []) {
+                for (const aln of group ?? []) {
+                    if (!aln.target)
+                        continue;
+                    hits.push(normalizeHit(aln, db));
+                    if (hits.length >= limit)
+                        return hits;
+                }
+            }
+        }
+        return hits;
+    }
+}
+// ─── Normalizers ──────────────────────────────────────────────────────────────
+function normalizeHit(aln, database) {
+    const target = aln.target;
+    const hit = { target, database, ...parseTarget(target) };
+    if (typeof aln.seqId === 'number')
+        hit.sequenceIdentity = aln.seqId;
+    if (typeof aln.alnLength === 'number')
+        hit.alignmentLength = aln.alnLength;
+    if (typeof aln.prob === 'number')
+        hit.probability = aln.prob;
+    if (typeof aln.eval === 'number')
+        hit.evalue = aln.eval;
+    if (typeof aln.score === 'number')
+        hit.score = aln.score;
+    return hit;
+}
+/** Resolve a Foldseek target header to an addressable identifier. */
+function parseTarget(target) {
+    const af = /^AF-([A-Za-z0-9]+)-F\d+/.exec(target);
+    if (af)
+        return { targetType: 'alphafold', uniprotAccession: af[1] };
+    const pdb = /^(\d[A-Za-z0-9]{3})[_-]([A-Za-z0-9]+)/.exec(target);
+    if (pdb)
+        return { targetType: 'pdb', pdbId: pdb[1].toUpperCase(), chain: pdb[2] };
+    return { targetType: 'other' };
+}
+let _service;
+export function initFoldseekService(config, storage, serverConfig) {
+    _service = new FoldseekService(config, storage, serverConfig);
+}
+export function getFoldseekService() {
+    if (!_service)
+        throw new Error('FoldseekService not initialized — call initFoldseekService() in setup()');
+    return _service;
+}
+//# sourceMappingURL=foldseek-service.js.map

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

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