search_pca

Instructions

Implementation Reference

• src/tools/search_pca.ts:20-88 (handler)

  The ToolDef definition for 'search_pca'. Contains both the input schema (dataInicio, dataFim, classificacao, pagina, tamanhoPagina) and the async handler function that parses arguments, validates dates, calls listPcaAtualizacao, and returns results with meta information.

  export const searchPca: ToolDef = {
    definition: {
      name: 'search_pca',
      description:
        `Search recently published/updated Plano de Contratação Anual (PCA) entries — what public agencies INTEND to buy. Returns PCA entries (one per agency unit) with their items embedded. Filter by classification: 'material' or 'servico'. Defaults: last 30 days, classification 'material'. Per Lei 14.133. Maximum date range per query: ${PNCP_MAX_DATE_RANGE_DAYS} days (PNCP limit).`,
      inputSchema: {
        type: 'object',
        properties: {
          dataInicio: {
            type: 'string',
            description: 'Start date YYYYMMDD. Default: 30 days ago.',
          },
          dataFim: { type: 'string', description: 'End date YYYYMMDD. Default: today.' },
          classificacao: {
            type: 'string',
            enum: ['material', 'servico'],
            default: 'material',
            description:
              'Top-level classification: material (codigoClassificacaoSuperior=01) or servico (=02).',
          },
          pagina: { type: 'integer', minimum: 1, default: 1 },
          tamanhoPagina: { type: 'integer', minimum: 10, maximum: 50, default: 20 },
        },
      },
    },
  
    async handler(rawArgs) {
      const parse = ArgsSchema.safeParse(rawArgs ?? {});
      if (!parse.success) return errorResult(`Invalid arguments: ${parse.error.message}`);
      const args = parse.data;
      const range =
        !args.dataInicio || !args.dataFim
          ? (() => {
              const r = defaultDateRange(30);
              return { dataInicio: r.dataInicial, dataFim: r.dataFinal };
            })()
          : { dataInicio: args.dataInicio, dataFim: args.dataFim };
  
      const validation = validatePncpDateRange(range.dataInicio, range.dataFim);
      if (!validation.ok) {
        return errorResult(validation.reason);
      }
  
      try {
        const page = await listPcaAtualizacao({
          dataInicio: range.dataInicio,
          dataFim: range.dataFim,
          codigoClassificacaoSuperior: args.classificacao === 'servico' ? '02' : '01',
          pagina: args.pagina,
          tamanhoPagina: args.tamanhoPagina,
        });
        return jsonResult({
          meta: {
            dataInicio: range.dataInicio,
            dataFim: range.dataFim,
            classificacao: args.classificacao,
            pagina: args.pagina,
            totalRetornados: page.data.length,
            totalPncp: page.totalRegistros,
            totalPaginas: page.totalPaginas,
          },
          results: page.data,
        });
      } catch (err) {
        const msg = err instanceof PncpError ? err.message : String(err);
        return errorResult(`Failed to search PCA: ${msg}`);
      }
    },
  };

• src/tools/search_pca.ts:12-18 (schema)

  Zod schema (ArgsSchema) for validating tool input parameters: dataInicio, dataFim (optional YYYYMMDD strings), classificacao (enum material/servico), pagina, tamanhoPagina.

  const ArgsSchema = z.object({
    dataInicio: z.string().refine(isValidPncpDate, 'Format must be YYYYMMDD').optional(),
    dataFim: z.string().refine(isValidPncpDate, 'Format must be YYYYMMDD').optional(),
    classificacao: z.enum(['material', 'servico']).default('material'),
    pagina: z.number().int().min(1).default(1),
    tamanhoPagina: z.number().int().min(10).max(50).default(20),
  });

• src/tools/search_pca.ts:21-44 (schema)

  MCP Tool inputSchema definition (JSON Schema) for 'search_pca' tool, describing the same parameters for MCP protocol compatibility.

  definition: {
    name: 'search_pca',
    description:
      `Search recently published/updated Plano de Contratação Anual (PCA) entries — what public agencies INTEND to buy. Returns PCA entries (one per agency unit) with their items embedded. Filter by classification: 'material' or 'servico'. Defaults: last 30 days, classification 'material'. Per Lei 14.133. Maximum date range per query: ${PNCP_MAX_DATE_RANGE_DAYS} days (PNCP limit).`,
    inputSchema: {
      type: 'object',
      properties: {
        dataInicio: {
          type: 'string',
          description: 'Start date YYYYMMDD. Default: 30 days ago.',
        },
        dataFim: { type: 'string', description: 'End date YYYYMMDD. Default: today.' },
        classificacao: {
          type: 'string',
          enum: ['material', 'servico'],
          default: 'material',
          description:
            'Top-level classification: material (codigoClassificacaoSuperior=01) or servico (=02).',
        },
        pagina: { type: 'integer', minimum: 1, default: 1 },
        tamanhoPagina: { type: 'integer', minimum: 10, maximum: 50, default: 20 },
      },
    },
  },

• src/tools/index.ts:15-15 (registration)

  Import of searchPca from search_pca.ts.

  import { searchPca } from './search_pca.js';

• src/tools/index.ts:39-40 (registration)

  Registration of searchPca in the allTools array, which is later exported as toolMap for MCP tool discovery.

  // PCA
  searchPca,