nas-runbooks/common/baserow-schema-mcp.md

baserow-schema-mcp — serveur MCP compagnon pour la gestion de schema Baserow (17/08/2026)

Statut : PRODUCTION (4 outils testes end-to-end). Reste une action manuelle : reverse-proxy DSM baserow-schema.bolbol.tn → 3101, puis ajout du connecteur cote Claude.ai.

Probleme

Le MCP natif de Baserow (https://baserow.bolbol.tn/mcp/<token>/sse, cf. baserow-mcp-oauth-fix.md) expose uniquement des outils de LIGNES (list_databases, list_tables, get_table_schema, create_rows, update_rows, delete_rows, list_table_rows) — aucun outil de gestion de schema (creer/supprimer une table ou un champ). Baserow tourne en image officielle (baserow/baserow:latest, watchtower), non patchable directement (meme constat que baserow-mcp-oauth-fix.md) : impossible d'ajouter ces outils au MCP natif.

Solution

Nouveau service independant, meme famille que baserow-oauth-stub (sidecar OAuth rubber-stamp devant un vrai serveur), a /volume1/docker/baserow-schema-mcp/ (Gitea bolbol/baserow-schema-mcp, prive) :

• baserow-schema-mcp (FastAPI-free, mcp.server.fastmcp.FastMCP, build local, pas de port publie) : 4 outils, perimetre strict, rien d'autre (pas de update_field, pas de gestion de databases/workspaces) :
  • create_table(database_id, name, data?, first_row_header?) → POST /api/database/tables/database/{database_id}/
  • delete_table(table_id) → DELETE /api/database/tables/{table_id}/
  • create_field(table_id, field) → POST /api/database/fields/table/{table_id}/ (field = payload brut Baserow, passthrough)
  • delete_field(field_id) → DELETE /api/database/fields/{field_id}/
• baserow-schema-mcp-oauth-app + baserow-schema-mcp-proxy (nginx, port 3101→80) : copie conforme du sidecar OAuth de baserow-oauth-stub, adaptee au domaine baserow-schema.bolbol.tn. Rubber-stamp uniquement — la vraie protection est le token secret dans l'URL /mcp/<token>/sse (meme logique que Baserow natif).
• Les 3 services sont uniquement sur le reseau externe n8n (pas de reseau default supplementaire) — lecon deja tiree dans baserow-mcp-oauth-fix.md, reappliquee directement ici sans la redecouvrir.

Piege n°1 — les 4 routes de schema n'acceptent PAS le Database API Token

Confirme via /api/redoc/ (schema OpenAPI complet, security par route) : POST /api/database/tables/database/{id}/, DELETE /api/database/tables/{id}/, DELETE /api/database/fields/{id}/ n'acceptent QUE JWT/UserSource JWT. Seul POST /api/database/fields/table/{id}/ (creation de champ) accepte aussi Database token — mais pas les 3 autres. Il faut donc un login email+mot de passe (POST /api/user/token-auth/, header ensuite Authorization: JWT <access_token>), pas le token Baserow simple utilise partout ailleurs sur cette infra (rla-api, gsparc-mezzouna, context-hub...).

Lien avec les incidents connus : dashboard-terrain et gsparc-mezzouna-api ont deja ete casses par un JWT Baserow cache indefiniment qui expire/rotate silencieusement (mot de passe ou BASEROW_JWT_SIGNING_KEY change), et le fix a chaque fois ete de fuir le JWT au profit d'un Database token statique. Ici c'est impossible (API Baserow l'exige). Mitigation dans app/baserow_client.py : re-login proactif toutes les 12h (moitie de l'expiration 24h du JWT Baserow) + re-login automatique et une seule retentative sur toute reponse 401, plutot que de laisser echouer silencieusement comme les incidents precedents.

Piege n°2 — API bas niveau mcp.server.sse.SseServerTransport non stable entre versions

Premiere version du code copiait le pattern SSE de bolbol/context-hub (transport.read_stream(), transport.write_stream(), transport.handle_sse(request)) — ces methodes n'existent plus dans mcp==1.29.0 (installe ici ; context-hub avait fige une version bien plus ancienne du meme mcp>=1.2.0,<2.0.0). Erreur en prod : AttributeError: 'SseServerTransport' object has no attribute 'handle_sse'.

L'API bas niveau actuelle expose connect_sse(scope, receive, send) (context manager async qui ecrit directement la reponse ASGI, incompatible avec un simple return EventSourceResponse(...) FastAPI) — fragile a cabler a la main. Fix retenu : passer par l'API haut niveau mcp.server.fastmcp.FastMCP (@mcp.tool() + mcp.sse_app()), maintenue par le SDK et deja correcte pour la version installee, plutot que de re-cabler le bas niveau a chaque bump de version. Le token secret est baked directement dans le chemin du Mount (Mount(f"/mcp/{TOKEN}", app=mcp.sse_app())), pas de validation manuelle necessaire.

A retenir pour tout futur service MCP maison sur cette infra : preferer FastMCP a la construction manuelle de Server + SseServerTransport — plus court ET plus stable dans le temps.

Piege n°3 — DNS-rebinding protection de mcp >=1.29 rejette tout par defaut

TransportSecuritySettings.allowed_hosts vaut [] par defaut avec enable_dns_rebinding_protection=True → tout Host header est rejete (421 Invalid Host header), y compris en interne. Fix : passer explicitement transport_security=TransportSecuritySettings(allowed_hosts=[...], allowed_origins=[...]) a FastMCP(...) avec la liste exacte des Host attendus (domaine public + nom de service Docker:port pour les tests internes directs).

Piege n°4 — 409 Conflict transitoire apres un champ link_row

Creer un champ juste apres un link_row (qui declenche la creation du champ inverse dans la table liee, cf verrou table cote Baserow) peut renvoyer un 409 Conflict sur le create_field suivant immediat. Mitigation appliquee lors de la creation des tables CI-CPT 2026 : retry avec backoff (jusqu'a 6 tentatives, 2s/4s/6s...) + 1-1.5s de pause entre chaque create_field. Un seul 409 rencontre en pratique (table "Bons de Commande CI-CPT 2026", champ lots_couverts juste apres fournisseur), resolu au 1er retry.

Reste a faire (action manuelle Nabil)

1. Reverse-proxy DSM : baserow-schema.bolbol.tn → 3101 (meme manip que cin.bolbol.tn/formation.bolbol.tn, pas d'automatisation connue depuis le NAS/Mac pour cette etape).
2. Ajouter le connecteur MCP personnalise cote Claude.ai avec l'URL https://baserow-schema.bolbol.tn/mcp/<TOKEN>/sse (TOKEN = MCP_SECRET_TOKEN dans /volume1/docker/baserow-schema-mcp/.env, non commite sur Gitea).

Fichiers

/volume1/docker/baserow-schema-mcp/ : app/main.py (FastMCP + 4 tools), app/baserow_client.py (JWT client), oauth_app.py/nginx.conf/ docker-compose.yml (sidecar OAuth, copie du pattern baserow-oauth-stub adaptee). Depot Gitea bolbol/baserow-schema-mcp (prive, .env gitignore). Entree ports-registry.md (port 3101) et miroir common/ports-registry.md a mettre a jour dans la meme session.

Usage — CI-CPT 2026 (premier cas d'usage reel)

3 tables creees dans la base "Zone Sud Achats" (id 229) via ces 4 outils : Bons de Commande CI-CPT 2026 (id 1090), Articles CI-CPT 2026 (id 1091), Répartition régionale CI-CPT 2026 (id 1092). Astuce utilisee pour nommer le champ primaire sans PATCH separe : create_table(..., data=[["nom_du_champ"]], first_row_header=true) — cree une table avec un seul champ primaire texte nomme comme voulu, sans les champs d'exemple par defaut (Name/Notes/Active). 15 tables obsoletes supprimees dans la foulee (AO 19/2026, Reglement definitif, AO 27/2026 — sous-ensemble confirme) avec delete_table.