get_fornecedor_contratos
Retrieve public contracts from the last year where a supplier CNPJ is listed. Analyze competitors or potential partners by viewing their contract history.
Instructions
List public contracts where a given CNPJ appears as the supplier (fornecedor). Useful for analyzing a competitor or a potential partner. Defaults to the last 365 days.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cnpj | Yes | Supplier CNPJ (14 digits) | |
| diasAtras | No | How many days back to search. | |
| pagina | No | ||
| tamanhoPagina | No |
Implementation Reference
- The main tool definition and handler. Exposes getFornecedorContratos with a 'handler' that validates arguments via Zod schema, normalizes the CNPJ, computes date range, calls listContratos adapter, and returns a JSON result with contract metadata.
export const getFornecedorContratos: ToolDef = { definition: { name: 'get_fornecedor_contratos', description: 'List public contracts where a given CNPJ appears as the supplier (fornecedor). Useful for analyzing a competitor or a potential partner. Defaults to the last 365 days.', inputSchema: { type: 'object', properties: { cnpj: { type: 'string', description: 'Supplier CNPJ (14 digits)' }, diasAtras: { type: 'integer', minimum: 1, maximum: 3650, default: 365, description: 'How many days back to search.', }, pagina: { type: 'integer', minimum: 1, default: 1 }, tamanhoPagina: { type: 'integer', minimum: 10, maximum: 50, default: 50 }, }, required: ['cnpj'], }, }, async handler(rawArgs) { const parse = ArgsSchema.safeParse(rawArgs ?? {}); if (!parse.success) return errorResult(`Invalid arguments: ${parse.error.message}`); const args = parse.data; try { const cnpj = normalizeCnpj(args.cnpj); const { dataInicial, dataFinal } = defaultDateRange(args.diasAtras); const page = await listContratos({ dataInicial, dataFinal, cnpjFornecedor: cnpj, pagina: args.pagina, tamanhoPagina: args.tamanhoPagina, }); return jsonResult({ meta: { cnpjFornecedor: cnpj, dataInicial, dataFinal, totalRetornados: page.data.length, totalPncp: page.totalRegistros, }, contratos: page.data.map((c) => ({ numeroControlePNCP: c.numeroControlePNCP, objeto: c.objetoContrato, valorInicial: c.valorInicial, valorGlobal: c.valorGlobal, orgao: c.orgaoEntidade?.razaoSocial, cnpjOrgao: c.orgaoEntidade?.cnpj, uf: c.unidadeOrgao?.ufSigla, dataAssinatura: c.dataAssinatura, vigenciaInicio: c.dataVigenciaInicio, vigenciaFim: c.dataVigenciaFim, })), }); } catch (err) { const msg = err instanceof PncpError ? err.message : String(err); return errorResult(`Failed to get fornecedor contratos: ${msg}`); } }, }; - Zod schema (ArgsSchema) defining input validation for cnpj (string), diasAtras (1-3650, default 365), pagina (min 1, default 1), and tamanhoPagina (10-50, default 50).
const ArgsSchema = z.object({ cnpj: z.string(), diasAtras: z.number().int().min(1).max(3650).default(365), pagina: z.number().int().min(1).default(1), tamanhoPagina: z.number().int().min(10).max(50).default(50), }); - src/tools/index.ts:14-39 (registration)Import of getFornecedorContratos from './get_fornecedor_contratos.js' on line 14 and inclusion in the allTools array on line 38, which is used to build the toolMap for registration with MCP.
import { getFornecedorContratos } from './get_fornecedor_contratos.js'; import { searchPca } from './search_pca.js'; import { listPcaItensTool } from './list_pca_itens.js'; import { getCnpjDataTool } from './get_cnpj_data.js'; import { aggregateLicitacoes } from './aggregate_licitacoes.js'; import { comparePeriodos } from './compare_periodos.js'; export const allTools: ToolDef[] = [ // Compras / Licitações searchLicitacoes, getLicitacao, listLicitacaoItens, listLicitacaoResultados, listLicitacaoArquivos, // Contratos searchContratos, getContratoTool, listContratoTermosTool, listContratoInstrumentosTool, // Atas RP searchAtasRp, getAtaRp, // Órgãos / Fornecedores getOrgaoTool, getFornecedorContratos, // PCA - src/adapters/pncp.ts:282-310 (helper)listContratos adapter function: builds query params (including cnpjFornecedor), checks cache, calls PNCP API /contratos endpoint, parses response with ContratosPageSchema, and caches for 5 min.
export interface ListContratosParams { dataInicial?: string; dataFinal?: string; cnpjOrgao?: string; cnpjFornecedor?: string; pagina?: number; tamanhoPagina?: number; } export async function listContratos(params: ListContratosParams): Promise<ContratosPage> { const tamanhoPagina = clampPageSize(params.tamanhoPagina); const pagina = Math.max(params.pagina ?? 1, 1); const query: Record<string, unknown> = { pagina, tamanhoPagina }; if (params.dataInicial) query.dataInicial = params.dataInicial; if (params.dataFinal) query.dataFinal = params.dataFinal; if (params.cnpjOrgao) query.cnpjOrgao = params.cnpjOrgao; if (params.cnpjFornecedor) query.cnpjFornecedor = params.cnpjFornecedor; const cacheKey = `list:contratos:${JSON.stringify(query)}`; const cached = cache.get<ContratosPage>(cacheKey); if (cached) return cached; try { const { data } = await withRetry(() => consultaClient.get('/contratos', { params: query })); const parsed = ContratosPageSchema.parse(data); cache.set(cacheKey, parsed, TTL_5_MIN); return parsed; } catch (err) { if (err instanceof AxiosError) { - Imports used by the tool: listContratos from pncp adapter, defaultDateRange from utils/dates, normalizeCnpj from utils/pncp_id, and ToolDef/result helpers from ./types.
import { z } from 'zod'; import { listContratos, PncpError } from '../adapters/pncp.js'; import { defaultDateRange } from '../utils/dates.js'; import { normalizeCnpj } from '../utils/pncp_id.js'; import type { ToolDef } from './types.js'; import { errorResult, jsonResult } from './types.js';