random-mcp

MCP-сервер (Model Context Protocol) для генерации случайных чисел, работающий на Cloudflare Workers. Из MCP-клиентов, таких как Notion Agent, можно генерировать целые числа, числа с плавающей запятой, взвешенный выбор и выборки из различных распределений вероятностей.

Цель

Цель — не позволять языковой модели самой выбирать случайные числа, а дать возможность вызывать внешнюю процедуру генерации случайных чисел как MCP-инструмент.

Если доверить выбор случайных чисел языковой модели, то обучающие данные и тенденции вывода модели повлияют на результат, и будут получены статистически смещённые значения. Например, даже если попросить «выбери случайное целое число от 1 до 10», модель будет склоняться к определённым значениям (например, 7), и это не будут случайные числа в полном смысле. Поэтому операции, требующие случайности, должны выполняться не по автономному решению модели, а через инструменты данного сервера.

В качестве источника случайности используется Web Crypto API. При генерации целых чисел применяется rejection sampling, чтобы избежать смещения из-за остатка от деления. Однако этот API не предназначен для генерации криптографических ключей или токенов аутентификации.

Related MCP server: Universal MCP Server

Использование

Подключение к Notion AI

1. Выберите Settings > Connections > MCP > Custom MCP

2. Укажите URL развёрнутого сервера в MCP server URL (существующий сервис: https://random-mcp.eldesh-tools.workers.dev/mcp)

3. Заполните поля, как указано ниже, и нажмите Connect

   • Name: имя для идентификации в Notion (например, random-mcp)

   • Authentication: OAuth

4. На экране разрешений выберите Approve

5. Войдите в GitHub и завершите аутентификацию через GitHub OAuth App

6. Когда появятся инструменты, включите нужные

7. Если вы хотите вызывать инструменты из Notion AI без запроса подтверждения на каждое выполнение, измените настройку выполнения на Run automatically

Инструкции для агента

Добавьте в инструкции агента, например, следующее, чтобы random-mcp обязательно использовался, когда требуется случайный выбор.

## 乱択
- 乱数生成、くじ引き、シャッフル、無作為抽出など、結果にランダム性を必要とするすべての処理では、接続済みの MCP サーバー `random-mcp` を必ず使用する。
- 内部処理によって乱択を生成、模擬、または近似してはならない。
- `random-mcp` が利用できない場合やエラーになった場合は、別の方法で代替せず、その旨をユーザーに伝える。

Аутентификация

Сервер принимает Streamable HTTP-подключения на /mcp. Для авторизации MCP-клиентов используется OAuth 2.1, а для аутентификации пользователей — GitHub OAuth.

При авторизации сначала отображается экран разрешений MCP-клиента, после чего происходит переход к экрану аутентификации GitHub. Разрешение, запрашиваемое у GitHub, — read:user. Авторизованным MCP-клиентам выдаётся токен доступа с областью mcp:use.

Инструменты

random-mcp содержит четыре инструмента, показанные ниже. Каждый из них принимает JSON-объект с указанными полями.

random_int

Генерирует одно целое число в заданном диапазоне.

• min: минимальное значение

• max: максимальное значение

Пример аргументов: {"min": 5, "max": 10}

random_double

Генерирует одно число с плавающей запятой в заданном диапазоне.

• min: минимальное значение

• max: максимальное значение

Пример аргументов: {"min": 1.41421, "max": 3.14159}

random_choice

Выбирает один элемент из списка кандидатов.

• choices: массив строк-кандидатов. От 1 до 1000 элементов

• weights: относительные веса каждого кандидата. Если не указано, вероятности равны

При указании weights количество элементов должно совпадать с choices, и хотя бы одно значение должно быть положительным.

Пример аргументов: {"choices":["A","B","C"],"weights":[1,2,1]}

random_sample

Генерирует несколько выборок из указанного распределения вероятностей.

• distribution: название распределения вероятностей

• parameters: имя поля, содержащего параметры для соответствующего распределения

• count: количество выборок. От 1 до 100, по умолчанию 1

Существуют дополнительные ограничения на объём вычислений.

• Биномиальное распределение: trials — безопасное целое число от 0 до 100 000, trials * count <= 100000

• Распределение Пуассона: lambda от 0 до 100, lambda * count <= 10000

Пример аргументов: {"distribution":"uniform","parameters":{"min":5,"max":15},"count":3}

Среда разработки

• Node.js 22.19.0 или выше

• npm

• учётная запись GitHub

• учётная запись Cloudflare (для развёртывания)

Установите зависимости.

npm install

Локальная разработка

Создание GitHub OAuth App

Создайте OAuth App в Developer settings на GitHub. Поскольку URL обратного вызова отличается в локальной среде и в продакшене, создайте отдельные OAuth App для каждой среды.

Для OAuth App, используемого в локальной разработке, задайте следующие значения.

• Homepage URL: http://localhost:8787

• Authorization callback URL: http://localhost:8787/callback

В продакшн OAuth App замените часть http://localhost:8787 на origin Worker, на который выполняется развёртывание. URL обратного вызова существующего сервиса: https://random-mcp.eldesh-tools.workers.dev/callback.

После создания получите Client ID и Client secret. OAuth-область, которую это приложение запрашивает у GitHub, — read:user.

Переменные окружения

Создайте .dev.vars в корне проекта.

GITHUB_CLIENT_ID=<GitHub OAuth App の Client ID>
GITHUB_CLIENT_SECRET=<GitHub OAuth App の Client secret>
COOKIE_ENCRYPTION_KEY=<Cookie の暗号化に使用するランダムな値>

COOKIE_ENCRYPTION_KEY можно сгенерировать, например, следующей командой.

openssl rand -hex 32

Временный state OAuth сохраняется в Cloudflare KV, указанном в привязке OAUTH_KV в wrangler.jsonc. При развёртывании в другом аккаунте Cloudflare создайте KV namespace и замените id в wrangler.jsonc на его namespace ID.

Запуск

Запустите локальный сервер.

npm run dev

Обычно MCP-эндпоинт доступен по следующему URL.

http://localhost:8787/mcp

[!NOTE] Даже если Wrangler выводит предупреждение о том, что не может получить Request.cf, в конце будет показано Ready on http://localhost:8787, и если этот проект не использует Request.cf, можно продолжить проверку.

Проверка работы с помощью MCP Inspector

При запущенном локальном сервере запустите веб-интерфейс MCP Inspector.

npx --yes @modelcontextprotocol/inspector@latest

В Inspector выберите Streamable HTTP и укажите http://localhost:8787/mcp в качестве адреса подключения. При подключении в браузере запускается процесс авторизации OAuth, поэтому разрешите доступ и завершите аутентификацию GitHub. Для проверки продакшена измените адрес подключения на URL развёрнутого MCP.

После подключения убедитесь, что на экране Tools отображаются инструменты, перечисленные в разделе Инструменты.

Развёртывание на Cloudflare Workers

Войдите в Cloudflare.

npx wrangler login

Зарегистрируйте учётные данные продакшн GitHub OAuth App и ключ шифрования Cookie как Cloudflare Secret.

npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY

Убедитесь, что Authorization callback URL GitHub OAuth App указывает на /callback Worker, на который выполняется развёртывание, и что OAUTH_KV в wrangler.jsonc указывает на доступный KV namespace.

Выполните развёртывание.

npm run deploy

Публичный URL обычно имеет следующий вид.

https://random-mcp.<subdomain>.workers.dev/mcp

[!IMPORTANT] .dev.vars не передаётся в Cloudflare автоматически. Продакшн Worker использует значения, зарегистрированные в Cloudflare Secret.

Лицензия

Опубликовано под лицензией MIT License.