mesh_search

Instructions

Implementation Reference

• src/tools/mesh.ts:270-294 (handler)

  The main handler function for the mesh_search tool. Parses input params via MeSHSearchParamsSchema, calls the MeSH client to search descriptors, builds structured output (query, match, total_count, descriptors), formats results as text, and returns a CallToolResult with both text and structured content.

  async function handleMeSHSearch(args: Record<string, unknown>): Promise<CallToolResult> {
    try {
      const params = MeSHSearchParamsSchema.parse(args);
      const client = getMeSHClient();
      const results = await client.searchDescriptors(params.query, params.match, params.max_results);
  
      const structured: MeSHSearchOutput = {
        query: params.query,
        match: params.match,
        total_count: results.length,
        descriptors: results.map((r) => ({
          id: r.id,
          uri: r.uri,
          label: r.label,
        })),
      };
  
      return {
        content: [{ type: 'text', text: formatSearchResults(params.query, results) }],
        structuredContent: structured,
      };
    } catch (error) {
      return handleToolError(error);
    }
  }

• src/types/index.ts:363-371 (schema)

  Input schema (MeSHSearchParamsSchema) for the mesh_search tool: defines 'query' (string, required), 'match' (enum: exact/contains/startswith, optional, default 'contains'), and 'max_results' (capped at 25).

  export const MeSHSearchParamsSchema = z.object({
    query: z.string().min(1).describe('Search term (e.g., "diabetes", "heart failure")'),
    match: z
      .enum(['exact', 'contains', 'startswith'])
      .optional()
      .default('contains')
      .describe('Match type: exact, contains, or startswith. Default: contains'),
    max_results: maxResults(25),
  });

• src/types/index.ts:393-404 (schema)

  Output schema (MeSHSearchOutputSchema) for the mesh_search tool: defines 'query', 'match', 'total_count', and array of 'descriptors' with id/uri/label.

  export const MeSHSearchOutputSchema = z.object({
    query: z.string(),
    match: z.enum(['exact', 'contains', 'startswith']),
    total_count: z.number().int(),
    descriptors: z.array(
      z.object({
        id: z.string(),
        uri: z.string(),
        label: z.string(),
      }),
    ),
  });

• src/tools/mesh.ts:45-58 (registration)

  Tool definition/registration object for 'mesh_search' with name, description, inputSchema, outputSchema, and annotations.

  const meshSearchTool: Tool = {
    name: 'mesh_search',
    description: `Search for MeSH (Medical Subject Headings) descriptors.
  
  Use this tool to:
  - Find MeSH terms for indexing medical literature
  - Look up subject headings for PubMed searches
  - Find controlled vocabulary terms
  
  Returns matching descriptors with MeSH IDs and labels.`,
    inputSchema: buildInputSchema(MeSHSearchParamsSchema),
    outputSchema: buildOutputSchema(MeSHSearchOutputSchema),
    annotations: READ_ONLY_TOOL_ANNOTATIONS,
  };

• src/tools/mesh.ts:109-130 (helper)

  Helper function that formats search results into a markdown table (MeSH ID | Label) for display.

  function formatSearchResults(query: string, results: MeSHSearchResult[]): string {
    const lines: string[] = [];
  
    lines.push(`## MeSH Search Results for "${query}"`);
    lines.push('');
  
    if (results.length === 0) {
      lines.push('No descriptors found.');
      return lines.join('\n');
    }
  
    lines.push(`Found ${results.length} descriptor(s):`);
    lines.push('');
    lines.push('| MeSH ID | Label |');
    lines.push('|---------|-------|');
  
    for (const result of results) {
      lines.push(`| ${result.id} | ${result.label} |`);
    }
  
    return lines.join('\n');
  }