baselinker-mcp

MCP-сервер, который предоставляет весь BaseLinker API — заказы, счета, возвраты, курьеров, CRM, склады, товары — LLM-клиенту, такому как Claude Code, Claude Desktop или Cursor.

• Полный. Все 179 документированных методов API, ни один не заглушен.

• Только чтение, пока вы не скажете иначе. 92 метода записи остаются невидимыми, пока вы не включите их; при выключенной записи каждый инструмент сообщает readOnlyHint: true.

• Локально или удалённо. stdio для клиента на вашей машине или Streamable HTTP с OAuth 2.1 (Keycloak) для общего эндпоинта в интернете.

"How many orders came in yesterday that aren't paid yet?"
"Which catalog products dropped below 5 in stock this week?"
"Pull the courier label for order 1234567 and tell me the tracking number."

Содержание

• Быстрый старт

• Подключение клиента

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

• Методы записи

• Поведение, о котором стоит знать

• Удалённое развёртывание (HTTP + OAuth)

• Справочник по конфигурации

• Устранение неполадок

• Разработка

Related MCP server: TextQL MCP Server

Быстрый старт

Требования: Node.js 20 или новее, а также токен BaseLinker API из панели BaseLinker в разделе Аккаунт и прочее → Мой аккаунт → API.

git clone https://github.com/PiotrRaszkowski/baselinker-mcp.git
cd baselinker-mcp
npm install
npm run build
cp .env.example .env     # paste your token into BASELINKER_API_TOKEN

Токен также может быть взят прямо из окружения, которое имеет приоритет над .env. .env читается из корня пакета, поэтому сервер запускается корректно независимо от того, из какой директории его запускает ваш MCP-клиент.

Подключение клиента

Claude Code

claude mcp add baselinker -e BASELINKER_API_TOKEN=your-token -- node /path/to/baselinker-mcp/dist/index.js

Claude Desktop, Cursor или любая конфигурация mcpServers

{
  "mcpServers": {
    "baselinker": {
      "command": "node",
      "args": ["/path/to/baselinker-mcp/dist/index.js"],
      "env": { "BASELINKER_API_TOKEN": "your-token" }
    }
  }
}

Для общего эндпоинта, доступного из claude.ai, см. Удалённое развёртывание.

Инструменты

179 отдельных инструментов перегрузили бы контекст модели и её способность выбирать между ними, поэтому методы сгруппированы так, как их группирует сам BaseLinker: десять инструментов, по одному на категорию API. Каждый принимает имя method и объект parameters, а описание каждого инструмента перечисляет принимаемые им методы с их параметрами и подсказками по пагинации.

Количества ниже — это read + write; методы записи появляются только при BASELINKER_ALLOW_WRITES=true.

Параметры проверяются по Zod-схеме для каждого метода до отправки, поэтому некорректный вызов возвращается как понятная ошибка, а не код ошибки BaseLinker. Неизвестные ключи передаются без изменений — BaseLinker добавляет параметры без предупреждения, и сервер не ломается, когда это происходит.

Методы записи

Отключены по умолчанию. Чтобы включить:

BASELINKER_ALLOW_WRITES=true

Пока отключены, методы записи не перечислены ни в одном enum method инструмента и не могут быть вызваны. Включение активирует все 92 сразу — создание, обновление и удаление заказов, товаров, остатков, цен, счетов, отгрузок, возвратов и складских документов. Некоторые из них удаляют записи; некоторые отправляют реальные курьерские отправки, которые стоят реальных денег. Нет раздельного включения по методам, поэтому включайте запись только для клиента, которому доверяете, и рассмотрите возможность запуска второго экземпляра только для чтения для всего остального.

Поведение, о котором стоит знать

Ограничение частоты запросов. BaseLinker разрешает 100 запросов в минуту. Клиентский ограничитель со скользящим окном обеспечивает это — лишние вызовы ждут своей очереди, а не падают.

Пагинация. Ответы списков ограничены (обычно 100 позиций для заказов, счетов и возвратов; 1000 для товаров каталога). Описание каждого метода содержит конкретную подсказку, например getOrders требует date_confirmed_from, установленный в date_confirmed последнего возвращённого заказа плюс одна секунда, а getInventoryProductsList принимает page с отсчётом от 1.

Скачивание файлов. getLabel, getProtocol, getCourierDocument, getInvoiceFile, getInventoryDocumentFile и getInventoryFulfillmentDeliveryLabels возвращают файл как встроенный ресурс MCP с реальным MIME-типом. Передайте дополнительный параметр save_to_path — обрабатывается локально, никогда не отправляется на BaseLinker — чтобы вместо этого декодировать его на диск и получить { saved_to, extension, bytes }. Это имеет смысл только через stdio, где сервер работает на вашей собственной машине; через HTTP это отклоняется с поясняющей ошибкой.

Удалённое развёртывание (HTTP + OAuth)

С --transport http сервер работает на Streamable HTTP и действует как OAuth 2.0 Resource Server (RFC 9728): он публикует метаданные защищённого ресурса, отвечает на неаутентифицированные вызовы 401 с WWW-Authenticate-запросом и проверяет каждый токен доступа как RS256 JWT против JWKS реалма Keycloak. Клиенты обнаруживают реалм из этих метаданных и регистрируются через Dynamic Client Registration, поэтому ни идентификатор клиента, ни секрет не настраиваются ни на одной стороне.

node dist/index.js --transport http --host 0.0.0.0 --port 8000 --path /mcp

HTTP-транспорт отказывается запускаться без реалма аутентификации, если вы явно не откажетесь с BASELINKER_MCP_AUTH_DISABLED=true. Это намеренно: при включённой записи неаутентифицированный эндпоинт отдаёт интернету ваш аккаунт BaseLinker.

deploy/ содержит полное руководство — настройка реалма Keycloak, защищённый сервис Compose с метками Traefik, фрагменты обратного прокси для Caddy и nginx, команды проверки и модель угроз. Краткая версия:

docker build -t baselinker-mcp:0.2.0 .
docker run -d --name baselinker-mcp -p 8000:8000 \
  -e BASELINKER_API_TOKEN=your-token \
  -e BASELINKER_MCP_AUTH_REALM_URL=https://keycloak.example.com/realms/myrealm \
  -e BASELINKER_MCP_AUTH_BASE_URL=https://mcp.example.com \
  baselinker-mcp:0.2.0

Затем подключите к нему клиента:

claude mcp add --transport http baselinker https://mcp.example.com/mcp

В claude.ai это Settings → Connectors → Add custom connector, URL https://mcp.example.com/mcp, с пустыми Client ID и Client Secret.

Одна вещь, которую стоит прояснить перед публикацией: токен BaseLinker общий. Каждый, кто может войти в реалм, работает с одним и тем же аккаунтом BaseLinker. Остальные границы — см. SECURITY.md.

Справочник по конфигурации

Всё настраивается через переменные окружения; .env в корне пакета загружается автоматически.

Всегда

Транспорт

CLI-флаги имеют приоритет над этими.

OAuth — требуется при транспорте http

Списки принимают запятые или пробелы.

Устранение неполадок

Больше случаев, специфичных для OAuth, — в deploy/README.md.

Разработка

npm run dev         # run from sources (tsx), stdio transport
npm run start:http  # built server, HTTP transport
npm test            # unit tests — fully offline, no live API calls
npm run check       # format check + typecheck + tests, what CI runs
npm run smoke       # manual smoke test against the live API (uses .env)
npm run inspect     # MCP Inspector against the built server

CONTRIBUTING.md описывает, как устроен реестр инструментов и на что обращать внимание при добавлении метода.

Лицензия

MIT. Не аффилирован с BaseLinker и не одобрен им.