gnomAD MCP Server

Instructions

Implementation Reference

• src/index.ts:697-706 (handler)

  Handler logic for the get_region_variants tool: parses arguments, calls GraphQL query via makeGraphQLRequest, and returns the variants array as JSON.

  case "get_region_variants":
    result = await makeGraphQLRequest(QUERIES.getRegionVariants, {
      chrom: String(args.chrom),
      start: parseInt(String(args.start)),
      stop: parseInt(String(args.stop)),
      datasetId: parseDatasetId((args.dataset as string) || "gnomad_r4"),
      referenceGenome: parseReferenceGenome((args.reference_genome as string) || "GRCh38"),
    });
    formattedResult = result.data?.region?.variants || [];
    break;

• src/index.ts:254-280 (schema)

  GraphQL query schema defining the structure and inputs for fetching region variants from gnomAD API.

  getRegionVariants: `
    query GetRegionVariants($chrom: String!, $start: Int!, $stop: Int!, $datasetId: DatasetId!, $referenceGenome: ReferenceGenomeId!) {
      region(chrom: $chrom, start: $start, stop: $stop, reference_genome: $referenceGenome) {
        variants(dataset: $datasetId) {
          variant_id
          pos
          rsids
          consequence
          hgvsc
          hgvsp
          lof
          exome {
            ac
            an
            af
            filters
          }
          genome {
            ac
            an
            af
            filters
          }
        }
      }
    }
  `,

• src/index.ts:526-557 (registration)

  MCP tool registration including name, description, and input schema for get_region_variants.

  {
    name: "get_region_variants",
    description: "Get variants in a specific genomic region",
    inputSchema: {
      type: "object",
      properties: {
        chrom: {
          type: "string",
          description: "Chromosome (1-22, X, Y)",
        },
        start: {
          type: "number",
          description: "Start position",
        },
        stop: {
          type: "number",
          description: "Stop position",
        },
        dataset: {
          type: "string",
          description: "Dataset ID",
          default: "gnomad_r4",
        },
        reference_genome: {
          type: "string",
          description: "Reference genome",
          default: "GRCh38",
        },
      },
      required: ["chrom", "start", "stop"],
    },
  },

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

  Helper function used by all tool handlers, including get_region_variants, to execute GraphQL requests to 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 to validate and parse the dataset ID used in the get_region_variants 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;
  }