agr-mcp-server 4.0.3 → 5.0.2

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { EntityType, SearchResponse, GeneData, DiseaseResponse, ExpressionResponse, OrthologyResponse, PhenotypeResponse, InteractionResponse, AlleleResponse, Species } from "./types.js";
+import { EntityType, SearchResponse, GeneData, DiseaseResponse, ExpressionResponse, OrthologyResponse, PhenotypeResponse, InteractionResponse, AlleleResponse, Species, QueryBuilder, PathQueryResult, MineTemplate, MineList, ListContents } from "./types.js";
 export declare class AllianceClient {
     private agrApiUrl;
     private allianceMineUrl;
@@ -9,9 +9,14 @@ export declare class AllianceClient {
      */
     search(query: string, category?: EntityType, species?: string, limit?: number): Promise<SearchResponse>;
     /**
-     * Search using AllianceMine for more advanced queries
+     * Search using AllianceMine for more advanced queries.
+     * Falls back to PathQuery-based search if keyword search fails.
      */
     searchMine(query: string, type?: string, limit?: number): Promise<SearchResponse>;
+    /**
+     * Fallback search using PathQuery when keyword search is unavailable
+     */
+    private searchMineViaPathQuery;
     private parseMineResults;
     /**
      * Get detailed gene information
@@ -57,4 +62,55 @@ export declare class AllianceClient {
      * Helper to resolve species short name
      */
     resolveSpecies(input: string): Species | null;
+    private getAuthToken;
+    private fetchWithAuth;
+    /**
+     * Run a raw PathQuery XML query against AllianceMine
+     */
+    runPathQuery(xml: string): Promise<PathQueryResult>;
+    /**
+     * Build PathQuery XML from QueryBuilder definition
+     */
+    buildPathQueryXml(query: QueryBuilder): string;
+    private escapeXml;
+    /**
+     * Build and run a query using the QueryBuilder DSL
+     */
+    buildAndRunQuery(query: QueryBuilder): Promise<PathQueryResult>;
+    /**
+     * List available query templates
+     */
+    listTemplates(): Promise<MineTemplate[]>;
+    /**
+     * Run a template query with parameters.
+     * Parameters should be provided as { "1": { path: "Gene", op: "LOOKUP", value: "BRCA1" } }
+     * or simplified as { "1": "BRCA1" } for LOOKUP constraints (path and op inferred from template).
+     */
+    runTemplate(name: string, params: Record<string, string | {
+        path?: string;
+        op?: string;
+        value: string;
+    }>, limit?: number): Promise<PathQueryResult>;
+    /**
+     * Get all available lists
+     */
+    getLists(type?: string): Promise<MineList[]>;
+    /**
+     * Get contents of a specific list
+     */
+    getList(name: string): Promise<ListContents | null>;
+    /**
+     * Create a new list (requires authentication)
+     */
+    createList(name: string, type: string, identifiers: string[], description?: string): Promise<MineList>;
+    /**
+     * Add items to an existing list (requires authentication)
+     */
+    addToList(name: string, identifiers: string[]): Promise<MineList>;
+    /**
+     * Delete a list (requires authentication)
+     */
+    deleteList(name: string): Promise<{
+        success: boolean;
+    }>;
 }

package/dist/client.js

@@ -1,6 +1,6 @@
 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";
+const ALLIANCEMINE_URL = "https://alliancemine.alliancegenome.org/alliancemine/service";
 export class AllianceClient {
     agrApiUrl;
     allianceMineUrl;
@@ -64,9 +64,11 @@ export class AllianceClient {
         }
     }
     /**
-     * Search using AllianceMine for more advanced queries
+     * Search using AllianceMine for more advanced queries.
+     * Falls back to PathQuery-based search if keyword search fails.
      */
     async searchMine(query, type, limit = 20) {
+        // Try keyword search first
         const params = new URLSearchParams({
             q: query,
             size: String(limit),
@@ -77,13 +79,51 @@ export class AllianceClient {
         const url = `${this.allianceMineUrl}/search?${params.toString()}`;
         try {
             const response = await this.fetch(url);
+            // Check if search service returned an error
+            if (response.wasSuccessful === false || response.error) {
+                throw new Error(response.error || "Search service unavailable");
+            }
             return {
                 query,
                 results: this.parseMineResults(response.results, limit),
                 total: response.totalHits,
             };
         }
-        catch (error) {
+        catch {
+            // Fallback to PathQuery-based search
+            return this.searchMineViaPathQuery(query, type, limit);
+        }
+    }
+    /**
+     * Fallback search using PathQuery when keyword search is unavailable
+     */
+    async searchMineViaPathQuery(query, type, limit = 20) {
+        const searchType = type || "Gene";
+        const xml = `<query model="genomic" view="${searchType}.primaryIdentifier ${searchType}.symbol ${searchType}.name ${searchType}.organism.shortName">
+      <constraint path="${searchType}.symbol" op="CONTAINS" value="${this.escapeXml(query)}"/>
+    </query>`;
+        const params = new URLSearchParams({
+            query: xml,
+            format: "json",
+            size: String(limit),
+        });
+        const url = `${this.allianceMineUrl}/query/results?${params.toString()}`;
+        try {
+            const response = await this.fetch(url);
+            const results = response.results.map((row) => ({
+                id: String(row[0] || ""),
+                symbol: String(row[1] || ""),
+                name: String(row[2] || row[1] || ""),
+                species: String(row[3] || ""),
+                category: searchType.toLowerCase(),
+            }));
+            return {
+                query,
+                results,
+                total: results.length,
+            };
+        }
+        catch {
             return { query, results: [], total: 0 };
         }
     }
@@ -238,4 +278,297 @@ export class AllianceClient {
         }
         return null;
     }
+    // ============================================
+    // AllianceMine API Methods
+    // ============================================
+    getAuthToken() {
+        return process.env.ALLIANCEMINE_TOKEN || null;
+    }
+    async fetchWithAuth(url, options = {}) {
+        const token = this.getAuthToken();
+        if (!token) {
+            throw new Error("Authentication required. Set ALLIANCEMINE_TOKEN environment variable.");
+        }
+        const headers = {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            Authorization: `Token ${token}`,
+        };
+        const response = await fetch(url, {
+            ...options,
+            headers: { ...headers, ...options.headers },
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        return response.json();
+    }
+    /**
+     * Run a raw PathQuery XML query against AllianceMine
+     */
+    async runPathQuery(xml) {
+        const params = new URLSearchParams({
+            query: xml,
+            format: "json",
+        });
+        const url = `${this.allianceMineUrl}/query/results?${params.toString()}`;
+        try {
+            const response = await this.fetch(url);
+            // Convert array results to objects using column headers
+            const headers = response.columnHeaders || [];
+            const results = response.results.map((row) => {
+                const obj = {};
+                row.forEach((val, idx) => {
+                    const key = headers[idx] || `col${idx}`;
+                    obj[key] = val;
+                });
+                return obj;
+            });
+            return {
+                results,
+                columnHeaders: headers,
+                rootClass: response.rootClass,
+            };
+        }
+        catch (error) {
+            throw new Error(`PathQuery failed: ${error}`);
+        }
+    }
+    /**
+     * Build PathQuery XML from QueryBuilder definition
+     */
+    buildPathQueryXml(query) {
+        const { from, select, where, joins, sort } = query;
+        // Prefix select fields with root class if not already prefixed
+        const viewFields = select.map((field) => field.startsWith(`${from}.`) ? field : `${from}.${field}`);
+        let xml = `<query model="genomic" view="${viewFields.join(" ")}"`;
+        if (sort) {
+            xml += ` sortOrder="${sort.field} ${sort.direction}"`;
+        }
+        xml += ">";
+        // Add outer joins
+        if (joins && joins.length > 0) {
+            for (const join of joins) {
+                xml += `<join path="${from}.${join}" style="OUTER"/>`;
+            }
+        }
+        // Add constraints
+        if (where) {
+            let code = "A";
+            for (const [field, constraint] of Object.entries(where)) {
+                const path = field.includes(".") ? `${from}.${field}` : `${from}.${field}`;
+                if (typeof constraint === "string") {
+                    xml += `<constraint path="${path}" op="=" value="${this.escapeXml(constraint)}" code="${code}"/>`;
+                }
+                else {
+                    const c = constraint;
+                    if (Array.isArray(c.value)) {
+                        xml += `<constraint path="${path}" op="${c.op}" code="${code}">${c.value.map((v) => `<value>${this.escapeXml(v)}</value>`).join("")}</constraint>`;
+                    }
+                    else if (c.op === "IS NULL" || c.op === "IS NOT NULL") {
+                        xml += `<constraint path="${path}" op="${c.op}" code="${code}"/>`;
+                    }
+                    else {
+                        xml += `<constraint path="${path}" op="${c.op}" value="${this.escapeXml(String(c.value))}" code="${code}"/>`;
+                    }
+                }
+                code = String.fromCharCode(code.charCodeAt(0) + 1);
+            }
+        }
+        xml += "</query>";
+        return xml;
+    }
+    escapeXml(str) {
+        return str
+            .replace(/&/g, "&amp;")
+            .replace(/</g, "&lt;")
+            .replace(/>/g, "&gt;")
+            .replace(/"/g, "&quot;")
+            .replace(/'/g, "&apos;");
+    }
+    /**
+     * Build and run a query using the QueryBuilder DSL
+     */
+    async buildAndRunQuery(query) {
+        const xml = this.buildPathQueryXml(query);
+        // Add limit via size parameter
+        const params = new URLSearchParams({
+            query: xml,
+            format: "json",
+            size: String(query.limit || 100),
+        });
+        const url = `${this.allianceMineUrl}/query/results?${params.toString()}`;
+        try {
+            const response = await this.fetch(url);
+            const headers = response.columnHeaders || [];
+            const results = response.results.map((row) => {
+                const obj = {};
+                row.forEach((val, idx) => {
+                    const key = headers[idx] || `col${idx}`;
+                    obj[key] = val;
+                });
+                return obj;
+            });
+            return {
+                results,
+                columnHeaders: headers,
+                rootClass: response.rootClass,
+            };
+        }
+        catch (error) {
+            throw new Error(`Query failed: ${error}`);
+        }
+    }
+    /**
+     * List available query templates
+     */
+    async listTemplates() {
+        const url = `${this.allianceMineUrl}/templates?format=json`;
+        try {
+            const response = await this.fetch(url);
+            return Object.entries(response.templates).map(([name, template]) => ({
+                ...template,
+                name,
+            }));
+        }
+        catch (error) {
+            return [];
+        }
+    }
+    /**
+     * Run a template query with parameters.
+     * Parameters should be provided as { "1": { path: "Gene", op: "LOOKUP", value: "BRCA1" } }
+     * or simplified as { "1": "BRCA1" } for LOOKUP constraints (path and op inferred from template).
+     */
+    async runTemplate(name, params, limit = 100) {
+        const queryParams = new URLSearchParams({
+            name,
+            format: "json",
+            size: String(limit),
+        });
+        // Add template parameters
+        for (const [key, param] of Object.entries(params)) {
+            if (typeof param === "string") {
+                // Simple format: just the value, assume LOOKUP
+                queryParams.set(`value${key}`, param);
+            }
+            else {
+                // Full format with path, op, value
+                if (param.path)
+                    queryParams.set(`constraint${key}`, param.path);
+                if (param.op)
+                    queryParams.set(`op${key}`, param.op);
+                queryParams.set(`value${key}`, param.value);
+            }
+        }
+        const url = `${this.allianceMineUrl}/template/results?${queryParams.toString()}`;
+        try {
+            const response = await this.fetch(url);
+            const headers = response.columnHeaders || [];
+            const results = response.results.map((row) => {
+                const obj = {};
+                row.forEach((val, idx) => {
+                    const key = headers[idx] || `col${idx}`;
+                    obj[key] = val;
+                });
+                return obj;
+            });
+            return {
+                results,
+                columnHeaders: headers,
+            };
+        }
+        catch (error) {
+            throw new Error(`Template query failed: ${error}`);
+        }
+    }
+    /**
+     * Get all available lists
+     */
+    async getLists(type) {
+        const params = new URLSearchParams();
+        if (type) {
+            params.set("type", type);
+        }
+        const url = `${this.allianceMineUrl}/lists?${params.toString()}`;
+        try {
+            const response = await this.fetch(url);
+            return response.lists || [];
+        }
+        catch (error) {
+            return [];
+        }
+    }
+    /**
+     * Get contents of a specific list
+     */
+    async getList(name) {
+        const url = `${this.allianceMineUrl}/list/results/${encodeURIComponent(name)}?format=json`;
+        try {
+            const response = await this.fetch(url);
+            const headers = response.columnHeaders || [];
+            const results = response.results.map((row) => {
+                const obj = {};
+                row.forEach((val, idx) => {
+                    const key = headers[idx] || `col${idx}`;
+                    obj[key] = val;
+                });
+                return obj;
+            });
+            return {
+                name: response.listInfo?.name || name,
+                type: response.listInfo?.type || "unknown",
+                size: response.listInfo?.size || results.length,
+                results,
+            };
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    /**
+     * Create a new list (requires authentication)
+     */
+    async createList(name, type, identifiers, description) {
+        const params = new URLSearchParams({
+            name,
+            type,
+        });
+        if (description) {
+            params.set("description", description);
+        }
+        const url = `${this.allianceMineUrl}/lists?${params.toString()}`;
+        const response = await this.fetchWithAuth(url, {
+            method: "POST",
+            body: identifiers.join("\n"),
+            headers: {
+                "Content-Type": "text/plain",
+            },
+        });
+        return response;
+    }
+    /**
+     * Add items to an existing list (requires authentication)
+     */
+    async addToList(name, identifiers) {
+        const url = `${this.allianceMineUrl}/lists/append/${encodeURIComponent(name)}`;
+        const response = await this.fetchWithAuth(url, {
+            method: "POST",
+            body: identifiers.join("\n"),
+            headers: {
+                "Content-Type": "text/plain",
+            },
+        });
+        return response;
+    }
+    /**
+     * Delete a list (requires authentication)
+     */
+    async deleteList(name) {
+        const url = `${this.allianceMineUrl}/lists/${encodeURIComponent(name)}`;
+        await this.fetchWithAuth(url, {
+            method: "DELETE",
+        });
+        return { success: true };
+    }
 }

package/dist/index.js

@@ -7,7 +7,7 @@ import { ENTITY_TYPES } from "./types.js";
 const client = new AllianceClient();
 const server = new McpServer({
     name: "agr-genomics",
-    version: "4.0.3",
+    version: "5.0.2",
 });
 // Tool: Search genes
 server.tool("search_genes", "Search for genes across all Alliance of Genome Resources model organisms. Supports species filtering.", {
@@ -234,6 +234,444 @@ server.tool("get_species_list", "Get list of model organisms supported by Allian
         };
     }
 });
+// ============================================
+// AllianceMine Tools
+// ============================================
+// Tool: Mine Search
+server.tool("mine_search", "Search AllianceMine for genes, proteins, diseases, and other biological entities using keyword search.", {
+    query: z.string().describe("Search query - keyword, gene symbol, protein name, etc."),
+    type: z
+        .string()
+        .optional()
+        .describe("Filter by type: Gene, Protein, Disease, Pathway, etc."),
+    limit: z.number().optional().default(20).describe("Maximum results"),
+}, async ({ query, type, limit }) => {
+    try {
+        const results = await client.searchMine(query, type, limit);
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error searching AllianceMine: ${error}` }],
+            isError: true,
+        };
+    }
+});
+// Tool: Mine Query (raw PathQuery XML)
+server.tool("mine_query", "Run a raw PathQuery XML query against AllianceMine. For power users who know InterMine PathQuery syntax.", {
+    xml: z.string().describe("PathQuery XML string"),
+}, async ({ xml }) => {
+    try {
+        const results = await client.runPathQuery(xml);
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `PathQuery error: ${error}` }],
+            isError: true,
+        };
+    }
+});
+// Tool: Mine Query Builder
+server.tool("mine_query_builder", `Build and run structured queries against AllianceMine using a JSON DSL.
+
+Example query - find human genes in DNA repair pathway:
+{
+  "from": "Gene",
+  "select": ["symbol", "name", "organism.name", "pathways.name"],
+  "where": {
+    "organism.name": "Homo sapiens",
+    "pathways.name": { "op": "CONTAINS", "value": "DNA repair" }
+  },
+  "limit": 50
+}
+
+Supported operators: =, !=, CONTAINS, LIKE, <, >, <=, >=, ONE OF, NONE OF, IS NULL, IS NOT NULL`, {
+    from: z.string().describe("Root class: Gene, Protein, Disease, Pathway, Phenotype, etc."),
+    select: z.array(z.string()).describe("Fields to return, e.g., ['symbol', 'organism.name']"),
+    where: z
+        .record(z.union([
+        z.string(),
+        z.object({
+            op: z.string(),
+            value: z.union([z.string(), z.array(z.string())]),
+        }),
+    ]))
+        .optional()
+        .describe("Constraints as field: value or field: {op, value}"),
+    joins: z.array(z.string()).optional().describe("OUTER JOIN paths for optional relationships"),
+    sort: z
+        .object({
+        field: z.string(),
+        direction: z.enum(["ASC", "DESC"]),
+    })
+        .optional()
+        .describe("Sort order"),
+    limit: z.number().optional().default(100).describe("Maximum results"),
+}, async ({ from, select, where, joins, sort, limit }) => {
+    try {
+        const results = await client.buildAndRunQuery({
+            from,
+            select,
+            where: where,
+            joins,
+            sort,
+            limit,
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Query error: ${error}` }],
+            isError: true,
+        };
+    }
+});
+// Tool: Mine Natural Query
+server.tool("mine_natural_query", `Process a natural language query and return schema information to construct a structured AllianceMine query.
+
+This tool returns the AllianceMine schema so you can convert the user's natural language into a mine_query_builder call.`, {
+    query: z.string().describe("Natural language query describing what to find"),
+    limit: z.number().optional().default(100).describe("Maximum results"),
+}, async ({ query, limit }) => {
+    // Return comprehensive schema for LLM to construct the query
+    const schema = {
+        user_query: query,
+        requested_limit: limit,
+        instruction: "Use mine_query_builder to execute this query. Analyze the user's natural language and construct the appropriate structured query using the schema below.",
+        classes: {
+            Gene: {
+                description: "Genes from all model organisms",
+                common_fields: ["primaryIdentifier", "symbol", "name", "description", "secondaryIdentifier"],
+                relationships: {
+                    "organism": "Organism (use organism.shortName or organism.name)",
+                    "chromosome": "Chromosome (use chromosome.primaryIdentifier)",
+                    "diseases": "Disease associations",
+                    "phenotypes": "Phenotype annotations",
+                    "pathways": "Pathway memberships",
+                    "alleles": "Gene alleles/variants",
+                    "goAnnotation": "GO term annotations",
+                    "homologues": "Ortholog/paralog relationships",
+                    "proteins": "Encoded proteins",
+                    "publications": "Related publications"
+                }
+            },
+            Protein: {
+                description: "Protein records",
+                common_fields: ["primaryIdentifier", "primaryAccession", "name", "length"],
+                relationships: {
+                    "genes": "Encoding genes",
+                    "organism": "Source organism",
+                    "proteinDomains": "Protein domains"
+                }
+            },
+            Disease: {
+                description: "Disease ontology terms (DO)",
+                common_fields: ["primaryIdentifier", "name", "description"],
+                relationships: {
+                    "genes": "Associated genes",
+                    "alleles": "Associated alleles",
+                    "parents": "Parent terms",
+                    "children": "Child terms"
+                }
+            },
+            Pathway: {
+                description: "Biological pathways",
+                common_fields: ["primaryIdentifier", "name", "description"],
+                relationships: {
+                    "genes": "Genes in pathway",
+                    "dataSets": "Data sources"
+                }
+            },
+            Phenotype: {
+                description: "Phenotype annotations",
+                common_fields: ["primaryIdentifier", "description"],
+                relationships: {
+                    "genes": "Associated genes",
+                    "alleles": "Associated alleles"
+                }
+            },
+            Allele: {
+                description: "Gene alleles and variants",
+                common_fields: ["primaryIdentifier", "symbol", "name", "alleleClass", "description"],
+                relationships: {
+                    "gene": "Parent gene",
+                    "organism": "Source organism",
+                    "phenotypes": "Associated phenotypes"
+                }
+            },
+            GOTerm: {
+                description: "Gene Ontology terms",
+                common_fields: ["primaryIdentifier", "name", "description", "namespace"],
+                relationships: {
+                    "genes": "Annotated genes",
+                    "parents": "Parent terms",
+                    "children": "Child terms"
+                }
+            },
+            Publication: {
+                description: "Scientific publications",
+                common_fields: ["primaryIdentifier", "pubMedId", "title", "firstAuthor", "year", "journal"],
+                relationships: {
+                    "genes": "Mentioned genes",
+                    "authors": "Author list"
+                }
+            },
+            Organism: {
+                description: "Species/organisms",
+                common_fields: ["shortName", "name", "taxonId"],
+                short_names: {
+                    "H. sapiens": "Human",
+                    "M. musculus": "Mouse",
+                    "R. norvegicus": "Rat",
+                    "D. rerio": "Zebrafish",
+                    "D. melanogaster": "Fly",
+                    "C. elegans": "Worm",
+                    "S. cerevisiae": "Yeast",
+                    "X. laevis": "Frog (Xenopus laevis)",
+                    "X. tropicalis": "Frog (Xenopus tropicalis)"
+                }
+            }
+        },
+        operators: {
+            "=": "Exact match",
+            "!=": "Not equal",
+            "CONTAINS": "Contains substring (case-insensitive)",
+            "LIKE": "Pattern match with wildcards (*)",
+            "<": "Less than",
+            ">": "Greater than",
+            "<=": "Less than or equal",
+            ">=": "Greater than or equal",
+            "ONE OF": "Match any in list (value should be array)",
+            "NONE OF": "Match none in list (value should be array)",
+            "IS NULL": "Field is empty",
+            "IS NOT NULL": "Field has value"
+        },
+        query_builder_format: {
+            from: "Root class name (e.g., 'Gene')",
+            select: "Array of fields to return (e.g., ['primaryIdentifier', 'symbol', 'name'])",
+            where: "Object with field constraints (e.g., { 'symbol': { op: 'CONTAINS', value: 'BRCA' } })",
+            joins: "Optional: array of paths to OUTER JOIN (for optional relationships)",
+            sort: "Optional: { field: 'symbol', direction: 'ASC' }",
+            limit: "Optional: max results (default 100)"
+        },
+        examples: [
+            {
+                natural: "human genes related to cancer",
+                structured: {
+                    from: "Gene",
+                    select: ["primaryIdentifier", "symbol", "name", "organism.shortName"],
+                    where: {
+                        "organism.shortName": "H. sapiens",
+                        "name": { op: "CONTAINS", value: "cancer" }
+                    },
+                    limit: 100
+                }
+            },
+            {
+                natural: "mouse genes on chromosome 11",
+                structured: {
+                    from: "Gene",
+                    select: ["primaryIdentifier", "symbol", "name", "chromosome.primaryIdentifier"],
+                    where: {
+                        "organism.shortName": "M. musculus",
+                        "chromosome.primaryIdentifier": "11"
+                    }
+                }
+            },
+            {
+                natural: "diseases associated with BRCA1",
+                structured: {
+                    from: "Disease",
+                    select: ["primaryIdentifier", "name", "genes.symbol"],
+                    where: {
+                        "genes.symbol": "BRCA1"
+                    }
+                }
+            },
+            {
+                natural: "all yeast genes with kinase activity",
+                structured: {
+                    from: "Gene",
+                    select: ["primaryIdentifier", "symbol", "name", "goAnnotation.ontologyTerm.name"],
+                    where: {
+                        "organism.shortName": "S. cerevisiae",
+                        "goAnnotation.ontologyTerm.name": { op: "CONTAINS", value: "kinase" }
+                    }
+                }
+            }
+        ]
+    };
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(schema, null, 2),
+            },
+        ],
+    };
+});
+// Tool: List Templates
+server.tool("mine_list_templates", "List available query templates in AllianceMine. Templates are pre-built queries for common use cases.", {}, async () => {
+    try {
+        const templates = await client.listTemplates();
+        return {
+            content: [{ type: "text", text: JSON.stringify(templates, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error listing templates: ${error}` }],
+            isError: true,
+        };
+    }
+});
+// Tool: Run Template
+server.tool("mine_run_template", `Run a pre-built query template with parameters.
+
+Parameter format: Use numeric keys ("1", "2", etc.) matching constraint positions.
+- Simple: {"1": "BRCA1"} - just the value
+- Full: {"1": {"path": "Gene", "op": "LOOKUP", "value": "BRCA1"}}
+
+Common templates:
+- Gene_Orthologs: Find orthologs (params: {"1": {"path": "Gene", "op": "LOOKUP", "value": "HGNC:1100"}})
+- Gene_GOTerms: GO annotations for a gene
+- Gene_DOTerm: Disease annotations for a gene
+- GOTerm_Genes: Find genes by GO term
+
+Use mine_list_templates to discover all available templates and their constraints.`, {
+    name: z.string().describe("Template name (e.g., 'Gene_Orthologs')"),
+    params: z
+        .record(z.union([
+        z.string(),
+        z.object({
+            path: z.string().optional(),
+            op: z.string().optional(),
+            value: z.string(),
+        }),
+    ]))
+        .describe("Template parameters with numeric keys, e.g., {'1': {'path': 'Gene', 'op': 'LOOKUP', 'value': 'HGNC:1100'}}"),
+    limit: z.number().optional().default(100).describe("Maximum results"),
+}, async ({ name, params, limit }) => {
+    try {
+        const results = await client.runTemplate(name, params, limit);
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Template error: ${error}` }],
+            isError: true,
+        };
+    }
+});
+// Tool: Get Lists
+server.tool("mine_get_lists", "Get all available gene/protein lists in AllianceMine.", {
+    type: z
+        .string()
+        .optional()
+        .describe("Filter by type: Gene, Protein, etc."),
+}, async ({ type }) => {
+    try {
+        const lists = await client.getLists(type);
+        return {
+            content: [{ type: "text", text: JSON.stringify(lists, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error fetching lists: ${error}` }],
+            isError: true,
+        };
+    }
+});
+// Tool: Get List Contents
+server.tool("mine_get_list", "Get the contents of a specific list.", {
+    name: z.string().describe("List name"),
+}, async ({ name }) => {
+    try {
+        const data = await client.getList(name);
+        if (!data) {
+            return {
+                content: [{ type: "text", text: `List not found: ${name}` }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error fetching list: ${error}` }],
+            isError: true,
+        };
+    }
+});
+// Tool: Create List (requires auth)
+server.tool("mine_create_list", "Create a new list in AllianceMine. Requires ALLIANCEMINE_TOKEN environment variable.", {
+    name: z.string().describe("List name"),
+    type: z.string().describe("List type: Gene, Protein, etc."),
+    identifiers: z
+        .array(z.string())
+        .describe("Array of identifiers to add to the list"),
+    description: z.string().optional().describe("List description"),
+}, async ({ name, type, identifiers, description }) => {
+    try {
+        const result = await client.createList(name, type, identifiers, description);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error creating list: ${error}` }],
+            isError: true,
+        };
+    }
+});
+// Tool: Add to List (requires auth)
+server.tool("mine_add_to_list", "Add items to an existing list. Requires ALLIANCEMINE_TOKEN environment variable.", {
+    name: z.string().describe("List name"),
+    identifiers: z.array(z.string()).describe("Identifiers to add"),
+}, async ({ name, identifiers }) => {
+    try {
+        const result = await client.addToList(name, identifiers);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error adding to list: ${error}` }],
+            isError: true,
+        };
+    }
+});
+// Tool: Delete List (requires auth)
+server.tool("mine_delete_list", "Delete a list from AllianceMine. Requires ALLIANCEMINE_TOKEN environment variable.", {
+    name: z.string().describe("List name to delete"),
+}, async ({ name }) => {
+    try {
+        const result = await client.deleteList(name);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error deleting list: ${error}` }],
+            isError: true,
+        };
+    }
+});
 // Resource: Entity types
 server.resource("entity-types", "agr://entity-types", async () => ({
     contents: [

package/dist/types.d.ts

@@ -160,6 +160,57 @@ export interface AllianceMineResponse {
     totalHits: number;
     facets?: Record<string, unknown>;
 }
+export type QueryOperator = "=" | "!=" | "CONTAINS" | "LIKE" | "<" | ">" | "<=" | ">=" | "ONE OF" | "NONE OF" | "IS NULL" | "IS NOT NULL";
+export interface QueryConstraint {
+    op: QueryOperator;
+    value: string | string[];
+}
+export interface QuerySort {
+    field: string;
+    direction: "ASC" | "DESC";
+}
+export interface QueryBuilder {
+    from: string;
+    select: string[];
+    where?: Record<string, string | QueryConstraint>;
+    joins?: string[];
+    sort?: QuerySort;
+    limit?: number;
+}
+export interface PathQueryResult {
+    results: Record<string, unknown>[];
+    columnHeaders?: string[];
+    rootClass?: string;
+}
+export interface MineTemplate {
+    name: string;
+    title: string;
+    description?: string;
+    rank?: number;
+    constraintLogic?: string;
+    constraints?: Record<string, unknown>[];
+}
+export interface TemplateParameter {
+    name: string;
+    path: string;
+    op: string;
+    value?: string;
+    code?: string;
+}
+export interface MineList {
+    name: string;
+    type: string;
+    size: number;
+    description?: string;
+    dateCreated?: string;
+    authorized?: boolean;
+}
+export interface ListContents {
+    name: string;
+    type: string;
+    size: number;
+    results: Record<string, unknown>[];
+}
 export interface APIError {
     status: number;
     message: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agr-mcp-server",
-  "version": "4.0.3",
+  "version": "5.0.2",
   "description": "MCP server for Alliance of Genome Resources - access genomics data across model organisms",
   "main": "dist/index.js",
   "bin": {