@clicbase/mcp 0.1.2 → 0.2.0

package/README.md

@@ -18,6 +18,38 @@ Outils :
 - `enable_realtime` — active le temps réel sur une table.
 - `set_oauth_provider` — configure Google OAuth.
 - `set_email_smtp` — configure un SMTP (sinon SMTP interne Clicbase par défaut).
+- `list_site_files` — liste les fichiers d'un site heberge (nom, taille, date).
+- `read_site_file` — rend le contenu d'UN fichier, en base64 cote API, decode cote outil.
+- `clicbase_conventions` — les regles de la plateforme : policies RLS, droits, PostgREST.
+
+## Les fichiers d'un site
+
+Jusqu'a la 0.2.0, une cle pouvait ECRASER les fichiers d'un site sans pouvoir
+les lire : l'interdit etait pose du mauvais cote, puisque ecrire est
+strictement plus dangereux que lire. La seule issue etait un mot de passe SFTP,
+c'est-a-dire un secret durable colle dans une conversation pour contourner un
+endpoint absent.
+
+```
+list_site_files(site_id)               -> un niveau de la racine publique
+list_site_files(site_id, "assets")     -> on descend
+read_site_file(site_id, "index.html")  -> le contenu, decode
+```
+
+L'id du site vient de `GET /api/v1/admin/sites`.
+
+⚠️ `list_site_files` est une LECTURE, `read_site_file` est un SECRET. Le nom
+d'un fichier revele une structure ; son contenu peut porter des identifiants
+dans un `config.php` ou un `settings.js`. Le second disparait donc du mode
+restreint, comme `get_credentials`.
+
+⚠️ LES FICHIERS CACHES SONT HORS D'ATTEINTE, a tout niveau : `.env` comme
+`assets/.env`. Le serveur refuse tout segment commencant par un point, aussi
+bien au depot qu'a la lecture. Cette garde existait pour empecher qu'ils soient
+SERVIS par le serveur web ; elle protege exactement le bon flanc.
+
+Plafond : 2 Mo cote API, 256 Ko cote outil. Au-dela, le telechargement du
+tableau de bord ou le SFTP.
 
 ## Lecture seule
 

package/clicbase-mcp.mjs

@@ -38,10 +38,112 @@ if (!CLE) {
 const out = (d) => ({ content: [{ type: "text", text: typeof d === "string" ? d : JSON.stringify(d, null, 2) }] });
 const fail = (e) => ({ isError: true, content: [{ type: "text", text: String(e?.message ?? e) }] });
 
+// L'API de LECTURE des projets, derivee de celle de provisioning.
+const API_LECTURE = API.replace(/\/databases\/?$/, "/admin/projects");
+
+/**
+ * Traduit un statut HTTP en phrase utile.
+ *
+ * ⚠️ « Clicbase 403 » NE DIT RIEN, ET ON L'A VU COUTER UNE HEURE. Le
+ * 2026-09-17, une session a lu ce nombre, conclu que la cle etait morte, et
+ * cherche du mauvais cote. Mesure ensuite : la cle etait vivante, jamais
+ * revoquee, et cette route ne peut PAS repondre 403 (400 sans en-tete, 401 cle
+ * refusee, 429 debit, 500 provisioning). Le nombre seul envoie chercher au
+ * hasard.
+ */
+/**
+ * Lit une reponse en echec SANS PERDRE CE QU'ELLE CONTENAIT.
+ *
+ * ⚠️ `res.json().catch(() => ({}))` EFFACE LA PREUVE. Le 2026-09-17, une session
+ * a rapporte « Clicbase 403: {} » sur trois tentatives. Ce `{}` ne voulait pas
+ * dire « corps vide » : il voulait dire « corps ILLISIBLE en JSON », donc pas
+ * notre application, qui rend toujours un champ `error`. L'information qui
+ * aurait tranche en dix secondes, l'en-tete `cf-ray` et les premiers octets du
+ * corps, avait ete jetee par le `catch`.
+ *
+ * On garde donc : le statut, l'origine declaree par le serveur, l'identifiant
+ * Cloudflare s'il existe, et le debut du corps tel quel.
+ */
+async function lireEchec(res) {
+  const brut = await res.text().catch(() => "");
+  let json = null;
+  try {
+    json = JSON.parse(brut);
+  } catch {
+    /* pas du JSON : c'est precisement ce qu'on veut savoir */
+  }
+  const via = res.headers.get("cf-ray")
+    ? `Cloudflare (cf-ray ${res.headers.get("cf-ray")})`
+    : (res.headers.get("server") ?? "origine inconnue");
+  return {
+    json,
+    // ⚠️ UN CORPS NON-JSON EST LA SIGNATURE D'UN REFUS EN AMONT. On le dit en
+    // clair au lieu de rendre un objet vide qui ressemble a une reponse.
+    detail: json
+      ? JSON.stringify(json)
+      : brut.trim()
+        ? `reponse NON-JSON de ${via} : ${brut.replace(/\s+/g, " ").slice(0, 180)}`
+        : `corps vide, servi par ${via} — la requete n'a probablement pas atteint Clicbase.`,
+  };
+}
+
+function expliquer(statut) {
+  if (statut === 400) return "requete incomplete : le champ `name` est obligatoire.";
+  if (statut === 401)
+    return "cle refusee : invalide, expiree ou revoquee. Attention, le bouton « Rouler » du tableau de bord REMPLACE le secret : l'ancien meurt aussitot.";
+  if (statut === 403)
+    return "hors du perimetre de cette cle. Une cle de Docker ne voit que son Docker. Verifie sa portee sur /api/v1/admin/me.";
+  if (statut === 429) return "trop de requetes, attends une minute.";
+  if (statut === 500)
+    return "la plateforme a refuse l'operation. Les creations de projet sont actuellement fermees : un projet qui n'existe pas deja ne peut pas etre cree.";
+  return "reponse inattendue.";
+}
+
+/**
+ * Trouve un projet SANS RIEN CREER.
+ *
+ * ⚠️ IL ACCEPTE LE NOM **OU** LE SLUG, et c'est le coeur du correctif. Le
+ * projet « présidence » a pour slug `presidence` : un assistant qui tape le
+ * slug, ou qui perd l'accent en chemin, ne trouvait rien. Ici on cherche dans
+ * les deux, puis on rend le nom EXACT tel qu'il est en base.
+ */
+async function trouver(name) {
+  const res = await fetch(API_LECTURE, {
+    headers: { authorization: `Bearer ${CLE}` },
+  });
+  if (!res.ok) {
+    const e = await lireEchec(res);
+    throw new Error(`Clicbase ${res.status} — ${expliquer(res.status)} ${e.detail}`);
+  }
+  const data = await res.json().catch(() => ({}));
+  const liste = Array.isArray(data.projects) ? data.projects : [];
+  const cible = String(name).trim().toLowerCase();
+  const p =
+    liste.find((x) => String(x.name ?? "").toLowerCase() === cible) ??
+    liste.find((x) => String(x.slug ?? "").toLowerCase() === cible);
+  if (!p) {
+    const noms = liste.map((x) => x.slug ?? x.name).filter(Boolean).join(", ");
+    throw new Error(
+      `Aucun projet « ${name} » dans le perimetre de cette cle.` +
+        (noms ? ` Projets visibles : ${noms}.` : " Cette cle ne voit aucun projet."),
+    );
+  }
+  return p;
+}
+
 // Provisionne (ou récupère, idempotent) un projet et renvoie ses infos.
+//
+// ⚠️ `creer: false` POUR TOUT OUTIL DE LECTURE. Cet appel est un POST sur
+// l'endpoint de provisioning : idempotent quand le projet existe, CREATEUR
+// sinon. `list_tables` survit au mode lecture seule et passait par ici : la
+// promesse « aucune ecriture » etait donc fausse au niveau du transport, pendant
+// que `create_database` disparaissait de la liste des outils. On verifie
+// l'existence par une LECTURE d'abord, et on ne poste qu'un nom deja connu.
 const cache = new Map();
-async function resolve(name, domain) {
+async function resolve(name, domain, { creer = true } = {}) {
   if (cache.has(name)) return cache.get(name);
+  let nomExact = name;
+  if (!creer) nomExact = (await trouver(name)).name ?? name;
   const res = await fetch(API, {
     method: "POST",
     headers: {
@@ -49,10 +151,13 @@ async function resolve(name, domain) {
       // ⚠️ UNE CLE, PAS UN MOT DE PASSE. Voir l'en-tete du fichier.
       authorization: `Bearer ${CLE}`,
     },
-    body: JSON.stringify({ name, domain }),
+    body: JSON.stringify({ name: nomExact, domain }),
   });
+  if (!res.ok) {
+    const e = await lireEchec(res);
+    throw new Error(`Clicbase ${res.status} — ${expliquer(res.status)} ${e.detail}`);
+  }
   const data = await res.json().catch(() => ({}));
-  if (!res.ok) throw new Error(`Clicbase ${res.status}: ${JSON.stringify(data)}`);
   const info = {
     url: data.restApi?.url,
     anonKey: data.restApi?.anonKey,
@@ -65,8 +170,8 @@ async function resolve(name, domain) {
 }
 
 // Appel d'un endpoint du projet avec la clé service.
-async function call(name, path, method = "POST", body) {
-  const p = await resolve(name);
+async function call(name, path, method = "POST", body, opts) {
+  const p = await resolve(name, undefined, opts);
   if (!p.url || !p.serviceKey) throw new Error("Projet non résolu (clés manquantes).");
   const res = await fetch(`${p.url}${path}`, {
     method,
@@ -129,7 +234,20 @@ outils.tool(
   "Liste les tables du schéma public d'un projet.",
   { name: z.string() },
   async ({ name }) => {
-    try { return out(await call(name, "/sql", "POST", { query: "select table_name from information_schema.tables where table_schema='public' order by table_name" })); } catch (e) { return fail(e); }
+    try {
+      // ⚠️ `creer: false` : un outil de lecture ne provisionne jamais.
+      return out(
+        await call(
+          name,
+          "/sql",
+          "POST",
+          { query: "select table_name from information_schema.tables where table_schema='public' order by table_name" },
+          { creer: false },
+        ),
+      );
+    } catch (e) {
+      return fail(e);
+    }
   },
 );
 
@@ -156,6 +274,63 @@ outils.tool(
   async ({ name, ...cfg }) => { try { return out(await call(name, "/email/config", "POST", cfg)); } catch (e) { return fail(e); } },
 );
 
+// Les fichiers d'un site heberge. `admin` cible l'API d'administration, la ou
+// `call` parle a la base d'un projet : deux surfaces differentes.
+async function admin(chemin, methode = "GET") {
+  const base = API_LECTURE.replace(/\/projects$/, "");
+  const res = await fetch(`${base}${chemin}`, {
+    method: methode,
+    headers: { authorization: `Bearer ${CLE}` },
+  });
+  if (!res.ok) {
+    const e = await lireEchec(res);
+    throw new Error(`Clicbase ${res.status} — ${expliquer(res.status)} ${e.detail}`);
+  }
+  return res.json();
+}
+
+outils.tool(
+  "list_site_files",
+  "Liste les fichiers d'un site heberge (nom, dossier ou non, taille, date). `dossier` pour descendre d'un niveau. L'id du site vient de GET /sites.",
+  { site_id: z.string(), dossier: z.string().optional() },
+  async ({ site_id, dossier }) => {
+    try {
+      const q = dossier ? `?dossier=${encodeURIComponent(dossier)}` : "";
+      return out(await admin(`/sites/${encodeURIComponent(site_id)}/files${q}`));
+    } catch (e) {
+      return fail(e);
+    }
+  },
+);
+
+outils.tool(
+  "read_site_file",
+  "Rend le contenu d'UN fichier d'un site heberge, en base64. Plafond 2 Mo. Les fichiers caches (.env, .git) sont refuses par le serveur, a tout niveau.",
+  { site_id: z.string(), chemin: z.string() },
+  async ({ site_id, chemin }) => {
+    try {
+      const d = await admin(
+        `/sites/${encodeURIComponent(site_id)}/files?chemin=${encodeURIComponent(chemin)}`,
+      );
+      // ⚠️ ON DECODE ICI, ET ON PLAFONNE PLUS BAS QUE L'API. Rendre du base64 a
+      // un modele lui fait depenser son contexte a le decoder, souvent mal. Et
+      // 2 Mo de source dans une conversation ne servent personne : au-dela de
+      // 256 Ko on refuse en le disant, plutot que de noyer la session.
+      const brut = Buffer.from(String(d.contenu ?? ""), "base64");
+      if (brut.byteLength > 256 * 1024) {
+        return fail(
+          new Error(
+            `Fichier de ${brut.byteLength} octets : trop gros pour une conversation. Telecharge-le par le tableau de bord ou par SFTP.`,
+          ),
+        );
+      }
+      return out({ chemin: d.chemin, octets: d.octets, contenu: brut.toString("utf8") });
+    } catch (e) {
+      return fail(e);
+    }
+  },
+);
+
 // ⚠️ LE MODE RESTREINT S'ANNONCE, SUR LA SORTIE D'ERREUR. Un serveur qui
 // retire des outils en silence se decouvre en pleine session : l'assistant
 // cherche une fonction qui devrait exister, ne la trouve pas, et conclut que le

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clicbase/mcp",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "bin": {
     "mcp": "clicbase-mcp.mjs",

package/portee.mjs

@@ -48,6 +48,14 @@ export const OUTILS = {
   // restreint qui en a le plus besoin, puisqu'il ne reste alors que trois
   // outils et qu'un assistant doit deviner le reste.
   clicbase_conventions: "lecture",
+  // --- fichiers d'un site heberge ---
+  // ⚠️ LISTER EST UNE LECTURE, LIRE EST UN SECRET. Le nom et la taille d'un
+  // fichier revelent une structure ; son CONTENU peut porter des identifiants,
+  // dans un config.php ou un settings.js. Meme raisonnement que
+  // get_credentials : il ne modifie rien, et il rend quand meme les clefs de
+  // la maison. Les fichiers caches, eux, sont deja impossibles cote serveur.
+  list_site_files: "lecture",
+  read_site_file: "secret",
 };
 
 /** Ce qu'on garde en lecture seule. */

package/savoir.mjs

@@ -35,6 +35,8 @@ SIX PIÈGES QUI NE LÈVENT AUCUNE ERREUR. Ils répondent tous « 200 OK ».
 5. Une fonction Edge renvoie \`{ status, body }\`, jamais \`new Response(...)\`.
 6. Deux authentifications sans rapport coexistent. Celle du PROJET (tes utilisateurs finaux) vit dans le schéma \`auth\` de cette base et alimente \`auth.uid()\` dans les policies. Celle de la PLATEFORME (le compte Clicbase) ne s'écrit jamais dans une policy.
 
+CE QUI N'EXISTE PAS, ET QUE DEUX ASSISTANTS ONT DEJA INVENTE. Il n'y a AUCUN registre Docker : ni \`docker login\`, ni \`docker pull\`, ni \`registry.*.clicbase.com\`. Ne devine aucun nom d'hote. Les fichiers d'un site heberge se lisent par \`list_site_files\` et \`read_site_file\`, et s'ecrivent par POST /sites/<id>/files. Inutile de reclamer un mot de passe SFTP pour cela : le SFTP reste utile pour un transfert volumineux, pas pour consulter. Les fichiers CACHES sont refuses a tout niveau, \`.env\` et \`.git\` compris : ils ne peuvent ni etre deposes ni etre lus. \`read_site_file\` est absent en lecture seule, parce qu'un source peut porter des identifiants dans un fichier non cache.
+
 APPELS REST : en-têtes \`apikey\` ET \`Authorization: Bearer\`, la même clé dans les deux. Filtres dans l'URL, façon PostgREST : \`?select=id,title&status=eq.published&order=created_at.desc\`.
 
 DEUX CLÉS À NE PAS CONFONDRE. \`anon\` est publique et soumise à la RLS, elle va dans le navigateur. \`service\` CONTOURNE la RLS et voit tout : serveur uniquement, jamais dans un front, jamais dans un dépôt.