@cyanheads/protein-mcp-server 0.1.0

package/dist/config/server-config.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Server-specific configuration parsed from environment variables.
+ * Every value is optional with a public-endpoint default — the server runs out
+ * of the box with no env file. No API keys: all upstreams are keyless.
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+declare const ServerConfigSchema: z.ZodObject<{
+    rcsbSearchBaseUrl: z.ZodDefault<z.ZodString>;
+    rcsbDataBaseUrl: z.ZodDefault<z.ZodString>;
+    rcsbFilesBaseUrl: z.ZodDefault<z.ZodString>;
+    rcsbAlignmentBaseUrl: z.ZodDefault<z.ZodString>;
+    beaconsBaseUrl: z.ZodDefault<z.ZodString>;
+    alphafoldBaseUrl: z.ZodDefault<z.ZodString>;
+    foldseekBaseUrl: z.ZodDefault<z.ZodString>;
+    uniprotBaseUrl: z.ZodDefault<z.ZodString>;
+    interproBaseUrl: z.ZodDefault<z.ZodString>;
+    asyncPollTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    maxBatchIds: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    maxCompareStructures: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    facetBucketCap: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    fanoutConcurrency: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type ServerConfig = z.infer<typeof ServerConfigSchema>;
+export declare function getServerConfig(): ServerConfig;
+export {};
+//# sourceMappingURL=server-config.d.ts.map

package/dist/config/server-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;iBAkFtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAkB9C"}

package/dist/config/server-config.js

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Server-specific configuration parsed from environment variables.
+ * Every value is optional with a public-endpoint default — the server runs out
+ * of the box with no env file. No API keys: all upstreams are keyless.
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
+const ServerConfigSchema = z.object({
+    rcsbSearchBaseUrl: z
+        .string()
+        .url()
+        .default('https://search.rcsb.org')
+        .describe('Base URL for the RCSB Search API v2.'),
+    rcsbDataBaseUrl: z
+        .string()
+        .url()
+        .default('https://data.rcsb.org')
+        .describe('Base URL for the RCSB Data API (REST + GraphQL).'),
+    rcsbFilesBaseUrl: z
+        .string()
+        .url()
+        .default('https://files.rcsb.org')
+        .describe('Base URL for RCSB coordinate-file downloads.'),
+    rcsbAlignmentBaseUrl: z
+        .string()
+        .url()
+        .default('https://alignment.rcsb.org')
+        .describe('Base URL for the RCSB Structural Comparison (alignment) service.'),
+    beaconsBaseUrl: z
+        .string()
+        .url()
+        .default('https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/api')
+        .describe('Base URL for the 3D-Beacons federated structure API.'),
+    alphafoldBaseUrl: z
+        .string()
+        .url()
+        .default('https://alphafold.ebi.ac.uk')
+        .describe('Base URL for the AlphaFold Protein Structure Database API.'),
+    foldseekBaseUrl: z
+        .string()
+        .url()
+        .default('https://search.foldseek.com')
+        .describe('Base URL for the Foldseek structural-similarity search service.'),
+    uniprotBaseUrl: z
+        .string()
+        .url()
+        .default('https://rest.uniprot.org')
+        .describe('Base URL for the UniProt REST API.'),
+    interproBaseUrl: z
+        .string()
+        .url()
+        .default('https://www.ebi.ac.uk/interpro/api')
+        .describe('Base URL for the InterPro REST API.'),
+    asyncPollTimeoutMs: z.coerce
+        .number()
+        .int()
+        .min(1000)
+        .default(30_000)
+        .describe('Max wall-clock to poll an async job (alignment / Foldseek) before returning a "still computing" result.'),
+    maxBatchIds: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .default(25)
+        .describe('Cap on the number of IDs accepted by protein_get_structure in one batch.'),
+    maxCompareStructures: z.coerce
+        .number()
+        .int()
+        .min(2)
+        .max(25)
+        .default(10)
+        .describe('Cap on structures per protein_compare_structures call (bounds pairwise fan-out).'),
+    facetBucketCap: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(500)
+        .default(50)
+        .describe('Default cap on buckets returned per protein_analyze_collection dimension.'),
+    fanoutConcurrency: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(16)
+        .default(5)
+        .describe('Max concurrent upstream requests for per-ID / per-pair fan-out.'),
+});
+let _config;
+export function getServerConfig() {
+    _config ??= parseEnvConfig(ServerConfigSchema, {
+        rcsbSearchBaseUrl: 'RCSB_SEARCH_BASE_URL',
+        rcsbDataBaseUrl: 'RCSB_DATA_BASE_URL',
+        rcsbFilesBaseUrl: 'RCSB_FILES_BASE_URL',
+        rcsbAlignmentBaseUrl: 'RCSB_ALIGNMENT_BASE_URL',
+        beaconsBaseUrl: 'BEACONS_BASE_URL',
+        alphafoldBaseUrl: 'ALPHAFOLD_BASE_URL',
+        foldseekBaseUrl: 'FOLDSEEK_BASE_URL',
+        uniprotBaseUrl: 'UNIPROT_BASE_URL',
+        interproBaseUrl: 'INTERPRO_BASE_URL',
+        asyncPollTimeoutMs: 'PROTEIN_ASYNC_POLL_TIMEOUT_MS',
+        maxBatchIds: 'PROTEIN_MAX_BATCH_IDS',
+        maxCompareStructures: 'PROTEIN_MAX_COMPARE_STRUCTURES',
+        facetBucketCap: 'PROTEIN_FACET_BUCKET_CAP',
+        fanoutConcurrency: 'PROTEIN_FANOUT_CONCURRENCY',
+    });
+    return _config;
+}
+//# sourceMappingURL=server-config.js.map

package/dist/config/server-config.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview protein-mcp-server MCP server entry point. Federates experimental
+ * (PDB) and predicted (AlphaFold / 3D-Beacons) protein structures behind one tool
+ * surface; initializes the six upstream services in setup().
+ * @module index
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG"}

package/dist/index.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview protein-mcp-server MCP server entry point. Federates experimental
+ * (PDB) and predicted (AlphaFold / 3D-Beacons) protein structures behind one tool
+ * surface; initializes the six upstream services in setup().
+ * @module index
+ */
+import { createApp } from '@cyanheads/mcp-ts-core';
+import { getServerConfig } from './config/server-config.js';
+import { afSummaryResource, pdbSummaryResource } from './mcp-server/resources/definitions/index.js';
+import { analyzeCollection, compareStructures, findSimilar, getAnnotations, getStructure, searchStructures, trackLigands, } from './mcp-server/tools/definitions/index.js';
+import { initAlignmentService } from './services/alignment/alignment-service.js';
+import { initAlphaFoldService } from './services/alphafold/alphafold-service.js';
+import { initBeaconsService } from './services/beacons/beacons-service.js';
+import { initFoldseekService } from './services/foldseek/foldseek-service.js';
+import { initRcsbService } from './services/rcsb/rcsb-service.js';
+import { initUniProtService } from './services/uniprot/uniprot-service.js';
+await createApp({
+    name: 'protein-mcp-server',
+    title: 'protein-mcp-server',
+    tools: [
+        searchStructures,
+        getStructure,
+        findSimilar,
+        trackLigands,
+        compareStructures,
+        analyzeCollection,
+        getAnnotations,
+    ],
+    resources: [pdbSummaryResource, afSummaryResource],
+    prompts: [],
+    // Public, keyless data server — serve the full inventory to unauthenticated callers.
+    landing: { requireAuth: false },
+    instructions: 'protein-mcp-server — federated protein structure & function research over experimental (PDB) and ' +
+        'predicted (AlphaFold) structures. No API keys required.\n' +
+        '- protein_search_structures: find structures by text, sequence, or organism/method/resolution; optional facet breakdown\n' +
+        '- protein_get_structure: fetch metadata + coordinate URLs for PDB IDs or UniProt accessions (batch, partial success)\n' +
+        '- protein_find_similar: sequence (mmseqs2) or structure (Foldseek) similarity search\n' +
+        '- protein_track_ligands: resolve ligands, find structures containing them, or map binding-site residues\n' +
+        '- protein_compare_structures: pairwise TM-align / jFATCAT over 2–10 structures\n' +
+        '- protein_analyze_collection: server-side facet distributions and trends over the PDB\n' +
+        '- protein_get_annotations: UniProt features + InterPro domains/GO terms',
+    setup(core) {
+        const serverConfig = getServerConfig();
+        initRcsbService(core.config, core.storage, serverConfig);
+        initAlphaFoldService(core.config, core.storage, serverConfig);
+        initBeaconsService(core.config, core.storage, serverConfig);
+        initUniProtService(core.config, core.storage, serverConfig);
+        initAlignmentService(core.config, core.storage, serverConfig);
+        initFoldseekService(core.config, core.storage, serverConfig);
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,6CAA6C,CAAC;AACpG,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAE3E,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,oBAAoB;IAC1B,KAAK,EAAE,oBAAoB;IAC3B,KAAK,EAAE;QACL,gBAAgB;QAChB,YAAY;QACZ,WAAW;QACX,YAAY;QACZ,iBAAiB;QACjB,iBAAiB;QACjB,cAAc;KACf;IACD,SAAS,EAAE,CAAC,kBAAkB,EAAE,iBAAiB,CAAC;IAClD,OAAO,EAAE,EAAE;IACX,qFAAqF;IACrF,OAAO,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;IAC/B,YAAY,EACV,mGAAmG;QACnG,2DAA2D;QAC3D,2HAA2H;QAC3H,wHAAwH;QACxH,wFAAwF;QACxF,2GAA2G;QAC3G,kFAAkF;QAClF,yFAAyF;QACzF,yEAAyE;IAC3E,KAAK,CAAC,IAAI;QACR,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;QACvC,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QACzD,oBAAoB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC9D,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC5D,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC5D,oBAAoB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC9D,mBAAmB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAC/D,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/resources/definitions/af-summary.resource.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview af://{uniprot} — predicted-structure summary for a UniProt
+ * accession (mean pLDDT, confidence-band fractions, model URLs, version) from the
+ * AlphaFold DB. The injectable-context twin of protein_get_structure for
+ * source: predicted.
+ * @module mcp-server/resources/definitions/af-summary.resource
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const afSummaryResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
+    uniprot: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    uniprotAccession: z.ZodString;
+    entryId: z.ZodOptional<z.ZodString>;
+    meanPlddt: z.ZodOptional<z.ZodNumber>;
+    confidenceBuckets: z.ZodOptional<z.ZodObject<{
+        veryLow: z.ZodNumber;
+        low: z.ZodNumber;
+        confident: z.ZodNumber;
+        veryHigh: z.ZodNumber;
+    }, z.core.$strip>>;
+    organism: z.ZodOptional<z.ZodString>;
+    uniprotDescription: z.ZodOptional<z.ZodString>;
+    modelVersion: z.ZodOptional<z.ZodNumber>;
+    cifUrl: z.ZodOptional<z.ZodString>;
+    pdbUrl: z.ZodOptional<z.ZodString>;
+    bcifUrl: z.ZodOptional<z.ZodString>;
+    paeDocUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, undefined>;
+//# sourceMappingURL=af-summary.resource.d.ts.map

package/dist/mcp-server/resources/definitions/af-summary.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"af-summary.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/af-summary.resource.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAIrD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;6BAmD5B,CAAC"}

package/dist/mcp-server/resources/definitions/af-summary.resource.js

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview af://{uniprot} — predicted-structure summary for a UniProt
+ * accession (mean pLDDT, confidence-band fractions, model URLs, version) from the
+ * AlphaFold DB. The injectable-context twin of protein_get_structure for
+ * source: predicted.
+ * @module mcp-server/resources/definitions/af-summary.resource
+ */
+import { resource, z } from '@cyanheads/mcp-ts-core';
+import { notFound } from '@cyanheads/mcp-ts-core/errors';
+import { getAlphaFoldService } from '../../../services/alphafold/alphafold-service.js';
+export const afSummaryResource = resource('af://{uniprot}', {
+    name: 'alphafold-structure-summary',
+    title: 'AlphaFold structure summary',
+    description: 'Predicted-structure summary for a UniProt accession from AlphaFold DB: mean pLDDT, confidence-band fractions, model URLs, and version.',
+    mimeType: 'application/json',
+    params: z.object({
+        uniprot: z.string().describe('UniProt accession (e.g. P69905).'),
+    }),
+    output: z.object({
+        uniprotAccession: z.string().describe('UniProt accession.'),
+        entryId: z.string().optional().describe('AlphaFold model entry ID (e.g. AF-P69905-F1).'),
+        meanPlddt: z.number().optional().describe('Mean pLDDT confidence (0–100).'),
+        confidenceBuckets: z
+            .object({
+            veryLow: z.number().describe('Fraction with pLDDT < 50.'),
+            low: z.number().describe('Fraction with pLDDT 50–70.'),
+            confident: z.number().describe('Fraction with pLDDT 70–90.'),
+            veryHigh: z.number().describe('Fraction with pLDDT > 90.'),
+        })
+            .optional()
+            .describe('Residue fractions per confidence band.'),
+        organism: z.string().optional().describe('Source organism.'),
+        uniprotDescription: z.string().optional().describe('UniProt protein description.'),
+        modelVersion: z.number().optional().describe('AlphaFold model version.'),
+        cifUrl: z.string().optional().describe('mmCIF coordinate file URL.'),
+        pdbUrl: z.string().optional().describe('PDB-format coordinate file URL.'),
+        bcifUrl: z.string().optional().describe('Binary CIF coordinate file URL.'),
+        paeDocUrl: z.string().optional().describe('Predicted Aligned Error documentation URL.'),
+    }),
+    async handler(params, ctx) {
+        const model = await getAlphaFoldService().getPrediction(params.uniprot, ctx);
+        if (!model)
+            throw notFound(`No AlphaFold model found for ${params.uniprot.toUpperCase()}`, {
+                uniprot: params.uniprot,
+            });
+        return {
+            uniprotAccession: model.uniprotAccession,
+            ...(model.entryId ? { entryId: model.entryId } : {}),
+            ...(typeof model.meanPlddt === 'number' ? { meanPlddt: model.meanPlddt } : {}),
+            ...(model.confidenceBuckets ? { confidenceBuckets: model.confidenceBuckets } : {}),
+            ...(model.organism ? { organism: model.organism } : {}),
+            ...(model.uniprotDescription ? { uniprotDescription: model.uniprotDescription } : {}),
+            ...(typeof model.modelVersion === 'number' ? { modelVersion: model.modelVersion } : {}),
+            ...(model.cifUrl ? { cifUrl: model.cifUrl } : {}),
+            ...(model.pdbUrl ? { pdbUrl: model.pdbUrl } : {}),
+            ...(model.bcifUrl ? { bcifUrl: model.bcifUrl } : {}),
+            ...(model.paeDocUrl ? { paeDocUrl: model.paeDocUrl } : {}),
+        };
+    },
+});
+//# sourceMappingURL=af-summary.resource.js.map

package/dist/mcp-server/resources/definitions/af-summary.resource.js.map

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

package/dist/mcp-server/resources/definitions/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel export for all protein-mcp-server resource definitions.
+ * @module mcp-server/resources/definitions/index
+ */
+export { afSummaryResource } from './af-summary.resource.js';
+export { pdbSummaryResource } from './pdb-summary.resource.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp-server/resources/definitions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/mcp-server/resources/definitions/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel export for all protein-mcp-server resource definitions.
+ * @module mcp-server/resources/definitions/index
+ */
+export { afSummaryResource } from './af-summary.resource.js';
+export { pdbSummaryResource } from './pdb-summary.resource.js';
+//# sourceMappingURL=index.js.map

package/dist/mcp-server/resources/definitions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/mcp-server/resources/definitions/pdb-summary.resource.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview pdb://{entry_id} — experimental structure summary (title, method,
+ * resolution, organism, ligands, chains). The injectable-context twin of
+ * protein_get_structure for source: experimental.
+ * @module mcp-server/resources/definitions/pdb-summary.resource
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const pdbSummaryResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
+    entry_id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    methods: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    resolution: z.ZodOptional<z.ZodNumber>;
+    molecularWeight: z.ZodOptional<z.ZodNumber>;
+    releaseDate: z.ZodOptional<z.ZodString>;
+    organisms: z.ZodArray<z.ZodString>;
+    polymerEntities: z.ZodArray<z.ZodObject<{
+        entityId: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        organism: z.ZodOptional<z.ZodString>;
+        chains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        sequenceLength: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    ligands: z.ZodArray<z.ZodObject<{
+        compId: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        formula: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, undefined>;
+//# sourceMappingURL=pdb-summary.resource.d.ts.map

package/dist/mcp-server/resources/definitions/pdb-summary.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdb-summary.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/pdb-summary.resource.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAIrD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;6BA+D7B,CAAC"}

package/dist/mcp-server/resources/definitions/pdb-summary.resource.js

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview pdb://{entry_id} — experimental structure summary (title, method,
+ * resolution, organism, ligands, chains). The injectable-context twin of
+ * protein_get_structure for source: experimental.
+ * @module mcp-server/resources/definitions/pdb-summary.resource
+ */
+import { resource, z } from '@cyanheads/mcp-ts-core';
+import { notFound } from '@cyanheads/mcp-ts-core/errors';
+import { getRcsbService } from '../../../services/rcsb/rcsb-service.js';
+export const pdbSummaryResource = resource('pdb://{entry_id}', {
+    name: 'pdb-structure-summary',
+    title: 'PDB structure summary',
+    description: 'Experimental structure summary for a PDB entry: title, method, resolution, organism, chains, and bound ligands.',
+    mimeType: 'application/json',
+    params: z.object({
+        entry_id: z.string().describe('PDB entry ID (e.g. 4HHB).'),
+    }),
+    output: z.object({
+        id: z.string().describe('PDB entry ID.'),
+        title: z.string().optional().describe('Structure title.'),
+        methods: z.array(z.string()).optional().describe('Experimental method(s).'),
+        resolution: z.number().optional().describe('Resolution in Å.'),
+        molecularWeight: z.number().optional().describe('Structure molecular weight (kDa).'),
+        releaseDate: z.string().optional().describe('Initial release date (ISO 8601).'),
+        organisms: z.array(z.string()).describe('Source organisms.'),
+        polymerEntities: z
+            .array(z
+            .object({
+            entityId: z.string().describe('Polymer entity ID.'),
+            description: z.string().optional().describe('Entity description.'),
+            organism: z.string().optional().describe('Source organism.'),
+            chains: z.array(z.string()).optional().describe('Author chain IDs.'),
+            sequenceLength: z.number().optional().describe('Residue count.'),
+        })
+            .describe('A modeled polymer entity (chain group).'))
+            .describe('Modeled polymer entities.'),
+        ligands: z
+            .array(z
+            .object({
+            compId: z.string().describe('Chemical component ID.'),
+            name: z.string().optional().describe('Chemical name.'),
+            formula: z.string().optional().describe('Molecular formula.'),
+        })
+            .describe('A bound ligand (non-polymer chemical component).'))
+            .describe('Bound ligands.'),
+    }),
+    async handler(params, ctx) {
+        const [meta] = await getRcsbService().getEntries([params.entry_id], ctx);
+        if (!meta)
+            throw notFound(`No PDB entry found for ${params.entry_id.toUpperCase()}`, {
+                entryId: params.entry_id,
+            });
+        return {
+            id: meta.id,
+            ...(meta.title ? { title: meta.title } : {}),
+            ...(meta.methods && meta.methods.length > 0 ? { methods: meta.methods } : {}),
+            ...(typeof meta.resolution === 'number' ? { resolution: meta.resolution } : {}),
+            ...(typeof meta.molecularWeight === 'number'
+                ? { molecularWeight: meta.molecularWeight }
+                : {}),
+            ...(meta.releaseDate ? { releaseDate: meta.releaseDate } : {}),
+            organisms: meta.organisms,
+            polymerEntities: meta.polymerEntities,
+            ligands: meta.ligands,
+        };
+    },
+});
+//# sourceMappingURL=pdb-summary.resource.js.map

package/dist/mcp-server/resources/definitions/pdb-summary.resource.js.map

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

package/dist/mcp-server/tools/definitions/_schemas.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Shared Zod output schemas and helpers for the facet breakdown
+ * surfaced by `protein_analyze_collection` and `protein_search_structures`. Nesting
+ * is bounded to two levels (a dimension's buckets may each carry one child
+ * dimension), matching the deepest cross-tab the facet engine produces.
+ * @module mcp-server/tools/definitions/_schemas
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import type { FacetDimension } from '../../../services/rcsb/types.js';
+/** A facet dimension and its buckets. */
+export declare const facetDimensionSchema: z.ZodObject<{
+    dimension: z.ZodString;
+    buckets: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        count: z.ZodNumber;
+        children: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            dimension: z.ZodString;
+            buckets: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                count: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type FacetDimensionOutput = z.infer<typeof facetDimensionSchema>;
+/** Project a domain {@link FacetDimension} to the output shape, capping buckets. */
+export declare function toFacetOutput(facet: FacetDimension, cap: number): FacetDimensionOutput;
+/** Render a list of facet dimensions to markdown lines for `format()` parity. */
+export declare function renderFacets(facets: FacetDimensionOutput[]): string[];
+//# sourceMappingURL=_schemas.d.ts.map

package/dist/mcp-server/tools/definitions/_schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_schemas.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_schemas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAgC/D,yCAAyC;AACzC,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;iBAW4B,CAAC;AAE9D,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAkBtF;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,MAAM,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,CAarE"}

package/dist/mcp-server/tools/definitions/_schemas.js

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Shared Zod output schemas and helpers for the facet breakdown
+ * surfaced by `protein_analyze_collection` and `protein_search_structures`. Nesting
+ * is bounded to two levels (a dimension's buckets may each carry one child
+ * dimension), matching the deepest cross-tab the facet engine produces.
+ * @module mcp-server/tools/definitions/_schemas
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+/** A flat (leaf) facet bucket. */
+const leafBucketSchema = z
+    .object({
+    label: z.string().describe('Bucket value — category, numeric bin start, or period.'),
+    count: z.number().describe('Number of entries in the bucket.'),
+})
+    .describe('A leaf aggregation bucket: a value and its entry count.');
+/** A child (nested) facet dimension within a cross-tab bucket. */
+const childDimensionSchema = z
+    .object({
+    dimension: z.string().describe('Nested dimension name.'),
+    buckets: z.array(leafBucketSchema).describe('Nested buckets within the parent bucket.'),
+})
+    .describe('A nested cross-tab dimension within a parent bucket.');
+/** A top-level facet bucket, optionally carrying a nested cross-tab dimension. */
+const bucketSchema = z
+    .object({
+    label: z.string().describe('Bucket value — category, numeric bin start, or period.'),
+    count: z.number().describe('Number of entries in the bucket.'),
+    children: z
+        .array(childDimensionSchema)
+        .optional()
+        .describe('Nested dimension breakdown for cross-tabs (present only for multidimensional facets).'),
+})
+    .describe('A top-level aggregation bucket, optionally cross-tabbed by a nested dimension.');
+/** A facet dimension and its buckets. */
+export const facetDimensionSchema = z
+    .object({
+    dimension: z
+        .string()
+        .describe('Friendly dimension name (e.g. method, organism, release_year).'),
+    buckets: z.array(bucketSchema).describe('Aggregation buckets, count-descending for terms.'),
+    truncated: z
+        .boolean()
+        .optional()
+        .describe('True when buckets were capped by the per-dimension bucket limit.'),
+})
+    .describe('A facet dimension and its aggregation buckets.');
+/** Project a domain {@link FacetDimension} to the output shape, capping buckets. */
+export function toFacetOutput(facet, cap) {
+    const truncated = facet.buckets.length > cap;
+    return {
+        dimension: facet.dimension,
+        buckets: facet.buckets.slice(0, cap).map((b) => ({
+            label: b.label,
+            count: b.count,
+            ...(b.children
+                ? {
+                    children: b.children.map((c) => ({
+                        dimension: c.dimension,
+                        buckets: c.buckets.slice(0, cap).map((cb) => ({ label: cb.label, count: cb.count })),
+                    })),
+                }
+                : {}),
+        })),
+        ...(truncated ? { truncated: true } : {}),
+    };
+}
+/** Render a list of facet dimensions to markdown lines for `format()` parity. */
+export function renderFacets(facets) {
+    const lines = [];
+    for (const f of facets) {
+        lines.push(`\n**${f.dimension}**${f.truncated ? ' (truncated)' : ''}`);
+        for (const b of f.buckets) {
+            lines.push(`- ${b.label}: ${b.count}`);
+            for (const c of b.children ?? []) {
+                const inner = c.buckets.map((cb) => `${cb.label}: ${cb.count}`).join(', ');
+                lines.push(`  - ${c.dimension} → ${inner}`);
+            }
+        }
+    }
+    return lines;
+}
+//# sourceMappingURL=_schemas.js.map

package/dist/mcp-server/tools/definitions/_schemas.js.map

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