rtx3/exray-kit

exray

exray ist ein entfernter MCP-Server, der Webseiten rendert und es Ihnen ermöglicht, Ihren eigenen TypeScript-Scraping- und Extraktionscode als wiederverwendbare, benannte Werkzeuge zu registrieren.

Sie führen exray weder aus noch installieren es. Es ist ein gehosteter Dienst unter https://mcp.exray.dev/mcp. Der Benutzer stellt ein Bearer-Token bereit; Sie rufen Werkzeuge über MCP auf.

Bevor Sie fortfahren: Ist es verbunden?

Wenn exray-Werkzeuge nicht in Ihrer Werkzeugliste sind, ist der MCP-Server nicht konfiguriert. Teilen Sie dem Benutzer mit:

1. Melden Sie sich unter https://app.exray.dev/sign-in an – die Seite /welcome stellt ein Token aus (wird genau einmal angezeigt)
2. Fügen Sie den Server zu Ihrem Client hinzu – die Konfiguration finden Sie unter https://docs.exray.dev/docs/mcp-clients
3. Starten Sie den Client neu – die MCP-Konfiguration wird beim Start gelesen

Versuchen Sie nicht, eine fehlende Verbindung durch Scraping mit fetch oder Shell-Werkzeugen zu umgehen. Sagen Sie, was fehlt, und brechen Sie ab.

Werkzeugauswahl

Situation	Werkzeug
Eine Seite, Inhalt gewünscht	scrape
Eine Seite, bestimmte Felder gewünscht	extract mit einem flachen Schema
Viele Seiten unter einer Website	crawl, dann get_crawl_results
Dieselbe Extraktion wiederholt oder Logik zu komplex für ein flaches Schema	define_extractor schreiben
Seite benötigt Klicks/Scrollen vor dem Rendern	define_fetcher schreiben
Benutzer möchte die Ergebnisse ansehen	define_handler schreiben (Ergebnisseite)

Greifen Sie zuerst zu scrape / extract. Schreiben Sie nur Code, wenn ein integriertes Werkzeug wirklich nicht ausdrücken kann, was benötigt wird – ein registriertes Asset ist etwas, das der Benutzer dann warten muss.

Nur flache Schemas

extract akzeptiert genau vier Typen: string, number, boolean, string[]. Keine Verschachtelung.

{ "title": "string", "price": "number", "tags": "string[]" }

Verschachtelte oder bedingte Formen erfordern stattdessen einen define_extractor.

Schreiben von Code-Assets

Drei Arten, alle in TypeScript, alle statisch validiert, bevor sie akzeptiert werden:

• fetcher – Einstieg fetch(ctx), steuert den Browser, gibt ein PageSnapshot zurück
• extractor – Einstieg extract(snapshot, ctx?), wandelt ein Snapshot in JSON um
• handler – Einstieg handle(request, ctx), stellt eine öffentliche Webseite bereit

Harte Einschränkungen – Code, der dagegen verstößt, wird bei der Registrierung abgelehnt:

• Der einzige erlaubte Import ist import type von @exray/exray-api. Keine Laufzeitimporte. Wenn Sie DOM-Abfragen benötigen, arbeiten Sie mit snapshot.html und String-Manipulation oder führen Sie die DOM-Arbeit in einem Fetcher über ctx.page.evaluate() durch.
• Kein eval / new Function, keine Nebenwirkungen auf oberster Ebene
• Kein Netzwerkzugriff aus der Sandbox

Die Registrierung belässt das Asset im Status draft – es kann noch nicht ausgeführt werden. Rufen Sie publish_definition auf, bevor Sie es verwenden. Das passiert ständig; melden Sie keinen Erfolg nach define_* allein.

Ergebnisseiten – lesen Sie next_action und handeln Sie danach

Wenn Sie einen handler veröffentlichen, enthält die Antwort ein site-Objekt. Eine erfolgreiche Veröffentlichung bedeutet nicht, dass die Seite erreichbar ist. Lesen Sie immer site.next_action und teilen Sie dem Benutzer mit, was genau noch fehlt:

next_action	Was Sie dem Benutzer sagen
set_username	"Legen Sie einen Benutzernamen unter app.exray.dev/settings/profile fest – die Adresse ist <username>-<project>.exray.app"
enable_site	"Ihre Seite wird unter <site.url> sein. Aktivieren Sie sie: exray site enable oder im Dashboard."
shorten_slug	"<username>-<slug> ist über 63 Bytes. Verwenden Sie einen kürzeren Projekt-Slug."
contact_support	Ein serverseitiges Konfigurationsproblem; melden Sie es als solches
null	Sie ist live unter site.url – geben Sie dem Benutzer den Link

Beenden Sie die Veröffentlichung eines Handlers niemals, ohne zu sagen, wo die Seite ist oder was sie blockiert. Der Benutzer hat keine andere Möglichkeit, dies herauszufinden, und "erfolgreich veröffentlicht" wird als "es ist fertig" verstanden.

Was ein Handler kann und nicht kann:

• Kann die Auftragsdaten dieses Projekts über ctx.data lesen (Aufträge auflisten, ein Ergebnis abrufen), HTML oder JSON zurückgeben, nach Pfad routen
• Kann nichts speichern, das Netzwerk erreichen, Formularübermittlungen akzeptieren oder Daten anderer Projekte lesen

Es ist eine Präsentationsschicht, kein Backend.

Speicherbindungen

Agent-Code hat standardmäßig keine Persistenz. Wenn Bindungen für das Projekt aktiviert sind, erhalten Fetcher ctx.kv / ctx.db / ctx.storage; Extractor erhalten nur ctx.kv; Handler erhalten alle drei schreibgeschützt.

Wenn ein Aufruf binding_not_enabled auslöst, ist die Bindung nicht aktiviert – das erfordert ein Admin-Token (exray bindings set --kv on). Teilen Sie es dem Benutzer mit; Sie können es nicht selbst aktivieren.

Erkennenswerte Fehler

Fehler	Bedeutung
403 forbidden	Dem Token fehlt ein Bereich. Ausführung benötigt tools.execute, Registrierung benötigt tools.define, Veröffentlichung benötigt tools.publish, Kontofunktionen benötigen admin
402	Monatliches Kontingent erschöpft. Stoppen und den Benutzer informieren
definition_incompatible_api	Das Asset wurde gegen eine andere Hauptversion von @exray/exray-api kompiliert. Erneut registrieren
extractor_invalid / fetcher_invalid	Statische Validierung hat den Code abgelehnt – normalerweise ein Laufzeitimport oder eine Nebenwirkung auf oberster Ebene
binding_not_enabled	Siehe Speicherbindungen oben
concurrent_exceeded	Zu viele gleichzeitige Aufrufe. Warten; nicht in einer engen Schleife wiederholen

Bei budget_exceeded oder 402: Stoppen. Wiederholungen verbrauchen das Kontingent des Benutzers ohne Fortschritt.

Bereiche

Ein erster Scrape-Workflow benötigt nur tools.read + tools.execute. Registrieren und Veröffentlichen benötigen tools.define / tools.publish. Alles, was das Konto betrifft – Token ausstellen, Ergebnisseiten aktivieren, Bindungen umschalten – benötigt admin und ist Aufgabe des Benutzers, nicht Ihre.

Vollständige Dokumentation

https://docs.exray.dev – Schnellstart, Client-Konfigurationen, CLI-Referenz, Ergebnisseiten, Werkzeugparameter und der Extractor-Vertrag.