@clicbase/mcp 0.1.1 → 0.1.4

package/README.md

@@ -80,6 +80,33 @@ projet** (`/dashboard?studio=<id>&section=api`) : « API REST » donne l'URL,
 « Cle service » la cle. Ce n'est PAS une cle `cbk_` : celles-la servent au
 serveur tout-en-un et n'apparaissent que pour qui possede un VPS ou un Docker.
 
+## Ce que l'assistant sait avant son premier appel
+
+Un serveur MCP qui n'expose que des outils laisse le modele deviner les
+conventions de la plateforme. Depuis la 0.1.2, celui-ci remplit le champ
+`instructions` du protocole : le client le pose dans le contexte du modele A LA
+CONNEXION, avant tout appel. On ne peut donc pas oublier de le lire.
+
+Six pieges y sont enumeres, et ils ont en commun de repondre **200 OK** :
+
+1. `with check` n'est pas `using`. Sur INSERT et UPDATE, PostgreSQL n'evalue
+   QUE `with check`.
+2. Chaque nouvelle table accorde le CRUD a `authenticated` : un `grant select`
+   ne restreint rien, il faut `revoke`.
+3. Toute DDL se termine par `notify pgrst, 'reload schema';`.
+4. `service_role` a besoin de `BYPASSRLS`, sinon 200 OK et un tableau vide.
+5. Une fonction Edge rend `{ status, body }`, jamais `new Response(...)`.
+6. L'auth du PROJET (schema `auth` de la base, `auth.uid()`) ne se confond pas
+   avec celle de la PLATEFORME.
+
+L'outil `clicbase_conventions` en rend le detail a la demande : formes exactes
+des policies, ordre `revoke` puis `grant`, operateurs PostgREST. Il est classe
+en LECTURE, donc il survit au mode restreint · c'est ce mode qui en a le plus
+besoin, puisqu'il ne laisse que trois autres outils.
+
+Le texte vit dans `savoir.mjs`, sans aucun import, pour rester chargeable par
+les tests du depot.
+
 ## Quand l'utiliser
 
 `run_sql` exécute du SQL arbitraire avec les droits du propriétaire de la base,

package/clicbase-db-mcp.mjs

@@ -12,6 +12,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { filtre, lectureSeule } from "./portee.mjs";
+import { CONVENTIONS, INSTRUCTIONS } from "./savoir.mjs";
 
 const BASE = process.env.CLICBASE_DB_URL ?? process.env.ROROUIRA_DB_URL;
 const KEY = process.env.CLICBASE_SERVICE_KEY ?? process.env.ROROUIRA_SERVICE_KEY;
@@ -51,7 +52,15 @@ async function api(path, method = "GET", body) {
 const out = (d) => ({ content: [{ type: "text", text: JSON.stringify(d, null, 2) }] });
 const fail = (e) => ({ isError: true, content: [{ type: "text", text: String(e?.message ?? e) }] });
 
-const server = new McpServer({ name: "clicbase-db", version: "1.0.0" });
+// ⚠️ `instructions` EST LU A LA CONNEXION, AVANT LE PREMIER APPEL. C'est le
+// seul endroit qu'un assistant ne peut pas oublier de consulter : le client
+// MCP le pose dans le contexte du modele. Sans lui, un assistant recevait
+// TROIS outils et trente mots de description, puis devinait les conventions
+// de la plateforme. Voir savoir.mjs.
+const server = new McpServer(
+  { name: "clicbase-db", version: "1.0.0" },
+  { instructions: INSTRUCTIONS },
+);
 
 // ⚠️ EN LECTURE SEULE, LES OUTILS QUI ECRIVENT NE SONT PAS ENREGISTRES. Voir
 // portee.mjs : un outil absent n'est jamais demande, un outil present qui
@@ -59,6 +68,13 @@ const server = new McpServer({ name: "clicbase-db", version: "1.0.0" });
 const SEULEMENT_LECTURE = lectureSeule();
 const outils = filtre(server, SEULEMENT_LECTURE);
 
+outils.tool(
+  "clicbase_conventions",
+  "Les conventions Clicbase : formes exactes des policies RLS, droits par defaut, rechargement du schema, appels REST, fonctions Edge. A lire AVANT d'ecrire du SQL ou une policy.",
+  {},
+  async () => ({ content: [{ type: "text", text: CONVENTIONS }] }),
+);
+
 outils.tool(
   "run_sql",
   "Exécute du SQL (DDL/DML/RLS) sur la base. Après un changement de schéma, termine par: NOTIFY pgrst, 'reload schema';",

package/clicbase-mcp.mjs

@@ -21,6 +21,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { filtre, lectureSeule } from "./portee.mjs";
+import { CONVENTIONS, INSTRUCTIONS } from "./savoir.mjs";
 
 const API = process.env.CLICBASE_API ?? process.env.ROROUIRA_API ?? "https://clicbase.com/api/v1/databases";
 
@@ -37,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: {
@@ -48,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,
@@ -64,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,
@@ -77,7 +183,15 @@ async function call(name, path, method = "POST", body) {
   return data;
 }
 
-const server = new McpServer({ name: "clicbase", version: "2.0.0" });
+// ⚠️ `instructions` EST LU A LA CONNEXION, AVANT LE PREMIER APPEL. C'est le
+// seul endroit qu'un assistant ne peut pas oublier de consulter : le client
+// MCP le pose dans le contexte du modele. Sans lui, un assistant recevait
+// TROIS outils et trente mots de description, puis devinait les conventions
+// de la plateforme. Voir savoir.mjs.
+const server = new McpServer(
+  { name: "clicbase", version: "2.0.0" },
+  { instructions: INSTRUCTIONS },
+);
 
 // ⚠️ EN LECTURE SEULE, LES OUTILS QUI ECRIVENT NE SONT PAS ENREGISTRES. Voir
 // portee.mjs : un outil absent n'est jamais demande, un outil present qui
@@ -85,6 +199,13 @@ const server = new McpServer({ name: "clicbase", version: "2.0.0" });
 const SEULEMENT_LECTURE = lectureSeule();
 const outils = filtre(server, SEULEMENT_LECTURE);
 
+outils.tool(
+  "clicbase_conventions",
+  "Les conventions Clicbase : formes exactes des policies RLS, droits par defaut, rechargement du schema, appels REST, fonctions Edge. A lire AVANT d'ecrire du SQL ou une policy.",
+  {},
+  async () => ({ content: [{ type: "text", text: CONVENTIONS }] }),
+);
+
 outils.tool(
   "create_database",
   "Crée (ou récupère, idempotent) une base Clicbase pour un site. Renvoie la chaîne de connexion PostgreSQL, l'URL de l'API REST et les clés anon/service.",
@@ -113,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);
+    }
   },
 );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clicbase/mcp",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "type": "module",
   "bin": {
     "mcp": "clicbase-mcp.mjs",
@@ -35,6 +35,7 @@
     "clicbase-mcp.mjs",
     "clicbase-db-mcp.mjs",
     "portee.mjs",
+    "savoir.mjs",
     "README.md",
     "LICENSE"
   ],

package/portee.mjs

@@ -43,6 +43,11 @@ export const OUTILS = {
   enable_rls: "ecriture",
   create_policy: "ecriture",
   get_oauth_provider: "lecture",
+  // ⚠️ RENDU EN LECTURE SEULE, ET C'EST TOUT L'INTERET. Cet outil ne rend que
+  // du texte : les conventions de la plateforme. C'est precisement le mode
+  // 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",
 };
 
 /** Ce qu'on garde en lecture seule. */

package/savoir.mjs

@@ -0,0 +1,122 @@
+// CE QUE L'ASSISTANT DOIT SAVOIR, ET QU'AUCUN OUTIL NE LUI APPREND.
+//
+// Question de Teiki le 2026-09-17 : « quand un client ajoute la commande MCP à
+// son IA, elle va tout comprendre ? » Mesuré dans le paquet publié, la réponse
+// était non. En lecture seule, un assistant reçoit TROIS outils et une
+// trentaine de mots de description. Il sait explorer un schéma. Il ignore tout
+// ce qui fait perdre des journées ici.
+//
+// ⚠️ LES SIX PIÈGES CI-DESSOUS SONT RÉELS, PAS THÉORIQUES. Ils viennent de la
+// section « Pièges qui ont déjà coûté cher » du dépôt, écrite après coup à
+// chaque fois. Ils ont en commun de ne produire NI exception NI ligne de
+// journal : une policy qui ne protège rien répond 200, un grant qui ne
+// restreint pas répond 200, une clé service sans BYPASSRLS répond 200 avec un
+// tableau vide. Un assistant qui les ignore croit avoir réussi.
+//
+// ⚠️ DEUX CANAUX, ET CE N'EST PAS UNE REDONDANCE. `INSTRUCTIONS` part dans le
+// champ prévu par le protocole : le client MCP le pose dans le contexte du
+// modèle À LA CONNEXION, avant le premier appel, et on ne peut donc pas
+// oublier de le lire. `CONVENTIONS` est le détail, rendu par un outil quand
+// l'assistant en a besoin. Tout mettre dans le premier gonflerait chaque
+// conversation ; tout mettre dans le second laisserait l'assistant écrire une
+// policy fausse sans avoir jamais su qu'il fallait demander.
+//
+// ⚠️ CE FICHIER N'IMPORTE RIEN, exprès : le lanceur de tests du dépôt charge
+// les modules voisins avec leur extension, et un import casserait sa lecture.
+
+/** Posé dans le contexte du modèle dès la connexion. Court par obligation. */
+export const INSTRUCTIONS = `Tu es connecté à un projet Clicbase : une base PostgreSQL managée, exposée en API REST par PostgREST.
+
+SIX PIÈGES QUI NE LÈVENT AUCUNE ERREUR. Ils répondent tous « 200 OK ».
+1. \`with check\` n'est PAS \`using\`. Sur INSERT et UPDATE, PostgreSQL n'évalue QUE \`with check\`. Une policy qui n'a qu'un \`using\` ne protège pas l'écriture.
+2. Chaque nouvelle table accorde le CRUD à \`authenticated\` par défaut. Un \`grant select\` ne restreint RIEN : il faut \`revoke\`.
+3. Après tout changement de schéma, termine par \`notify pgrst, 'reload schema';\` sinon l'API continue de servir l'ancien schéma.
+4. Le rôle \`service_role\` a besoin de \`BYPASSRLS\`. Sans lui : 200 OK et un tableau vide, sans explication.
+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. Ce serveur MCP ne rend pas le code source d'un site heberge : pour recuperer des fichiers, c'est le SFTP du tableau de bord ou son gestionnaire de fichiers, et l'API d'administration ne fait que les ECRIRE (POST /sites/<id>/files), jamais les lire.
+
+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.
+
+Appelle \`clicbase_conventions\` avant d'écrire du SQL ou une policy : tu y trouveras les formes exactes.`;
+
+/** Le détail, rendu à la demande par un outil de lecture. */
+export const CONVENTIONS = `# Conventions Clicbase
+
+## Row Level Security
+
+\`\`\`sql
+alter table articles enable row level security;
+
+-- LECTURE : using suffit.
+create policy "lecture_publique" on articles
+  for select to anon, authenticated using (status = 'published');
+
+-- ÉCRITURE : with check est OBLIGATOIRE, using ne sert pas.
+create policy "chacun_ses_lignes" on articles
+  for insert to authenticated with check (user_id = auth.uid());
+
+create policy "modifier_les_siennes" on articles
+  for update to authenticated
+  using (user_id = auth.uid())          -- quelles lignes il peut viser
+  with check (user_id = auth.uid());    -- ce qu'il peut y écrire
+
+notify pgrst, 'reload schema';
+\`\`\`
+
+⚠️ Sur UPDATE, les deux clauses ont des rôles différents : \`using\` choisit les
+lignes visées, \`with check\` valide le résultat. Omettre la seconde laisse
+réécrire \`user_id\` vers quelqu'un d'autre.
+
+## Les droits, avant la RLS
+
+La RLS filtre les lignes ; les GRANT décident si la table est atteignable. Une
+nouvelle table est ouverte en CRUD à \`authenticated\` par défaut, donc :
+
+\`\`\`sql
+revoke all on articles from anon, authenticated;
+grant select on articles to anon, authenticated;
+grant insert, update, delete on articles to authenticated;
+\`\`\`
+
+Un \`grant select\` seul n'enlève rien : il ajoute. C'est \`revoke\` qui ferme.
+
+## auth.uid()
+
+Il rend le \`sub\` du JWT du projet, donc l'identifiant de l'utilisateur final
+connecté. Il vaut NULL avec la clé \`anon\`. Une policy qui doit exiger un compte
+écrit \`auth.uid() is not null\`, pas \`true\`.
+
+## API REST
+
+\`\`\`
+GET /db/<slug>/articles?select=id,title&status=eq.published&order=created_at.desc
+en-têtes : apikey: <clé>   et   Authorization: Bearer <clé>
+\`\`\`
+
+Opérateurs : \`eq.\`, \`neq.\`, \`gt.\`, \`gte.\`, \`lt.\`, \`lte.\`, \`like.\`, \`ilike.\`,
+\`in.(a,b)\`, \`is.null\`. Les relations se tirent par \`select=*,auteur(*)\`.
+
+## Après toute DDL
+
+\`notify pgrst, 'reload schema';\` dans la même exécution. Sans cela, la table
+existe en base et l'API répond 404 : le défaut ressemble à une erreur de nom.
+
+## Fonctions Edge
+
+\`\`\`js
+export default async function (req) {
+  return { status: 200, body: { ok: true } };
+}
+\`\`\`
+
+Jamais \`new Response(...)\` : l'hôte attend un objet, pas une réponse HTTP.
+
+## Ce qu'aucun outil ne fera pour toi
+
+Distinguer un \`drop table\` prévu d'un \`drop table\` accidentel. Le DDL est la
+raison d'être de \`run_sql\`, et aucune liste de mots interdits ne sépare les
+deux. Avant un ordre destructeur, dis ce que tu vas faire et demande.`;