@cyanheads/protein-mcp-server 0.1.0

package/dist/services/rcsb/facets.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview Maps the agent-facing facet dimension enum to RCSB attributes +
+ * aggregation types. Shared by `protein_analyze_collection` and the optional
+ * facet breakdown on `protein_search_structures`.
+ * @module services/rcsb/facets
+ */
+import type { FacetSpec } from './rcsb-service.js';
+/** The supported `group_by` / facet dimensions and how RCSB aggregates each. */
+export declare const FACET_DIMENSIONS: {
+    readonly method: {
+        readonly attribute: "exptl.method";
+        readonly aggregation: "terms";
+        readonly label: "Experimental method";
+    };
+    readonly organism: {
+        readonly attribute: "rcsb_entity_source_organism.ncbi_scientific_name";
+        readonly aggregation: "terms";
+        readonly label: "Source organism";
+    };
+    readonly polymer_type: {
+        readonly attribute: "rcsb_entry_info.polymer_composition";
+        readonly aggregation: "terms";
+        readonly label: "Polymer composition";
+    };
+    readonly resolution: {
+        readonly attribute: "rcsb_entry_info.resolution_combined";
+        readonly aggregation: "histogram";
+        readonly defaultInterval: 0.5;
+        readonly label: "Resolution (Å)";
+    };
+    readonly release_year: {
+        readonly attribute: "rcsb_accession_info.initial_release_date";
+        readonly aggregation: "date_histogram";
+        readonly defaultInterval: "year";
+        readonly label: "Release year";
+    };
+    readonly molecular_weight: {
+        readonly attribute: "rcsb_entry_info.molecular_weight";
+        readonly aggregation: "histogram";
+        readonly defaultInterval: 50;
+        readonly label: "Molecular weight (kDa)";
+    };
+};
+/** A supported facet dimension name. */
+export type FacetDimensionName = keyof typeof FACET_DIMENSIONS;
+/** All supported dimension names (for Zod enums). */
+export declare const FACET_DIMENSION_NAMES: [FacetDimensionName, ...FacetDimensionName[]];
+/** Build a {@link FacetSpec} for a dimension, with an optional interval override and nested child. */
+export declare function buildFacetSpec(dimension: FacetDimensionName, interval?: number | string, child?: FacetDimensionName): FacetSpec;
+//# sourceMappingURL=facets.d.ts.map

package/dist/services/rcsb/facets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facets.d.ts","sourceRoot":"","sources":["../../../src/services/rcsb/facets.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAWnD,gFAAgF;AAChF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCoB,CAAC;AAElD,wCAAwC;AACxC,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAE/D,qDAAqD;AACrD,eAAO,MAAM,qBAAqB,EAAoC,CACpE,kBAAkB,EAClB,GAAG,kBAAkB,EAAE,CACxB,CAAC;AAEF,sGAAsG;AACtG,wBAAgB,cAAc,CAC5B,SAAS,EAAE,kBAAkB,EAC7B,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAC1B,KAAK,CAAC,EAAE,kBAAkB,GACzB,SAAS,CAYX"}

package/dist/services/rcsb/facets.js

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Maps the agent-facing facet dimension enum to RCSB attributes +
+ * aggregation types. Shared by `protein_analyze_collection` and the optional
+ * facet breakdown on `protein_search_structures`.
+ * @module services/rcsb/facets
+ */
+/** The supported `group_by` / facet dimensions and how RCSB aggregates each. */
+export const FACET_DIMENSIONS = {
+    method: {
+        attribute: 'exptl.method',
+        aggregation: 'terms',
+        label: 'Experimental method',
+    },
+    organism: {
+        attribute: 'rcsb_entity_source_organism.ncbi_scientific_name',
+        aggregation: 'terms',
+        label: 'Source organism',
+    },
+    polymer_type: {
+        attribute: 'rcsb_entry_info.polymer_composition',
+        aggregation: 'terms',
+        label: 'Polymer composition',
+    },
+    resolution: {
+        attribute: 'rcsb_entry_info.resolution_combined',
+        aggregation: 'histogram',
+        defaultInterval: 0.5,
+        label: 'Resolution (Å)',
+    },
+    release_year: {
+        attribute: 'rcsb_accession_info.initial_release_date',
+        aggregation: 'date_histogram',
+        defaultInterval: 'year',
+        label: 'Release year',
+    },
+    molecular_weight: {
+        attribute: 'rcsb_entry_info.molecular_weight',
+        aggregation: 'histogram',
+        defaultInterval: 50,
+        label: 'Molecular weight (kDa)',
+    },
+};
+/** All supported dimension names (for Zod enums). */
+export const FACET_DIMENSION_NAMES = Object.keys(FACET_DIMENSIONS);
+/** Build a {@link FacetSpec} for a dimension, with an optional interval override and nested child. */
+export function buildFacetSpec(dimension, interval, child) {
+    const def = FACET_DIMENSIONS[dimension];
+    const resolvedInterval = interval ?? def.defaultInterval;
+    return {
+        dimension,
+        attribute: def.attribute,
+        aggregation: def.aggregation,
+        ...(def.aggregation !== 'terms' && resolvedInterval !== undefined
+            ? { interval: resolvedInterval }
+            : {}),
+        ...(child ? { child: buildFacetSpec(child) } : {}),
+    };
+}
+//# sourceMappingURL=facets.js.map

package/dist/services/rcsb/facets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"facets.js","sourceRoot":"","sources":["../../../src/services/rcsb/facets.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH,gFAAgF;AAChF,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,MAAM,EAAE;QACN,SAAS,EAAE,cAAc;QACzB,WAAW,EAAE,OAAO;QACpB,KAAK,EAAE,qBAAqB;KAC7B;IACD,QAAQ,EAAE;QACR,SAAS,EAAE,kDAAkD;QAC7D,WAAW,EAAE,OAAO;QACpB,KAAK,EAAE,iBAAiB;KACzB;IACD,YAAY,EAAE;QACZ,SAAS,EAAE,qCAAqC;QAChD,WAAW,EAAE,OAAO;QACpB,KAAK,EAAE,qBAAqB;KAC7B;IACD,UAAU,EAAE;QACV,SAAS,EAAE,qCAAqC;QAChD,WAAW,EAAE,WAAW;QACxB,eAAe,EAAE,GAAG;QACpB,KAAK,EAAE,gBAAgB;KACxB;IACD,YAAY,EAAE;QACZ,SAAS,EAAE,0CAA0C;QACrD,WAAW,EAAE,gBAAgB;QAC7B,eAAe,EAAE,MAAM;QACvB,KAAK,EAAE,cAAc;KACtB;IACD,gBAAgB,EAAE;QAChB,SAAS,EAAE,kCAAkC;QAC7C,WAAW,EAAE,WAAW;QACxB,eAAe,EAAE,EAAE;QACnB,KAAK,EAAE,wBAAwB;KAChC;CAC8C,CAAC;AAKlD,qDAAqD;AACrD,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAGhE,CAAC;AAEF,sGAAsG;AACtG,MAAM,UAAU,cAAc,CAC5B,SAA6B,EAC7B,QAA0B,EAC1B,KAA0B;IAE1B,MAAM,GAAG,GAAiB,gBAAgB,CAAC,SAAS,CAAC,CAAC;IACtD,MAAM,gBAAgB,GAAG,QAAQ,IAAI,GAAG,CAAC,eAAe,CAAC;IACzD,OAAO;QACL,SAAS;QACT,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,GAAG,CAAC,GAAG,CAAC,WAAW,KAAK,OAAO,IAAI,gBAAgB,KAAK,SAAS;YAC/D,CAAC,CAAC,EAAE,QAAQ,EAAE,gBAAgB,EAAE;YAChC,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnD,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview RCSB service — wraps the RCSB Search API v2 (text / sequence /
+ * chemical search + server-side faceted aggregation), the Data API GraphQL
+ * endpoint (batched entry metadata + ligand binding-site residues via
+ * `rcsb_target_neighbors`), the REST chemical-component endpoint, and coordinate
+ * file URLs. The PDB's full query surface lives only here; predicted models are
+ * served by the AlphaFold / 3D-Beacons services.
+ * @module services/rcsb/rcsb-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';
+import type { BindingSite, ChemComp, ContentType, EntryMeta, FacetDimension, SearchResult, StructureSearchParams } from './types.js';
+/** RCSB return types relevant to this server. */
+export type ReturnType = 'entry' | 'polymer_entity' | 'mol_definition';
+/** A facet dimension request: friendly name + how RCSB should aggregate it. */
+export interface FacetSpec {
+    /** Aggregation kind. */
+    aggregation: 'terms' | 'histogram' | 'date_histogram';
+    /** RCSB attribute to aggregate. */
+    attribute: string;
+    /** Optional nested dimension for a cross-tab. */
+    child?: FacetSpec;
+    /** Friendly dimension name surfaced to the agent. */
+    dimension: string;
+    /** Numeric bin width (histogram) or period string `year`/`month`/`quarter` (date_histogram). */
+    interval?: number | string;
+}
+export declare class RcsbService {
+    private readonly searchUrl;
+    private readonly graphqlUrl;
+    private readonly dataRestBase;
+    private readonly filesBase;
+    constructor(_config: AppConfig, _storage: StorageService, serverConfig: ServerConfig);
+    /** Full-text / filtered structure search, optionally with a facet breakdown. */
+    search(params: StructureSearchParams, ctx: Context, facets?: FacetSpec[]): Promise<SearchResult>;
+    /** mmseqs2 sequence-similarity search. Returns polymer-entity hits. */
+    searchSequence(sequence: string, opts: {
+        maxEvalue?: number;
+        minIdentity?: number;
+        limit?: number;
+        contentType?: ContentType;
+    }, ctx: Context): Promise<SearchResult>;
+    /** Find entries containing a given ligand (exact chemical component ID). */
+    searchByLigand(compId: string, opts: {
+        limit?: number;
+        contentType?: ContentType;
+    }, ctx: Context): Promise<SearchResult>;
+    /** Resolve a ligand name/synonym to candidate chemical component IDs. */
+    findChemComps(query: string, limit: number, ctx: Context): Promise<string[]>;
+    /** Facet-only aggregation over an optional scoping query (no row pull). */
+    analyzeFacets(params: StructureSearchParams, facets: FacetSpec[], ctx: Context): Promise<{
+        total: number;
+        facets: FacetDimension[];
+    }>;
+    /** Batched entry metadata for up to N PDB IDs in one GraphQL call. */
+    getEntries(ids: string[], ctx: Context): Promise<EntryMeta[]>;
+    /** Resolve a PDB entry to its cross-referenced UniProt accession(s). */
+    resolveUniprot(pdbId: string, ctx: Context): Promise<string[]>;
+    /** First polymer entity's one-letter sequence for a PDB entry. */
+    getSequence(pdbId: string, ctx: Context): Promise<{
+        entityId: string;
+        sequence: string;
+    } | null>;
+    /** Ligand binding-site residues for an entry, optionally filtered to one ligand. */
+    getBindingSites(pdbId: string, compId: string | undefined, ctx: Context): Promise<BindingSite[]>;
+    /** Chemical-component metadata (formula, weight, SMILES, InChIKey). */
+    getChemComp(compId: string, ctx: Context): Promise<ChemComp | null>;
+    /** Construct a coordinate-file download URL for a PDB entry. */
+    coordinateFileUrl(pdbId: string, format: 'cif' | 'pdb' | 'bcif'): string;
+    private postSearch;
+    private graphql;
+}
+/** Build the RCSB query node from search params (match-all when no constraint given). */
+export declare function buildQuery(params: StructureSearchParams): unknown;
+/** Translate a friendly FacetSpec into the RCSB facet request shape (recursively). */
+export declare function toRcsbFacet(spec: FacetSpec): Record<string, unknown>;
+export declare function initRcsbService(config: AppConfig, storage: StorageService, serverConfig: ServerConfig): void;
+export declare function getRcsbService(): RcsbService;
+//# sourceMappingURL=rcsb-service.d.ts.map

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

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