@clicbase/mcp 0.1.0 → 0.1.2

package/README.md

@@ -47,6 +47,66 @@ une **écriture** : il disparaît du mode restreint au lieu d'y être admis. Un
 oubli coûte alors une fonction manquante, que l'on remarque ; l'inverse aurait
 coûté une écriture ouverte dans un mode qui promet de ne pas écrire.
 
+## ⚠️ La forme de la commande npx
+
+`npx -y @clicbase/mcp` **echouait** en `could not determine executable to run`
+jusqu'a la version 0.1.1 : le paquet porte plusieurs commandes et aucune ne
+s'appelait `mcp`, donc npx ne pouvait pas choisir. Deux formes sont justes :
+
+```bash
+npx -y -p @clicbase/mcp clicbase-mcp       # tout-en-un, marche des 0.1.0
+npx -y -p @clicbase/mcp clicbase-db-mcp    # un seul projet
+npx -y @clicbase/mcp                       # depuis 0.1.1 seulement
+```
+
+`-p` designe le PAQUET a installer, l'argument suivant la COMMANDE a lancer.
+Sans lui, npx cherche une commande portant le dernier segment du nom du paquet.
+
+## Un seul projet : `clicbase-db-mcp`
+
+C'est la variante qu'utilise un client sur sa propre base. Elle ne cree pas de
+projet et ne voit que celui qu'on lui donne :
+
+```bash
+claude mcp add ma-base \
+  -e CLICBASE_DB_URL=https://clicbase.com/db/<slug> \
+  -e CLICBASE_SERVICE_KEY=<cle service> \
+  -e CLICBASE_READ_ONLY=1 \
+  -- npx -y -p @clicbase/mcp clicbase-db-mcp
+```
+
+Les deux valeurs se trouvent dans le tableau de bord Clicbase, **section API du
+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,
@@ -69,7 +129,7 @@ En clair :
 claude mcp add clicbase \
   -e CLICBASE_API_KEY=cbk_... \
   -e CLICBASE_READ_ONLY=1 \
-  -- npx -y @clicbase/mcp
+  -- npx -y -p @clicbase/mcp clicbase-mcp
 ```
 
 > ⚠️ `CLICBASE_READ_ONLY=1` est volontairement dans la commande d'installation.
@@ -77,12 +137,14 @@ claude mcp add clicbase \
 > projet et la clé `service`. Retire cette ligne seulement quand tu sais
 > pourquoi, et lis la section « Quand l'utiliser » avant.
 
-### Depuis le dépôt
+### Depuis les sources
 
+⚠️ `cd mcp` ne vaut que dans le monorepo Clicbase. Depuis le depot public, la
+racine EST le paquet : ce README est publie aux deux endroits, et une ligne
+juste d'un cote se trompe de l'autre.
 
 ```bash
-cd mcp
-npm install
+git clone https://github.com/clicbase/mcp && cd mcp && npm install
 ```
 
 ## Configuration dans Claude Code

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";
 
@@ -77,7 +78,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 +94,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.",

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@clicbase/mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "bin": {
+    "mcp": "clicbase-mcp.mjs",
     "clicbase-mcp": "clicbase-mcp.mjs",
     "clicbase-db-mcp": "clicbase-db-mcp.mjs"
   },
@@ -34,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,120 @@
+// 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.
+
+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.`;