OpenTargets MCP Server

Instructions

Implementation Reference

• src/index.ts:433-508 (handler)

  The main execution logic for the 'get_target_disease_associations' tool. Validates arguments, constructs and executes GraphQL queries to fetch target-disease associations from Open Targets API based on targetId or diseaseId, handles specific pair lookup (not implemented), and returns JSON results or errors.

  private async handleGetTargetDiseaseAssociations(args: any) {
    if (!isValidAssociationArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid association arguments');
    }
  
    try {
      // If only targetId provided, get associations for that target
      if (args.targetId && !args.diseaseId) {
        const query = `query GetTargetAssociations($ensemblId: String!) { target(ensemblId: $ensemblId) { id approvedSymbol associatedDiseases { rows { disease { id name } score } } } }`;
  
        const response = await this.graphqlClient.post('', {
          query,
          variables: {
            ensemblId: args.targetId,
            size: args.size || 25
          }
        });
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(response.data, null, 2),
            },
          ],
        };
      }
  
      // If only diseaseId provided, get associations for that disease
      else if (args.diseaseId && !args.targetId) {
        const query = `query GetDiseaseAssociations($efoId: String!) { disease(efoId: $efoId) { id name associatedTargets { rows { target { id approvedSymbol approvedName } score } } } }`;
  
        const response = await this.graphqlClient.post('', {
          query,
          variables: {
            efoId: args.diseaseId,
            size: args.size || 25
          }
        });
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(response.data, null, 2),
            },
          ],
        };
      }
  
      // If both provided, return the association between them
      else {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                message: "Specific target-disease pair association lookup not yet implemented",
                suggestion: "Use targetId OR diseaseId to get associations for that entity"
              }, null, 2),
            },
          ],
        };
      }
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error getting associations: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:239-248 (schema)

  JSON Schema defining the input parameters for the tool: targetId, diseaseId, minScore, size. No required fields, allowing queries by target or disease.

  inputSchema: {
    type: 'object',
    properties: {
      targetId: { type: 'string', description: 'Target Ensembl gene ID' },
      diseaseId: { type: 'string', description: 'Disease EFO ID' },
      minScore: { type: 'number', description: 'Minimum association score (0-1)', minimum: 0, maximum: 1 },
      size: { type: 'number', description: 'Number of results to return (1-500, default: 25)', minimum: 1, maximum: 500 },
    },
    required: [],
  },

• src/index.ts:236-249 (registration)

  Registration of the tool in the ListTools handler response array, including name, description, and input schema.

  {
    name: 'get_target_disease_associations',
    description: 'Get target-disease associations with evidence scores',
    inputSchema: {
      type: 'object',
      properties: {
        targetId: { type: 'string', description: 'Target Ensembl gene ID' },
        diseaseId: { type: 'string', description: 'Disease EFO ID' },
        minScore: { type: 'number', description: 'Minimum association score (0-1)', minimum: 0, maximum: 1 },
        size: { type: 'number', description: 'Number of results to return (1-500, default: 25)', minimum: 1, maximum: 500 },
      },
      required: [],
    },
  },

• src/index.ts:38-48 (helper)

  Type guard and validation function for association tool arguments, ensuring valid types and at least one ID provided.

  const isValidAssociationArgs = (args: any): args is { targetId?: string; diseaseId?: string; minScore?: number; size?: number } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      (args.targetId === undefined || typeof args.targetId === 'string') &&
      (args.diseaseId === undefined || typeof args.diseaseId === 'string') &&
      (args.minScore === undefined || (typeof args.minScore === 'number' && args.minScore >= 0 && args.minScore <= 1)) &&
      (args.size === undefined || (typeof args.size === 'number' && args.size > 0 && args.size <= 500)) &&
      (args.targetId !== undefined || args.diseaseId !== undefined)
    );
  };

• src/index.ts:296-297 (registration)

  Dispatch case in the CallToolRequestSchema handler that routes the tool call to the specific handler method.

  case 'get_target_disease_associations':
    return this.handleGetTargetDiseaseAssociations(args);