search_by_location

Find nearby clinical trials by geographic coordinates to identify recruiting studies within a specified radius, with optional filters for conditions and keywords.

Instructions

根据地理坐标搜索附近的临床试验。默认查询招募中且3个月内更新的30个最相关结果。

Input Schema

TableJSON Schema

Name	Required	Description	Default
`latitude`	Yes	纬度
`longitude`	Yes	经度
`radius`	No	搜索半径（英里），默认50英里
`condition`	No	疾病或状况（可选）
`keywords`	No	关键词（可选）
`status`	No	招募状态，默认RECRUITING	RECRUITING
`months`	No	时间范围（月），默认3个月
`pageSize`	No	每页返回的结果数量，默认30

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);
  }
}

Clinical Trials MCP Server