Ensembl MCP Server

Instructions

Implementation Reference

• src/index.ts:1553-1581 (handler)

  The handler function that executes the get_karyotype tool. It validates input, queries the Ensembl REST API /info/assembly/{species}?bands=1 endpoint, extracts karyotype and chromosome data, and formats the response.

  private async handleGetKaryotype(args: any) {
    if (!isValidAssemblyArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid karyotype arguments');
    }
  
    try {
      const species = this.getDefaultSpecies(args.species);
  
      const response = await this.apiClient.get(`/info/assembly/${species}`, {
        params: { bands: 1 },
      });
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              species,
              assembly_name: response.data.assembly_name,
              karyotype: response.data.karyotype || [],
              chromosomes: response.data.top_level_region || [],
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return this.handleError(error, 'fetching karyotype');
    }
  }

• src/index.ts:873-874 (registration)

  The switch case in the CallToolRequestSchema handler that routes calls to the get_karyotype tool to its handler function.

  case 'get_karyotype':
    return this.handleGetKaryotype(args);

• src/index.ts:790-799 (registration)

  The tool registration entry in the ListToolsRequestSchema response, defining the name, description, and input schema for get_karyotype.

    name: 'get_karyotype',
    description: 'Get chromosome information and karyotype',
    inputSchema: {
      type: 'object',
      properties: {
        species: { type: 'string', description: 'Species name (default: homo_sapiens)' },
      },
      required: [],
    },
  },

• src/index.ts:272-281 (schema)

  Type guard function used to validate input arguments for the get_karyotype tool (shared with get_assembly_info).

  const isValidAssemblyArgs = (
    args: any
  ): args is { species?: string; bands?: boolean } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      (args.species === undefined || typeof args.species === 'string') &&
      (args.bands === undefined || typeof args.bands === 'boolean')
    );
  };

• src/index.ts:890-892 (helper)

  Utility method used in get_karyotype handler to provide default species value.

  private getDefaultSpecies(species?: string): string {
    return species || 'homo_sapiens';
  }