MCP-сервер Rakuraku Hanbai

Это MCP-сервер, который позволяет вызывать следующие API из «пользовательских коннекторов» Claude на основе руководства по интеграции API Rakuraku Hanbai (RAKUS) (февраль 2025 г., 15-е издание):

• Загрузка файла / импорт CSV-файла / импорт CSV-данных / проверка статуса импорта CSV / экспорт CSV

• Регистрация / обновление / удаление / просмотр записей

Предварительная подготовка (на стороне Rakuraku Hanbai)

1. Обязательны контракт на опцию интеграции API + настройка ограничения доступа по IP (главы 1 и 5 руководства). Разрешите исходный IP-адрес сервера развёртывания в разделе «Настройки администратора» > вкладка «Настройки безопасности» > «Настройки, касающиеся ограничения доступа по IP». (На PaaS без фиксированного IP, таких как Render, может потребоваться использование аддона статического исходящего IP-адреса)

2. Выпустите и подтвердите API-токен на экране настроек пользователя (глава 3 руководства).

3. «dbSchemaId», «importId», «ID элементов» и т. д. для каждой БД можно проверить в разделе «Настройки администратора» > вкладка «Функции обслуживания» > «Информация о параметрах API».

Процедура развёртывания (Render, подробная версия)

Для тех, кто впервые пользуется PaaS, пошаговая инструкция от push в GitHub до подключения к Claude собрана в RENDER_DEPLOY.md. Сначала ознакомьтесь с ней. Поддерживается развёртывание Blueprint с использованием render.yaml.

Если кратко:

1. Запушьте эту папку в репозиторий GitHub

2. Создайте Web Service из Blueprint (render.yaml) в Render (план — starter или выше)

3. Задайте в переменных окружения RAKURAKU_DOMAIN / RAKURAKU_ACCOUNT / RAKURAKU_API_TOKEN / MCP_SHARED_SECRET

4. Включите «Static Outbound IP Addresses» на экране Settings и зарегистрируйте отображаемый фиксированный IP в ограничении доступа по IP Rakuraku Hanbai

5. Зарегистрируйте https://<место развёртывания>.onrender.com/mcp как URL коннектора Claude

На платформах, отличных от Render (Railway / Fly.io / собственный VPS + PM2 и т. д.), развёртывание можно выполнить аналогичным образом, если среда поддерживает Node.js 18 или выше.

Настройка коннектора на стороне Claude

1. Откройте «Добавить пользовательский коннектор» на экране настроек Claude.ai.

2. Заполните каждый пункт.

   • Имя: произвольное (например, Rakuraku Hanbai)

   • URL удалённого MCP-сервера: https://<место развёртывания>/mcp

   • OAuth Client ID / Secret: можно оставить пустыми (этот сервер использует простой способ общего секрета)

3. Если задан MCP_SHARED_SECRET, настройте коннектор так, чтобы он мог отправлять заголовок Authorization: Bearer <MCP_SHARED_SECRET> (в текущем интерфейсе пользовательских коннекторов Claude.ai дополнительные заголовки иногда нельзя указать напрямую. В таком случае либо работайте с пустым MCP_SHARED_SECRET, либо защитите сервер ограничением доступа по IP или собственным промежуточным ПО аутентификации).

4. Нажмите «Добавить», чтобы подключиться.

Локальная проверка работы

npm install
cp .env.example .env
# .env を編集して RAKURAKU_DOMAIN / RAKURAKU_ACCOUNT / RAKURAKU_API_TOKEN を設定
npm start

Проверка связи из другого терминала:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Список предоставляемых инструментов

Примечания

• ID элементов (например, «105110»), указываемые в values для API регистрации/обновления записей и т. п., различаются для каждой БД. Заранее проверьте их на экране «Информация о параметрах API» и сообщите Claude «ID элементов для этой БД — такие-то», прежде чем просить выполнить операции.

• API Rakuraku Hanbai имеет ограничение 20 запросов в минуту (глава 5 руководства). Будьте осторожны при работе с большими объёмами данных.

• Не передавайте RAKURAKU_API_TOKEN третьим лицам. Рекомендуется использовать функцию переменных окружения (Secret) места развёртывания и не записывать токен непосредственно в код или Git-репозиторий.