API ВЕГА
English

Примеры API Obolus Finance и удалённого MCP

Публичные примеры работы с API Obolus для расчёта заработной платы и налогов в нескольких странах. В репозитории собраны небольшое приложение-клиент на Vite, примеры подключения и документация. Размещённые сервисы расчётов и MCP-сервер работают на obolusfinanz.de; исходный код сервера в этом репозитории отсутствует.

Удалённый MCP-сервер

Obolus предоставляет общедоступную конечную точку MCP только для чтения:

  • Streamable HTTP: https://www.obolusfinanz.de/api/mcp/claude

  • Инструменты: berechne для подробного расчёта заработной платы в одной стране и taxcompare для сравнения двух или более стран

  • Доступ: для использования этих инструментов только для чтения не нужны учётная запись или API-ключ

  • Реестр: io.github.sanzation/obolus

  • Полная документация по API и MCP: Документация для разработчиков Obolus

URL /claude — это интерфейс MCP, нейтральный к агенту, несмотря на историческое название маршрута. Он подходит для MCP-клиентов, отличных от Claude. Этот интерфейс отделён от интеграции с приложением ChatGPT, доступной через браузер по адресу /api/mcp.

Подключение из VS Code / GitHub Copilot

В репозитории есть файл рабочей области .mcp.json. Откройте папку в VS Code, перейдите к списку MCP-серверов и запустите obolus. Конфигурацию также можно скопировать в собственную рабочую область:

{
  "servers": {
    "obolus": {
      "type": "http",
      "url": "https://www.obolusfinanz.de/api/mcp/claude"
    }
  }
}

Например, попросите агента: «Сравни годовую зарплату брутто в размере 60 000 EUR в Германии и Австрии для налогового года 2026 с помощью Obolus». Если данных о профиле не хватает, агент должен запросить их, а не придумывать. Расчёты являются оценочными: прежде чем использовать результат, проверьте допущения и сведения об источниках, возвращаемые каждым инструментом.

Чтобы проверить подключение к общедоступному MCP-серверу без выполнения расчёта, запустите npm run mcp:check. Команда выведет список доступных инструментов и проверит наличие обоих ожидаемых инструментов.

Демонстрационное приложение REST API

Приложение на Vite демонстрирует прямые REST-запросы к POST /api/berechne и POST /api/taxcompare. Это клиент API, а не локальный MCP-сервер и не копия налогового движка.

npm install
npm run dev

Откройте http://localhost:8080. Прокси Vite перенаправляет запросы к API; подробности приведены в файле vite.config.js. Для сборки выполните npm run build.

Актуальную полную схему запроса и примеры ответов смотрите на странице для разработчиков или в документе OpenAPI. Демонстрационное приложение в браузере использует устаревший псевдоним annual_gross, значение которого указывается в основных единицах валюты. В новых интеграциях с taxcompare рекомендуется использовать salary_ct, значение которого указывается в минимальных единицах валюты: 6000000 соответствует 60 000 EUR, если для currency задано значение eur, а для salary_period — annual. Необходимо указать как минимум две страны и поддерживаемый налоговый год. В подробном методе berechne значения полей зарплаты также указываются в минимальных единицах валюты.

Пример запроса для сравнения:

const response = await fetch("https://www.obolusfinanz.de/api/taxcompare", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    salary_ct: 6000000,
    salary_period: "annual",
    tax_year: "2026",
    countries: ["DE", "AT"],
    currency: "eur"
  })
});
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
console.log(result);

Поддерживаемые страны: Германия, Австрия, Швейцария, США, Великобритания, Ирландия, Канада и Австралия. Возвращаемая сумма нетто отражает результат расчёта налогов и заработной платы. Расходы на жильё, продукты, медицинские услуги, не учитываемые при расчёте заработной платы, и поправки на покупательную способность рассчитываются отдельно. Не следует описывать сумму нетто после расчёта заработной платы как располагаемый доход за вычетом расходов на жизнь.

Назначение и использование репозитория

Это общедоступный пример интеграции, а не репозиторий с исходным кодом MCP-сервера. На размещённый API распространяются условия использования и ограничения частоты запросов; не считайте, что демонстрационное приложение предоставляет неограниченный доступ для использования в рабочей среде. Не добавляйте API-ключи и другие учётные данные в репозиторий. Для общедоступных инструментов MCP только для чтения ключ не требуется.