UNPKG

clinicaltrialsgov-mcp-server

Version:

ClinicalTrials.gov Model Context Protocol (MCP) Server that provides a suite of tools for interacting with the official ClinicalTrials.gov v2 API. Enables AI agents and LLMs to programmatically search, retrieve, and analyze clinical trial data.

1,007 lines (1,006 loc) 38.4 kB
/** * @fileoverview Defines the core logic, schemas, and types for the `clinicaltrials_get_study` tool. * @module src/mcp-server/tools/getStudy/logic */ import { z } from "zod"; import { type RequestContext } from "../../../utils/index.js"; /** * Zod schema for the input of the `clinicaltrials_get_study` tool. */ export declare const GetStudyInputSchema: z.ZodObject<{ nctIds: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>; markupFormat: z.ZodOptional<z.ZodDefault<z.ZodEnum<["markdown", "legacy"]>>>; fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; summaryOnly: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>; }, "strip", z.ZodTypeAny, { nctIds: string | string[]; fields?: string[] | undefined; markupFormat?: "markdown" | "legacy" | undefined; summaryOnly?: boolean | undefined; }, { nctIds: string | string[]; fields?: string[] | undefined; markupFormat?: "markdown" | "legacy" | undefined; summaryOnly?: boolean | undefined; }>; /** * TypeScript type inferred from the input schema. */ export type GetStudyInput = z.infer<typeof GetStudyInputSchema>; /** * Zod schema for a summarized study, containing only essential fields for a concise overview. */ export declare const StudySummarySchema: z.ZodObject<{ nctId: z.ZodOptional<z.ZodString>; title: z.ZodOptional<z.ZodString>; briefSummary: z.ZodOptional<z.ZodString>; overallStatus: z.ZodOptional<z.ZodString>; conditions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; interventions: z.ZodOptional<z.ZodArray<z.ZodObject<{ name: z.ZodOptional<z.ZodString>; type: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { type?: string | undefined; name?: string | undefined; }, { type?: string | undefined; name?: string | undefined; }>, "many">>; leadSponsor: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { title?: string | undefined; nctId?: string | undefined; overallStatus?: string | undefined; leadSponsor?: string | undefined; briefSummary?: string | undefined; conditions?: string[] | undefined; interventions?: { type?: string | undefined; name?: string | undefined; }[] | undefined; }, { title?: string | undefined; nctId?: string | undefined; overallStatus?: string | undefined; leadSponsor?: string | undefined; briefSummary?: string | undefined; conditions?: string[] | undefined; interventions?: { type?: string | undefined; name?: string | undefined; }[] | undefined; }>; /** * TypeScript type inferred from the summary schema. */ export type StudySummary = z.infer<typeof StudySummarySchema>; /** * Zod schema for the output of the `clinicaltrials_get_study` tool. */ export declare const GetStudyOutputSchema: z.ZodObject<{ studies: z.ZodArray<z.ZodUnion<[z.ZodObject<{ protocolSection: z.ZodOptional<z.ZodObject<{ identificationModule: z.ZodOptional<z.ZodObject<{ nctId: z.ZodString; orgStudyIdInfo: z.ZodOptional<z.ZodObject<{ id: z.ZodString; }, "strip", z.ZodTypeAny, { id: string; }, { id: string; }>>; organization: z.ZodOptional<z.ZodObject<{ fullName: z.ZodString; class: z.ZodString; }, "strip", z.ZodTypeAny, { class: string; fullName: string; }, { class: string; fullName: string; }>>; briefTitle: z.ZodOptional<z.ZodString>; officialTitle: z.ZodOptional<z.ZodString>; acronym: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { nctId: string; orgStudyIdInfo?: { id: string; } | undefined; organization?: { class: string; fullName: string; } | undefined; briefTitle?: string | undefined; officialTitle?: string | undefined; acronym?: string | undefined; }, { nctId: string; orgStudyIdInfo?: { id: string; } | undefined; organization?: { class: string; fullName: string; } | undefined; briefTitle?: string | undefined; officialTitle?: string | undefined; acronym?: string | undefined; }>>; statusModule: z.ZodOptional<z.ZodObject<{ overallStatus: z.ZodOptional<z.ZodString>; lastKnownStatus: z.ZodOptional<z.ZodString>; startDateStruct: z.ZodOptional<z.ZodObject<{ date: z.ZodString; type: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { date: string; type?: string | undefined; }, { date: string; type?: string | undefined; }>>; primaryCompletionDateStruct: z.ZodOptional<z.ZodObject<{ date: z.ZodString; type: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { date: string; type?: string | undefined; }, { date: string; type?: string | undefined; }>>; completionDateStruct: z.ZodOptional<z.ZodObject<{ date: z.ZodString; type: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { date: string; type?: string | undefined; }, { date: string; type?: string | undefined; }>>; }, "strip", z.ZodTypeAny, { overallStatus?: string | undefined; lastKnownStatus?: string | undefined; startDateStruct?: { date: string; type?: string | undefined; } | undefined; primaryCompletionDateStruct?: { date: string; type?: string | undefined; } | undefined; completionDateStruct?: { date: string; type?: string | undefined; } | undefined; }, { overallStatus?: string | undefined; lastKnownStatus?: string | undefined; startDateStruct?: { date: string; type?: string | undefined; } | undefined; primaryCompletionDateStruct?: { date: string; type?: string | undefined; } | undefined; completionDateStruct?: { date: string; type?: string | undefined; } | undefined; }>>; sponsorCollaboratorsModule: z.ZodOptional<z.ZodObject<{ responsibleParty: z.ZodOptional<z.ZodObject<{ type: z.ZodString; }, "strip", z.ZodTypeAny, { type: string; }, { type: string; }>>; leadSponsor: z.ZodOptional<z.ZodObject<{ name: z.ZodString; class: z.ZodString; }, "strip", z.ZodTypeAny, { name: string; class: string; }, { name: string; class: string; }>>; collaborators: z.ZodOptional<z.ZodArray<z.ZodObject<{ name: z.ZodString; class: z.ZodString; }, "strip", z.ZodTypeAny, { name: string; class: string; }, { name: string; class: string; }>, "many">>; }, "strip", z.ZodTypeAny, { responsibleParty?: { type: string; } | undefined; leadSponsor?: { name: string; class: string; } | undefined; collaborators?: { name: string; class: string; }[] | undefined; }, { responsibleParty?: { type: string; } | undefined; leadSponsor?: { name: string; class: string; } | undefined; collaborators?: { name: string; class: string; }[] | undefined; }>>; descriptionModule: z.ZodOptional<z.ZodObject<{ briefSummary: z.ZodOptional<z.ZodString>; detailedDescription: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { briefSummary?: string | undefined; detailedDescription?: string | undefined; }, { briefSummary?: string | undefined; detailedDescription?: string | undefined; }>>; conditionsModule: z.ZodOptional<z.ZodObject<{ conditions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; keywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strip", z.ZodTypeAny, { conditions?: string[] | undefined; keywords?: string[] | undefined; }, { conditions?: string[] | undefined; keywords?: string[] | undefined; }>>; armsInterventionsModule: z.ZodOptional<z.ZodObject<{ arms: z.ZodOptional<z.ZodArray<z.ZodObject<{ name: z.ZodString; type: z.ZodString; description: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { type: string; name: string; description?: string | undefined; }, { type: string; name: string; description?: string | undefined; }>, "many">>; interventions: z.ZodOptional<z.ZodArray<z.ZodObject<{ type: z.ZodString; name: z.ZodString; description: z.ZodOptional<z.ZodString>; armNames: z.ZodArray<z.ZodString, "many">; }, "strip", z.ZodTypeAny, { type: string; name: string; armNames: string[]; description?: string | undefined; }, { type: string; name: string; armNames: string[]; description?: string | undefined; }>, "many">>; }, "strip", z.ZodTypeAny, { arms?: { type: string; name: string; description?: string | undefined; }[] | undefined; interventions?: { type: string; name: string; armNames: string[]; description?: string | undefined; }[] | undefined; }, { arms?: { type: string; name: string; description?: string | undefined; }[] | undefined; interventions?: { type: string; name: string; armNames: string[]; description?: string | undefined; }[] | undefined; }>>; designModule: z.ZodOptional<z.ZodObject<{ studyType: z.ZodOptional<z.ZodString>; phases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; designInfo: z.ZodOptional<z.ZodObject<{ allocation: z.ZodOptional<z.ZodString>; interventionModel: z.ZodOptional<z.ZodString>; primaryPurpose: z.ZodOptional<z.ZodString>; maskingInfo: z.ZodOptional<z.ZodObject<{ masking: z.ZodString; }, "strip", z.ZodTypeAny, { masking: string; }, { masking: string; }>>; }, "strip", z.ZodTypeAny, { allocation?: string | undefined; interventionModel?: string | undefined; primaryPurpose?: string | undefined; maskingInfo?: { masking: string; } | undefined; }, { allocation?: string | undefined; interventionModel?: string | undefined; primaryPurpose?: string | undefined; maskingInfo?: { masking: string; } | undefined; }>>; }, "strip", z.ZodTypeAny, { studyType?: string | undefined; phases?: string[] | undefined; designInfo?: { allocation?: string | undefined; interventionModel?: string | undefined; primaryPurpose?: string | undefined; maskingInfo?: { masking: string; } | undefined; } | undefined; }, { studyType?: string | undefined; phases?: string[] | undefined; designInfo?: { allocation?: string | undefined; interventionModel?: string | undefined; primaryPurpose?: string | undefined; maskingInfo?: { masking: string; } | undefined; } | undefined; }>>; contactsLocationsModule: z.ZodOptional<z.ZodObject<{ locations: z.ZodOptional<z.ZodArray<z.ZodObject<{ city: z.ZodOptional<z.ZodString>; state: z.ZodOptional<z.ZodString>; country: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { city?: string | undefined; state?: string | undefined; country?: string | undefined; }, { city?: string | undefined; state?: string | undefined; country?: string | undefined; }>, "many">>; }, "strip", z.ZodTypeAny, { locations?: { city?: string | undefined; state?: string | undefined; country?: string | undefined; }[] | undefined; }, { locations?: { city?: string | undefined; state?: string | undefined; country?: string | undefined; }[] | undefined; }>>; }, "strip", z.ZodTypeAny, { identificationModule?: { nctId: string; orgStudyIdInfo?: { id: string; } | undefined; organization?: { class: string; fullName: string; } | undefined; briefTitle?: string | undefined; officialTitle?: string | undefined; acronym?: string | undefined; } | undefined; statusModule?: { overallStatus?: string | undefined; lastKnownStatus?: string | undefined; startDateStruct?: { date: string; type?: string | undefined; } | undefined; primaryCompletionDateStruct?: { date: string; type?: string | undefined; } | undefined; completionDateStruct?: { date: string; type?: string | undefined; } | undefined; } | undefined; sponsorCollaboratorsModule?: { responsibleParty?: { type: string; } | undefined; leadSponsor?: { name: string; class: string; } | undefined; collaborators?: { name: string; class: string; }[] | undefined; } | undefined; descriptionModule?: { briefSummary?: string | undefined; detailedDescription?: string | undefined; } | undefined; conditionsModule?: { conditions?: string[] | undefined; keywords?: string[] | undefined; } | undefined; armsInterventionsModule?: { arms?: { type: string; name: string; description?: string | undefined; }[] | undefined; interventions?: { type: string; name: string; armNames: string[]; description?: string | undefined; }[] | undefined; } | undefined; designModule?: { studyType?: string | undefined; phases?: string[] | undefined; designInfo?: { allocation?: string | undefined; interventionModel?: string | undefined; primaryPurpose?: string | undefined; maskingInfo?: { masking: string; } | undefined; } | undefined; } | undefined; contactsLocationsModule?: { locations?: { city?: string | undefined; state?: string | undefined; country?: string | undefined; }[] | undefined; } | undefined; }, { identificationModule?: { nctId: string; orgStudyIdInfo?: { id: string; } | undefined; organization?: { class: string; fullName: string; } | undefined; briefTitle?: string | undefined; officialTitle?: string | undefined; acronym?: string | undefined; } | undefined; statusModule?: { overallStatus?: string | undefined; lastKnownStatus?: string | undefined; startDateStruct?: { date: string; type?: string | undefined; } | undefined; primaryCompletionDateStruct?: { date: string; type?: string | undefined; } | undefined; completionDateStruct?: { date: string; type?: string | undefined; } | undefined; } | undefined; sponsorCollaboratorsModule?: { responsibleParty?: { type: string; } | undefined; leadSponsor?: { name: string; class: string; } | undefined; collaborators?: { name: string; class: string; }[] | undefined; } | undefined; descriptionModule?: { briefSummary?: string | undefined; detailedDescription?: string | undefined; } | undefined; conditionsModule?: { conditions?: string[] | undefined; keywords?: string[] | undefined; } | undefined; armsInterventionsModule?: { arms?: { type: string; name: string; description?: string | undefined; }[] | undefined; interventions?: { type: string; name: string; armNames: string[]; description?: string | undefined; }[] | undefined; } | undefined; designModule?: { studyType?: string | undefined; phases?: string[] | undefined; designInfo?: { allocation?: string | undefined; interventionModel?: string | undefined; primaryPurpose?: string | undefined; maskingInfo?: { masking: string; } | undefined; } | undefined; } | undefined; contactsLocationsModule?: { locations?: { city?: string | undefined; state?: string | undefined; country?: string | undefined; }[] | undefined; } | undefined; }>>; }, "strip", z.ZodTypeAny, { protocolSection?: { identificationModule?: { nctId: string; orgStudyIdInfo?: { id: string; } | undefined; organization?: { class: string; fullName: string; } | undefined; briefTitle?: string | undefined; officialTitle?: string | undefined; acronym?: string | undefined; } | undefined; statusModule?: { overallStatus?: string | undefined; lastKnownStatus?: string | undefined; startDateStruct?: { date: string; type?: string | undefined; } | undefined; primaryCompletionDateStruct?: { date: string; type?: string | undefined; } | undefined; completionDateStruct?: { date: string; type?: string | undefined; } | undefined; } | undefined; sponsorCollaboratorsModule?: { responsibleParty?: { type: string; } | undefined; leadSponsor?: { name: string; class: string; } | undefined; collaborators?: { name: string; class: string; }[] | undefined; } | undefined; descriptionModule?: { briefSummary?: string | undefined; detailedDescription?: string | undefined; } | undefined; conditionsModule?: { conditions?: string[] | undefined; keywords?: string[] | undefined; } | undefined; armsInterventionsModule?: { arms?: { type: string; name: string; description?: string | undefined; }[] | undefined; interventions?: { type: string; name: string; armNames: string[]; description?: string | undefined; }[] | undefined; } | undefined; designModule?: { studyType?: string | undefined; phases?: string[] | undefined; designInfo?: { allocation?: string | undefined; interventionModel?: string | undefined; primaryPurpose?: string | undefined; maskingInfo?: { masking: string; } | undefined; } | undefined; } | undefined; contactsLocationsModule?: { locations?: { city?: string | undefined; state?: string | undefined; country?: string | undefined; }[] | undefined; } | undefined; } | undefined; }, { protocolSection?: { identificationModule?: { nctId: string; orgStudyIdInfo?: { id: string; } | undefined; organization?: { class: string; fullName: string; } | undefined; briefTitle?: string | undefined; officialTitle?: string | undefined; acronym?: string | undefined; } | undefined; statusModule?: { overallStatus?: string | undefined; lastKnownStatus?: string | undefined; startDateStruct?: { date: string; type?: string | undefined; } | undefined; primaryCompletionDateStruct?: { date: string; type?: string | undefined; } | undefined; completionDateStruct?: { date: string; type?: string | undefined; } | undefined; } | undefined; sponsorCollaboratorsModule?: { responsibleParty?: { type: string; } | undefined; leadSponsor?: { name: string; class: string; } | undefined; collaborators?: { name: string; class: string; }[] | undefined; } | undefined; descriptionModule?: { briefSummary?: string | undefined; detailedDescription?: string | undefined; } | undefined; conditionsModule?: { conditions?: string[] | undefined; keywords?: string[] | undefined; } | undefined; armsInterventionsModule?: { arms?: { type: string; name: string; description?: string | undefined; }[] | undefined; interventions?: { type: string; name: string; armNames: string[]; description?: string | undefined; }[] | undefined; } | undefined; designModule?: { studyType?: string | undefined; phases?: string[] | undefined; designInfo?: { allocation?: string | undefined; interventionModel?: string | undefined; primaryPurpose?: string | undefined; maskingInfo?: { masking: string; } | undefined; } | undefined; } | undefined; contactsLocationsModule?: { locations?: { city?: string | undefined; state?: string | undefined; country?: string | undefined; }[] | undefined; } | undefined; } | undefined; }>, z.ZodObject<{ nctId: z.ZodOptional<z.ZodString>; title: z.ZodOptional<z.ZodString>; briefSummary: z.ZodOptional<z.ZodString>; overallStatus: z.ZodOptional<z.ZodString>; conditions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; interventions: z.ZodOptional<z.ZodArray<z.ZodObject<{ name: z.ZodOptional<z.ZodString>; type: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { type?: string | undefined; name?: string | undefined; }, { type?: string | undefined; name?: string | undefined; }>, "many">>; leadSponsor: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { title?: string | undefined; nctId?: string | undefined; overallStatus?: string | undefined; leadSponsor?: string | undefined; briefSummary?: string | undefined; conditions?: string[] | undefined; interventions?: { type?: string | undefined; name?: string | undefined; }[] | undefined; }, { title?: string | undefined; nctId?: string | undefined; overallStatus?: string | undefined; leadSponsor?: string | undefined; briefSummary?: string | undefined; conditions?: string[] | undefined; interventions?: { type?: string | undefined; name?: string | undefined; }[] | undefined; }>]>, "many">; errors: z.ZodOptional<z.ZodArray<z.ZodObject<{ nctId: z.ZodString; error: z.ZodString; }, "strip", z.ZodTypeAny, { error: string; nctId: string; }, { error: string; nctId: string; }>, "many">>; }, "strip", z.ZodTypeAny, { studies: ({ protocolSection?: { identificationModule?: { nctId: string; orgStudyIdInfo?: { id: string; } | undefined; organization?: { class: string; fullName: string; } | undefined; briefTitle?: string | undefined; officialTitle?: string | undefined; acronym?: string | undefined; } | undefined; statusModule?: { overallStatus?: string | undefined; lastKnownStatus?: string | undefined; startDateStruct?: { date: string; type?: string | undefined; } | undefined; primaryCompletionDateStruct?: { date: string; type?: string | undefined; } | undefined; completionDateStruct?: { date: string; type?: string | undefined; } | undefined; } | undefined; sponsorCollaboratorsModule?: { responsibleParty?: { type: string; } | undefined; leadSponsor?: { name: string; class: string; } | undefined; collaborators?: { name: string; class: string; }[] | undefined; } | undefined; descriptionModule?: { briefSummary?: string | undefined; detailedDescription?: string | undefined; } | undefined; conditionsModule?: { conditions?: string[] | undefined; keywords?: string[] | undefined; } | undefined; armsInterventionsModule?: { arms?: { type: string; name: string; description?: string | undefined; }[] | undefined; interventions?: { type: string; name: string; armNames: string[]; description?: string | undefined; }[] | undefined; } | undefined; designModule?: { studyType?: string | undefined; phases?: string[] | undefined; designInfo?: { allocation?: string | undefined; interventionModel?: string | undefined; primaryPurpose?: string | undefined; maskingInfo?: { masking: string; } | undefined; } | undefined; } | undefined; contactsLocationsModule?: { locations?: { city?: string | undefined; state?: string | undefined; country?: string | undefined; }[] | undefined; } | undefined; } | undefined; } | { title?: string | undefined; nctId?: string | undefined; overallStatus?: string | undefined; leadSponsor?: string | undefined; briefSummary?: string | undefined; conditions?: string[] | undefined; interventions?: { type?: string | undefined; name?: string | undefined; }[] | undefined; })[]; errors?: { error: string; nctId: string; }[] | undefined; }, { studies: ({ protocolSection?: { identificationModule?: { nctId: string; orgStudyIdInfo?: { id: string; } | undefined; organization?: { class: string; fullName: string; } | undefined; briefTitle?: string | undefined; officialTitle?: string | undefined; acronym?: string | undefined; } | undefined; statusModule?: { overallStatus?: string | undefined; lastKnownStatus?: string | undefined; startDateStruct?: { date: string; type?: string | undefined; } | undefined; primaryCompletionDateStruct?: { date: string; type?: string | undefined; } | undefined; completionDateStruct?: { date: string; type?: string | undefined; } | undefined; } | undefined; sponsorCollaboratorsModule?: { responsibleParty?: { type: string; } | undefined; leadSponsor?: { name: string; class: string; } | undefined; collaborators?: { name: string; class: string; }[] | undefined; } | undefined; descriptionModule?: { briefSummary?: string | undefined; detailedDescription?: string | undefined; } | undefined; conditionsModule?: { conditions?: string[] | undefined; keywords?: string[] | undefined; } | undefined; armsInterventionsModule?: { arms?: { type: string; name: string; description?: string | undefined; }[] | undefined; interventions?: { type: string; name: string; armNames: string[]; description?: string | undefined; }[] | undefined; } | undefined; designModule?: { studyType?: string | undefined; phases?: string[] | undefined; designInfo?: { allocation?: string | undefined; interventionModel?: string | undefined; primaryPurpose?: string | undefined; maskingInfo?: { masking: string; } | undefined; } | undefined; } | undefined; contactsLocationsModule?: { locations?: { city?: string | undefined; state?: string | undefined; country?: string | undefined; }[] | undefined; } | undefined; } | undefined; } | { title?: string | undefined; nctId?: string | undefined; overallStatus?: string | undefined; leadSponsor?: string | undefined; briefSummary?: string | undefined; conditions?: string[] | undefined; interventions?: { type?: string | undefined; name?: string | undefined; }[] | undefined; })[]; errors?: { error: string; nctId: string; }[] | undefined; }>; /** * TypeScript type inferred from the output schema. */ export type GetStudyOutput = z.infer<typeof GetStudyOutputSchema>; /** * Fetches one or more clinical studies from ClinicalTrials.gov by their NCT IDs. * Returns either complete study data or concise summaries for each. * * @param params - The validated input parameters, defining which studies to fetch and in what format. * @param context - The request context for logging and tracing. * @returns A promise resolving to an object containing an array of studies or summaries. * @throws {McpError} Throws if a study is not found or if the API request fails. */ export declare function getStudyLogic(params: GetStudyInput, context: RequestContext): Promise<GetStudyOutput>;