Plan de contrôle

Vue D'Ensemble

Yayaw expose un plan de contrôle production via MCP. Codex est un client pris en charge, mais l'endpoint est conçu pour tout client MCP ou runner d'automatisation de confiance.

• La production et le staging utilisent Streamable HTTP sur /api/mcp.
• Le développement local peut utiliser stdio avec bun --conditions react-server --env-file=.env src/lib/scripts/mcp/yayaw-mcp-server.ts.
• Les requêtes production peuvent s'authentifier avec une clé API Better Auth ou un access token OAuth Better Auth. Les deux chemins utilisent des permissions explicites de plan de contrôle.
• Le réglage de site control-plane-mcp-enabled est le kill switch serveur.
• L'autorisation Yayaw sous-jacente passe toujours par can(...) ou des checks équivalents de membership borné.

Permissions Du Plan De Contrôle

Les clés API utilisent les permissions Better Auth API key sous la ressource control-plane:

• read: statut, discovery, ressources, outils list/get.
• write: mutations brouillon/données/média/design-token.
• publish: outils de cycle de vie publish/archive.
• admin: administration d'audit et de feature flags.

admin ne contourne pas l'autorisation de ressource Yayaw. Il satisfait seulement la porte de permission du plan de contrôle.

Connexion MCP Production

Créez une clé MCP production, stockez-la dans l'environnement du client comme YAYAW_MCP_API_KEY, puis configurez le client MCP. Codex peut utiliser:

[mcp_servers.yayaw-prod]
url = "https://yayaw.app/api/mcp"
bearer_token_env_var = "YAYAW_MCP_API_KEY"

Avant la connexion, activez le réglage de site:

bun run seed

Puis passez control-plane-mcp-enabled à true depuis les réglages Admin ou avec l'outil de flag du plan de contrôle en utilisant une clé admin existante.

Connexion MCP OAuth

Yayaw expose aussi une discovery OAuth 2.1 compatible MCP pour ChatGPT Apps et les autres clients qui suivent le flux d'autorisation MCP. OAuth supporte authorization code avec PKCE et refresh tokens; l'accès machine-to-machine doit continuer à utiliser les clés API MCP.

• Métadonnées de ressource protégée: /.well-known/oauth-protected-resource/api/mcp
• Métadonnées du serveur d'autorisation: /.well-known/oauth-authorization-server/api/auth
• Métadonnées OpenID: /.well-known/openid-configuration/api/auth
• Base du serveur d'autorisation: /api/auth
• Ressource/audience MCP: /api/mcp

L'endpoint MCP renvoie un challenge WWW-Authenticate sur les requêtes OAuth non authentifiées ou invalides afin que les clients découvrent les métadonnées de ressource protégée. Les tokens OAuth sont vérifiés avec le JWKS Better Auth, l'issuer, l'audience, l'expiration et les scopes de plan de contrôle avant l'exécution d'un outil.

Le fournisseur OAuth annonce volontairement toute la surface de permissions MCP:

control-plane:read control-plane:write control-plane:publish control-plane:admin

Cela garde la surface d'outils MCP inchangée pour les clients liés de confiance. Les handlers appliquent toujours la permission de plan de contrôle requise et l'autorisation Yayaw sous-jacente pour chaque opération; les scopes OAuth ne remplacent donc jamais l'autorisation applicative.

Pour les ChatGPT Apps publiées, vérifiez que NEXT_PUBLIC_BASE_URL est l'origine HTTPS publique avant de générer les métadonnées. ChatGPT redirige vers https://chatgpt.com/connector/oauth/{callback_id}; le client OAuth enregistré doit autoriser cette redirect URI.

Connexion MCP Locale

Le stdio local est utile en développement et ne nécessite pas d'ouvrir un endpoint public. Codex peut l'enregistrer avec:

codex mcp add yayaw-local -- bun --conditions react-server --env-file=.env src/lib/scripts/mcp/yayaw-mcp-server.ts

Pour le stdio local, définissez YAYAW_MCP_API_KEY pour tester une vérification de clé API comme en production. Sans clé, le lanceur crée un acteur de développement local avec YAYAW_MCP_LOCAL_USER_ID ou local-codex.

Gestion Des Clés

Pour une clé opérateur MCP totalement de confiance, utilisez l'ensemble complet de permissions:

control-plane:read,write,publish,admin

La page Developer settings du dashboard utilise le bloc de clé API custom Yayaw plutôt que l'UI Better Auth générique, parce que Better Auth traite les permissions de clés API comme des champs server-only. Utilisez ce bloc pour créer des clés MCP avec scopes explicites ou réparer une clé existante avec le preset Full MCP access. Le preset écrit:

control-plane:read,write,publish,admin

L'UI peut mettre à jour les permissions d'une clé existante sans révéler ou faire tourner le secret. Utilisez cela seulement lorsque le secret actuel est déjà stocké en sécurité, parce que Better Auth n'affiche le secret qu'une fois.

Les clés détenues par l'organisation sont le choix par défaut pour les clients MCP qui opèrent sur un périmètre client/workspace. Elles sont émises pour l'organisation active, gérables par les propriétaires, admins et managers Better Auth, portent des métadonnées d'émetteur et sont limitées à leur organisation pour les opérations bornées sur pages, données CMS et médias.

Les clés personnelles sont superadmin-only et destinées à l'administration globale de Yayaw. Utilisez-les pour le contenu global, les feature flags ou les opérations inter-organisations uniquement lorsque c'est intentionnel.

Émettre une clé API MCP détenue par utilisateur:

bun run mcp:key -- issue --email admin@example.com --permissions read,write,publish,admin

Émettre une clé API MCP détenue par organisation:

bun run mcp:key -- issue --email owner@example.com --organization-slug acme --permissions read,write,publish,admin

Lister les clés d'un utilisateur et leurs permissions stockées:

bun run mcp:key -- list --email admin@example.com

Lister les clés d'une organisation et leurs permissions stockées:

bun run mcp:key -- list --organization-slug acme

Inspecter une clé par id:

bun run mcp:key -- inspect --key-id <api-key-id>

Inspecter le secret configuré pour un client MCP local:

YAYAW_MCP_API_KEY=<secret> bun run mcp:key -- inspect --token-env YAYAW_MCP_API_KEY

Révoquer une clé:

bun run mcp:key -- revoke --key-id <api-key-id>

La commande issue affiche le secret une seule fois. Stockez-le dans un gestionnaire de secrets ou l'environnement du client MCP local; ne le commitez pas.

Outils

Noyau:

• yayaw_capabilities
• yayaw_status
• yayaw_audit_list
• yayaw_deploy_status

CMS et pages:

• yayaw_pages_list, yayaw_pages_get, yayaw_pages_validate, yayaw_pages_diff
• yayaw_pages_save_draft, yayaw_pages_publish, yayaw_pages_archive
• yayaw_pages_create_draft
• yayaw_components_list, yayaw_component_get, yayaw_component_import
• yayaw_components_sync_registry, yayaw_component_recompile
• yayaw_component_publish, yayaw_component_delete
• yayaw_sections_list, yayaw_sections_get, yayaw_sections_create_draft
• yayaw_sections_validate, yayaw_sections_save_draft
• yayaw_sections_publish, yayaw_sections_archive
• yayaw_kibo_sections_generate
• yayaw_cms_page_design
• yayaw_data_models_list, yayaw_data_schema_get, yayaw_data_entry_get
• yayaw_data_entry_upsert, yayaw_data_entry_publish
• yayaw_email_templates_list, yayaw_email_template_get
• yayaw_email_template_save, yayaw_email_templates_sync_system
• yayaw_org_domains_list, yayaw_org_domain_add, yayaw_org_domain_check
• yayaw_org_domain_set_primary, yayaw_org_domain_archive

Opérations site:

• yayaw_billing_products_list, yayaw_billing_product_update
• yayaw_stripe_discounts_list, yayaw_stripe_discounts_sync
• yayaw_media_list, yayaw_media_generate
• yayaw_design_tokens_get, yayaw_design_tokens_save
• yayaw_flags_list, yayaw_flags_update

Lors de l'ajout d'un outil, préférez une implémentation service-layer réutilisable par les server actions UI ou les scripts. Les handlers doivent rester fins: valider l'entrée, vérifier les permissions, appeler le service partagé et écrire l'audit.

Ressources

• yayaw://status
• yayaw://schemas
• yayaw://pages/{scope}/{slug}
• yayaw://data/{scope}/{modelSlug}/{entrySlug}
• yayaw://email-templates/{slug}
• yayaw://audit/recent

Les workflows facturation, remises, médias, design tokens, feature flags et domaines d'organisation sont exposés comme outils plutôt que comme ressources MCP. Les lectures de pages et données scopées organisation doivent utiliser les outils lorsqu'un orgId explicite est requis.

Règles De Sécurité

Les écritures production exigent tout ce qui suit:

• control-plane-mcp-enabled est activé.
• Une clé API Better Auth valide ou un access token OAuth est fourni comme Authorization: Bearer <token>.
• La clé ou le token OAuth a la permission de plan de contrôle requise.
• L'acteur passe les checks d'autorisation de ressource Yayaw sous-jacents.
• L'entrée de l'outil inclut reason.

Les clés détenues par l'organisation sont en plus limitées à leur organisation pour les opérations contenu/média bornées. Les clés personnelles nécessitent toujours la permission seedée Yayaw apikey:manage pour être émises depuis le dashboard.

Les outils de domaines publics d'organisation suivent la même frontière d'organisation. Les clés d'organisation opèrent uniquement sur leur organisation; les clés personnelles doivent passer un orgId explicite. Les mutations de domaines exigent organization:update ou organization-settings:manage, un reason, et utilisent dryRun pour le prévol. PUBLIC_DOMAIN_PROVIDER=vercel attache le hostname au projet Vercel partagé, lit les enregistrements DNS recommandés et vérifie les challenges de propriété Vercel. PUBLIC_DOMAIN_PROVIDER=manual-dns génère un token TXT de propriété et vérifie le DNS public pour le TXT attendu plus les indications CNAME/A configurées.

yayaw_deploy_status renvoie des métadonnées de déploiement neutres vis-à-vis du fournisseur. Sur Vercel, il expose les champs runtime Vercel; sur les déploiements auto-hébergés, il expose les valeurs statiques DEPLOYMENT_URL, DEPLOYMENT_ENV, DEPLOYMENT_GIT_COMMIT_SHA et DEPLOYMENT_GIT_COMMIT_REF lorsqu'elles sont configurées.

Les écritures de composants sont des imports catalogue ou recompilations en base depuis des snapshots source stockés. Les outils MCP composants ne mutent jamais les fichiers du dépôt en production et n'exécutent jamais de source stockée en base au runtime.

Les outils de sections réutilisables et de design de page CMS créent d'abord des brouillons. yayaw_cms_page_design peut assembler composants brouillon, ressources, sections et page depuis un prompt avec dryRun=false, mais ne publie pas. Utilisez les outils publish de section et page après validation des diagnostics et demande explicite de publication.

yayaw_kibo_sections_generate crée ou met à jour des recettes CMS natives kibo-ui-block pour le catalogue Kibo UI suivi. Il ne stocke jamais du TSX tiers arbitraire comme contenu exécutable au runtime: chaque section générée est une section recipe Yayaw rendue par des exemples Kibo présents dans le dépôt et leurs dépendances Kibo/shadcn vendored. Les recettes générées exposent des props éditables texte, lien, média et listes JSON afin que les pages lient du contenu Yayaw localisé via PageSection.inputBindings pendant que les défauts Kibo restent le repli de prévisualisation. Utilisez dryRun=true pour inspecter les slugs cibles et publish=true seulement lorsque l'appelant veut explicitement publier les révisions validées.

Les outils de publication/archive de page, publication d'entrée de données et publication de section exigent expectedRevisionId pour préserver le verrouillage optimiste. L'archive de section accepte expectedRevisionId lorsque l'appelant connaît la dernière révision. Les outils d'archive destructeurs, y compris page, section, composant et domaine public d'organisation, exigent confirm: true.

Chaque appel d'outil MCP tente d'écrire control_plane_audit_events avec acteur, clé API, opération, cible, environnement, transport, état dry-run, raison, statut, résumé d'erreur et métadonnées de résultat. Une insertion d'audit réussie renvoie auditId dans la réponse de l'outil; si le stockage d'audit est indisponible, le serveur journalise l'échec et renvoie la réponse sans auditId.

Contrat Des Futures Fonctionnalités

Les nouvelles fonctionnalités opérationnelles doivent être conçues comme opérables par le plan de contrôle sauf exclusion volontaire UI-only.

Lorsqu'une fonctionnalité nécessite des workflows de contenu, configuration, publication, statut ou audit, implémentez-la avec le pattern partagé du plan de contrôle:

• Placez la logique métier dans un point d'entrée service réutilisable qui accepte un argument acteur/contexte explicite.
• Gardez les lectures de cookie-session dans les adaptateurs UI, pas dans la couche service réutilisable.
• Faites appeler la même logique permissionnée par les server actions UI, outils MCP, scripts CLI et API HTTP optionnelles.
• Enregistrez des outils/ressources MCP typés dans src/lib/server/services/control-plane lorsque les clients MCP doivent opérer ou inspecter la fonctionnalité.
• Exigez reason pour les écritures, dryRun lorsque c'est pratique, expectedRevisionId pour les flux publish optimistes et confirm: true pour les actions destructrices.
• Gatez l'accès par clé API avec les permissions Better Auth control-plane:* et exécutez quand même l'autorisation Yayaw avec can(...) ou des checks de membership borné.
• Tentez l'enregistrement d'événements d'audit pour toutes les opérations et exposez auditId lorsque le stockage réussit.
• Mettez à jour cette documentation et content/llm/llm-source.md, puis régénérez les fichiers assistants avec bun run docs:llm:generate.
• Ajoutez des tests ciblés pour schémas, mapping de permissions, gardes dry-run/write, insertion d'audit et couverture smoke discovery MCP ou appel d'outil.

Si une fonctionnalité est volontairement exclue de MCP/CLI, documentez la raison dans les docs de fonctionnalité ou le résumé de PR.

Validation

Checks utiles après des changements du plan de contrôle:

bun test src/lib/server/services/control-plane/control-plane.test.ts
bun test src/lib/server/services/control-plane/oauth-metadata.test.ts
bun run mcp:stdio