agr-mcp-server 4.0.0

package/dist/client.js

@@ -0,0 +1,235 @@
+import { SPECIES_MAP, SPECIES, } from "./types.js";
+const AGR_API_URL = "https://www.alliancegenome.org/api";
+const ALLIANCEMINE_URL = "https://www.alliancegenome.org/alliancemine/service";
+export class AllianceClient {
+    agrApiUrl;
+    allianceMineUrl;
+    constructor(agrApiUrl, allianceMineUrl) {
+        this.agrApiUrl = agrApiUrl || AGR_API_URL;
+        this.allianceMineUrl = allianceMineUrl || ALLIANCEMINE_URL;
+    }
+    async fetch(url) {
+        const response = await fetch(url, {
+            headers: {
+                Accept: "application/json",
+                "Accept-Language": "en-US,en;q=0.9",
+                "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+                "Sec-Fetch-Dest": "empty",
+                "Sec-Fetch-Mode": "cors",
+                "Sec-Fetch-Site": "cross-site",
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        return response.json();
+    }
+    /**
+     * Search AGR using the main search API
+     */
+    async search(query, category, species, limit = 20) {
+        const params = new URLSearchParams({
+            q: query,
+            limit: String(limit),
+        });
+        if (category) {
+            params.set("category", category);
+        }
+        // Resolve species short name to full name
+        if (species) {
+            const speciesName = SPECIES_MAP[species.toLowerCase()] || species;
+            if (SPECIES.includes(speciesName)) {
+                params.set("species", speciesName);
+            }
+        }
+        const url = `${this.agrApiUrl}/search?${params.toString()}`;
+        try {
+            const response = await this.fetch(url);
+            return {
+                query,
+                results: response.results.map((r) => ({
+                    id: r.id,
+                    symbol: r.symbol,
+                    name: r.name || r.name_key || r.id,
+                    species: r.species?.name,
+                    category: r.category,
+                    description: r.highlights?.description?.[0],
+                    highlights: r.highlights,
+                })),
+                total: response.total,
+                aggregations: response.aggregations,
+            };
+        }
+        catch (error) {
+            return { query, results: [], total: 0 };
+        }
+    }
+    /**
+     * Search using AllianceMine for more advanced queries
+     */
+    async searchMine(query, type, limit = 20) {
+        const params = new URLSearchParams({
+            q: query,
+            size: String(limit),
+        });
+        if (type) {
+            params.set(`facet_Category`, type);
+        }
+        const url = `${this.allianceMineUrl}/search?${params.toString()}`;
+        try {
+            const response = await this.fetch(url);
+            return {
+                query,
+                results: this.parseMineResults(response.results, limit),
+                total: response.totalHits,
+            };
+        }
+        catch (error) {
+            return { query, results: [], total: 0 };
+        }
+    }
+    parseMineResults(results, limit) {
+        return results.slice(0, limit).map((r) => ({
+            id: String(r.fields.primaryIdentifier || r.fields.secondaryIdentifier || r.id),
+            symbol: String(r.fields.symbol || ""),
+            name: String(r.fields.name || r.fields.symbol || r.fields.primaryIdentifier || ""),
+            species: String(r.fields["organism.name"] || ""),
+            category: r.type.toLowerCase(),
+            description: String(r.fields.briefDescription || r.fields.description || ""),
+        }));
+    }
+    /**
+     * Get detailed gene information
+     */
+    async getGene(geneId) {
+        const url = `${this.agrApiUrl}/gene/${encodeURIComponent(geneId)}`;
+        try {
+            const data = await this.fetch(url);
+            return data;
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    /**
+     * Get disease associations for a gene
+     */
+    async getGeneDiseases(geneId, limit = 100) {
+        const url = `${this.agrApiUrl}/gene/${encodeURIComponent(geneId)}/diseases?limit=${limit}`;
+        try {
+            const data = await this.fetch(url);
+            return data;
+        }
+        catch (error) {
+            return { results: [], total: 0 };
+        }
+    }
+    /**
+     * Search diseases
+     */
+    async searchDiseases(query, limit = 20) {
+        return this.search(query, "disease", undefined, limit);
+    }
+    /**
+     * Get expression data for a gene
+     */
+    async getGeneExpression(geneId, limit = 100) {
+        const url = `${this.agrApiUrl}/gene/${encodeURIComponent(geneId)}/expression?limit=${limit}`;
+        try {
+            const data = await this.fetch(url);
+            return data;
+        }
+        catch (error) {
+            return { results: [], total: 0 };
+        }
+    }
+    /**
+     * Get orthologs for a gene
+     */
+    async getOrthologs(geneId) {
+        const url = `${this.agrApiUrl}/gene/${encodeURIComponent(geneId)}/homologs`;
+        try {
+            const data = await this.fetch(url);
+            return data;
+        }
+        catch (error) {
+            return { results: [], total: 0 };
+        }
+    }
+    /**
+     * Get phenotypes for a gene
+     */
+    async getGenePhenotypes(geneId, limit = 100) {
+        const url = `${this.agrApiUrl}/gene/${encodeURIComponent(geneId)}/phenotypes?limit=${limit}`;
+        try {
+            const data = await this.fetch(url);
+            return data;
+        }
+        catch (error) {
+            return { results: [], total: 0 };
+        }
+    }
+    /**
+     * Get interactions for a gene
+     */
+    async getGeneInteractions(geneId, limit = 100) {
+        const url = `${this.agrApiUrl}/gene/${encodeURIComponent(geneId)}/interactions?limit=${limit}`;
+        try {
+            const data = await this.fetch(url);
+            return data;
+        }
+        catch (error) {
+            return { results: [], total: 0 };
+        }
+    }
+    /**
+     * Get alleles for a gene
+     */
+    async getGeneAlleles(geneId, limit = 100) {
+        const url = `${this.agrApiUrl}/gene/${encodeURIComponent(geneId)}/alleles?limit=${limit}`;
+        try {
+            const data = await this.fetch(url);
+            return data;
+        }
+        catch (error) {
+            return { results: [], total: 0 };
+        }
+    }
+    /**
+     * Search alleles/variants
+     */
+    async searchAlleles(query, limit = 20) {
+        return this.search(query, "allele", undefined, limit);
+    }
+    /**
+     * Get list of supported species
+     */
+    getSpeciesList() {
+        // Return hardcoded list of Alliance model organisms
+        const speciesList = [
+            { name: "Homo sapiens", shortName: "human" },
+            { name: "Mus musculus", shortName: "mouse" },
+            { name: "Rattus norvegicus", shortName: "rat" },
+            { name: "Danio rerio", shortName: "zebrafish" },
+            { name: "Drosophila melanogaster", shortName: "fly" },
+            { name: "Caenorhabditis elegans", shortName: "worm" },
+            { name: "Saccharomyces cerevisiae", shortName: "yeast" },
+            { name: "Xenopus laevis", shortName: "frog" },
+            { name: "Xenopus tropicalis", shortName: "xenopus" },
+        ];
+        return speciesList;
+    }
+    /**
+     * Helper to resolve species short name
+     */
+    resolveSpecies(input) {
+        const lower = input.toLowerCase();
+        if (SPECIES_MAP[lower]) {
+            return SPECIES_MAP[lower];
+        }
+        if (SPECIES.includes(input)) {
+            return input;
+        }
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { AllianceClient } from "./client.js";
+import { ENTITY_TYPES } from "./types.js";
+const client = new AllianceClient();
+const server = new McpServer({
+    name: "agr-genomics",
+    version: "4.0.0",
+});
+// Tool: Search genes
+server.tool("search_genes", "Search for genes across all Alliance of Genome Resources model organisms. Supports species filtering.", {
+    query: z
+        .string()
+        .describe("Search query - gene symbol (e.g., 'BRCA1', 'daf-2'), name, or keyword"),
+    species: z
+        .string()
+        .optional()
+        .describe("Filter by species: human, mouse, rat, zebrafish, fly, worm, yeast, frog, or full name like 'Homo sapiens'"),
+    limit: z
+        .number()
+        .optional()
+        .default(20)
+        .describe("Maximum number of results to return"),
+}, async ({ query, species, limit }) => {
+    try {
+        const results = await client.search(query, "gene", species, limit);
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error searching genes: ${error}` }],
+            isError: true,
+        };
+    }
+});
+// Tool: Get Gene Info
+server.tool("get_gene_info", "Get detailed information about a specific gene including symbol, name, location, species, and cross-references.", {
+    gene_id: z
+        .string()
+        .describe("Gene identifier - e.g., 'HGNC:1100' (human BRCA1), 'MGI:95892' (mouse), 'ZFIN:ZDB-GENE-990415-72'"),
+}, async ({ gene_id }) => {
+    try {
+        const data = await client.getGene(gene_id);
+        if (!data) {
+            return {
+                content: [{ type: "text", text: `Gene not found: ${gene_id}` }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error fetching gene: ${error}` }],
+            isError: true,
+        };
+    }
+});
+// Tool: Get Gene Diseases
+server.tool("get_gene_diseases", "Get disease associations for a gene, including human disease models and annotations.", {
+    gene_id: z.string().describe("Gene identifier"),
+    limit: z.number().optional().default(100).describe("Maximum results"),
+}, async ({ gene_id, limit }) => {
+    try {
+        const data = await client.getGeneDiseases(gene_id, limit);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error fetching diseases: ${error}` }],
+            isError: true,
+        };
+    }
+});
+// Tool: Search Diseases
+server.tool("search_diseases", "Search for diseases in the Alliance database.", {
+    query: z
+        .string()
+        .describe("Disease name or keyword (e.g., 'breast cancer', 'diabetes')"),
+    limit: z.number().optional().default(20).describe("Maximum results"),
+}, async ({ query, limit }) => {
+    try {
+        const results = await client.searchDiseases(query, limit);
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                { type: "text", text: `Error searching diseases: ${error}` },
+            ],
+            isError: true,
+        };
+    }
+});
+// Tool: Get Gene Expression
+server.tool("get_gene_expression", "Get expression data for a gene including tissue/cell type expression and developmental stages.", {
+    gene_id: z.string().describe("Gene identifier"),
+    limit: z.number().optional().default(100).describe("Maximum results"),
+}, async ({ gene_id, limit }) => {
+    try {
+        const data = await client.getGeneExpression(gene_id, limit);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                { type: "text", text: `Error fetching expression: ${error}` },
+            ],
+            isError: true,
+        };
+    }
+});
+// Tool: Find Orthologs
+server.tool("find_orthologs", "Find orthologous genes across species. Returns homologs from all Alliance model organisms.", {
+    gene_id: z.string().describe("Gene identifier"),
+}, async ({ gene_id }) => {
+    try {
+        const data = await client.getOrthologs(gene_id);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                { type: "text", text: `Error fetching orthologs: ${error}` },
+            ],
+            isError: true,
+        };
+    }
+});
+// Tool: Get Gene Phenotypes
+server.tool("get_gene_phenotypes", "Get phenotype annotations for a gene.", {
+    gene_id: z.string().describe("Gene identifier"),
+    limit: z.number().optional().default(100).describe("Maximum results"),
+}, async ({ gene_id, limit }) => {
+    try {
+        const data = await client.getGenePhenotypes(gene_id, limit);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                { type: "text", text: `Error fetching phenotypes: ${error}` },
+            ],
+            isError: true,
+        };
+    }
+});
+// Tool: Get Gene Interactions
+server.tool("get_gene_interactions", "Get molecular and genetic interactions for a gene.", {
+    gene_id: z.string().describe("Gene identifier"),
+    limit: z.number().optional().default(100).describe("Maximum results"),
+}, async ({ gene_id, limit }) => {
+    try {
+        const data = await client.getGeneInteractions(gene_id, limit);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                { type: "text", text: `Error fetching interactions: ${error}` },
+            ],
+            isError: true,
+        };
+    }
+});
+// Tool: Get Gene Alleles
+server.tool("get_gene_alleles", "Get alleles/variants associated with a gene.", {
+    gene_id: z.string().describe("Gene identifier"),
+    limit: z.number().optional().default(100).describe("Maximum results"),
+}, async ({ gene_id, limit }) => {
+    try {
+        const data = await client.getGeneAlleles(gene_id, limit);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error fetching alleles: ${error}` }],
+            isError: true,
+        };
+    }
+});
+// Tool: Search Alleles
+server.tool("search_alleles", "Search for alleles/variants in the Alliance database.", {
+    query: z.string().describe("Allele name or keyword"),
+    limit: z.number().optional().default(20).describe("Maximum results"),
+}, async ({ query, limit }) => {
+    try {
+        const results = await client.searchAlleles(query, limit);
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error searching alleles: ${error}` }],
+            isError: true,
+        };
+    }
+});
+// Tool: Get Species List
+server.tool("get_species_list", "Get list of model organisms supported by Alliance of Genome Resources.", {}, async () => {
+    try {
+        const species = client.getSpeciesList();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        description: "Model organisms in the Alliance of Genome Resources",
+                        species,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                { type: "text", text: `Error fetching species list: ${error}` },
+            ],
+            isError: true,
+        };
+    }
+});
+// Resource: Entity types
+server.resource("entity-types", "agr://entity-types", async () => ({
+    contents: [
+        {
+            uri: "agr://entity-types",
+            mimeType: "application/json",
+            text: JSON.stringify({
+                description: "Entity types available in Alliance of Genome Resources",
+                types: ENTITY_TYPES.map((t) => ({
+                    name: t,
+                    description: getEntityDescription(t),
+                })),
+            }, null, 2),
+        },
+    ],
+}));
+// Resource: Species
+server.resource("species", "agr://species", async () => ({
+    contents: [
+        {
+            uri: "agr://species",
+            mimeType: "application/json",
+            text: JSON.stringify({
+                description: "Model organisms in Alliance of Genome Resources",
+                species: client.getSpeciesList(),
+            }, null, 2),
+        },
+    ],
+}));
+function getEntityDescription(type) {
+    const descriptions = {
+        gene: "Genes across all model organisms",
+        allele: "Genetic variants and alleles",
+        disease: "Human diseases and disease models",
+        phenotype: "Observable characteristics and traits",
+        expression: "Gene expression data",
+        orthology: "Cross-species ortholog relationships",
+        interaction: "Molecular and genetic interactions",
+        variant: "Sequence variants",
+        transgenic_allele: "Transgenic constructs",
+        construct: "Molecular constructs",
+        affected_genomic_model: "Animal models with genetic modifications",
+        go_term: "Gene Ontology terms",
+        do_term: "Disease Ontology terms",
+        publication: "Scientific publications",
+    };
+    return descriptions[type] || `${type} entities`;
+}
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("AGR Genomics MCP server running on stdio");
+}
+main().catch(console.error);

package/dist/types.d.ts

@@ -0,0 +1,167 @@
+export declare const ENTITY_TYPES: readonly ["gene", "allele", "disease", "phenotype", "expression", "orthology", "interaction", "variant", "transgenic_allele", "construct", "affected_genomic_model", "go_term", "do_term", "publication"];
+export type EntityType = (typeof ENTITY_TYPES)[number];
+export declare const SPECIES: readonly ["Homo sapiens", "Mus musculus", "Rattus norvegicus", "Danio rerio", "Drosophila melanogaster", "Caenorhabditis elegans", "Saccharomyces cerevisiae", "Xenopus laevis", "Xenopus tropicalis"];
+export type Species = (typeof SPECIES)[number];
+export declare const SPECIES_MAP: Record<string, Species>;
+export declare const GENE_ID_PREFIXES: readonly ["HGNC", "MGI", "RGD", "ZFIN", "FB", "WB", "SGD", "Xenbase"];
+export interface SearchResult {
+    id: string;
+    symbol?: string;
+    name: string;
+    species?: string;
+    category: string;
+    description?: string;
+    highlights?: Record<string, string[]>;
+}
+export interface SearchResponse {
+    query: string;
+    results: SearchResult[];
+    total: number;
+    aggregations?: Record<string, unknown>;
+}
+export interface GeneBasicInfo {
+    id: string;
+    symbol: string;
+    name: string;
+    species: {
+        name: string;
+        commonNames?: string;
+        taxonId: string;
+    };
+    soTermName?: string;
+    geneSynopsis?: string;
+    geneSynopsisUrl?: string;
+    automatedGeneSynopsis?: string;
+}
+export interface GeneLocation {
+    chromosome: string;
+    start: number;
+    end: number;
+    strand?: string;
+    assembly?: string;
+}
+export interface CrossReference {
+    id: string;
+    displayName?: string;
+    globalCrossRefId?: string;
+    pages?: string[];
+    url?: string;
+}
+export interface GeneData extends GeneBasicInfo {
+    genomeLocations?: GeneLocation[];
+    crossReferences?: CrossReference[];
+    synonyms?: string[];
+}
+export interface DiseaseAnnotation {
+    id: string;
+    name: string;
+    doId?: string;
+    associationType?: string;
+    evidence?: string[];
+    publications?: PublicationRef[];
+}
+export interface DiseaseResponse {
+    results: DiseaseAnnotation[];
+    total: number;
+}
+export interface ExpressionAnnotation {
+    id: string;
+    assay?: string;
+    anatomicalStructure?: {
+        id: string;
+        name: string;
+    };
+    stage?: {
+        id: string;
+        name: string;
+    };
+    publications?: PublicationRef[];
+}
+export interface ExpressionResponse {
+    results: ExpressionAnnotation[];
+    total: number;
+}
+export interface Ortholog {
+    gene: {
+        id: string;
+        symbol: string;
+        species: {
+            name: string;
+        };
+    };
+    homologyType?: string;
+    methodCount?: number;
+    best?: boolean;
+    bestReverse?: boolean;
+}
+export interface OrthologyResponse {
+    results: Ortholog[];
+    total: number;
+}
+export interface PhenotypeAnnotation {
+    id: string;
+    phenotype: string;
+    phenotypeStatement?: string;
+    primaryAnnotatedEntities?: Array<{
+        id: string;
+        name: string;
+        type: string;
+    }>;
+    publications?: PublicationRef[];
+}
+export interface PhenotypeResponse {
+    results: PhenotypeAnnotation[];
+    total: number;
+}
+export interface Interaction {
+    interactorAGeneId: string;
+    interactorASymbol: string;
+    interactorBGeneId: string;
+    interactorBSymbol: string;
+    interactionType?: string;
+    detectionMethod?: string;
+    publications?: PublicationRef[];
+}
+export interface InteractionResponse {
+    results: Interaction[];
+    total: number;
+}
+export interface Allele {
+    id: string;
+    symbol: string;
+    name?: string;
+    synonyms?: string[];
+    alleleType?: string;
+    gene?: {
+        id: string;
+        symbol: string;
+    };
+    species?: {
+        name: string;
+    };
+}
+export interface AlleleResponse {
+    results: Allele[];
+    total: number;
+}
+export interface PublicationRef {
+    id: string;
+    pubMedId?: string;
+    citation?: string;
+}
+export interface AllianceMineResult {
+    type: string;
+    id: number;
+    relevance: number;
+    fields: Record<string, unknown>;
+}
+export interface AllianceMineResponse {
+    results: AllianceMineResult[];
+    totalHits: number;
+    facets?: Record<string, unknown>;
+}
+export interface APIError {
+    status: number;
+    message: string;
+    details?: string;
+}