random-mcp

Ein MCP-Server (Model Context Protocol) zur Zufallszahlengenerierung, der auf Cloudflare Workers läuft. Von MCP-Clients wie Notion Agent können ganze Zahlen, Gleitkommazahlen, gewichtete Auswahlen und Stichproben verschiedener Wahrscheinlichkeitsverteilungen generiert werden.

Zweck

Ziel ist es, das Sprachmodell nicht selbst Zufallszahlen wählen zu lassen, sondern die externe Zufallszahlengenerierung als MCP-Tool aufrufbar zu machen.

Wenn man die Auswahl von Zufallszahlen dem Sprachmodell überlässt, beeinflussen die Trainingsdaten und Ausgabetendenzen des Modells das Ergebnis, wodurch statistisch verzerrte Werte erzeugt werden. Wenn man beispielsweise anweist, „wähle zufällig eine ganze Zahl von 1 bis 10", neigt das Modell dazu, bestimmte Werte (wie 7) zu bevorzugen, was im eigentlichen Sinne keine Zufallszahl ist. Daher müssen Prozesse, die Zufallszahlen benötigen, nicht durch autonome Entscheidungen des Modells, sondern über die Tools dieses Servers generiert werden.

Als Zufallsquelle wird die Web Crypto API verwendet. Bei der Ganzzahlgenerierung wird Rejection Sampling durchgeführt, um Verzerrungen durch den Restwert zu vermeiden. Diese API ist jedoch nicht für die Erzeugung von Verschlüsselungsschlüsseln oder Authentifizierungstokens gedacht.

Related MCP server: Universal MCP Server

Verwendung

Verbindung zu Notion AI

1. Wählen Sie Settings > Connections > MCP > Custom MCP

2. Geben Sie in der MCP server URL die bereitgestellte URL an (bestehender Dienst: https://random-mcp.eldesh-tools.workers.dev/mcp)

3. Füllen Sie die einzelnen Felder wie folgt aus und klicken Sie auf Connect

   • Name: Name zur Identifizierung in Notion (z. B. random-mcp)

   • Authentication: OAuth

4. Wählen Sie im Berechtigungsbildschirm Approve

5. Melden Sie sich bei GitHub an und schließen Sie die Authentifizierung über die GitHub OAuth App ab

6. Sobald die Tools angezeigt werden, aktivieren Sie die benötigten Tools

7. Wenn Sie möchten, dass Notion AI die Tools ohne Bestätigung bei jeder Ausführung aufruft, ändern Sie die Ausführungseinstellung auf Run automatically

Anweisungen an den Agent

Fügen Sie den Anweisungen des Agents beispielsweise Folgendes hinzu, damit bei zufälligen Auswahlen immer random-mcp verwendet wird.

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

Authentifizierung

Der Server akzeptiert Streamable-HTTP-Verbindungen unter /mcp. Für die Autorisierung mit MCP-Clients wird OAuth 2.1 verwendet, für die Authentifizierung der Benutzer GitHub OAuth.

Bei der Autorisierung wird nach der Anzeige des Berechtigungsbildschirms des MCP-Clients zum GitHub-Authentifizierungsbildschirm weitergeleitet. Die von GitHub angeforderte Berechtigung ist read:user. Autorisierten MCP-Clients wird ein Zugriffstoken mit dem Scope mcp:use ausgestellt.

Tools

random-mcp umfasst die folgenden vier Tools, die jeweils ein JSON-Objekt mit den angegebenen Feldern erfordern.

random_int

Generiert eine ganze Zahl innerhalb des angegebenen Bereichs.

• min: Mindestwert

• max: Höchstwert

Beispiel für Argumente: {"min": 5, "max": 10}

random_double

Generiert eine Gleitkommazahl innerhalb des angegebenen Bereichs.

• min: Mindestwert

• max: Höchstwert

Beispiel für Argumente: {"min": 1.41421, "max": 3.14159}

random_choice

Wählt ein Element aus den Kandidaten aus.

• choices: Array von Kandidatenzeichenfolgen. Mindestens 1 und höchstens 1.000

• weights: Relative Gewichte der einzelnen Kandidaten. Bei Weglassen gleichwahrscheinlich

Wenn weights angegeben wird, muss die Elementanzahl mit choices übereinstimmen und mindestens ein Wert positiv sein.

Beispiel für Argumente: {"choices":["A","B","C"],"weights":[1,2,1]}

random_sample

Generiert mehrere Stichproben aus der angegebenen Wahrscheinlichkeitsverteilung.

• distribution: Name der Wahrscheinlichkeitsverteilung

• parameters: Feldname für die Parameter der jeweiligen Verteilung

• count: Anzahl der Stichproben. Mindestens 1 und höchstens 100, Standardwert ist 1

Es gibt zusätzliche Rechenaufwand-Beschränkungen.

• Binomialverteilung: trials ist eine sichere ganze Zahl zwischen 0 und 100.000, mit trials * count <= 100000

• Poisson-Verteilung: lambda liegt zwischen 0 und 100, mit lambda * count <= 10000

Beispiel für Argumente: {"distribution":"uniform","parameters":{"min":5,"max":15},"count":3}

Entwicklungsumgebung

• Node.js 22.19.0 oder höher

• npm

• GitHub-Konto

• Cloudflare-Konto (für die Bereitstellung)

Installieren Sie die Abhängigkeiten.

npm install

Lokale Entwicklung

Erstellen einer GitHub OAuth App

Erstellen Sie eine OAuth App in den GitHub Developer settings. Da sich die Callback-URL zwischen lokaler und Produktionsumgebung unterscheidet, erstellen Sie jeweils eine separate OAuth App.

Legen Sie für die lokale Entwicklungs-OAuth App die folgenden Werte fest.

• Homepage URL: http://localhost:8787

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

Ersetzen Sie bei der Produktions-OAuth App http://localhost:8787 durch den Ursprung des Ziel-Workers. Die Callback-URL des bestehenden Dienstes lautet https://random-mcp.eldesh-tools.workers.dev/callback.

Nach der Erstellung erhalten Sie die Client ID und das Client secret. Der von dieser Anwendung angeforderte OAuth-Scope bei GitHub ist read:user.

Umgebungsvariablen

Erstellen Sie .dev.vars im Projektverzeichnis.

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

COOKIE_ENCRYPTION_KEY kann beispielsweise mit dem folgenden Befehl generiert werden.

openssl rand -hex 32

Der temporäre OAuth-State wird in der Cloudflare-KV gespeichert, die über die OAUTH_KV-Bindung in wrangler.jsonc angegeben ist. Wenn Sie in ein anderes Cloudflare-Konto bereitstellen, erstellen Sie einen KV-Namespace und ersetzen Sie die id in wrangler.jsonc durch die Namespace-ID.

Start

Starten Sie den lokalen Server.

npm run dev

Normalerweise lautet der MCP-Endpunkt wie folgt.

http://localhost:8787/mcp

[!NOTE] Auch wenn Wrangler eine Warnung anzeigt, dass Request.cf nicht abgerufen werden kann, wird am Ende Ready on http://localhost:8787 angezeigt, und solange dieses Projekt Request.cf nicht verwendet, können Sie mit der Funktionsprüfung fortfahren.

Funktionsprüfung mit MCP Inspector

Starten Sie bei laufendem lokalen Server die Web-UI des MCP Inspectors.

npx --yes @modelcontextprotocol/inspector@latest

Wählen Sie im Inspector Streamable HTTP und geben Sie als Verbindungsziel http://localhost:8787/mcp an. Beim Verbinden wird im Browser der OAuth-Autorisierungsfluss gestartet. Erlauben Sie daher den Zugriff und schließen Sie die GitHub-Authentifizierung ab. Wenn Sie die Produktionsumgebung prüfen möchten, ändern Sie das Verbindungsziel auf die bereitgestellte MCP-URL.

Nach der Verbindung prüfen Sie, ob auf dem Tools-Bildschirm die unter Tools aufgeführten Elemente angezeigt werden.

Bereitstellung auf Cloudflare Workers

Melden Sie sich bei Cloudflare an.

npx wrangler login

Registrieren Sie die Anmeldeinformationen der Produktions-GitHub OAuth App und den Cookie-Verschlüsselungsschlüssel als Cloudflare Secret.

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

Stellen Sie sicher, dass die Authorization callback URL der GitHub OAuth App auf /callback des Ziel-Workers zeigt und dass OAUTH_KV in wrangler.jsonc auf einen verfügbaren KV-Namespace verweist.

Stellen Sie bereit.

npm run deploy

Die öffentliche URL hat normalerweise das folgende Format.

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

[!IMPORTANT] .dev.vars wird nicht automatisch an Cloudflare übertragen. Der Produktions-Worker referenziert die in Cloudflare Secret registrierten Werte.

Lizenz

Dieses Projekt ist unter der MIT License veröffentlicht.