tsb-kasko-mcp — MCP-сервер и CLI для списка страховых сумм каско TSB

Сервер с открытым исходным кодом MCP, инструмент командной строки и клиент Python для запроса Списка страховых сумм каско, публикуемого Турецкой ассоциацией страхования (TSB). С помощью Claude, ChatGPT, Gemini и Cursor можно спросить: «Сколько стоит страховка каско на Audi A3 2025 года?»; написать в терминале tsb-kasko lookup 2025 "audi a3"; или использовать как библиотеку в своём проекте Python.

Список сумм каско — это эталонная стоимость, по которой оценивается каждый полис каско, продаваемый в Турции. Она также является основой для выплаты в случае полного ущерба (перт) и кражи. Этот проект превращает конечные точки, используемые в фоновом режиме веб-сайта TSB и не требующие аутентификации, в типизированный клиент.

При установке пакета появляются обе команды; устанавливать отдельный пакет CLI не нужно.

Содержание

• Для чего это нужно

• Установка

• Установка MCP

• Инструменты MCP

• Использование командной строки

• Как библиотека Python

• Docker

• Конфигурация

• Используемые конечные точки TSB

• Структура проекта

• Разработка

• Часто задаваемые вопросы

• Отказ от ответственности

Related MCP server: RACV Insurance MCP Server

Для чего это нужно

• Запрос суммы каско через ИИ-ассистента. Задаёте вопрос на естественном языке в Claude, ChatGPT и Gemini, модель вызывает инструмент и возвращает актуальную сумму.

• Запрос из терминала. Команда tsb-kasko lookup 2025 "audi a3 sportback" выводит таблицу, JSON или CSV напрямую.

• Код транспортного средства в полисе. Результаты также содержат пару код марки - код модели, которую запрашивает страховщик, например 9-1616.

• Архивные списки. TSB публикует список каждый месяц. Вы можете скачать Excel-файл за прошлые месяцы или выполнить поиск внутри него.

• Библиотека Python. В своём проекте вы можете напрямую использовать класс TsbKaskoClient.

Установка

Предварительное условие: uv. Он также установит Python.

Для пробы без установки:

uvx --from git+https://github.com/hmtkyn/tsb-kasko-mcp tsb-kasko lookup 2025 "audi a3 sportback"

Постоянная установка:

uv tool install git+https://github.com/hmtkyn/tsb-kasko-mcp

или с помощью pip:

pip install git+https://github.com/hmtkyn/tsb-kasko-mcp

Пакет ещё не опубликован на PyPI. Когда будет опубликован, uv tool install tsb-kasko-mcp и pip install tsb-kasko-mcp также будут работать; рабочий процесс публикации готов в репозитории.

Инструкции по установке для разработки из репозитория см. в разделе Разработка.

Установка MCP

Сервер поддерживает как транспорт stdio, так и потоковый HTTP, поэтому он работает как с настольными клиентами, так и с хостингованными коннекторами.

Claude Code

claude mcp add tsb-kasko -- uvx --from git+https://github.com/hmtkyn/tsb-kasko-mcp tsb-kasko-mcp

Claude Desktop

Добавьте в файл claude_desktop_config.json:

{
  "mcpServers": {
    "tsb-kasko": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/hmtkyn/tsb-kasko-mcp", "tsb-kasko-mcp"]
    }
  }
}

Cursor / VS Code

Добавьте тот же блок mcpServers в файл .cursor/mcp.json или .vscode/mcp.json в рабочей области.

Gemini CLI

Добавьте в файл ~/.gemini/settings.json:

{
  "mcpServers": {
    "tsb-kasko": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/hmtkyn/tsb-kasko-mcp", "tsb-kasko-mcp"]
    }
  }
}

ChatGPT и другие удалённые клиенты

Коннекторы ChatGPT подключаются к серверу через HTTP. Запустите сервер в режиме HTTP:

TSB_KASKO_TRANSPORT=http TSB_KASKO_HOST=0.0.0.0 TSB_KASKO_PORT=8000 tsb-kasko-mcp

или с любым ASGI-сервером:

uvicorn tsb_kasko.asgi:app --host 0.0.0.0 --port 8000

Конечная точка по умолчанию публикуется по адресу http://сервер:8000/mcp. Самый простой способ — см. раздел Docker.

Инструменты MCP

Все инструменты, кроме kasko_download_archive, помечены как readOnlyHint; то есть клиент может вызывать их без запроса подтверждения.

Использование командной строки

# Kapsanan model yılları
tsb-kasko years

# Bir model yılındaki markalar
tsb-kasko brands 2025

# Bir markanın tipleri
tsb-kasko models 2025 audi

# Serbest metinle sorgulama
tsb-kasko lookup 2025 "audi a3 sportback s line"

# Markayı sabitleyerek hızlandırma
tsb-kasko lookup 2025 "corolla hybrid" --brand toyota --limit 10

# JSON veya CSV çıktısı
tsb-kasko lookup 2025 "audi a3" --format json
tsb-kasko brands 2025 --format csv > markalar.csv

# Arşiv
tsb-kasko archive months
tsb-kasko archive file 2025 2
tsb-kasko archive search 2025 2 --query "sahin" --limit 20
tsb-kasko archive download 2025 2 --output ~/Downloads

# Önbellek
tsb-kasko cache path
tsb-kasko cache clear

# MCP sunucusunu CLI üzerinden çalıştırma
tsb-kasko serve --transport http --port 8000

Пример вывода:

                      audi a3 sportback in 2025
┏━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Vehicle Code ┃ Brand ┃ Model                               ┃ Kasko Value    ┃
┡━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ 9-1616       │ AUDI  │ A3 SPORTBACK 35 TFSI 150 S LINE ... │ 3.695.439,00 TL│
└──────────────┴───────┴─────────────────────────────────────┴────────────────┘

Как библиотека Python

import asyncio

from tsb_kasko import TsbKaskoClient


async def main() -> None:
    async with TsbKaskoClient() as client:
        for value in await client.lookup(2025, "audi a3 sportback"):
            print(value.vehicle_code, value.model_name, value.amount)


asyncio.run(main())

Docker

Контейнер публикует MCP-сервер через HTTP-транспорт. Использует двухэтапную сборку, работает от непривилегированного пользователя, файловая система только для чтения.

docker compose up --build
# -> http://127.0.0.1:8000/mcp

Чтобы только собрать образ и запустить CLI:

docker build -f .docker/python/Dockerfile -t tsb-kasko-mcp .
docker run --rm --entrypoint tsb-kasko tsb-kasko-mcp lookup 2025 "audi a3"

Версия Python фиксируется в образе через ARG PYTHON_VERSION и использует ту же версию, что и .python-version в репозитории.

Конфигурация

Все настройки можно переопределить через переменные окружения.

Используемые конечные точки TSB

TSB не публикует контракт API. Ниже приведены конечные точки, используемые внешним интерфейсом сайта, не требующие аутентификации и куки. Все они определены в одном месте в src/tsb_kasko/endpoints.py.

Две детали примечательны:

1. Поле VehicleBrandCode в списке марок всегда равно 0. Реальный код марки, указанный в полисе, приходит только в ответе GetInsuranceDatas.

2. Поле Id в GetMonthList не является номером месяца календаря. Январь имеет идентификатор 2, Октябрь — 1. Поэтому клиент не вычисляет идентификатор месяца, а получает его из живого списка.

Структура проекта

Все три интерфейса — это тонкие обёртки поверх одного и того же ядра. Поэтому все они живут в одном репозитории: если TSB переименует какую-либо конечную точку, исправление вносится в один файл, и не требуется синхронизация трёх отдельных версий.

src/tsb_kasko/
├── client.py      # çekirdek: HTTP, yeniden deneme, önbellek
├── endpoints.py   # TSB uçlarının tek tanım yeri
├── models.py      # Pydantic modelleri
├── parsing.py     # zarf açma, Türkçe sayı ve metin normalleştirme
├── archive.py     # aylık Excel listelerinin okuyucusu
├── server.py      # kabuk 1: FastMCP sunucusu
├── cli.py         # kabuk 2: Typer komut satırı
└── asgi.py        # HTTP taşıması için ASGI uygulaması

Такая же структура используется в проектах github/github-mcp-server, microsoft/playwright-mcp и grafana/mcp-grafana: общее ядро, поверх него несколько точек входа.

Разработка

git clone https://github.com/hmtkyn/tsb-kasko-mcp.git
cd tsb-kasko-mcp
uv sync --all-extras --all-groups
uv run pre-commit install

uv run pytest                                  # 146 test, kayıtlı gerçek yanıtlarla
uv run pytest --cov --cov-report=term-missing  # kapsam raporu
uv run ruff check .                            # lint
uv run ruff format .                           # biçimlendirme
uv run mypy src/tsb_kasko                      # strict tip denetimi
uv run pre-commit run --all-files              # CI'ın yaptığının tamamı

Тесты используют точные копии реальных ответов от TSB, поэтому при изменении контракта тесты сломаются. Нет тестов, выходящих в сеть.

Одинаковый результат на Windows, macOS и Linux

Этот репозиторий настроен для одинакового поведения на всех трёх операционных системах:

• .python-version фиксирует версию Python на 3.14; uv при необходимости загрузит её. Однако поддерживаемый пакетом диапазон — >=3.11, и CI тестирует все четыре версии.

• .gitattributes хранит каждый текстовый файл в репозитории с окончанием строки LF. Даже если core.autocrlf включён в Windows, в репозиторий не попадут символы CRLF. В CI есть отдельный шаг для проверки этого.

• .editorconfig фиксирует отступы, кодировку и конец строки независимо от редактора.

• С помощью .devcontainer/ вы можете разрабатывать внутри контейнера, ничего не устанавливая.

Подробности см. в CONTRIBUTING.md.

Часто задаваемые вопросы

Что такое стоимость каско и как она определяется? Это эталонная стоимость транспортного средства по марке и типу, публикуемая TSB ежемесячно. Страховые компании рассчитывают на основе этой стоимости премию полиса и выплату по ущербу.

Как узнать стоимость каско моего автомобиля? Выполните команду tsb-kasko lookup <модельный_год> "<марка и тип>" или установите MCP-сервер и спросите своего ассистента. Официальный источник всегда — tsb.org.tr.

Что такое код транспортного средства в полисе? Это пара код марки - код модели, которую запрашивает страховщик, например 9-1616. В результатах возвращается в поле vehicle_code.

Какие модельные годы охватываются? 2012 и более поздние. Актуальный список можно увидеть с помощью tsb-kasko years.

Могу ли я получить список за прошлый месяц? Да. tsb-kasko archive search 2025 2 --query "sahin" выполняет поиск в Excel-файле за прошлый месяц, а archive download скачивает сам файл.

Этот проект официальный? Нет. См. отказ от ответственности ниже.

Отказ от ответственности

Этот проект не связан с TSB и не поддерживается TSB. Данные берутся с общедоступной страницы TSB. По собственному заявлению TSB, они не несут ответственности за последствия использования этих значений в сделках. Официальный источник всегда — tsb.org.tr.

Поскольку конечные точки не задокументированы TSB, они могут измениться без предупреждения. В таком случае достаточно обновить файл src/tsb_kasko/endpoints.py.

Вклад и лицензия

• Руководство по вкладу: CONTRIBUTING.md

• Кодекс поведения: CODE_OF_CONDUCT.md

• Политика безопасности: SECURITY.md

• Журнал изменений: CHANGELOG.md

MIT опубликовано под лицензией. Перевод на турецкий язык: docs/lisans.md.