exray
exray est un serveur MCP distant qui rend des pages web et vous permet d'enregistrer votre propre code TypeScript de scraping et d'extraction sous forme d'outils nommés réutilisables.
Vous n'exécutez ni n'installez exray. C'est un service hébergé à l'adresse https://mcp.exray.dev/mcp.
L'utilisateur fournit un jeton porteur ; vous appelez les outils via MCP.
Avant toute chose : est-ce connecté ?
Si les outils exray ne sont pas dans votre liste d'outils, le serveur MCP n'est pas configuré. Dites à l'utilisateur de :
- S'inscrire sur
https://app.exray.dev/sign-in— la page/welcomeémet un jeton (affiché une seule fois) - Ajouter le serveur à son client — la configuration se trouve sur https://docs.exray.dev/docs/mcp-clients
- Redémarrer le client — la configuration MCP est lue au démarrage
N'essayez pas de contourner une connexion manquante en scrapant avec fetch ou des outils shell.
Dites ce qui manque et arrêtez-vous.
Choisir un outil
| Situation | Outil |
|---|---|
| Une page, on veut le contenu | scrape |
| Une page, on veut des champs spécifiques | extract avec un schéma plat |
| Plusieurs pages sous un site | crawl, puis get_crawl_results |
| La même extraction de manière répétée, ou logique trop complexe pour un schéma plat | écrire un define_extractor |
| La page a besoin de clics/défilement avant de s'afficher | écrire un define_fetcher |
| L'utilisateur veut voir les résultats | écrire un define_handler (page de résultats) |
Utilisez scrape / extract en premier. N'écrivez du code que lorsqu'un outil intégré ne peut
très clairement pas exprimer ce qui est nécessaire — un asset enregistré est quelque chose que l'utilisateur devra ensuite maintenir.
Schémas plats uniquement
extract accepte exactement quatre types : string, number, boolean, string[]. Pas d'imbrication.
{ "titre": "string", "prix": "number", "tags": "string[]" }
Les formes imbriquées ou conditionnelles nécessitent un define_extractor.
Écrire des assets de code
Trois types, tous en TypeScript, tous validés statiquement avant d'être acceptés :
- fetcher — point d'entrée
fetch(ctx), pilote le navigateur, renvoie unPageSnapshot - extractor — point d'entrée
extract(snapshot, ctx?), transforme un snapshot en JSON - handler — point d'entrée
handle(request, ctx), sert une page web publique
Contraintes strictes — le code qui les viole est rejeté lors de l'enregistrement :
- La seule importation autorisée est
import typedepuis@exray/exray-api. Pas d'importations runtime. Si vous avez besoin d'interroger le DOM, travaillez à partir desnapshot.htmlavec du traitement de chaîne, ou faites le travail DOM dans un fetcher viactx.page.evaluate(). - Pas de
eval/new Function, pas d'effets de bord au niveau racine - Pas d'accès réseau depuis l'intérieur du bac à sable
L'enregistrement laisse l'asset à l'état draft — il ne peut pas encore s'exécuter. Appelez publish_definition
avant d'essayer de l'utiliser. Cela piège constamment les gens ; ne signalez pas le succès après
define_* seul.
Pages de résultats — lisez next_action et agissez en conséquence
Lorsque vous publiez un handler, la réponse contient un objet site. Publier avec succès
ne signifie pas que la page est accessible. Lisez toujours site.next_action et dites à
l'utilisateur ce qui manque précisément :
next_action | Quoi dire à l'utilisateur |
|---|---|
set_username | "Définissez un nom d'utilisateur sur app.exray.dev/settings/profile — l'adresse sera <nom-utilisateur>-<projet>.exray.app" |
enable_site | "Votre page sera à <site.url>. Activez-la : exray site enable, ou dans le tableau de bord." |
shorten_slug | "<nom-utilisateur>-<slug> dépasse 63 octets. Utilisez un slug de projet plus court." |
contact_support | Un problème de configuration côté serveur ; signalez-le comme tel |
null | C'est en ligne à site.url — donnez le lien |
Ne terminez jamais une publication de handler sans dire où se trouve la page ou ce qui la bloque. L'utilisateur n'a aucun autre moyen de le savoir, et "publié avec succès" est interprété comme "c'est fini".
Ce qu'un handler peut et ne peut pas faire :
- Peut lire les données de tâche de ce projet via
ctx.data(lister les tâches, récupérer un résultat), renvoyer du HTML ou du JSON, router par chemin - Ne peut pas stocker quoi que ce soit, accéder au réseau, accepter des soumissions de formulaire, ni lire les données d'autres projets
C'est une couche de présentation, pas un backend.
Liaisons de stockage
Le code de l'agent n'a pas de persistance par défaut. Si les liaisons du projet sont activées, les fetchers reçoivent
ctx.kv / ctx.db / ctx.storage ; les extracteurs reçoivent ctx.kv uniquement ; les handlers reçoivent les trois
en lecture seule.
Si un appel lève binding_not_enabled, la liaison n'est pas activée — cela nécessite un jeton
administrateur (exray bindings set --kv on). Dites-le à l'utilisateur ; vous ne pouvez pas l'activer vous-même.
Erreurs à reconnaître
| Erreur | Signification |
|---|---|
403 forbidden | Le jeton manque d'une portée. L'exécution nécessite tools.execute, l'enregistrement nécessite tools.define, la publication nécessite tools.publish, les actions de compte nécessitent admin |
402 | Quota mensuel épuisé. Arrêtez-vous et dites-le à l'utilisateur |
definition_incompatible_api | L'asset a été compilé contre une version majeure différente de @exray/exray-api. Réenregistrez-le |
extractor_invalid / fetcher_invalid | La validation statique a rejeté le code — généralement une importation runtime ou un effet de bord au niveau racine |
binding_not_enabled | Voir liaisons de stockage ci-dessus |
concurrent_exceeded | Trop d'appels en vol. Attendez ; ne réessayez pas en boucle serrée |
En cas de budget_exceeded ou 402, arrêtez-vous. Réessayer consomme le quota de l'utilisateur sans progrès.
Portées
Un workflow de premier scraping nécessite seulement tools.read + tools.execute. L'enregistrement et la publication
nécessitent tools.define / tools.publish. Tout ce qui touche au compte — émettre des jetons,
activer des pages de résultats, basculer des liaisons — nécessite admin et c'est le travail de l'utilisateur, pas le vôtre.
Documentation complète
https://docs.exray.dev — guide de démarrage rapide, configurations client, référence CLI, pages de résultats, paramètres d'outils, et contrat d'extracteur.