SidneyBissoli/bcb-br-mcp

Ищет серии BCB по ключевому слову (или коду) в ДВА слоя: сначала локальный курируемый каталог из 135 серий, сверенных с первоисточником, и в нём fonteNome показывает, взято ли имя с портала BCB или унаследовано; затем индекс Portal de Dados Abertos do BCB, где тысячи серий идентифицируются по коду. Игнорирует диакритические знаки и регистр ('inflacao' находит 'Inflação'); несколько терминов комбинируются через И ('ipca servicos'). Когда использовать: чтобы узнать код серии, прежде чем запрашивать значения. Когда НЕ использовать: чтобы просматривать всё по категориям, используйте bcb_series_populares; для значений используйте bcb_serie_valores. Возвращает: termo, totalEncontradas, series (каждый элемент содержит codigo, nome, origem - 'curado' или 'indice' - и, в индексе, dataset со страницей портала), catalogo (origem, obtidoEm, seriesIndexadas, cobertura) и, когда применимо, observacao, avisos, mensagem и sugestao. Покрытие: индекс - это НЕ весь SGS, поэтому отсутствие результата здесь не доказывает, что серии не существует. Поле catalogo.cobertura явно указывает на это в каждом ответе. Сетевое поведение: индекс отдаётся из кэша со сроком действия 24 часа и обновляется при первом поиске после его истечения (один запрос к порталу, ~1 с); остальные поиски не обращаются к сети. Если портал недоступен, поиск деградирует до курируемого каталога (или последнего полученного индекса) и сигнализирует об этом в avisos, при этом дата получения всегда видна.

Запрашивает курс PTAX для валюты по отношению к реалу на конкретный день или в интервале дат. По умолчанию: доллар США (USD). Возвращает покупку, продажу, дату/время и тип бюллетеня; для недолларовых валют также возвращает паритет по отношению к USD с указанием источника. Когда использовать: для официального курса закрытия за один день или ряда за короткий период. Когда НЕ использовать: для длинного исторического ряда доллара как временного ряда SGS используйте bcb_serie_valores (коды: 1 = свободная продажа, 3698 = PTAX продажа, 3697 = PTAX покупка, 3695 = PTAX средний) — этот инструмент является первичным источником бюллетеня, с покупкой и продажей в одной записи; для определения символа валюты используйте bcb_cambio_moedas. Возвращает: moeda (валюта), periodo (dataInicial, dataFinal, janelaPadrao), totalRegistros (общее количество записей), cotacoes (котировки), disclaimer (отказ от ответственности), qualificacaoParidade (только для недолларовых валют), urlConsulta (URL запроса), consultadoEm (дата запроса) и, если применимо, observacao (примечание). Без указания дат охватывает последние 7 дней (чтобы захватить выходные и праздники). Источник: PTAX / Котировки и бюллетени валютного рынка Центрального банка Бразилии через Olinda OData. Ответ дословно передает отказ от ответственности BCB в поле disclaimer. Котировки существуют только в рабочие дни с закрытием валютного рынка. Паритеты недолларовых валют поступают от информационного агентства (Refinitiv), распространяются BCB — не рассчитываются Центральным банком.

Выводит список валют с курсами, опубликованными Центральным банком, с символом, названием и типом, и принимает термин для фильтрации. Когда использовать: чтобы узнать правильный символ перед вызовом bcb_cambio_cotacao (это самая частая причина пустого курса). Когда НЕ использовать: для значений курса. Возвращает: termo, totalMoedas, moedas (simbolo, nome, tipo), disclaimer, qualificacaoParidade, urlConsulta и consultadoEm. Источник: PTAX / Курсы и бюллетени обмена валют Центрального банка Бразилии, через Olinda OData. Ответ передаёт буквально отказ от ответственности BCB в поле disclaimer. Курсы существуют только в рабочий день с закрытием обмена валют.

Сравнивает от 2 до 5 временных рядов за ОДИН И ТОТ ЖЕ период (dataInicial и dataFinal обязательны), вычисляя процентное изменение каждого и сортируя их в рейтинг (от большего к меньшему изменению). Ряд уровня входит через изменение между крайними точками; ряд, который уже является изменением за период (ежемесячные IPCA, INPC, IGP-M из каталога; накопленные за месяц Selic/CDI; poupança) входит через СЦЕПЛЕННОЕ НАКОПЛЕНИЕ за период — каждый элемент указывает в metodo, какой расчёт был выполнен, так что «какой индекс цен вырос больше всего в 2024 году» — это данная tool. Когда использовать: для сравнения/корреляции эволюции нескольких индикаторов рядом. Когда НЕ использовать: для одного ряда используйте bcb_variacao. Возвращает: periodo, totalSeries, seriesComDados, seriesComErro, ranking (каждый элемент с posicao, codigo, nome, metodo, valorInicial, valorFinal, variacaoPercentual, maximo, minimo, media) и erros. Устойчив: ряды без данных за период и ряды с накопленным скользящим (IPCA за 12 месяцев) изолируются в erros без аннулирования сравнения. Разная периодичность: сравнение дневного ряда с месячным выравнивает точки, которые несопоставимы, и ответ предупреждает об этом в aviso; укажите frequencia (mensal|trimestral|anual), чтобы привести все к одной сетке перед сравнением, выбрав соглашение в agregacao. Длинные окна в дневных рядах разрезаются автоматически (лимит 10 лет API BCB). Поведение: использует публичный API SGS Центрального банка Бразилии — без аутентификации, ключа API или регистрации и без объявленного лимита запросов (использование best-effort). При временном сбое или таймауте вызов автоматически повторяется (до 3 попыток, экспоненциальная задержка); при сохранении ошибки возвращает isError: true с сообщением на португальском (HTTP 404 = ряд не существует или нет данных за запрошенный период). Результат приходит в виде JSON как в тексте, так и в structuredContent (в соответствии с outputSchema); даты в формате dd/MM/yyyy и числовые значения (десятичная точка).

Вычисляет попарную статистическую корреляцию между 2–5 временными рядами БЦБ за ОДИН И ТОТ ЖЕ период (dataInicial и dataFinal обязательны). Когда использовать: чтобы проверить, движутся ли два показателя вместе (например, доллар и Selic, IPCA и IGP-M). Когда НЕ использовать: для сравнения изменений рядов бок о бок применяйте bcb_comparar; для одного ряда — bcb_variacao. Методы: pearson (по умолчанию) измеряет ЛИНЕЙНУЮ зависимость между значениями; spearman измеряет МОНОТОННУЮ зависимость между рангами и подходит, когда связь нелинейна или один ряд застывает на плато (ставка между заседаниями Copom). База: nivel (по умолчанию) коррелирует значения; variacao коррелирует процентное изменение от точки к точке — отдавайте предпочтение variacao, если оба ряда имеют тренд (цена, индекс, запас), потому что уровень двух растущих рядов даёт высокую корреляцию лишь из-за того, что оба растут во времени. Возвращает: periodo, metodo, base, series, alinhamento (пересекающиеся, полные и частичные даты), pares (каждая пара с codigoA/codigoB, coeficiente от -1 до 1, n, descartados и interpretacao в свободной форме), erros и derivacao. Коэффициент, который невозможно вычислить, приходит null с полем motivo — никогда не 0, потому что 0 означал бы измеренное отсутствие связи. Разные периодичности ОТКЛОНЯЮТСЯ, а не предупреждаются: скрещивание дневного ряда с месячным по дате совместит только совпадающие даты (около 7 за год) и даст коэффициент по этой горстке; укажите frequencia, чтобы привести все ряды к единой сетке перед корреляцией. Корреляция не устанавливает причинно-следственную связь. Поведение: использует публичный API SGS Центрального банка Бразилии — без аутентификации, ключа API или регистрации, без объявленного лимита запросов (работает best-effort). При временном сбое или тайм-ауте вызов автоматически повторяется (до 3 попыток, экспоненциальная задержка); если ошибка сохраняется, возвращает isError: true с сообщением на португальском (HTTP 404 = ряд не существует или нет данных за запрошенный период).

Преобразует номинальный ряд BCB в РЕАЛЬНЫЕ значения (постоянная валюта), вычитая инфляцию за период — разница между «минимальная зарплата выросла на 46% с 2020 года» и «минимальная зарплата выросла на 5% в покупательной способности». Когда использовать: всякий раз, когда сравниваются значения в реалах из разных эпох. Когда НЕ использовать: для рядов, которые уже являются процентными, индексами или ставками (дефлировать процентную ставку не имеет смысла); для сырого номинального ряда используйте bcb_serie_valores. Индекс: ipca (по умолчанию), inpc или igpm. База: mesBase в формате yyyy-MM определяет, в реалах какого месяца выражены значения; без него используется последний опубликованный месяц индекса («в сегодняшних реалах»). Возвращает: serie, deflator (индекс, код, покрытие), base, periodo, dados (каждая точка с valorNominal, valorReal и fator), variacao (номинальный процент рядом с реальным за тот же период), derivacao и avisos. Ограничение источника: SGS не публикует число-индекс, поэтому индекс восстанавливается путём компоновки ежемесячных изменений — восстановление проверено по самому источнику (максимальная разница 0,0052 процентного пункта против официального накопления за 12 месяцев). Точка данных вне покрытия индекса получает valorReal: null, никогда не вымышленное значение; поскольку индекс публикуется с задержкой, текущий месяц обычно попадает в этот случай. Поведение: использует публичный API SGS Центрального банка Бразилии — без аутентификации, ключа API или регистрации, и без объявленного лимита запросов (использование best-effort). При временном сбое или тайм-ауте вызов повторяется автоматически (до 3 попыток, экспоненциальная задержка); если ошибка сохраняется, возвращает isError: true с сообщением на португальском (HTTP 404 = ряд не существует или нет данных за запрошенный период). Результат приходит в формате JSON как в тексте, так и в structuredContent (согласно outputSchema); даты в формате dd/MM/yyyy и числовые значения (десятичная точка).

Запрашивает рыночные ожидания из бюллетеня Focus для ОДНОГО показателя, с горизонтом в качестве параметра: месячный, квартальный, годовой, инфляция на ближайшие 12 месяцев и на ближайшие 24 месяца. Возвращает среднее, медиану, стандартное отклонение, минимум, максимум и количество респондентов по дате сбора. Когда использовать: для ожидания IPCA, IGP-M, ВВП, курса валюты и подобных за конкретный месяц, квартал или год, или для скользящей инфляции. Когда НЕ использовать: для ожидания Selic по заседанию Copom используйте bcb_focus_selic; для ФАКТИЧЕСКОГО (не ожидаемого) значения используйте bcb_serie_valores. Правила контракта: referencia обязательна для календарных горизонтов (месячный, квартальный, годовой) и отвергается для скользящих; suavizada действует только для скользящих; top5: true возвращает ожидания пяти наиболее точных институтов и существует для всех пяти горизонтов. Если вы не знаете точный текст показателя или ссылки, сначала вызовите bcb_focus_referencias — набор показателей МЕНЯЕТСЯ в зависимости от горизонта, и запрос показателя на горизонте, где источник его не публикует, является самой частой причиной пустого ответа. Возвращает: indicador, horizonte, base (consenso|top5), filtro (referencia, dataInicial, dataFinal, janelaPadrao, suavizada), totalRegistros, expectativas (нормализованный массив), urlConsulta, consultadoEm и, если применимо, observacao. Без указания дат окно по умолчанию составляет 30 дней. Источник: Рыночные ожидания (Focus) Центрального банка Бразилии, через Olinda OData. Focus по своей сути является винтажным: coletadoEm — это дата сбора, а referencia — цель ожидания — одна и та же ссылка появляется во многих сборах, и именно это позволяет увидеть, как ожидание меняется со временем. Подсчет ведется с нашей стороны, потому что источник игнорирует $count; и фильтр обязателен по построению, потому что запрос без фильтра не завершается в источнике. Микроданные по институтам НЕ предоставляются: источник отключил эту функцию из-за риска нарушения конфиденциальности.

Перечисли, ПО ОБЪЁМУ, индикаторы и ссылки, которые Focus фактически публикует, чтобы ты использовал ТОЧНЫЙ текст в bcb_focus_expectativas и в bcb_focus_selic. Объём = пять горизонтов bcb_focus_expectativas плюс 'selic', который не является горизонтом: его ось — заседание Copom, а потребляет его bcb_focus_selic. Каждый блок указывает в tool, кто его потребляет. Использовать: перед первым запросом к Focus или когда запрос возвращает пустой результат — самая частая причина не отсутствие данных, а то, что индикатор НЕ СУЩЕСТВУЕТ в ЭТОМ объёме (источник публикует 9 индикаторов в месячном и 26 в годовом: 'PIB Total', например, не существует в месячном) или ссылка имеет формат, отличный от опубликованного. НЕ использовать: для значений самих ожиданий. Без escopo запрашивает все шесть и возвращает всё; с escopo запрашивает только его. Возвращает: escopos (для каждого: tool, который его потребляет, formatoReferencia, exigeReferencia, temTop5, indicadores, referencias, urlConsulta и disponivel), плюс indicadores и referencias как объединение всех, janela, totalRegistros и consultadoEm. Если какой-то объём не ответил, остальные всё равно возвращаются, с заполненным falhas. Источник: Ожидания рынка (Focus) Центрального банка Бразилии, через Olinda OData. Focus является винтажным по построению: coletadoEm — дата сбора, а referencia — цель ожидания — одна и та же ссылка появляется во многих сборах, и это позволяет видеть, как ожидание меняется со временем. Подсчёт ведётся на нашей стороне, потому что источник игнорирует $count; а фильтр обязателен по построению, потому что запрос без фильтра не завершается в источнике. Микроданные по учреждениям НЕ раскрываются: источник отключил эту возможность из-за риска нарушения конфиденциальности.

Получает рыночные ожидания Focus для ставки Selic, сгруппированные по ЗАСЕДАНИЮ Copom (формат R1/2026 = 1-е заседание 2026 года). Возвращает среднее, медиану, стандартное отклонение, минимум, максимум и количество респондентов на дату сбора. Когда использовать: для «что рынок ожидает от Selic на следующем заседании» или ожидаемой траектории ставок. Когда НЕ использовать: для ожидаемой средней Selic за календарный год используйте bcb_focus_expectativas с годовым горизонтом; для ФАКТИЧЕСКОЙ Selic используйте bcb_serie_valores (коды 432, 1178, 4390). Отделена от bcb_focus_expectativas, потому что временная ось — это заседание Copom, а не календарь. Возвращает: base (consensus|top5), filter, totalRecords, expectations (с reference = заседание), queryUrl, queriedAt и axisObservation. Без дат окно по умолчанию — 30 дней. Источник: Рыночные ожидания (Focus) Центрального банка Бразилии через Olinda OData. Focus по построению является винтажным: collectedAt — дата сбора, а reference — цель ожидания: одна и та же ссылка встречается во многих сборах, и именно это позволяет увидеть изменение ожиданий во времени. Подсчёт ведётся на нашей стороне, потому что источник игнорирует $count; фильтр обязателен по построению, так как запрос без фильтра не завершается в источнике. Микроданные по учреждениям НЕ раскрываются: источник отключил эту функцию из-за риска нарушения конфиденциальности.

Аталка, которая возвращает за один вызов последние значения ключевых индикаторов экономики Бразилии: годовая Selic, месячный IPCA, IPCA накопленный за 12 месяцев, курс доллара PTAX (продажа) и IBC-Br. Не принимает параметров. Когда использовать: для быстрого обзора экономики. Когда НЕ использовать: для любых других рядов, исторических данных или выбора периода — используйте bcb_serie_ultimos или bcb_serie_valores. Возвращает: consultadoEm (временная метка ISO 8601) и indicadores (массив с индикатором, кодом, датой, значением — или erro в элементе). Отказоустойчивый: каждый индикатор запрашивается независимо, поэтому сбой одного не роняет остальные. Поведение: использует публичный API SGS Центрального банка Бразилии — без аутентификации, ключа API или регистрации и без заявленного лимита запросов (использование best-effort). При временном сбое или тайм-ауте вызов повторяется автоматически (до 3 попыток, экспоненциальная задержка); при сохраняющейся ошибке возвращает isError: true с сообщением на португальском (HTTP 404 = ряд не существует или нет данных за запрошенный период). Результат приходит в JSON как в текстовом виде, так и в structuredContent (согласно outputSchema); даты в формате dd/MM/yyyy и числовые значения (десятичная точка).

Получает описание ОДНОЙ серии BCB (название, периодичность, категория, источник и последнее значение) без исторических данных. Когда использовать: чтобы проверить, что это за серия и как часто она публикуется, до запроса данных. Когда НЕ использовать: для самих значений используйте bcb_serie_valores или bcb_serie_ultimos. Возвращает: codigo, nome, periodicidade, categoria, fonte, ultimoValor и прямые URL API (urlConsulta, urlUltimos10). Ограничение источника: API SGS НЕ публикует endpoint метаданных по серии - единица измерения недоступна. Nome и categoria берутся из курируемого каталога сервера (135 серий проверены против источника), а вне его периодичность выводится из интервала между наблюдениями, о чем сигнализирует periodicidadeInferida. Поведение: использует публичный API SGS Центрального банка Бразилии - без аутентификации, API-ключа или регистрации и без объявленного лимита запросов (использование best-effort). При временном сбое или таймауте вызов повторяется автоматически (до 3 попыток, экспоненциальная задержка); если ошибка сохраняется, возвращает isError: true с сообщением на португальском (HTTP 404 = серия не существует или нет данных за запрошенный период). Результат приходит в виде JSON как в тексте, так и в structuredContent (согласно outputSchema); даты в формате dd/MM/yyyy и числовые значения (десятичная точка).

Перечисляет внутренний курируемый каталог из 135 экономических серий BCB с их кодами, сгруппированных по категориям (Juros, Inflação, Câmbio, Atividade Econômica, Emprego, Fiscal, Setor Externo, Crédito, Agregados Monetários, Poupança); принимает фильтр по категории. Когда использовать: чтобы просматривать и находить доступные серии по теме. Когда НЕ использовать: для поиска по ключевому слову используйте bcb_buscar_serie; этот инструмент не ищет значения. Возвращает: totalSeries, categorias (количество категорий) и series - объект, сгруппированный по категориям, когда фильтр не задан, или плоский массив при фильтрации по категории; каждый элемент содержит codigo, nome, categoria, periodicidade и fonteNome. Локальный каталог: не делает сетевых вызовов. Происхождение: fonteNome = 'portal', когда имя взято из датасета серии на Портале открытых данных BCB (82 серии, с unidade), и 'medido', когда у серии нет там датасета - в этом случае имя наследуется, а с источником сверялись периодичность и порядок величины. Ожиданий Focus здесь НЕТ: используйте bcb_focus_expectativas.

Получает последние N наблюдений ОДНОГО временного ряда BCB (самые свежие первыми, начиная с конца ряда). Когда использовать: чтобы увидеть последние данные без необходимости вычислять даты (например, последние 12 месяцев IPCA). Количество от 1 до 1000 (по умолчанию 10). Когда НЕ использовать: для диапазона дат или полной истории используйте bcb_serie_valores. Возвращает: объект serie, totalRegistros и dados (массив {data, valor}); при отсутствии данных totalRegistros = 0 и observacao. Поведение: использует публичное API SGS Банка Бразилии — без аутентификации, ключа API или регистрации, и без объявленного лимита запросов (использование best-effort). При временной ошибке или тайм-ауте вызов автоматически повторяется (до 3 попыток, экспоненциальный backoff); при сохранении ошибки возвращает isError: true с сообщением на португальском (HTTP 404 = ряд не существует или нет данных за запрошенный период). Результат выдается в формате JSON как в тексте, так и в structuredContent (согласно outputSchema); даты в формате dd/MM/yyyy и числовые значения (десятичная точка).

Запрашивает историю значений ОДНОГО временного ряда BCB по коду SGS, опционально ограниченную диапазоном дат (dataInicial/dataFinal). Когда использовать: чтобы получить полную историю ряда или окно конкретных дат. Когда НЕ использовать: для получения только последних точек используйте bcb_serie_ultimos; для процентного изменения — bcb_variacao; для сравнения нескольких рядов — bcb_comparar; если вы не знаете код, сначала найдите его с помощью bcb_buscar_serie или bcb_series_populares. Возвращает: объект serie (codigo, nome, categoria, periodicidade), totalRegistros, periodoInicial, periodoFinal и dados (массив {data, valor}); когда данных нет, totalRegistros = 0 и поясняющее observacao. Поведение: использует публичное API SGS Banco Central do Brasil — без аутентификации, API-ключа или регистрации, и без объявленного лимита запросов (использование best-effort). При временном сбое или тайм-ауте вызов автоматически повторяется (до 3 попыток, экспоненциальная задержка); если ошибка сохраняется, возвращает isError: true с сообщением на португальском (HTTP 404 = ряд не существует или нет данных за запрошенный период). Результат приходит в виде JSON как в тексте, так и в structuredContent (согласно outputSchema); даты в формате dd/MM/yyyy и числовые значения (десятичная точка).

Вычисляет процентное изменение одного ряда за период, а также описательную статистику. Для ряда УРОВНЯ (доллар, Selic, долг, производство) — это изменение между первой и последней точкой; для ряда, который УЖЕ является изменением за период (IPCA 433, INPC 188, IGP-M 189 и остальные месячные индексы цен из каталога; накопленная за месяц Selic/CDI 4390/4391; доходность сбережений 25/195) — это НАКОПЛЕНИЕ за период через сцепку — «сколько накопил IPCA в 2024 году» или «сколько принесла Selic в 2024 году» — это и есть этот инструмент. Поле analise.metodo показывает, какой из двух расчётов выполнен; код вне каталога считается уровнем. Ряд скользящего накопления (IPCA за 12 месяцев, 13522) возвращает ошибку с пояснением — опубликованное значение уже является ответом. Период можно задать датами (dataInicial/dataFinal) ИЛИ последними N периодами (параметр periodos, который имеет приоритет и игнорирует даты). Когда использовать: для измерения тренда/изменения/накопления одного ряда. Когда НЕ использовать: для сравнения нескольких рядов используй bcb_comparar; для сырых значений используй bcb_serie_valores. Требуется минимум 2 наблюдения за период (иначе возвращает isError). Возвращает: serie, periodo (dataInicial, dataFinal, totalPeriodos), analise (metodo, valorInicial, valorFinal, diferencaAbsoluta — null при сцепке —, variacaoPercentual, variacaoFormatada) и estatisticas (maximo, minimo, media, amplitude). Длинные периоды обрабатываются автоматически: дневное окно более 10 лет разбивается на фрагменты (API BCB отвечает 406), а periodos больше 20 обслуживается через окно дат; chunking и janelaAplicada появляются в ответе, когда это происходит. Поведение: потребляет публичный API SGS Центрального банка Бразилии — без аутентификации, ключа API или регистрации, и без объявленного лимита запросов (использование best-effort). При временном сбое или таймауте вызов автоматически повторяется (до 3 попыток, экспоненциальная задержка); если ошибка сохраняется, возвращает isError: true с сообщением на португальском (HTTP 404 =…).

Возвращает полный документ для идентификатора, полученного из search, в виде { id, title, text, url, metadata }: text содержит читаемое содержимое (Markdown), а url - каноническую публичную страницу для цитирования. Парный инструмент к search в контракте OpenAI Deep Research, работающий с каталогом временных рядов Banco Central do Brasil (SGS: процентные ставки, инфляция, обменные курсы, кредит, фискальный и внешний сектор: курируемый каталог плюс индекс портала открытых данных). Допустимы только идентификаторы, возвращенные search; неизвестный идентификатор приводит к ошибке. Инструменты bcb_* остаются инструментами для запросов данных. Поведение: только чтение и идемпотентность: выполняется живой GET-запрос к публичному источнику, когда документ этого требует.

Ищет в каталоге временных рядов Banco Central do Brasil (SGS: процентные ставки, инфляция, валютные курсы, кредит, фискальный и внешний сектора; это курируемый каталог плюс индекс портала открытых данных) и возвращает до 10 подходящих документов в виде { id, title, url }, отсортированных по релевантности (пустой список означает, что ничего не найдено). Этот инструмент существует для контракта OpenAI Deep Research: ChatGPT deep research, корпоративные знания и исследовательские рабочие процессы через Responses API требуют именно инструментов search и fetch. Передайте один из возвращённых идентификаторов в fetch, чтобы прочитать документ. Для прямых вопросов и данных (значения, ряды, рейтинги) предпочитайте инструменты bcb_*, которые возвращают фактические данные с указанием источника. Это индекс каталога, а не запрос данных. Запрос: естественный язык или ключевые слова, португальский или английский; диакритические знаки и регистр не учитываются. Поведение: только чтение и идемпотентность. Каталог берётся из публичного источника и кэшируется в памяти.