cid10_search

Instructions

Implementation Reference

• src/tools/cid10.ts:122-164 (handler)

  The main handler function for cid10_search. It parses the input params using CID10SearchParamsSchema, calls client.search() with the query, level, and max_results, formats results using formatHit(), and returns both text and structured content. On error, delegates to handleToolError().

  async function handleCID10Search(args: Record<string, unknown>): Promise<CallToolResult> {
    try {
      const params = CID10SearchParamsSchema.parse(args);
      const client = getCID10Client();
      const { totalCount, hits } = client.search(
        params.query,
        params.level,
        params.max_results,
      );
  
      const structured: CID10SearchOutput = {
        query: params.query,
        level: params.level,
        total_count: totalCount,
        shown_count: hits.length,
        hits,
      };
  
      if (hits.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: `Nenhum código CID-10 encontrado para "${params.query}".`,
            },
          ],
          structuredContent: structured,
        };
      }
  
      const header =
        `## Resultados CID-10 para "${params.query}"\n\n` +
        `Total: ${totalCount} (mostrando ${hits.length}, escopo: ${params.level}).\n\n`;
      const body = hits.map((h, i) => `${i + 1}. ${formatHit(h)}`).join('\n\n');
  
      return {
        content: [{ type: 'text', text: header + body }],
        structuredContent: structured,
      };
    } catch (error) {
      return handleToolError(error);
    }
  }

• src/types/index.ts:724-737 (schema)

  Input validation schema (CID10SearchParamsSchema) for cid10_search. Defines: query (string, min 2 chars), level (enum: categories/subcategories/all, default: all), and max_results (1-100, default: 25).

  export const CID10SearchParamsSchema = z.object({
    query: z
      .string()
      .min(2)
      .describe('Search term in Portuguese (e.g., "diabetes", "infarto", "tuberculose")'),
    level: z
      .enum(['categories', 'subcategories', 'all'])
      .optional()
      .default('all')
      .describe(
        'Restrict search to 3-char categories, 4-char subcategories, or both. Default: all',
      ),
    max_results: maxResults(25),
  });

• src/tools/cid10.ts:299-299 (registration)

  Registration of the cid10_search tool via toolRegistry.register(cid10SearchTool, handleCID10Search) at the bottom of src/tools/cid10.ts.

  toolRegistry.register(cid10SearchTool, handleCID10Search);

• src/clients/cid10-client.ts:73-87 (helper)

  The CID10SearchHit interface — the return type for search results, containing level, code, display, title, chapter_num, group_range, and other metadata fields.

  export interface CID10SearchHit {
    level: 'category' | 'subcategory';
    code: string;
    display: string;
    classif: string;
    title: string;
    title_short: string;
    refer: string;
    excluidos: string;
    restr_sexo: string;
    causa_obito: string;
    chapter_num: number | null;
    group_range: string | null;
  }

• src/clients/cid10-client.ts:229-264 (helper)

  The client.search() method on CID10Client. Performs diacritic-insensitive substring matching across categories and/or subcategories by title and title_short. Returns totalCount and hits (sliced to maxResults).

  search(
    query: string,
    level: 'categories' | 'subcategories' | 'all',
    maxResults: number,
  ): { totalCount: number; hits: CID10SearchHit[] } {
    const needle = deburr(query);
    if (needle.length === 0) {
      return { totalCount: 0, hits: [] };
    }
  
    const all: CID10SearchHit[] = [];
  
    if (level === 'categories' || level === 'all') {
      for (const c of categories()) {
        if (
          deburr(c.title).includes(needle) ||
          deburr(c.title_short).includes(needle)
        ) {
          all.push(categoryToHit(c));
        }
      }
    }
  
    if (level === 'subcategories' || level === 'all') {
      for (const s of subcategories()) {
        if (
          deburr(s.title).includes(needle) ||
          deburr(s.title_short).includes(needle)
        ) {
          all.push(subcategoryToHit(s));
        }
      }
    }
  
    return { totalCount: all.length, hits: all.slice(0, maxResults) };
  }