WormBase MCP Server

Instructions

Implementation Reference

• src/index.ts:156-176 (registration)

  Registration of the MCP 'get_variation' tool. Includes tool name, description, input schema (Zod validation for 'id' and optional 'widgets'), and inline handler that fetches data via WormBaseClient.getEntity('variation', ...) and returns JSON or error.

  server.tool(
    "get_variation",
    "Get information about a genetic variation/allele including molecular details, phenotypes, and strains.",
    {
      id: z.string().describe("Variation identifier - allele name (e.g., 'e1370') or WormBase variation ID"),
      widgets: z.array(z.string()).optional().describe("Specific widgets to fetch: overview, molecular_details, phenotypes, references"),
    },
    async ({ id, widgets }) => {
      try {
        const data = await client.getEntity("variation", id, widgets);
        return {
          content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
        };
      } catch (error) {
        return {
          content: [{ type: "text", text: `Error fetching variation: ${error}` }],
          isError: true,
        };
      }
    }
  );

• src/client.ts:111-132 (handler)

  Core handler logic in WormBaseClient.getEntity(), called by get_variation tool with type='variation'. Fetches data from WormBase REST API endpoints for specified widgets, cleans the data, and handles errors per widget.

  async getEntity(
    type: EntityType,
    id: string,
    widgets?: string[]
  ): Promise<Record<string, unknown>> {
    const defaultWidgets = ["overview"];
    const requestedWidgets = widgets || defaultWidgets;
  
    const result: Record<string, unknown> = { id, type };
  
    for (const widget of requestedWidgets) {
      try {
        const url = `${this.baseUrl}/rest/widget/${type}/${encodeURIComponent(id)}/${widget}`;
        const data = await this.fetch<any>(url);
        result[widget] = this.cleanWidgetData(data);
      } catch (error) {
        result[widget] = { error: `Failed to fetch ${widget}` };
      }
    }
  
    return result;
  }

• src/index.ts:159-162 (schema)

  Zod input schema specific to get_variation tool: required 'id' string, optional 'widgets' array.

  {
    id: z.string().describe("Variation identifier - allele name (e.g., 'e1370') or WormBase variation ID"),
    widgets: z.array(z.string()).optional().describe("Specific widgets to fetch: overview, molecular_details, phenotypes, references"),
  },

• src/types.ts:1-43 (helper)

  EntityType union includes 'variation', used in getEntity type parameter and schema validation.

  // WormBase entity types
  export const ENTITY_TYPES = [
    "gene",
    "protein",
    "transcript",
    "cds",
    "pseudogene",
    "phenotype",
    "disease",
    "strain",
    "variation",
    "transgene",
    "rnai",
    "anatomy_term",
    "life_stage",
    "go_term",
    "interaction",
    "expression_cluster",
    "expr_pattern",
    "paper",
    "person",
    "laboratory",
    "clone",
    "sequence",
    "feature",
    "operon",
    "gene_class",
    "molecule",
    "antibody",
    "construct",
    "motif",
    "homology_group",
    "rearrangement",
    "transposon",
    "transposon_family",
    "pcr_oligo",
    "position_matrix",
    "microarray_results",
    "structure_data",
    "analysis",
    "gene_cluster",
    "expr_profile",
  ] as const;