Clinical Trials MCP Server

Instructions

Implementation Reference

• src/index.js:185-207 (handler)

  MCP tool handler for 'search_by_location': extracts latitude, longitude, radius and other params, validates required fields, calls ClinicalTrialsClient.searchByLocation, and returns JSON stringified results.

  case 'search_by_location': {
    const { latitude, longitude, radius = 50, ...otherParams } = args;
    
    if (latitude === undefined || longitude === undefined) {
      throw new Error('经纬度是必需的');
    }
    
    const results = await clinicalTrialsClient.searchByLocation(
      latitude,
      longitude,
      radius,
      otherParams
    );
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(results, null, 2),
        },
      ],
    };
  }

• src/index.js:99-140 (schema)

  Input schema for the 'search_by_location' tool defining parameters like latitude, longitude (required), radius, condition, keywords, status, months, pageSize with descriptions and defaults.

  inputSchema: {
    type: 'object',
    properties: {
      latitude: {
        type: 'number',
        description: '纬度',
      },
      longitude: {
        type: 'number',
        description: '经度',
      },
      radius: {
        type: 'number',
        description: '搜索半径（英里），默认50英里',
        default: 50,
      },
      condition: {
        type: 'string',
        description: '疾病或状况（可选）',
      },
      keywords: {
        type: 'string',
        description: '关键词（可选）',
      },
      status: {
        type: 'string',
        description: '招募状态，默认RECRUITING',
        default: 'RECRUITING',
      },
      months: {
        type: 'number',
        description: '时间范围（月），默认3个月',
        default: 3,
      },
      pageSize: {
        type: 'number',
        description: '每页返回的结果数量，默认30',
        default: 30,
      },
    },
    required: ['latitude', 'longitude'],
  },

• src/index.js:96-141 (registration)

  Registration of the 'search_by_location' tool in the ListTools response, including name, description, and full input schema.

  {
    name: 'search_by_location',
    description: '根据地理坐标搜索附近的临床试验。默认查询招募中且3个月内更新的30个最相关结果。',
    inputSchema: {
      type: 'object',
      properties: {
        latitude: {
          type: 'number',
          description: '纬度',
        },
        longitude: {
          type: 'number',
          description: '经度',
        },
        radius: {
          type: 'number',
          description: '搜索半径（英里），默认50英里',
          default: 50,
        },
        condition: {
          type: 'string',
          description: '疾病或状况（可选）',
        },
        keywords: {
          type: 'string',
          description: '关键词（可选）',
        },
        status: {
          type: 'string',
          description: '招募状态，默认RECRUITING',
          default: 'RECRUITING',
        },
        months: {
          type: 'number',
          description: '时间范围（月），默认3个月',
          default: 3,
        },
        pageSize: {
          type: 'number',
          description: '每页返回的结果数量，默认30',
          default: 30,
        },
      },
      required: ['latitude', 'longitude'],
    },
  },

• src/clinical-trials-client.js:152-229 (helper)

  Core helper function implementing the search logic: constructs advanced filter query using geolocation DISTANCE operator, adds condition/keywords/status/date filters, fetches from ClinicalTrials.gov API v2 /studies endpoint, formats results.

  async searchByLocation(latitude, longitude, radius, otherParams = {}) {
    const queryParams = new URLSearchParams();
  
    // 使用 AREA 和 DISTANCE 操作符进行地理位置查询
    const geoQuery = `AREA[LocationGeoPoint]DISTANCE[${latitude},${longitude},${radius}mi]`;
    queryParams.append('filter.advanced', geoQuery);
  
    // 疾病/状况
    if (otherParams.condition) {
      queryParams.append('query.cond', otherParams.condition);
    }
  
    // 关键词
    if (otherParams.keywords) {
      queryParams.append('query.term', otherParams.keywords);
    }
  
    // 默认只查招募中的
    const status = otherParams.status || 'RECRUITING';
    queryParams.append('filter.overallStatus', status);
  
    // 时间过滤：默认3个月内
    const months = otherParams.months || 3;
    const endDate = new Date();
    const startDate = new Date();
    startDate.setMonth(startDate.getMonth() - months);
    
    const startDateStr = this.formatDate(startDate);
    const endDateStr = this.formatDate(endDate);
    
    const dateQuery = `AREA[LastUpdatePostDate]RANGE[${startDateStr},${endDateStr}]`;
    const existing = queryParams.get('filter.advanced');
    queryParams.set('filter.advanced', `${existing} AND ${dateQuery}`);
  
    // 分页：默认30个结果
    const pageSize = otherParams.pageSize || 30;
    queryParams.append('pageSize', pageSize.toString());
  
    if (otherParams.pageToken) {
      queryParams.append('pageToken', otherParams.pageToken);
    }
  
    // 指定返回字段
    queryParams.append('fields', [
      'NCTId',
      'BriefTitle',
      'OfficialTitle',
      'OverallStatus',
      'Condition',
      'InterventionName',
      'Phase',
      'StudyType',
      'LocationFacility',
      'LocationCity',
      'LocationState',
      'LocationCountry',
      'LocationStatus',
      'LocationGeoPoint',
      'ContactName',
      'ContactPhone',
      'ContactEmail',
      'BriefSummary',
    ].join(','));
  
    // 排序
    queryParams.append('sort', 'LastUpdatePostDate:desc');
    queryParams.append('countTotal', 'true');
  
    try {
      const response = await this.axios.get('/studies', {
        params: queryParams,
      });
  
      return this.formatSearchResults(response.data);
    } catch (error) {
      throw this.handleError(error);
    }
  }