list_licitacao_arquivos

Instructions

Implementation Reference

• src/tools/list_licitacao_arquivos.ts:22-39 (handler)

  The handler function that executes the tool logic. It parses arguments using PncpIdInputSchema, resolves the PNCP ID, calls listContratacaoArquivos adapter function, and returns the list of files.

    async handler(rawArgs) {
      const parse = PncpIdInputSchema.safeParse(rawArgs ?? {});
      if (!parse.success) {
        return errorResult(`Invalid arguments: ${parse.error.message}`);
      }
      try {
        const { orgaoCnpj, ano, sequencial } = resolvePncpId(parse.data);
        const files = await listContratacaoArquivos(orgaoCnpj, ano, sequencial);
        return jsonResult({
          meta: { orgaoCnpj, ano, sequencial, total: files.length },
          arquivos: files,
        });
      } catch (err) {
        const msg = err instanceof PncpError ? err.message : String(err);
        return errorResult(`Failed to list arquivos: ${msg}`);
      }
    },
  };

• src/tools/list_licitacao_arquivos.ts:11-19 (schema)

  Input schema for the tool, accepting numeroControlePNCP or orgaoCnpj/ano/sequencial fields.

  inputSchema: {
    type: 'object',
    properties: {
      numeroControlePNCP: { type: 'string' },
      orgaoCnpj: { type: 'string' },
      ano: { type: 'integer' },
      sequencial: { type: 'integer' },
    },
  },

• src/schemas/pncp.ts:129-143 (schema)

  ArquivoSchema: Zod schema defining the shape of each file/attachment returned by the API.

  export const ArquivoSchema = z
    .object({
      sequencialDocumento: z.number(),
      titulo: z.string().nullable().optional(),
      tipoDocumentoNome: z.string().nullable().optional(),
      url: z.string().nullable().optional(),
      uri: z.string().nullable().optional(),
      dataPublicacaoPncp: z.string().nullable().optional(),
      cnpj: z.string().nullable().optional(),
      anoCompra: z.number().nullable().optional(),
      sequencialCompra: z.number().nullable().optional(),
    })
    .passthrough();
  
  export type Arquivo = z.infer<typeof ArquivoSchema>;

• src/adapters/pncp.ts:254-278 (helper)

  listContratacaoArquivos adapter function that calls the PNCP API endpoint /orgaos/{cnpj}/compras/{ano}/{sequencial}/arquivos and returns parsed Arquivo objects.

  export async function listContratacaoArquivos(
    orgaoCnpj: string,
    ano: number,
    sequencial: number,
  ): Promise<Arquivo[]> {
    const cacheKey = `list:arquivos:${orgaoCnpj}:${ano}:${sequencial}`;
    const cached = cache.get<Arquivo[]>(cacheKey);
    if (cached) return cached;
  
    try {
      const { data } = await withRetry(() =>
        pncpClient.get(`/orgaos/${orgaoCnpj}/compras/${ano}/${sequencial}/arquivos`),
      );
      const arr = asArray(data);
      const parsed = ArquivoSchema.array().parse(arr);
      cache.set(cacheKey, parsed, TTL_30_MIN);
      return parsed;
    } catch (err) {
      if (err instanceof AxiosError) {
        if (err.response?.status === 404) return [];
        throw new PncpError(describeAxiosError(err), err);
      }
      throw err;
    }
  }

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

  Registration of listLicitacaoArquivos in the allTools array and dynamically in toolMap.

    listLicitacaoArquivos,
    // Contratos
    searchContratos,
    getContratoTool,
    listContratoTermosTool,
    listContratoInstrumentosTool,
    // Atas RP
    searchAtasRp,
    getAtaRp,
    // Órgãos / Fornecedores
    getOrgaoTool,
    getFornecedorContratos,
    // PCA
    searchPca,
    listPcaItensTool,
    // CNPJ enrichment
    getCnpjDataTool,
    // Análise agregada (v0.2.0)
    aggregateLicitacoes,
    comparePeriodos,
  ];
  
  export const toolMap = new Map<string, ToolDef>(allTools.map((t) => [t.definition.name, t]));