specrails-desktop 2.16.0 → 2.17.0

package/docs/guide/en/integrations/5-mcp-server.md

@@ -0,0 +1,74 @@
+# Control Specrails from any AI (MCP server)
+
+Specrails can expose **itself** to any AI assistant that speaks the [Model Context Protocol](https://modelcontextprotocol.io) — Claude Desktop, Claude Code, Cursor, Cline, or your own agent. Turn it on, point your assistant at Specrails, and you can drive the whole app by chatting: *"list my projects", "create a spec for social login in the API project", "launch rail 0 and tell me when it's done", "how much did I spend this week?"*. Your assistant calls Specrails' tools under the hood instead of you clicking around.
+
+This is the opposite direction from the plugins and "My approved MCPs" features: those let Specrails *use* other MCP servers; this lets other apps use **Specrails**.
+
+## Turning it on
+
+It's **off by default**. Open **Settings ▸ MCP** and flip **Enable MCP**. That's it — the server starts immediately, no restart.
+
+You stay in control of *what* an external AI may do through a set of permission tiers:
+
+| Tier | What it allows | Default |
+|---|---|---|
+| **Read** | List and inspect projects, specs, jobs, analytics… | Always on (when MCP is enabled) |
+| **Write** | Create and edit specs, change settings and rail config | Off — opt in |
+| **AI-spawn** | Actions that run an AI and **cost money** (launch a rail, generate a spec, send a chat turn) | Off — opt in |
+| **Destructive** | Delete projects/specs/jobs, stop running work | Off — opt in |
+
+If your assistant tries something a disabled tier covers, Specrails refuses with a clear message telling you which tier to switch on. So you can start read-only and open up exactly what you need.
+
+## Connecting your assistant
+
+The panel shows a ready-to-paste configuration block. The simplest, universal path is the bundled **bridge** (`specrails-mcp`): your assistant runs it, and it relays to Specrails for you. The bridge reads the access token locally, so **the token never appears in your assistant's config**.
+
+In a client like Claude Desktop or Cursor, the config looks like:
+
+```json
+{ "mcpServers": { "specrails": { "command": "specrails-mcp" } } }
+```
+
+Clients that support remote HTTP MCP servers can instead point straight at `http://127.0.0.1:4200/api/mcp` with the token from the panel.
+
+Once connected, your assistant sees about **18 tools** covering the whole app — projects, specs, rails and jobs, chat/Explore, agents, plugins, Jira, loops, the code explorer, analytics, settings — plus a built-in **guide** tool it reads first so it understands how Specrails works without you explaining anything.
+
+## What you can do with it
+
+A few recipes once your assistant is connected. Start with **Read** on, then turn on **Write** and **AI-spawn** when you want it to actually create and launch work.
+
+**Turn work from your other tools into specs.** If your assistant also has GitHub, Jira, Gmail or Slack connected, it can bring the work to Specrails for you:
+> *"Take this week's open GitHub issues labelled 'bug', create a spec for each in the API project, and launch them."*
+>
+> *"Read my latest customer-feedback emails, group them by theme, and create one spec per theme."*
+
+**Overnight autopilot.** Leave it running with the app in the tray and come back to a report:
+> *"Here are 12 ideas. Turn each into a spec, launch them three at a time across the rails, watch every job, and tomorrow give me a summary of what finished, what failed and what it cost."*
+
+Keep **Destructive** off and it can build all night without ever deleting anything.
+
+**Across all your projects.** Something the dashboard doesn't do on its own:
+> *"Check all my projects. Tell me which have specs in the backlog and no rail running, and start the highest-priority one in each."*
+
+**Hands-free while you code.** Drive Specrails from your editor or by voice, without switching windows:
+> *"Launch rail 0 in ultracode mode with Opus for ticket #42 and tell me when it's done."*
+
+**Ask about cost and history.** Your analytics, in plain language:
+> *"Where did I spend the most on AI this week, by project and by model? Show me the five most expensive tickets."*
+
+**Your daily standup.**
+> *"Write my standup: which rails ran yesterday, what completed, what failed, total cost — as bullets ready to paste into Slack."*
+
+**Understand the code.** No editor needed:
+> *"Which files did ticket #38 touch? Summarise in one line what changed in each."*
+
+Because your assistant reads the built-in guide first, you rarely need to name tools or specs — describe the outcome and it works out the calls.
+
+## A few things to know
+
+- **Specrails must be running.** The MCP server lives inside the app, so your assistant can reach it only while Specrails is open. Thanks to the tray, closing the window keeps it running in the background — only **Exit** from the tray (Mac menu bar / Windows system tray) actually stops it.
+- **Long actions stream.** Launching a rail or generating a spec returns immediately and finishes in the background; your assistant can "watch" it and report back when it settles.
+- **Security.** The MCP uses its own access token, separate from everything else, and only listens on your own machine (loopback). You can copy or regenerate that token any time from the panel.
+- **Not exposed (v1).** For safety, a few high-risk capabilities are intentionally left out: running shell commands in the terminal, the embedded browser, in-app file editing, and installing system prerequisites. Everything that *manages* Specrails is available; raw machine access is not.
+
+You can disable MCP at any time from the same panel — your assistant simply loses access, and nothing else changes.

package/docs/guide/es/integrations/5-mcp-server.md

@@ -0,0 +1,74 @@
+# Controla Specrails desde cualquier IA (servidor MCP)
+
+Specrails puede exponerse **a sí mismo** a cualquier asistente de IA que hable el [Model Context Protocol](https://modelcontextprotocol.io) — Claude Desktop, Claude Code, Cursor, Cline o tu propio agente. Actívalo, apunta tu asistente a Specrails y podrás manejar toda la app conversando: *"lista mis proyectos", "crea una spec para login social en el proyecto de la API", "lanza el rail 0 y avísame cuando termine", "¿cuánto he gastado esta semana?"*. Tu asistente llama por debajo a las herramientas de Specrails en lugar de que tú andes haciendo clics.
+
+Esta es la dirección opuesta a las funciones de plugins y "Mis MCPs aprobados": esas dejan que Specrails *use* otros servidores MCP; esta deja que otras apps usen **Specrails**.
+
+## Cómo activarlo
+
+Está **desactivado por defecto**. Abre **Configuración ▸ MCP** y activa **Habilitar MCP**. Eso es todo — el servidor arranca de inmediato, sin reiniciar.
+
+Tú mantienes el control de *qué* puede hacer una IA externa mediante un conjunto de niveles de permiso:
+
+| Nivel | Qué permite | Por defecto |
+|---|---|---|
+| **Lectura** | Listar e inspeccionar proyectos, specs, trabajos, analíticas… | Siempre activo (cuando MCP está habilitado) |
+| **Escritura** | Crear y editar specs, cambiar la configuración y la config de los rails | Desactivado — actívalo tú |
+| **Lanzar IA** | Acciones que ejecutan una IA y **cuestan dinero** (lanzar un rail, generar una spec, enviar un turno de chat) | Desactivado — actívalo tú |
+| **Destructivo** | Borrar proyectos/specs/trabajos, detener trabajo en curso | Desactivado — actívalo tú |
+
+Si tu asistente intenta algo que cubre un nivel desactivado, Specrails lo rechaza con un mensaje claro que te indica qué nivel activar. Así puedes empezar en modo solo lectura y abrir exactamente lo que necesites.
+
+## Conectar tu asistente
+
+El panel muestra un bloque de configuración listo para pegar. La vía más sencilla y universal es el **puente** (bridge) incluido (`specrails-mcp`): tu asistente lo ejecuta y este se encarga de retransmitir a Specrails por ti. El puente lee el token de acceso localmente, así que **el token nunca aparece en la configuración de tu asistente**.
+
+En un cliente como Claude Desktop o Cursor, la configuración tiene este aspecto:
+
+```json
+{ "mcpServers": { "specrails": { "command": "specrails-mcp" } } }
+```
+
+Los clientes que admiten servidores MCP remotos por HTTP pueden, en su lugar, apuntar directamente a `http://127.0.0.1:4200/api/mcp` con el token del panel.
+
+Una vez conectado, tu asistente ve unas **18 herramientas** que cubren toda la app — proyectos, specs, rails y trabajos, chat/Explore, agentes, plugins, Jira, loops, el explorador de código, analíticas, configuración — más una herramienta de **guía** incorporada que lee primero para entender cómo funciona Specrails sin que tú tengas que explicar nada.
+
+## Qué puedes hacer con él
+
+Unas cuantas recetas una vez que tu asistente está conectado. Empieza con **Lectura** activado y, cuando quieras que de verdad cree y lance trabajo, activa **Escritura** y **Lanzar IA**.
+
+**Convierte en specs el trabajo de tus otras herramientas.** Si tu asistente también tiene conectados GitHub, Jira, Gmail o Slack, puede traerte el trabajo a Specrails:
+> *"Coge las incidencias abiertas de GitHub de esta semana con la etiqueta 'bug', crea una spec para cada una en el proyecto de la API y lánzalas."*
+>
+> *"Lee mis últimos correos de feedback de clientes, agrúpalos por tema y crea una spec por tema."*
+
+**Piloto automático nocturno.** Déjalo en marcha con la app en la bandeja y vuelve a un informe:
+> *"Aquí tienes 12 ideas. Convierte cada una en una spec, lánzalas de tres en tres por los rails, vigila cada trabajo y mañana dame un resumen de lo que terminó, lo que falló y lo que costó."*
+
+Mantén **Destructivo** desactivado y podrá trabajar toda la noche sin borrar nada nunca.
+
+**En todos tus proyectos.** Algo que el panel no hace por sí solo:
+> *"Revisa todos mis proyectos. Dime cuáles tienen specs en el backlog y ningún rail en marcha, y arranca el de mayor prioridad en cada uno."*
+
+**Sin manos mientras programas.** Maneja Specrails desde tu editor o por voz, sin cambiar de ventana:
+> *"Lanza el rail 0 en modo ultracode con Opus para el ticket #42 y avísame cuando termine."*
+
+**Pregunta por el coste y el historial.** Tus analíticas, en lenguaje natural:
+> *"¿Dónde he gastado más en IA esta semana, por proyecto y por modelo? Enséñame los cinco tickets más caros."*
+
+**Tu standup diario.**
+> *"Escribe mi standup: qué rails se ejecutaron ayer, qué se completó, qué falló y el coste total — en viñetas listas para pegar en Slack."*
+
+**Entiende el código.** Sin necesidad de editor:
+> *"¿Qué archivos tocó el ticket #38? Resume en una línea qué cambió en cada uno."*
+
+Como tu asistente lee primero la guía incorporada, rara vez necesitas nombrar herramientas ni specs — describe el resultado que quieres y él se encarga de las llamadas.
+
+## Algunas cosas que conviene saber
+
+- **Specrails tiene que estar en ejecución.** El servidor MCP vive dentro de la app, así que tu asistente solo puede alcanzarlo mientras Specrails esté abierto. Gracias al icono de la bandeja, cerrar la ventana lo mantiene en ejecución en segundo plano — solo **Salir** desde la bandeja (barra de menú de Mac / bandeja del sistema de Windows) lo detiene de verdad.
+- **Las acciones largas se transmiten.** Lanzar un rail o generar una spec devuelve el control de inmediato y termina en segundo plano; tu asistente puede "vigilarlo" e informarte cuando se resuelva.
+- **Seguridad.** El MCP usa su propio token de acceso, separado de todo lo demás, y solo escucha en tu propia máquina (loopback). Puedes copiar o regenerar ese token en cualquier momento desde el panel.
+- **No expuesto (v1).** Por seguridad, unas pocas capacidades de alto riesgo se dejan fuera a propósito: ejecutar comandos de shell en la terminal, el navegador integrado, la edición de archivos dentro de la app y la instalación de prerrequisitos del sistema. Todo lo que *gestiona* Specrails está disponible; el acceso directo a la máquina, no.
+
+Puedes desactivar MCP en cualquier momento desde el mismo panel — tu asistente simplemente pierde el acceso y nada más cambia.

package/docs/guide/fr/integrations/5-mcp-server.md

@@ -0,0 +1,74 @@
+# Piloter Specrails depuis n'importe quelle IA (serveur MCP)
+
+Specrails peut s'exposer **lui-même** à n'importe quel assistant IA qui parle le [Model Context Protocol](https://modelcontextprotocol.io) — Claude Desktop, Claude Code, Cursor, Cline, ou votre propre agent. Activez-le, pointez votre assistant vers Specrails, et vous pouvez piloter toute l'app en discutant : *« liste mes projets », « crée une spec pour la connexion sociale dans le projet API », « lance le rail 0 et préviens-moi quand c'est terminé », « combien ai-je dépensé cette semaine ? »*. Votre assistant appelle les outils de Specrails en coulisses, plutôt que de vous faire cliquer partout.
+
+C'est la direction inverse des fonctionnalités plugins et « Mes MCP approuvés » : celles-ci permettent à Specrails d'*utiliser* d'autres serveurs MCP ; ceci permet à d'autres apps d'utiliser **Specrails**.
+
+## L'activer
+
+C'est **désactivé par défaut**. Ouvrez **Paramètres ▸ MCP** et basculez **Activer MCP**. C'est tout — le serveur démarre immédiatement, sans redémarrage.
+
+Vous gardez le contrôle de *ce qu'*une IA externe peut faire grâce à un ensemble de niveaux de permission :
+
+| Niveau | Ce qu'il autorise | Par défaut |
+|---|---|---|
+| **Lecture** | Lister et inspecter les projets, specs, jobs, analyses… | Toujours actif (lorsque MCP est activé) |
+| **Écriture** | Créer et modifier des specs, changer les paramètres et la configuration des rails | Désactivé — à activer |
+| **Lancement d'IA** | Actions qui exécutent une IA et **coûtent de l'argent** (lancer un rail, générer une spec, envoyer un tour de chat) | Désactivé — à activer |
+| **Destructif** | Supprimer des projets/specs/jobs, arrêter un travail en cours | Désactivé — à activer |
+
+Si votre assistant tente quelque chose que couvre un niveau désactivé, Specrails refuse avec un message clair vous indiquant quel niveau activer. Vous pouvez donc commencer en lecture seule et ouvrir exactement ce dont vous avez besoin.
+
+## Connecter votre assistant
+
+Le panneau affiche un bloc de configuration prêt à coller. La voie la plus simple et universelle est le **pont** (« bridge ») embarqué (`specrails-mcp`) : votre assistant l'exécute, et il relaie vers Specrails pour vous. Le pont lit le jeton d'accès localement, donc **le jeton n'apparaît jamais dans la configuration de votre assistant**.
+
+Dans un client comme Claude Desktop ou Cursor, la configuration ressemble à ceci :
+
+```json
+{ "mcpServers": { "specrails": { "command": "specrails-mcp" } } }
+```
+
+Les clients qui prennent en charge les serveurs MCP HTTP distants peuvent à la place pointer directement vers `http://127.0.0.1:4200/api/mcp` avec le jeton du panneau.
+
+Une fois connecté, votre assistant voit environ **18 outils** couvrant toute l'app — projets, specs, rails et jobs, chat/Explore, agents, plugins, Jira, loops, l'explorateur de code, les analyses, les paramètres — plus un outil **guide** intégré qu'il lit en premier afin de comprendre le fonctionnement de Specrails sans que vous ayez à expliquer quoi que ce soit.
+
+## Ce que vous pouvez en faire
+
+Quelques recettes une fois votre assistant connecté. Commencez avec **Lecture** activée, puis activez **Écriture** et **Lancement d'IA** quand vous voulez qu'il crée et lance réellement du travail.
+
+**Transformez le travail de vos autres outils en specs.** Si votre assistant a aussi GitHub, Jira, Gmail ou Slack connectés, il peut amener le travail jusqu'à Specrails pour vous :
+> *« Prends les issues GitHub ouvertes cette semaine étiquetées "bug", crée une spec pour chacune dans le projet API, et lance-les. »*
+>
+> *« Lis mes derniers e-mails de retours clients, regroupe-les par thème, et crée une spec par thème. »*
+
+**Pilote automatique nocturne.** Laissez-le tourner avec l'app dans la zone de notification et revenez à un rapport :
+> *« Voici 12 idées. Transforme chacune en une spec, lance-les trois par trois à travers les rails, surveille chaque job, et demain donne-moi un résumé de ce qui s'est terminé, ce qui a échoué et ce que ça a coûté. »*
+
+Gardez **Destructif** désactivé et il peut construire toute la nuit sans jamais rien supprimer.
+
+**À travers tous vos projets.** Quelque chose que le tableau de bord ne fait pas tout seul :
+> *« Vérifie tous mes projets. Dis-moi lesquels ont des specs dans le backlog sans aucun rail en cours, et démarre la plus prioritaire dans chacun. »*
+
+**Sans les mains pendant que vous codez.** Pilotez Specrails depuis votre éditeur ou à la voix, sans changer de fenêtre :
+> *« Lance le rail 0 en mode ultracode avec Opus pour le ticket #42 et préviens-moi quand c'est terminé. »*
+
+**Interrogez les coûts et l'historique.** Vos analyses, en langage clair :
+> *« Où ai-je le plus dépensé en IA cette semaine, par projet et par modèle ? Montre-moi les cinq tickets les plus coûteux. »*
+
+**Votre point quotidien.**
+> *« Rédige mon point quotidien : quels rails ont tourné hier, ce qui s'est terminé, ce qui a échoué, le coût total — sous forme de puces prêtes à coller dans Slack. »*
+
+**Comprenez le code.** Aucun éditeur nécessaire :
+> *« Quels fichiers le ticket #38 a-t-il touchés ? Résume en une ligne ce qui a changé dans chacun. »*
+
+Parce que votre assistant lit d'abord le guide intégré, vous avez rarement besoin de nommer des outils ou des specs — décrivez le résultat voulu et il trouve les appels à faire.
+
+## Quelques points à connaître
+
+- **Specrails doit être en cours d'exécution.** Le serveur MCP vit à l'intérieur de l'app, donc votre assistant ne peut l'atteindre que tant que Specrails est ouvert. Grâce à la zone de notification, fermer la fenêtre laisse l'app tourner en arrière-plan — seul **Quitter** depuis la zone de notification (barre de menus Mac / zone de notification Windows) l'arrête réellement.
+- **Les actions longues sont diffusées en flux.** Lancer un rail ou générer une spec renvoie une réponse immédiate et se termine en arrière-plan ; votre assistant peut le « surveiller » et vous faire un retour une fois l'action stabilisée.
+- **Sécurité.** Le MCP utilise son propre jeton d'accès, distinct de tout le reste, et n'écoute que sur votre propre machine (boucle locale). Vous pouvez copier ou régénérer ce jeton à tout moment depuis le panneau.
+- **Non exposé (v1).** Par sécurité, quelques capacités à haut risque sont volontairement laissées de côté : exécuter des commandes shell dans le terminal, le navigateur embarqué, l'édition de fichiers dans l'app, et l'installation des prérequis système. Tout ce qui *gère* Specrails est disponible ; l'accès brut à la machine ne l'est pas.
+
+Vous pouvez désactiver MCP à tout moment depuis le même panneau — votre assistant perd simplement l'accès, et rien d'autre ne change.

package/docs/guide/it/integrations/5-mcp-server.md

@@ -0,0 +1,74 @@
+# Controlla Specrails da qualsiasi AI (server MCP)
+
+Specrails può esporre **se stesso** a qualsiasi assistente AI che parli il [Model Context Protocol](https://modelcontextprotocol.io) — Claude Desktop, Claude Code, Cursor, Cline o un tuo agente. Attivalo, punta il tuo assistente verso Specrails e potrai pilotare l'intera app chiacchierando: *"elenca i miei progetti", "crea una spec per il login social nel progetto API", "lancia il rail 0 e dimmi quando ha finito", "quanto ho speso questa settimana?"*. Il tuo assistente richiama gli strumenti di Specrails dietro le quinte, al posto tuo che clicchi qua e là.
+
+Questa è la direzione opposta rispetto alle funzionalità dei plugin e degli "MCP approvati da me": quelle permettono a Specrails di *usare* altri server MCP; questa permette ad altre app di usare **Specrails**.
+
+## Come attivarlo
+
+È **disattivato di default**. Apri **Impostazioni ▸ MCP** e attiva **Abilita MCP**. Fatto — il server si avvia immediatamente, senza riavvii.
+
+Resti tu a controllare *cosa* può fare un'AI esterna tramite una serie di livelli di permesso:
+
+| Livello | Cosa consente | Default |
+|---|---|---|
+| **Lettura** | Elencare e ispezionare progetti, spec, job, analisi… | Sempre attivo (quando l'MCP è abilitato) |
+| **Scrittura** | Creare e modificare spec, cambiare impostazioni e configurazione dei rail | Disattivato — da abilitare |
+| **AI-spawn** | Azioni che eseguono un'AI e **costano denaro** (lanciare un rail, generare una spec, inviare un turno di chat) | Disattivato — da abilitare |
+| **Distruttivo** | Eliminare progetti/spec/job, fermare il lavoro in corso | Disattivato — da abilitare |
+
+Se il tuo assistente prova a fare qualcosa coperto da un livello disattivato, Specrails rifiuta con un messaggio chiaro che ti indica quale livello attivare. Così puoi partire in sola lettura e aprire esattamente ciò che ti serve.
+
+## Collegare il tuo assistente
+
+Il pannello mostra un blocco di configurazione pronto da incollare. Il percorso più semplice e universale è il **bridge** incluso (`specrails-mcp`): il tuo assistente lo esegue e quello fa da tramite verso Specrails per te. Il bridge legge il token di accesso in locale, quindi **il token non compare mai nella configurazione del tuo assistente**.
+
+In un client come Claude Desktop o Cursor, la configurazione si presenta così:
+
+```json
+{ "mcpServers": { "specrails": { "command": "specrails-mcp" } } }
+```
+
+I client che supportano i server MCP HTTP remoti possono invece puntare direttamente a `http://127.0.0.1:4200/api/mcp` con il token preso dal pannello.
+
+Una volta collegato, il tuo assistente vede circa **18 strumenti** che coprono l'intera app — progetti, spec, rail e job, chat/Explore, agenti, plugin, Jira, loop, l'esploratore del codice, le analisi, le impostazioni — più uno strumento **guida** integrato che legge per primo, così capisce come funziona Specrails senza che tu debba spiegargli nulla.
+
+## Cosa puoi farci
+
+Qualche ricetta una volta collegato il tuo assistente. Parti con la **Lettura** attiva, poi accendi **Scrittura** e **AI-spawn** quando vuoi che crei e lanci davvero il lavoro.
+
+**Trasforma il lavoro degli altri tuoi strumenti in spec.** Se il tuo assistente ha collegati anche GitHub, Jira, Gmail o Slack, può portare il lavoro dentro Specrails al posto tuo:
+> *"Prendi le issue GitHub aperte di questa settimana con etichetta 'bug', crea una spec per ognuna nel progetto API e lanciale."*
+>
+> *"Leggi le ultime email di feedback dei clienti, raggruppale per tema e crea una spec per ogni tema."*
+
+**Pilota automatico notturno.** Lascialo in esecuzione con l'app nella barra di sistema e torna a un resoconto:
+> *"Ecco 12 idee. Trasforma ognuna in una spec, lanciale tre alla volta sui rail, tieni d'occhio ogni job e domani dammi un riepilogo di cosa è finito, cosa è fallito e quanto è costato."*
+
+Tieni **Distruttivo** disattivato e potrà lavorare tutta la notte senza mai eliminare nulla.
+
+**Su tutti i tuoi progetti.** Qualcosa che la dashboard da sola non fa:
+> *"Controlla tutti i miei progetti. Dimmi quali hanno spec nel backlog e nessun rail in esecuzione, e avvia in ognuno quella a priorità più alta."*
+
+**Senza mani mentre programmi.** Pilota Specrails dal tuo editor o a voce, senza cambiare finestra:
+> *"Lancia il rail 0 in modalità ultracode con Opus per il ticket #42 e dimmi quando ha finito."*
+
+**Chiedi di costi e cronologia.** Le tue analisi, in linguaggio naturale:
+> *"Dove ho speso di più in AI questa settimana, per progetto e per modello? Mostrami i cinque ticket più costosi."*
+
+**Il tuo standup quotidiano.**
+> *"Scrivi il mio standup: quali rail hanno girato ieri, cosa è stato completato, cosa è fallito, costo totale — come elenco puntato pronto da incollare in Slack."*
+
+**Capire il codice.** Senza bisogno di un editor:
+> *"Quali file ha toccato il ticket #38? Riassumi in una riga cosa è cambiato in ognuno."*
+
+Dato che il tuo assistente legge per prima la guida integrata, raramente devi nominare strumenti o spec — descrivi il risultato e lui calcola le chiamate da fare.
+
+## Qualche cosa da sapere
+
+- **Specrails deve essere in esecuzione.** Il server MCP vive dentro l'app, quindi il tuo assistente può raggiungerlo solo finché Specrails è aperto. Grazie all'icona nella barra di sistema, chiudere la finestra lo mantiene attivo in background — solo **Esci** dall'icona (barra dei menu su Mac / barra di sistema su Windows) lo ferma davvero.
+- **Le azioni lunghe trasmettono in streaming.** Lanciare un rail o generare una spec restituisce subito il controllo e termina in background; il tuo assistente può "tenerlo d'occhio" e riferirti quando si conclude.
+- **Sicurezza.** L'MCP usa un proprio token di accesso, separato da tutto il resto, e ascolta soltanto sulla tua macchina (loopback). Puoi copiare o rigenerare quel token in qualsiasi momento dal pannello.
+- **Non esposto (v1).** Per sicurezza, alcune capacità ad alto rischio sono volutamente escluse: eseguire comandi shell nel terminale, il browser integrato, la modifica dei file nell'app e l'installazione dei prerequisiti di sistema. Tutto ciò che *gestisce* Specrails è disponibile; l'accesso diretto alla macchina no.
+
+Puoi disattivare l'MCP in qualsiasi momento dallo stesso pannello — il tuo assistente perde semplicemente l'accesso e nient'altro cambia.

package/docs/guide/ja/integrations/5-mcp-server.md

@@ -0,0 +1,74 @@
+# 任意の AI から Specrails を操作する（MCP サーバー）
+
+Specrails は、[Model Context Protocol](https://modelcontextprotocol.io) を話す任意の AI アシスタント（Claude Desktop、Claude Code、Cursor、Cline、あるいは自作のエージェント）に対して、**自分自身**を公開できます。これをオンにしてアシスタントを Specrails に向ければ、チャットするだけでアプリ全体を操作できます。たとえば *「プロジェクト一覧を見せて」「API プロジェクトにソーシャルログインのスペックを作って」「レール 0 を起動して、終わったら教えて」「今週はいくら使った？」* といった具合です。あなたがあちこちクリックする代わりに、アシスタントが裏側で Specrails のツールを呼び出します。
+
+これは、プラグインや「My approved MCPs」機能とは逆方向の働きをします。それらは Specrails が*ほかの* MCP サーバーを*使う*ためのものですが、こちらは他のアプリに **Specrails** を使わせるためのものです。
+
+## オンにする
+
+これは**デフォルトでオフ**です。**Settings ▸ MCP** を開いて **Enable MCP** を切り替えてください。それだけです — サーバーは即座に起動し、再起動は不要です。
+
+外部の AI がどんな操作をできるかは、一連の権限ティアで*あなた*がコントロールできます。
+
+| ティア | 許可される内容 | デフォルト |
+|---|---|---|
+| **Read**（読み取り） | プロジェクト、スペック、ジョブ、アナリティクスなどの一覧表示と確認 | 常時オン（MCP が有効なとき） |
+| **Write**（書き込み） | スペックの作成・編集、設定やレール構成の変更 | オフ — 任意で有効化 |
+| **AI-spawn**（AI 起動） | AI を走らせて**お金がかかる**操作（レールの起動、スペックの生成、チャットターンの送信） | オフ — 任意で有効化 |
+| **Destructive**（破壊的操作） | プロジェクト／スペック／ジョブの削除、実行中の作業の停止 | オフ — 任意で有効化 |
+
+無効なティアに該当する操作をアシスタントが試みると、Specrails はそれを拒否し、どのティアをオンにすればよいかを明確なメッセージで知らせます。ですから、まずは読み取り専用から始め、必要なものだけをぴったり開放できます。
+
+## アシスタントを接続する
+
+パネルには、そのまま貼り付けられる構成ブロックが表示されます。最もシンプルで汎用的な方法は、同梱の**ブリッジ**（`specrails-mcp`）を使うことです。アシスタントがこれを実行し、ブリッジがあなたに代わって Specrails に中継します。ブリッジはアクセストークンをローカルで読み取るので、**トークンがアシスタントの設定に現れることはありません**。
+
+Claude Desktop や Cursor のようなクライアントでは、設定は次のようになります。
+
+```json
+{ "mcpServers": { "specrails": { "command": "specrails-mcp" } } }
+```
+
+リモートの HTTP MCP サーバーに対応しているクライアントなら、代わりにパネルのトークンを使って `http://127.0.0.1:4200/api/mcp` を直接指すこともできます。
+
+接続が完了すると、アシスタントにはアプリ全体をカバーする約 **18 個のツール**が見えるようになります — プロジェクト、スペック、レールとジョブ、チャット／Explore、エージェント、プラグイン、Jira、ループ、コードエクスプローラー、アナリティクス、設定など。さらに、最初に読み込む組み込みの**ガイド**ツールも含まれているので、あなたが何も説明しなくても、アシスタントは Specrails の仕組みを理解できます。
+
+## これで何ができるか
+
+アシスタントを接続したあとの、いくつかのレシピを紹介します。まずは **Read**（読み取り）をオンにして始め、実際に作業を作成・起動させたくなったら **Write**（書き込み）と **AI-spawn**（AI 起動）をオンにしてください。
+
+**ほかのツールにある作業をスペックに変える。** アシスタントが GitHub、Jira、Gmail、Slack にも接続されていれば、その作業をあなたの代わりに Specrails へ持ち込めます。
+> *「今週の 'bug' ラベルの付いた未解決の GitHub Issue を取り込んで、API プロジェクトにそれぞれスペックを作って、起動して。」*
+>
+> *「最新の顧客フィードバックのメールを読んで、テーマごとにまとめて、テーマごとにスペックを 1 つずつ作って。」*
+
+**夜通しのオートパイロット。** アプリをトレイに置いたまま走らせておけば、戻ってきたときにはレポートができています。
+> *「アイデアが 12 個あります。それぞれをスペックにして、レールで 3 つずつ起動して、すべてのジョブを見守って、明日になったら何が完了して、何が失敗して、いくらかかったかをまとめて教えて。」*
+
+**Destructive**（破壊的操作）をオフにしておけば、何ひとつ削除することなく一晩中ビルドを続けられます。
+
+**すべてのプロジェクトをまたいで。** ダッシュボードだけでは単独でできないことです。
+> *「私のプロジェクトを全部チェックして。バックログにスペックがあるのにレールが 1 つも動いていないものを教えて、それぞれで最も優先度の高いものを 1 つ起動して。」*
+
+**コーディング中も手を止めずに。** エディタからでも音声でも、ウィンドウを切り替えずに Specrails を操作できます。
+> *「チケット #42 のためにレール 0 を Opus で ultracode モードで起動して、終わったら教えて。」*
+
+**コストと履歴について尋ねる。** あなたのアナリティクスを、普通の言葉で。
+> *「今週、AI に一番お金を使ったのはどこ？ プロジェクト別とモデル別で。最もコストのかかったチケットを 5 つ見せて。」*
+
+**毎日のスタンドアップ。**
+> *「私のスタンドアップを書いて。昨日どのレールが走って、何が完了して、何が失敗して、合計コストはいくらか — Slack にそのまま貼れる箇条書きで。」*
+
+**コードを理解する。** エディタは不要です。
+> *「チケット #38 がどのファイルに触れたか教えて。それぞれ何が変わったかを 1 行で要約して。」*
+
+アシスタントはまず組み込みのガイドを読むので、ツールやスペックの名前をあなたが指定する必要はめったにありません — 望む結果を伝えれば、アシスタントが呼び出しを組み立ててくれます。
+
+## 知っておきたいこと
+
+- **Specrails が起動している必要があります。** MCP サーバーはアプリの内部に存在するため、アシスタントが到達できるのは Specrails が開いている間だけです。トレイのおかげで、ウィンドウを閉じてもバックグラウンドで動き続けます — 実際に停止させるには、トレイ（Mac のメニューバー／Windows のシステムトレイ）から **Exit** を選ぶ必要があります。
+- **長い操作はストリームされます。** レールの起動やスペックの生成はすぐに戻り、バックグラウンドで完了します。アシスタントはそれを「見守り」、決着したときに報告してくれます。
+- **セキュリティ。** MCP は他のすべてとは分離された専用のアクセストークンを使い、あなた自身のマシン上（ループバック）でのみ待ち受けます。このトークンはパネルからいつでもコピー、または再生成できます。
+- **公開されていないもの（v1）。** 安全のため、いくつかの高リスクな機能は意図的に除外されています。ターミナルでのシェルコマンド実行、組み込みブラウザ、アプリ内でのファイル編集、システム前提条件のインストールなどです。Specrails を*管理する*ものはすべて利用できますが、マシンへの生のアクセスはできません。
+
+MCP は同じパネルからいつでも無効にできます — アシスタントはアクセスを失うだけで、それ以外は何も変わりません。

package/docs/guide/pt/integrations/5-mcp-server.md

@@ -0,0 +1,74 @@
+# Controlar o Specrails a partir de qualquer IA (servidor MCP)
+
+O Specrails pode expor-se **a si próprio** a qualquer assistente de IA que fale o [Model Context Protocol](https://modelcontextprotocol.io) — Claude Desktop, Claude Code, Cursor, Cline ou o seu próprio agente. Ative-o, aponte o seu assistente para o Specrails e poderá conduzir a app inteira conversando: *"lista os meus projetos", "cria uma spec para login social no projeto da API", "lança o rail 0 e avisa-me quando terminar", "quanto gastei esta semana?"*. O seu assistente invoca as ferramentas do Specrails nos bastidores em vez de ser você a clicar por toda a parte.
+
+Este é o sentido oposto das funcionalidades de plugins e "Os meus MCPs aprovados": essas permitem que o Specrails *use* outros servidores MCP; esta permite que outras apps usem o **Specrails**.
+
+## Como ativar
+
+Está **desativado por predefinição**. Abra **Definições ▸ MCP** e ligue o **Enable MCP**. É só isso — o servidor arranca imediatamente, sem reiniciar.
+
+Mantém o controlo *do que* uma IA externa pode fazer através de um conjunto de níveis de permissão:
+
+| Nível | O que permite | Predefinição |
+|---|---|---|
+| **Leitura** | Listar e inspecionar projetos, specs, trabalhos, análises… | Sempre ativo (quando o MCP está ativado) |
+| **Escrita** | Criar e editar specs, alterar definições e configuração de rails | Desativado — ativação opcional |
+| **Invocação de IA** | Ações que correm uma IA e **custam dinheiro** (lançar um rail, gerar uma spec, enviar um turno de chat) | Desativado — ativação opcional |
+| **Destrutivo** | Eliminar projetos/specs/trabalhos, parar trabalho em curso | Desativado — ativação opcional |
+
+Se o seu assistente tentar algo abrangido por um nível desativado, o Specrails recusa com uma mensagem clara que lhe diz qual o nível a ativar. Assim, pode começar apenas em modo de leitura e abrir exatamente aquilo de que precisa.
+
+## Ligar o seu assistente
+
+O painel mostra um bloco de configuração pronto a colar. O caminho mais simples e universal é a **ponte** (bridge) incorporada (`specrails-mcp`): o seu assistente executa-a e ela retransmite para o Specrails por si. A ponte lê o token de acesso localmente, por isso **o token nunca aparece na configuração do seu assistente**.
+
+Num cliente como o Claude Desktop ou o Cursor, a configuração tem este aspeto:
+
+```json
+{ "mcpServers": { "specrails": { "command": "specrails-mcp" } } }
+```
+
+Os clientes que suportam servidores MCP HTTP remotos podem, em alternativa, apontar diretamente para `http://127.0.0.1:4200/api/mcp` com o token do painel.
+
+Uma vez ligado, o seu assistente vê cerca de **18 ferramentas** que cobrem a app inteira — projetos, specs, rails e trabalhos, chat/Explore, agentes, plugins, Jira, loops, o explorador de código, análises, definições — mais uma ferramenta de **guia** incorporada que lê primeiro, para que perceba como o Specrails funciona sem que lhe explique seja o que for.
+
+## O que pode fazer com ele
+
+Algumas receitas assim que o seu assistente estiver ligado. Comece com a **Leitura** ativa e, depois, ligue a **Escrita** e a **Invocação de IA** quando quiser que ele crie e lance trabalho de verdade.
+
+**Transforme em specs o trabalho das suas outras ferramentas.** Se o seu assistente também tiver o GitHub, o Jira, o Gmail ou o Slack ligados, ele pode trazer esse trabalho para o Specrails por si:
+> *"Pega nas issues abertas do GitHub desta semana com a etiqueta 'bug', cria uma spec para cada uma no projeto da API e lança-as."*
+>
+> *"Lê os meus emails de feedback de clientes mais recentes, agrupa-os por tema e cria uma spec por tema."*
+
+**Piloto automático durante a noite.** Deixe-o a correr com a app no tabuleiro (tray) e volte para encontrar um relatório:
+> *"Aqui estão 12 ideias. Transforma cada uma numa spec, lança-as três de cada vez pelos rails, vigia todos os trabalhos e amanhã dá-me um resumo do que terminou, do que falhou e do que custou."*
+
+Mantenha o **Destrutivo** desativado e ele pode trabalhar a noite toda sem nunca eliminar nada.
+
+**Em todos os seus projetos.** Algo que o painel não faz por si só:
+> *"Verifica todos os meus projetos. Diz-me quais têm specs no backlog e nenhum rail a correr, e arranca o de prioridade mais alta em cada um."*
+
+**Sem usar as mãos enquanto programa.** Conduza o Specrails a partir do seu editor ou por voz, sem trocar de janela:
+> *"Lança o rail 0 em modo ultracode com o Opus para o ticket #42 e avisa-me quando estiver pronto."*
+
+**Pergunte sobre custos e histórico.** As suas análises, em linguagem simples:
+> *"Onde gastei mais em IA esta semana, por projeto e por modelo? Mostra-me os cinco tickets mais caros."*
+
+**O seu standup diário.**
+> *"Escreve o meu standup: que rails correram ontem, o que terminou, o que falhou, o custo total — em tópicos prontos a colar no Slack."*
+
+**Perceba o código.** Sem precisar de editor:
+> *"Que ficheiros é que o ticket #38 tocou? Resume numa linha o que mudou em cada um."*
+
+Como o seu assistente lê primeiro o guia incorporado, raramente precisa de nomear ferramentas ou specs — descreva o resultado e ele descobre as chamadas certas.
+
+## Algumas coisas a saber
+
+- **O Specrails tem de estar a correr.** O servidor MCP vive dentro da app, por isso o seu assistente só lhe consegue chegar enquanto o Specrails está aberto. Graças ao tabuleiro (tray), fechar a janela mantém-no a correr em segundo plano — só o **Exit** a partir do tabuleiro (barra de menus no Mac / área de notificação no Windows) é que efetivamente o para.
+- **As ações longas transmitem em fluxo.** Lançar um rail ou gerar uma spec devolve resultado de imediato e termina em segundo plano; o seu assistente pode "vigiá-lo" e relatar quando estabilizar.
+- **Segurança.** O MCP usa o seu próprio token de acesso, separado de tudo o resto, e escuta apenas na sua própria máquina (loopback). Pode copiar ou regenerar esse token a qualquer momento a partir do painel.
+- **Não exposto (v1).** Por segurança, algumas capacidades de risco elevado são deliberadamente deixadas de fora: correr comandos de shell no terminal, o browser embutido, a edição de ficheiros dentro da app e a instalação de pré-requisitos do sistema. Tudo o que *gere* o Specrails está disponível; o acesso direto à máquina não está.
+
+Pode desativar o MCP a qualquer momento a partir do mesmo painel — o seu assistente simplesmente perde o acesso, e mais nada muda.

package/docs/guide/zh/integrations/5-mcp-server.md

@@ -0,0 +1,74 @@
+# 从任意 AI 操控 Specrails（MCP 服务器）
+
+Specrails 可以把**自己**暴露给任何会说 [Model Context Protocol](https://modelcontextprotocol.io) 的 AI 助手——Claude Desktop、Claude Code、Cursor、Cline，或者你自己的 agent。打开这个功能，把你的助手指向 Specrails，你就能靠聊天来驱动整个应用：*「列出我的项目」「在 API 项目里为社交登录创建一份规格」「启动 rail 0，跑完了告诉我」「我这周花了多少钱？」*。你的助手会在幕后调用 Specrails 的工具，而不用你点来点去。
+
+这和插件以及「My approved MCPs」功能的方向正好相反：那些功能是让 Specrails 去*使用*别的 MCP 服务器；而这个功能是让别的应用来使用 **Specrails**。
+
+## 打开它
+
+它**默认是关闭的**。打开 **Settings ▸ MCP**，把 **Enable MCP** 拨开。就这样——服务器会立即启动，无需重启。
+
+通过一组权限层级，你可以始终掌控外部 AI 能透过它做*哪些*事：
+
+| 层级 | 它允许什么 | 默认 |
+|---|---|---|
+| **Read** | 列出并查看项目、规格、任务、分析数据等等…… | 始终开启（在 MCP 启用时） |
+| **Write** | 创建和编辑规格、修改设置与 rail 配置 | 关闭——需手动开启 |
+| **AI-spawn** | 会运行 AI 并**产生费用**的操作（启动一条 rail、生成一份规格、发送一次聊天） | 关闭——需手动开启 |
+| **Destructive** | 删除项目 / 规格 / 任务，停止正在运行的工作 | 关闭——需手动开启 |
+
+如果你的助手试图做某个被禁用层级所涵盖的事，Specrails 会拒绝，并给出一条清晰的提示，告诉你该打开哪个层级。所以你可以先从只读开始，再精确地放开你需要的部分。
+
+## 连接你的助手
+
+面板会显示一段可直接粘贴的配置块。最简单、最通用的方式是使用内置的**桥接**（`specrails-mcp`）：你的助手运行它，由它代你转发到 Specrails。这个桥接会在本地读取访问令牌，所以**令牌绝不会出现在你助手的配置里**。
+
+在像 Claude Desktop 或 Cursor 这样的客户端里，配置看起来是这样：
+
+```json
+{ "mcpServers": { "specrails": { "command": "specrails-mcp" } } }
+```
+
+支持远程 HTTP MCP 服务器的客户端，则可以直接指向 `http://127.0.0.1:4200/api/mcp`，并配上面板里的令牌。
+
+一旦连上，你的助手会看到大约 **18 个工具**，覆盖整个应用——项目、规格、rail 和任务、聊天 / Explore、agent、插件、Jira、loop、代码浏览器、分析、设置——外加一个内置的**指南（guide）**工具，它会先读这个工具，从而无需你解释任何东西就能理解 Specrails 是怎么运作的。
+
+## 你能用它做些什么
+
+连上助手后，这里有几个上手的小配方。先打开 **Read**，等你真想让它创建并启动工作时，再打开 **Write** 和 **AI-spawn**。
+
+**把你其他工具里的工作变成规格。** 如果你的助手还连着 GitHub、Jira、Gmail 或 Slack，它就能替你把这些工作搬进 Specrails：
+> *「把本周打了 'bug' 标签的开放 GitHub issue 拿过来，在 API 项目里为每个创建一份规格，然后启动它们。」*
+>
+> *「读一下我最近的客户反馈邮件，按主题分组，每个主题创建一份规格。」*
+
+**通宵自动驾驶。** 让应用待在托盘里跑着，回来时就能拿到一份报告：
+> *「这里有 12 个点子。把每个变成一份规格，在 rail 上每次三个地启动它们，盯着每一个任务，明天给我一份总结：哪些完成了、哪些失败了、各花了多少钱。」*
+
+只要让 **Destructive** 保持关闭，它就能跑一整夜而绝不会删掉任何东西。
+
+**横跨你所有的项目。** 这是 dashboard 自己做不到的事：
+> *「检查我所有的项目。告诉我哪些在 backlog 里有规格却没有 rail 在跑，并在每个项目里启动优先级最高的那一个。」*
+
+**写代码时不用动手。** 从你的编辑器里或用语音来驱动 Specrails，无需切换窗口：
+> *「用 Opus、以 ultracode 模式在 rail 0 上为任务 #42 启动一条 rail，跑完了告诉我。」*
+
+**询问费用和历史。** 用大白话查你的分析数据：
+> *「我这周在 AI 上花得最多的是哪里，按项目、按模型分别列出来？给我看最贵的五个任务。」*
+
+**你的每日站会。**
+> *「帮我写站会汇报：昨天哪些 rail 跑了、哪些完成了、哪些失败了、总花费多少——做成可以直接粘进 Slack 的要点列表。」*
+
+**读懂代码。** 不需要编辑器：
+> *「任务 #38 改动了哪些文件？用一句话总结每个文件改了什么。」*
+
+因为你的助手会先读那份内置指南，所以你很少需要点名具体的工具或规格——描述你想要的结果，它就能算出该调用哪些工具。
+
+## 几点须知
+
+- **Specrails 必须在运行。** MCP 服务器活在应用内部，所以只有在 Specrails 开着的时候，你的助手才能连上它。多亏了托盘，关掉窗口它仍会在后台运行——只有从托盘（Mac 菜单栏 / Windows 系统托盘）选择 **Exit**，才会真正把它停掉。
+- **长任务会流式返回。** 启动一条 rail 或生成一份规格会立即返回，并在后台完成；你的助手可以「盯着」它，等它尘埃落定再回来报告。
+- **安全。** MCP 使用它自己专属的访问令牌，与其他一切都分开，并且只监听你自己的机器（本地回环）。你随时可以从面板里复制或重新生成那个令牌。
+- **未暴露的部分（v1）。** 出于安全考虑，有几项高风险能力被刻意排除在外：在终端里执行 shell 命令、内嵌浏览器、应用内文件编辑，以及安装系统先决条件。一切*管理* Specrails 的能力都开放可用；对机器的原始访问则不开放。
+
+你随时可以从同一个面板禁用 MCP——你的助手只是会失去访问权，其余一切照旧。