get_similar_studies

Instructions

Implementation Reference

• src/index.ts:1801-1918 (handler)

  The handleGetSimilarStudies function is the handler that executes the logic for finding similar clinical trials based on a provided NCT ID. It retrieves the reference study, determines the similarity type (CONDITION, SPONSOR, or PHASE), performs a new search on the ClinicalTrials.gov API using criteria extracted from the reference study, and filters out the reference study from the results.

  private async handleGetSimilarStudies(args: any) {
    if (!args?.nctId || !/^NCT\d{8}$/.test(args.nctId)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        "Valid NCT ID is required (format: NCT########)"
      );
    }
  
    try {
      // First get the reference study to extract similarity criteria
      const referenceResponse: AxiosResponse<StudySearchResponse> =
        await this.axiosInstance.get("/studies", {
          params: {
            format: "json",
            "query.term": args.nctId,
            pageSize: 1,
          },
        });
  
      if (
        !referenceResponse.data.studies ||
        referenceResponse.data.studies.length === 0
      ) {
        return {
          content: [
            {
              type: "text",
              text: `Reference study not found: ${args.nctId}`,
            },
          ],
          isError: true,
        };
      }
  
      const referenceStudy = referenceResponse.data.studies[0];
      const similarityType = args.similarityType || "CONDITION";
      let searchParams: any = {
        format: "json",
        pageSize: args?.pageSize || 10,
      };
  
      // Build search based on similarity type
      switch (similarityType) {
        case "CONDITION":
          const condition =
            referenceStudy.protocolSection.conditionsModule?.conditions?.[0];
          if (condition) {
            searchParams["query.cond"] = condition;
          }
          break;
        case "SPONSOR":
          const sponsor =
            referenceStudy.protocolSection.sponsorCollaboratorsModule
              ?.leadSponsor?.name;
          if (sponsor) {
            searchParams["query.spons"] = sponsor;
          }
          break;
        case "PHASE":
          const phase =
            referenceStudy.protocolSection.designModule?.phases?.[0];
          if (phase) {
            searchParams["filter.phase"] = phase;
          }
          break;
      }
  
      const response: AxiosResponse<StudySearchResponse> =
        await this.axiosInstance.get("/studies", { params: searchParams });
  
      const studies = response.data.studies || [];
      const results = studies
        .filter(
          (study) =>
            study.protocolSection.identificationModule.nctId !== args.nctId
        ) // Exclude reference study
        .map((study) => this.formatStudySummary(study));
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                referenceStudy: {
                  nctId: args.nctId,
                  title:
                    referenceStudy.protocolSection.identificationModule
                      .briefTitle,
                },
                similarityType,
                totalCount: response.data.totalCount || 0,
                resultsShown: results.length,
                similarStudies: results,
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error) {
      if (axios.isAxiosError(error)) {
        return {
          content: [
            {
              type: "text",
              text: `Clinical Trials API error: ${
                error.response?.data?.message || error.message
              }`,
            },
          ],
          isError: true,
        };
      }
      throw error;
    }
  }

• src/index.ts:531-558 (registration)

  Tool registration definition for "get_similar_studies" in the server's tool list.

    name: "get_similar_studies",
    description:
      "Find clinical trials similar to a specific study by NCT ID",
    inputSchema: {
      type: "object",
      properties: {
        nctId: {
          type: "string",
          description:
            "NCT ID of the reference study (e.g., NCT00000419)",
          pattern: "^NCT\\d{8}$",
        },
        similarityType: {
          type: "string",
          description: "Type of similarity to search for",
          enum: ["CONDITION", "INTERVENTION", "SPONSOR", "PHASE"],
          default: "CONDITION",
        },
        pageSize: {
          type: "number",
          description: "Number of results to return (default 10, max 50)",
          minimum: 1,
          maximum: 50,
        },
      },
      required: ["nctId"],
    },
  },