ribbo-mcp

Сервер MCP (Model Context Protocol) от Ribbo. Подключает вашего ИИ-ассистента (Claude Desktop, Cursor и т.д.) к API рекуррентных платежей Ribbo и превращает его в оператора: ИИ начинает выполнять реальные действия — создавать и управлять подписками, проверять entitlements, возвращать платежи, списывать сразу и генерировать ссылки на оплату/продление.

Аутентификация по API key вашего тенанта (префикс bk_), который создаётся в панели в разделе Разработчики → API keys. Сервер — это тонкий клиент публичного API: в коде нет секретов — вы передаёте свой ключ через переменную окружения.

Требования

• Node.js 18+

• API key Ribbo (bk_…). Используйте ключ с областью read, если нужно только запрашивать данные, или write, чтобы позволить ИИ действовать (возвраты, списания, отмены и т.д.).

Related MCP server: Agent Billy MCP Server

Установка

Самый быстрый способ — без клонирования — указать вашему ИИ-клиенту на пакет через npx. Чтобы проверить в терминале:

# direto do GitHub (funciona já):
npx -y github:andrespadeto/ribbo-mcp

# ou, depois de publicado no npm:
npx -y ribbo-mcp

Он остаётся ожидать в stdio — так работает MCP-сервер. С ним «общается» ваш ИИ-клиент (ниже), а не терминал. Для выхода: Ctrl+C.

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

Две переменные окружения:

Claude Desktop

В claude_desktop_config.json (меню → Настройки → Разработчик → Изменить конфигурацию):

{
  "mcpServers": {
    "ribbo": {
      "command": "npx",
      "args": ["-y", "github:andrespadeto/ribbo-mcp"],
      "env": {
        "RIBBO_API_KEY": "bk_sua_chave_aqui",
        "RIBBO_API_BASE": "https://api.ribbo.app"
      }
    }
  }
}

Перезапустите Claude Desktop. Инструменты Ribbo появятся в наборе инструментов в чате.

Cursor

В .cursor/mcp.json (в проекте) или в глобальных настройках MCP используйте тот же блок mcpServers, что и выше.

После публикации в npm замените "github:andrespadeto/ribbo-mcp" на "ribbo-mcp".

Инструменты

Чтение (достаточно ключа read):

Запись (требуется ключ write — перемещает деньги/состояние):

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

• Ключ идентифицирует и изолирует ваш тенант — данные других тенантов никогда не доступны.

• Инструменты записи перемещают деньги/состояние (возврат, списание, отмена). Используйте ключ read, когда ИИ нужен только для запросов, и write — только когда нужно действовать.

• Ключ хранится в env MCP-клиента (на вашей машине) — обращайтесь с ним как с секретом; никогда не коммитьте его.

• Код открыт и не содержит секретов: все учётные данные поступают из окружения.

Соглашения API

Деньги в центах (целое число); ID с префиксами (sub_, cus_, pay_, ord_…); даты в ISO-8601 UTC. Ошибки приходят в виде Erro <status>: {…}. Полный контракт (OpenAPI 3.1) находится в GET {RIBBO_API_BASE}/v1/public/schema/.

Разработка

git clone https://github.com/andrespadeto/ribbo-mcp.git
cd ribbo-mcp
npm install          # o "prepare" compila o TypeScript para dist/
cp .env.example .env # preencha RIBBO_API_KEY e RIBBO_API_BASE
npm run dev          # build + start

• Исходный код в src/ (TypeScript ESM). src/index.ts регистрирует инструменты; src/api.ts — это HTTP-клиент (Bearer).

• Сборка (dist/) создаётся с помощью npm run build и не версионируется.

Лицензия

MIT © Ribbo