mcp-expose

MCP Expose — Generer un MCP Server pour un Module

Ce skill genere un MCP server Edge Function qui expose un module Somtech via MCP. Il supporte deux modes :

• Mode Edge Function : wrappe une Edge Function API existante
• Mode PostgREST : genere un CRUD direct sur les tables du module via le client Supabase

Le MCP server supporte l'auth dual (OAuth prefere, API key en fallback) et est consommable par Claude Code, Claude Cowork, et les agents SDK Anthropic.

Pre-requis

• Un projet avec Supabase configure
• (Optionnel) Table external_api_keys pour le support API key — voir references/AUTH_PATTERNS.md

Workflow

Etape 1 : Identifier le module et le mode

Demander a l'utilisateur quel module exposer. Determiner le mode automatiquement :

# Verifier si une Edge Function existe
ls supabase/functions/{module}/index.ts 2>/dev/null

Situation	Mode
supabase/functions/{module}/index.ts existe	Edge Function — wrapper
Pas d'Edge Function, tables connues	PostgREST — CRUD direct
Pas d'Edge Function, tables inconnues	PostgREST — detecter via schema DB

Etape 2A : Analyser les endpoints (mode Edge Function)

Lire le code source de supabase/functions/{module}/index.ts et detecter les routes/operations :

Patterns a chercher :

1. Routing par methode HTTP :

   • req.method === "GET" / "POST" / "PATCH" / "PUT" / "DELETE"
   • switch / if sur la methode ou le path

2. Operations Supabase :

   • .from("table").select(...) → operation list ou get
   • .from("table").insert(...) → operation create
   • .from("table").update(...) → operation update
   • .from("table").delete() → operation delete
   • .eq("id", ...) → operation sur un element (get/update/delete)

3. Parametres :

   • url.searchParams.get("...") → parametres de filtre (list)
   • await req.json() → body (create/update)
   • Path segments → id (get/update/delete)

Mapping :

Pattern	Tool MCP	Schema
select() sans .eq('id')	app_{module_plural}_list	filtres optionnels + limit/offset
select().eq('id')	app_{module_singular}_get	id requis
insert()	app_{module_singular}_create	champs du body
update().eq('id')	app_{module_singular}_update	id requis + champs
delete().eq('id')	app_{module_singular}_delete	id requis
autre logique	app_{module}_{action}	a determiner

Fallback : si la detection automatique ne trouve rien (code non standard, logique repartie), demander a l'utilisateur de lister les operations a exposer manuellement.

Etape 2B : Detecter le schema (mode PostgREST)

Recuperer les informations des tables du module. Utiliser une de ces methodes (par ordre de preference) :

Methode 1 — Via le MCP Supabase du projet (si configure dans .mcp.json ou .cursor/mcp.json) :

Utiliser l'outil MCP Supabase execute_sql pour querier le schema :

SELECT
  c.table_name,
  c.column_name,
  c.data_type,
  c.is_nullable,
  c.column_default,
  tc.constraint_type,
  ccu.table_name AS foreign_table
FROM information_schema.columns c
LEFT JOIN information_schema.key_column_usage kcu
  ON c.table_name = kcu.table_name AND c.column_name = kcu.column_name
LEFT JOIN information_schema.table_constraints tc
  ON kcu.constraint_name = tc.constraint_name AND tc.constraint_type = 'FOREIGN KEY'
LEFT JOIN information_schema.constraint_column_usage ccu
  ON tc.constraint_name = ccu.constraint_name
WHERE c.table_schema = 'public'
  AND c.table_name IN ('table1', 'table2')
ORDER BY c.table_name, c.ordinal_position;

Methode 2 — Via les types TypeScript generes :

Lire le fichier de types genere par supabase gen types typescript (souvent src/types/supabase.ts ou types/database.ts). Chercher les interfaces Tables pour extraire les colonnes et types.

Methode 3 — Demander a l'utilisateur :

Si aucune des methodes precedentes n'est disponible, demander :

• Quelles tables exposer
• Pour chaque table : quelles colonnes sont filtrables, quels champs sont requis en creation

Pour chaque table detectee, generer les tools CRUD :

Tool	Description	inputSchema
app_{table_plural}_list	Liste avec filtres	colonnes filtrables + limit/offset
app_{table_singular}_get	Recupere par ID	id requis
app_{table_singular}_create	Cree un enregistrement	colonnes sans default/auto (id, created_at exclus)
app_{table_singular}_update	Met a jour par ID	id requis + colonnes modifiables
app_{table_singular}_delete	Supprime par ID	id requis

Colonnes a exclure du create/update :

• id (auto-genere)
• created_at, updated_at (auto-generes)
• created_by, updated_by (auto-generes si RLS)

Colonnes filtrables pour list :

• Toutes les colonnes FK (*_id) → filtre exact .eq()
• Colonnes text → filtre recherche .ilike()
• Colonnes enum/status → filtre exact .eq()
• Toujours inclure limit (default 50) et offset (default 0)

Etape 3 : Generer le MCP server

1. Executer le script de generation :

# Mode Edge Function (auto-detecte)
./scripts/mcp-expose.sh {module}

# Mode PostgREST avec tables specifiees
./scripts/mcp-expose.sh {module} --tables table1,table2

Ce script :

• Detecte le mode automatiquement
• Copie mcp-core/ dans _shared/ si absent (avec gestion de version)
• Cree supabase/functions/{module}-mcp/index.ts (squelette adapte au mode)
• Declare dans supabase/config.toml

2. Remplir le squelette avec les tools detectes :

Utiliser le template dans references/TEMPLATE_MCP_WRAPPER.md comme guide.

Convention de nommage :

• List : pluriel (app_contacts_list)
• CRUD unitaire : singulier (app_contact_get, app_contact_create)
• Custom : descriptif (app_devis_generate_pdf)

Contexte disponible dans runTool :

ctx: {
  accessToken: string;   // JWT OAuth ou "api_key"
  userId: string;        // UUID user ou "api_key:{id}"
  clientId?: string;     // OAuth client_id ou "api_key:{id}"
  supabase: SupabaseClient; // User-bound (OAuth) ou service-role (API key)
}

Le supabase client est automatiquement configure selon le mode d'auth :

• OAuth : createUserSupabaseClient(accessToken) — RLS actif, filtrage automatique
• API key : createServiceSupabaseClient() — service-role, pas de RLS

Important : le runTool doit retourner les donnees brutes (pas de wrapping { content: [...] }). Le handler edgeMcpHandler.ts wrappe automatiquement en format MCP.

Exemple de tool CRUD PostgREST genere :

case "app_devis_list": {
  let query = supabase.from("devis").select("*, client:entreprises(nom)");
  if (args.client_id) query = query.eq("client_id", args.client_id);
  if (args.statut) query = query.eq("statut", args.statut);
  if (args.search) query = query.ilike("titre", `%${args.search}%`);
  query = query.order("created_at", { ascending: false });
  const { data, error } = await query.range(args.offset ?? 0, (args.offset ?? 0) + (args.limit ?? 50) - 1);
  if (error) throw error;
  return data;
}

case "app_devis_get": {
  const { data, error } = await supabase
    .from("devis")
    .select("*, lignes:ligne_devis(*), client:entreprises(nom, email)")
    .eq("id", args.id)
    .single();
  if (error) throw error;
  return data;
}

case "app_devis_create": {
  const { data, error } = await supabase
    .from("devis")
    .insert({ titre: args.titre, client_id: args.client_id, montant: args.montant })
    .select()
    .single();
  if (error) throw error;
  return data;
}

Etape 4 : Valider

1. Verification syntaxique : s'assurer que le code genere est du TypeScript valide

2. Tester localement (si Supabase local tourne) :

# Health check
curl http://127.0.0.1:54321/functions/v1/{module}-mcp/health

# Tools listing (avec auth)
curl -X POST http://127.0.0.1:54321/functions/v1/{module}-mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

3. Verifier config.toml : s'assurer que le bloc [functions.{module}-mcp] est present avec verify_jwt = false

Etape 5 : Informer l'utilisateur

Afficher un resume :

• Mode utilise (Edge Function ou PostgREST)
• Fichiers generes
• Tools MCP crees (avec liste)
• Tables exposees (mode PostgREST)
• Prochaines etapes (deploiement, configuration client via configure-mcp-server)

References

• Template : references/TEMPLATE_MCP_WRAPPER.md
• Auth : references/AUTH_PATTERNS.md
• Lib : lib/mcp-core/ (source de verite pour les fichiers runtime)