# ibronevik-taxi-mcp

MCP-сервер над самописным API такси-сервиса (`/taxi/api/v1/...`). Выставляет ручки
бэка как инструменты для языковой модели.

Это **каркас** (этап 1). В нём собрана и проверена вся общая механика, на которую
дальше навешиваются ручки. Изменяющие инструменты сценария «жизненный цикл заказа»
подключаются поверх готового `TaxiClient`.

## Что уже работает

Четыре read-only инструмента, работающих **без учётной записи** (публичный
справочник прода):

| Инструмент | Назначение |
|---|---|
| `taxi_status` | доступность бэка, арендатор, версия справочника, состояние авторизации |
| `taxi_reference_list` | имена и размеры всех справочных таблиц |
| `taxi_reference_get` | содержимое указанных таблиц (`car_classes`, `currencies`, …) |
| `taxi_authenticate` | проверка входа по `TAXI_LOGIN`/`TAXI_PASSWORD` (токен не разглашается) |

## Что внутри каркаса

Три неочевидные особенности бэка, ради которых каркас и нужен, инкапсулированы
здесь один раз:

- **Тело запроса — форма, а не JSON.** Данные передаются полем `data` с
  JSON-строкой (`src/core/transport.ts`). Отправка `application/json` молча
  ломает поведение бэка.
- **Двухступенчатая авторизация с окном 10 секунд.**
  `POST /auth/` → `auth_hash` → сразу `POST /token/` → `token` + `u_hash`
  (`src/core/auth.ts`). Токен долгоживущий, кешируется; куки между шагами
  тащить не нужно. На каждом запросе прикладываются `token` и `u_hash`;
  при `auth_error` — один прозрачный перелогин.
- **Ответ всегда HTTP 200, код внутри тела; `304` для справочника — это успех.**
  Кеш справочника по версии, обновление через `ucv`/`304` (`src/core/client.ts`).

Структура:

```
src/
  config.ts            конфигурация из окружения, построение URL ручки
  core/
    transport.ts       form-кодирование, прокси-осведомлённый fetch, разбор JSON
    auth.ts            цепочка auth -> token, кеш token/u_hash
    client.ts          единый call(), разбор ответа, кеш справочника
    errors.ts          типы ошибок (транспорт / api / auth / запись)
  mcp/
    server.ts          MCP stdio-сервер, регистрация инструментов
test/
  smoke.ts             проверка каркаса против прода (read-only, без аккаунта)
  mcp-check.ts         проверка MCP-слоя end-to-end настоящим MCP-клиентом
```

## Требования

- Node.js ≥ 22.6 (запускает TypeScript напрямую, без сборки).

## Установка и запуск

```bash
npm install
cp .env.example .env      # при необходимости отредактировать

npm run smoke             # проверка каркаса против прода (read-only)
node test/mcp-check.ts    # проверка MCP-слоя end-to-end
npm start                 # запустить MCP-сервер (stdio)
npm run typecheck         # проверка типов
```

Подключение к MCP-клиенту (stdio), пример конфигурации:

```json
{
  "mcpServers": {
    "ibronevik-taxi": {
      "command": "node",
      "args": ["/путь/к/mcp-server/src/mcp/server.ts"],
      "env": { "TAXI_CONFIG": "0" }
    }
  }
}
```

## Тестирование: что можно и чего нельзя

- **Read-часть** (справочник) — тестируется на проде без учётной записи. Именно
  это делают `smoke.ts` и `mcp-check.ts`.
- **Авторизация** — требует реальной учётной записи; замокать нельзя, шифрование
  `u_hash` завязано на серверный секрет.
- **Изменяющие ручки** (сценарий 1) — на проде тестировать нельзя: каждый вызов
  создаёт реальные записи в боевой базе. Нужен **тестовый тенант** (изолированная
  база, где можно свободно создавать и удалять) либо тестовый аккаунт, чьи заказы
  разрешено отменять. Полный цикл требует двух ролей — клиент (1) и водитель (2).

## Политика записи

Переменная `TAXI_WRITE_MODE` (`block` | `confirm` | `allow`, по умолчанию
`confirm`). Значение по умолчанию не случайно: MCP отдаёт ручки языковой модели,
а бэкенд не проверяет HTTP-метод (записи проходят и по GET). Поэтому запись по
умолчанию не должна выполняться «молча» — изменяющие инструменты проходят через
эту политику.

## Безопасность

Секретов в коде нет — вся конфигурация из окружения, `.env` не коммитится.