gnomAD MCP Server

Instructions

Implementation Reference

• src/index.ts:668-674 (handler)

  The core handler logic for the 'get_variant' tool within the CallToolRequestSchema handler. It invokes the GraphQL query using makeGraphQLRequest with the provided variant_id and parsed dataset_id.

  case "get_variant":
    result = await makeGraphQLRequest(QUERIES.getVariant, {
      variantId: args.variant_id as string,
      datasetId: parseDatasetId((args.dataset as string) || "gnomad_r4"),
    });
    formattedResult = result.data?.variant || null;
    break;

• src/index.ts:461-479 (schema)

  Input schema definition and registration for the 'get_variant' tool in the ListTools response.

  {
    name: "get_variant",
    description: "Get detailed information about a specific variant",
    inputSchema: {
      type: "object",
      properties: {
        variant_id: {
          type: "string",
          description: "Variant ID in format: chr-pos-ref-alt (e.g., 1-55516888-G-A)",
        },
        dataset: {
          type: "string",
          description: "Dataset ID (gnomad_r4, gnomad_r3, gnomad_r2_1, etc.)",
          default: "gnomad_r4",
        },
      },
      required: ["variant_id"],
    },
  },

• src/index.ts:117-186 (schema)

  GraphQL query schema (QUERIES.getVariant) that defines the structure and fields retrieved for the variant data.

  getVariant: `
    query GetVariant($variantId: String!, $datasetId: DatasetId!) {
      variant(variantId: $variantId, dataset: $datasetId) {
        variant_id
        reference_genome
        chrom
        pos
        ref
        alt
        rsids
        caid
        colocated_variants
        multi_nucleotide_variants {
          combined_variant_id
          changes_amino_acids
          n_individuals
          other_constituent_snvs
        }
        exome {
          ac
          an
          ac_hemi
          ac_hom
          faf95 {
            popmax
            popmax_population
          }
          filters
          populations {
            id
            ac
            an
            ac_hemi
            ac_hom
          }
        }
        genome {
          ac
          an
          ac_hemi
          ac_hom
          faf95 {
            popmax
            popmax_population
          }
          filters
          populations {
            id
            ac
            an
            ac_hemi
            ac_hom
          }
        }
        transcript_consequences {
          gene_id
          gene_symbol
          transcript_id
          consequence_terms
          is_canonical
          major_consequence
          polyphen_prediction
          sift_prediction
          lof
          lof_filter
          lof_flags
        }
      }
    }
  `,

• src/index.ts:44-61 (helper)

  Helper function makeGraphQLRequest used by the get_variant handler to execute the GraphQL query against the gnomAD API.

  async function makeGraphQLRequest(query: string, variables: Record<string, any> = {}): Promise<GnomadResponse> {
    const response: Response = await fetch(GNOMAD_API_URL, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        query,
        variables,
      }),
    });
  
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
  
    return await response.json() as GnomadResponse;
  }

• src/index.ts:384-400 (helper)

  Helper function parseDatasetId used to validate and default the dataset parameter in the get_variant handler.

  function parseDatasetId(dataset: string): string {
    const validDatasets = [
      "gnomad_r2_1",
      "gnomad_r3",
      "gnomad_r4",
      "gnomad_sv_r2_1",
      "gnomad_sv_r4",
      "gnomad_cnv_r4",
      "exac",
    ];
    
    const datasetLower = dataset.toLowerCase();
    if (!validDatasets.includes(datasetLower)) {
      return "gnomad_r4"; // Default to latest version
    }
    return datasetLower;
  }