random-mcp

Servidor MCP (Model Context Protocol) para generación de números aleatorios que se ejecuta en Cloudflare Workers. Permite generar enteros, números de coma flotante, selecciones ponderadas y muestras de diversas distribuciones de probabilidad desde clientes MCP como Notion Agent.

Propósito

El objetivo es no dejar que el propio modelo de lenguaje elija los números aleatorios, sino permitir invocar un proceso externo de generación de números aleatorios como herramienta MCP.

Si se delega la elección de números aleatorios al modelo de lenguaje, los datos de entrenamiento y las tendencias de salida del modelo influyen en el resultado, generando valores estadísticamente sesgados. Por ejemplo, aunque se le indique «elige un entero aleatorio del 1 al 10», el modelo tiende a preferir valores concretos (como el 7), por lo que no produce números aleatorios en el sentido estricto. Por esta razón, los procesos que requieren números aleatorios deben generarse a través de las herramientas de este servidor, y no mediante el juicio autónomo del modelo.

Como fuente de aleatoriedad se utiliza la Web Crypto API. En la generación de enteros se aplica rejection sampling para evitar el sesgo por residuo. No obstante, esta API no está pensada para la generación de claves criptográficas ni tokens de autenticación.

Related MCP server: Universal MCP Server

Uso

Conexión a Notion AI

1. Seleccione Settings > Connections > MCP > Custom MCP

2. Especifique la URL desplegada en MCP server URL (servicio existente: https://random-mcp.eldesh-tools.workers.dev/mcp)

3. Rellene cada campo de la siguiente manera y pulse Connect

   • Name: nombre para identificar dentro de Notion (p. ej. random-mcp)

   • Authentication: OAuth

4. Seleccione Approve en la pantalla de permiso de acceso

5. Inicie sesión en GitHub y complete la autenticación mediante la GitHub OAuth App

6. Cuando aparezcan las herramientas, active las que necesite

7. Si desea invocarlas desde Notion AI sin confirmación en cada ejecución, cambie la configuración de ejecución a Run automatically

Instrucciones al Agent

Añada, por ejemplo, lo siguiente a las instrucciones del Agent para que random-mcp se utilice siempre que se necesite una elección aleatoria.

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

Autenticación

El servidor acepta conexiones Streamable HTTP en /mcp. Para la autorización con el cliente MCP se utiliza OAuth 2.1, y para la autenticación del usuario, GitHub OAuth.

En la autorización, tras mostrar la pantalla de permiso de acceso del cliente MCP, se redirige a la pantalla de autenticación de GitHub. El permiso que se obtiene de GitHub es read:user. A los clientes MCP autorizados se les emite un token de acceso con el ámbito mcp:use.

Herramientas

random-mcp dispone de las 4 herramientas que se indican a continuación, cada una de las cuales requiere un objeto JSON con los campos especificados.

random_int

Genera un entero dentro del rango especificado.

• min: valor mínimo

• max: valor máximo

Ejemplo de argumentos: {"min": 5, "max": 10}

random_double

Genera un número de coma flotante dentro del rango especificado.

• min: valor mínimo

• max: valor máximo

Ejemplo de argumentos: {"min": 1.41421, "max": 3.14159}

random_choice

Selecciona un elemento de entre los candidatos.

• choices: matriz de cadenas candidatas. Entre 1 y 1.000 elementos

• weights: peso relativo de cada candidato. Si se omite, probabilidad uniforme

Si se especifica weights, debe coincidir en número de elementos con choices y al menos uno debe ser un valor positivo.

Ejemplo de argumentos: {"choices":["A","B","C"],"weights":[1,2,1]}

random_sample

Genera varias muestras a partir de la distribución de probabilidad especificada.

• distribution: nombre de la distribución de probabilidad

• parameters: nombre del campo que recibe los parámetros según la distribución

• count: número de muestras. Entre 1 y 100, valor predeterminado 1

Existen restricciones adicionales de coste computacional.

• Distribución binomial: trials debe ser un entero seguro entre 0 y 100.000, y trials * count <= 100000

• Distribución de Poisson: lambda debe estar entre 0 y 100, y lambda * count <= 10000

Ejemplo de argumentos: {"distribution":"uniform","parameters":{"min":5,"max":15},"count":3}

Entorno de desarrollo

• Node.js 22.19.0 o superior

• npm

• Cuenta de GitHub

• Cuenta de Cloudflare (para desplegar)

Instale las dependencias.

npm install

Desarrollo local

Creación de la GitHub OAuth App

Cree una OAuth App en GitHub Developer settings. Dado que la URL de callback difiere entre el entorno local y el de producción, cree una OAuth App distinta para cada uno.

Para la OAuth App de desarrollo local, configure los siguientes valores.

• Homepage URL: http://localhost:8787

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

En la OAuth App de producción, sustituya http://localhost:8787 por el origen del Worker donde se despliegue. La URL de callback del servicio existente es https://random-mcp.eldesh-tools.workers.dev/callback.

Tras crearla, obtenga el Client ID y el Client secret. El ámbito OAuth que esta aplicación solicita a GitHub es read:user.

Variables de entorno

Cree .dev.vars en la raíz del proyecto.

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

COOKIE_ENCRYPTION_KEY puede generarse, por ejemplo, con el siguiente comando.

openssl rand -hex 32

El state temporal de OAuth se guarda en el Cloudflare KV especificado en el binding OAUTH_KV de wrangler.jsonc. Si despliega en otra cuenta de Cloudflare, cree un KV namespace y sustituya el id de wrangler.jsonc por el ID de ese namespace.

Inicio

Inicie el servidor local.

npm run dev

Normalmente, el endpoint MCP será la siguiente URL.

http://localhost:8787/mcp

[!NOTE] Aunque Wrangler muestre una advertencia de que no puede obtener Request.cf, si al final aparece Ready on http://localhost:8787 y este proyecto no utiliza Request.cf, puede continuar con la comprobación de funcionamiento.

Comprobación de funcionamiento con MCP Inspector

Con el servidor local iniciado, abra la interfaz web de MCP Inspector.

npx --yes @modelcontextprotocol/inspector@latest

En Inspector, seleccione Streamable HTTP y especifique http://localhost:8787/mcp como destino de conexión. Al conectar, se inicia el flujo de autorización OAuth en el navegador, por lo que debe permitir el acceso y completar la autenticación de GitHub. Para comprobar el entorno de producción, cambie el destino de conexión a la URL MCP ya desplegada.

Tras la conexión, compruebe que en la pantalla Tools aparecen las herramientas indicadas en Herramientas.

Despliegue en Cloudflare Workers

Inicie sesión en Cloudflare.

npx wrangler login

Registre las credenciales de la GitHub OAuth App de producción y la clave de cifrado de cookies como Cloudflare Secret.

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

Compruebe que la Authorization callback URL de la GitHub OAuth App apunta a /callback del Worker de destino y que OAUTH_KV de wrangler.jsonc apunta a un KV namespace disponible.

Despliegue.

npm run deploy

La URL pública suele tener el siguiente formato.

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

[!IMPORTANT] .dev.vars no se refleja automáticamente en Cloudflare. El Worker de producción hace referencia a los valores registrados en Cloudflare Secret.

Licencia

Se publica bajo la MIT License.