RetailCRM plugin

Официальный плагин для работы с RetailCRM из OpenAI Codex и Claude Code. Позволяет подключать AI-агента к RetailCRM через MCP и помогает безопасно находить, проверять и выполнять GraphQL-запросы и мутации.

Один репозиторий, устанавливаемый и в OpenAI Codex, и в Claude Code, объединяет:

RetailCRM MCP server — удалённый MCP-сервер по адресу https://mcp.rcrm-tech.ru/mcp, предоставляющий инструменты для работы с API RetailCRM.
Skill use-retailcrm — инструкции для агента, которые помогают найти подходящие операции, получить необходимую часть схемы, построить и проверить GraphQL-документ, а затем безопасно выполнить его. Перед выполнением мутаций skill требует отдельного явного подтверждения пользователя.

MCP-сервер предоставляет инструменты и доступ к данным, а skill объясняет агенту, как корректно ими пользоваться.

Установка плагина

OpenAI Codex

Откройте File → Settings → Integrations → Plugins, нажмите Add → Add a marketplace и заполните форму:

Source: https://github.com/ilyavlasoff/RetailCRM-Plugin;
Git ref: main.

Нажмите Add marketplace. После добавления:

Откройте вкладку Personal в разделе Plugins.
Выберите Created by you → RetailCRM.
Нажмите Install Plugin, затем Try Now или создайте новый чат.

Marketplace также можно добавить из командной строки:

codex plugin marketplace add ilyavlasoff/RetailCRM-Plugin

Затем установите плагин:

codex plugin add retailcrm@retailcrm

Вместо второй команды можно открыть /plugins, выбрать marketplace retailcrm и установить плагин retailcrm интерактивно. После установки создайте новый тред.

Claude Code

Добавьте marketplace и установите плагин:

claude plugin marketplace add ilyavlasoff/RetailCRM-Plugin
claude plugin install retailcrm@retailcrm-plugin

После установки запустите новую сессию Claude Code, чтобы плагин стал доступен.

Установка плагина не требует OAuth-входа. Для обращения к RetailCRM MCP необходимо отдельно настроить персональный токен.

Аутентификация и подключение MCP

Получение персонального токена

Откройте страницу создания токена в системе:
```
https://<домен-вашей-системы>/profile/access-tokens/new
```
Укажите название токена, например Codex — работа с CRM или Claude Code — работа с CRM.
При необходимости задайте срок действия.
Выдайте только те права, которые нужны для планируемых операций через MCP.
Нажмите Сохранить и скопируйте токен. После создания он показывается только один раз.

Используйте отдельный токен с минимально необходимыми правами. Не добавляйте значение токена в репозиторий, конфигурационные файлы или сообщения агенту.

Сохраните токен в переменной окружения до запуска OpenAI Codex или Claude Code:

export RETAILCRM_TOKEN="ваш-персональный-токен"

Для текущей сессии PowerShell:

$env:RETAILCRM_TOKEN = "ваш-персональный-токен"

OpenAI Codex

Добавьте сервер в ~/.codex/config.toml:

[mcp_servers.retailcrm_mcp]
url = "https://mcp.rcrm-tech.ru/mcp"
bearer_token_env_var = "RETAILCRM_TOKEN"
enabled = true
enabled_tools = [
  "GqlSearchOperations",
  "GqlDescribeOperations",
  "GqlDescribeTypes",
  "GqlExecuteOperation",
]

Перезапустите Codex и проверьте подключение командой /mcp.

Claude Code

Создайте или дополните файл .mcp.json в корне проекта:

{
  "mcpServers": {
    "retailcrm_mcp": {
      "type": "http",
      "url": "https://mcp.rcrm-tech.ru/mcp",
      "headers": {
        "Authorization": "Bearer ${RETAILCRM_TOKEN}"
      }
    }
  }
}

Перезапустите Claude Code и проверьте подключение командой /mcp. В репозиторий можно добавлять конфигурацию со ссылкой на переменную окружения, но не само значение токена.

Standalone-подключение MCP

RetailCRM MCP можно использовать без установки плагина:

Получите персональный токен и сохраните его в RETAILCRM_TOKEN, как описано выше.

Добавьте сервер в OpenAI Codex:

codex mcp add retailcrm_mcp \
  --url https://mcp.rcrm-tech.ru/mcp \
  --bearer-token-env-var RETAILCRM_TOKEN

Добавьте сервер в Claude Code:

claude mcp add --transport http retailcrm_mcp https://mcp.rcrm-tech.ru/mcp \
  --header 'Authorization: Bearer ${RETAILCRM_TOKEN}'

Перезапустите клиент и проверьте доступность retailcrm_mcp через /mcp.

В standalone-режиме инструменты MCP будут доступны, но skill use-retailcrm и его правила построения, проверки и безопасного выполнения операций установлены не будут.

Что внутри

RetailCRM-Plugin/
├── .agents/plugins/marketplace.json      # Marketplace для OpenAI Codex
├── .codex-plugin/plugin.json             # Манифест плагина OpenAI Codex
├── .claude-plugin/
│   ├── marketplace.json                  # Marketplace для Claude Code
│   └── plugin.json                       # Манифест плагина Claude Code
├── assets/
│   ├── logo.svg                           # Логотип плагина
│   └── composer-icon.svg                  # Иконка в composer
├── skills/use-retailcrm/
│   ├── SKILL.md                           # Основной рабочий процесс
│   ├── agents/openai.yaml                 # Метаданные скилла для OpenAI Codex
│   └── references/
│       ├── list-operations.md             # Работа со списками и пагинацией
│       ├── mutations.md                   # Подтверждение и выполнение изменений
│       ├── repeated-queries.md            # Повторный запуск запросов с переменными
│       └── schema-resolution.md           # Выборочное раскрытие типов GraphQL
├── plugin.json                            # Общий манифест Agent Plugins
└── LICENSE

Лицензия

Проект распространяется по лицензии MIT.