specrails-desktop 2.16.0 → 2.18.0

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/pt/integrations/6-agent-chat.md

@@ -0,0 +1,64 @@
+# Comande o Specrails conversando (Agent Chat)
+
+O **Agent Chat** é um copiloto que vive *dentro* do Specrails e pode conduzir a aplicação inteira por você. Em vez de ficar clicando por projetos, specs, trilhos e análises, basta pedir: *«quantos jobs deram certo esta semana?»*, *«cria uma spec para o login social no projeto da API»*, *«lança os três tickets de maior prioridade e me avisa quando terminarem»*. Ele realiza o trabalho chamando as próprias ferramentas do Specrails — as mesmas que o [servidor MCP](./5-mcp-server.md) expõe — enquanto você vê o painel se atualizar ao vivo por trás dele.
+
+> **Não confunda com os agentes do pipeline.** A seção *Agentes* (Architect → Developer → Reviewer) trata de *como um trilho implementa uma spec*. O **Agent Chat** é um único assistente que *opera a própria aplicação*. Coisas diferentes, mesma palavra.
+
+## Como abrir
+
+Há uma **bolha** flutuante na parte inferior da janela — clique nela para abrir o painel, ou pressione **⌘⇧A** (**Ctrl+Shift+A** no Windows/Linux) de qualquer lugar. O painel é uma janela de verdade que você pode mover, redimensionar, maximizar e devolver à bolha; ele lembra onde você o deixou.
+
+Ele é **não modal de propósito**: o painel por trás continua vivo, então quando o agente lança um trilho ou cria uma spec você o vê aparecer em tempo real — não está olhando para uma tela congelada.
+
+## Pré-requisito: o servidor MCP
+
+O Agent Chat opera a aplicação através do **servidor MCP do Specrails** integrado, então ele precisa estar ativo. Se não estiver, o painel abre com um banner de **Ativar Specrails MCP** de um clique — pressione-o e está pronto (sem reiniciar). Veja [Controle o Specrails a partir de qualquer IA](./5-mcp-server.md) para os detalhes; nada é instalado, tudo é local na sua máquina.
+
+## Escolher sobre o que ele trabalha
+
+O cabeçalho tem um **seletor de projeto** (como o do Cursor). Escolha um projeto e tudo o que você pedir fica restrito a ele — *«lança os de alta prioridade»* se resolve contra esse projeto. Deixe-o em **Início** e o agente trabalha sobre toda a sua configuração: ele pode listar ou criar projetos e responder perguntas que abrangem tudo. Se você pedir algo específico de um projeto estando em Início, ele vai perguntar qual (ou se oferecer para criar um) em vez de adivinhar.
+
+Escolher um projeto aqui **não** move o seu painel — o alvo do agente e o que você está vendo são independentes.
+
+## Provedor e modelo
+
+Logo acima da caixa de mensagem você escolhe o **provedor** (Claude, Codex ou Gemini) e o seu **modelo**. Cada provedor tem a sua própria lista de modelos, e trocar de provedor inicia uma sessão nova com o modelo padrão daquele provedor — assim você pode, por exemplo, conduzir a aplicação com o Claude e passar para o Codex em outra conversa sem que nada se misture.
+
+## Níveis de permissão — a rédea está com você
+
+O agente pode mexer na aplicação inteira, então você decide quanta liberdade ele tem por meio de um **nível** que você muda ao vivo pressionando **Shift+Tab** (o mesmo ciclo que o Claude Code usa). Cada nível inclui tudo o que está abaixo:
+
+| Nível | O que ele pode fazer |
+|---|---|
+| 👀 **Observa** | Somente leitura — listar e inspecionar projetos, specs, jobs, análises. Nada muda. |
+| ✍️ **Edita** | O acima **+** criar e editar (specs, ajustes, configuração de trilhos) — mudanças reversíveis. |
+| ⚡ **Opera** | O acima **+** lançar trabalho de IA que **custa dinheiro** (trilhos, geração de specs). |
+| 🔥 **Autônomo** | O acima **+** apagar e parar coisas — ações irreversíveis. |
+
+Comece em **Observa** e suba o nível apenas quando quiser que o agente aja. Se ele tentar algo acima do nível atual, ele para e diz exatamente qual nível ativar — nunca contorna o limite. Isso é separado dos níveis de Ajustes ▸ MCP, que regem os assistentes *externos*; o nível aqui é só para este agente interno da aplicação.
+
+## Algumas coisas que você pode pedir
+
+Quando estiver em **Opera**, experimente:
+
+> *«Lista todas as specs pendentes do projeto da API e depois lança as três de maior prioridade em trilhos separados e fica de olho nelas.»*
+>
+> *«Quanto gastei esta semana, detalhado por projeto?»*
+>
+> *«Cria uma spec para um botão de alternância de modo escuro no projeto web, com Contract Layer.»*
+>
+> *«Algo falhou no último lote — encontra os jobs que falharam e resume o porquê.»*
+
+As respostas chegam de forma fluida e já formatadas (títulos, tabelas, listas), cada uma com um pequeno botão de **copiar**. Uma etiqueta de status embaixo mostra o que o agente está fazendo agora — *Pensando…*, *MCP · jobs*, *Terminal* — para que você sempre saiba o estado dele.
+
+## Detalhes práticos
+
+- **Histórico de prompts.** Com a caixa vazia, pressione **↑**/**↓** para percorrer o que você perguntou antes (mostrado esmaecido enquanto rola); comece a digitar para editar, ou pressione Enter para enviar.
+- **Minimize sem perder nada.** Clique no ✕ para devolver o painel à bolha — a conversa continua rodando. Reabra e você chega na mensagem mais recente; nada é redigitado.
+- **Nova conversa.** O botão **+** inicia um fio limpo; o histórico vive no nível da aplicação, acima de qualquer projeto individual.
+
+## Algumas coisas para saber
+
+- **Opera e Autônomo custam dinheiro** porque executam IA. O agente destaca as ações que geram custo antes de fazê-las; mantenha o nível em Observa ou Edita se você só quer olhar e organizar.
+- **O agente é de toda a aplicação**, não está atrelado ao projeto que você tem aberto — é por isso que ele tem o próprio seletor e o histórico dele não é por projeto.
+- **Ele é tão capaz quanto o MCP permitir.** Se uma área inteira parecer bloqueada, verifique se o servidor MCP está ativado.

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——你的助手只是会失去访问权，其余一切照旧。

package/docs/guide/zh/integrations/6-agent-chat.md

@@ -0,0 +1,64 @@
+# 用对话操作 Specrails（Agent Chat）
+
+**Agent Chat** 是一个住在 Specrails *内部*的副驾驶，可以替你驱动整个应用。你不必再在项目、规格、轨道和分析之间来回点击，只需开口就行：*「这周有多少任务成功了？」*、*「在 API 项目里为社交登录创建一份规格」*、*「启动优先级最高的三个工单，完成后告诉我」*。它通过调用 Specrails 自己的工具来完成工作——正是 [MCP 服务器](./5-mcp-server.md)所暴露的那些工具——与此同时你能看到后面的仪表盘实时更新。
+
+> **不要与流水线智能体混淆。** *智能体*板块（Architect → Developer → Reviewer）讲的是*轨道如何实现一份规格*。而 **Agent Chat** 是一个*操作应用本身*的单一助手。两回事，同一个词。
+
+## 如何打开
+
+窗口底部有一个漂浮的**气泡**——点击它即可打开面板，或在任何地方按 **⌘⇧A**（Windows/Linux 上为 **Ctrl+Shift+A**）。面板是一个真正的窗口，你可以移动、缩放、最大化，也可以把它收回气泡；它会记住你上次放的位置。
+
+它**特意设计为非模态**：后面的仪表盘保持鲜活，所以当智能体启动一条轨道或创建一份规格时，你能实时看到它出现——你面对的不是一块冻结的屏幕。
+
+## 前提条件：MCP 服务器
+
+Agent Chat 通过内嵌的 **Specrails MCP 服务器**来驱动应用，因此它必须处于开启状态。如果没有开启，面板会打开并显示一个一键式的**启用 Specrails MCP** 横幅——按一下即可就绪（无需重启）。详情见[从任意 AI 控制 Specrails](./5-mcp-server.md)；不安装任何东西，一切都在你本机本地运行。
+
+## 选择它作用的对象
+
+标题栏有一个**项目选择器**（就像 Cursor 的那样）。选定一个项目，你提出的一切都会限定在它之内——*「启动高优先级的那些」*会针对那个项目来解析。把它留在**首页**，智能体就在你的整套配置上工作：它可以列出或创建项目，并回答涵盖全局的问题。如果你在首页却问了某个项目专属的事情，它会反问你是哪个项目（或主动提议创建一个），而不是瞎猜。
+
+在这里选择项目**不会**移动你的仪表盘——智能体的目标和你正在看的内容是彼此独立的。
+
+## 提供方与模型
+
+在消息框正上方，你可以选择**提供方**（Claude、Codex 或 Gemini）及其**模型**。每个提供方都有各自的模型清单，切换提供方会以该提供方的默认模型开启一段全新会话——因此你可以，比如说，用 Claude 驱动应用，再切到 Codex 进行另一段对话，两者互不串扰。
+
+## 权限级别——缰绳在你手里
+
+智能体可以触及整个应用，因此由你来决定给它多大的自由，方法是按 **Shift+Tab** 实时切换的一个**级别**（与 Claude Code 使用的是同一套循环）。每个级别都包含其下方的一切：
+
+| 级别 | 它能做什么 |
+|---|---|
+| 👀 **观察** | 只读——列出并查看项目、规格、任务、分析。什么都不会改变。 |
+| ✍️ **编辑** | 以上 **+** 创建和编辑（规格、设置、轨道配置）——可撤销的改动。 |
+| ⚡ **操作** | 以上 **+** 启动**会产生费用**的 AI 工作（轨道、规格生成）。 |
+| 🔥 **自主** | 以上 **+** 删除和停止各种东西——不可逆的操作。 |
+
+从**观察**开始，只有当你想让智能体动手时才提升级别。如果它尝试超出当前级别的操作，它会停下来，并准确告诉你需要切换到哪个级别——它绝不会绕过限制。这与 设置 ▸ MCP 的分级是相互独立的，后者管辖的是*外部*助手；这里的级别只针对这个应用内的智能体。
+
+## 一些可以让它做的事
+
+进入**操作**后，试试：
+
+> *「列出 API 项目里所有待办规格，然后把优先级最高的三个分别放到独立的轨道上启动并盯着它们。」*
+>
+> *「我这周花了多少钱，按项目拆分一下？」*
+>
+> *「在 web 项目里为深色模式开关创建一份规格，带上 Contract Layer。」*
+>
+> *「上一批里有东西失败了——找出失败的任务并总结原因。」*
+
+回复会顺滑地流式呈现，并已排版落地（标题、表格、列表），每一段都带一个小小的**复制**按钮。底部的状态标签会显示智能体此刻正在做什么——*思考中……*、*MCP · jobs*、*Terminal*——让你随时了解它的状态。
+
+## 贴心细节
+
+- **提示词历史。** 在输入框为空时，按 **↑**/**↓** 浏览你之前问过的内容（滚动时以淡化样式显示）；开始输入即可编辑，或按回车发送。
+- **最小化，而不丢失。** 点击 ✕ 把面板收回气泡——对话仍在继续运行。重新打开时你会落在最新一条消息上；无需重新输入任何内容。
+- **新建对话。** **+** 按钮开启一段全新的线程；历史记录存在于整个应用层面，凌驾于任何单个项目之上。
+
+## 一些需要知道的事
+
+- **操作和自主会产生费用**，因为它们运行 AI。智能体会在执行会产生费用的操作前把它们摆到明面上；如果你只想查看和整理，就把级别保持在观察或编辑。
+- **智能体是全应用范围的**，并不绑定于你当前打开的项目——这正是它拥有自己的选择器、且历史记录不按项目区分的原因。
+- **它的能力上限取决于 MCP 允许的范围。** 如果整个区域看起来都被禁用，请检查 MCP 服务器是否已启用。

package/docs/mcp.md

@@ -0,0 +1,249 @@
+# The Specrails MCP server
+
+Specrails Desktop can expose itself to **any MCP client** — Claude Desktop,
+Claude Code, Cursor, or your own agent — as a local
+[Model Context Protocol](https://modelcontextprotocol.io) server. Turn it on
+and an external LLM can drive the whole dashboard: list your projects, read and
+create specs, launch the AI pipeline, watch jobs settle, inspect analytics, and
+more — through ~18 well-described tools instead of clicking around the UI.
+
+> **Just want to get going?** Open **Settings ▸ MCP**, flip **Enable MCP** on,
+> click **Copy client config**, and paste it into your MCP client. By default
+> only **read** actions are allowed; turn on the **Write** / **AI-spawn** /
+> **Destructive** tiers when you want the agent to actually change things or
+> spend money. Everything below is detail for when you need it.
+
+This is the **app talking to an outside agent** — the opposite direction from
+the [Serena plugin](running-pipelines.md#plugins) or
+`codex mcp add`, where Specrails *consumes* an MCP server. Here Specrails *is*
+the server.
+
+The MCP server is **off by default** and entirely local: it listens only on
+loopback (`127.0.0.1`), is authenticated by a token separate from the app's
+master token, and serves nothing until you explicitly enable it in Settings.
+
+## What the MCP exposes
+
+When enabled, the server registers a compact catalog of **domain-facade tools**
+plus a few **meta tools**, a set of read-only **resources**, and a self-contained
+**guide** an LLM can read to learn the platform with no prior knowledge.
+
+### Tools (~18)
+
+Each domain is a single tool with an `action` enum, rather than dozens of
+narrow tools — so the catalog stays small and an agent discovers actions by
+reading one description. The tools are:
+
+| Tool | What it covers |
+|---|---|
+| `specrails_projects` | List / resolve projects; unregister (destructive) |
+| `specrails_specs` | The spec/ticket backlog: list, get, create, update, delete, drafts, AI generate, AI-edit, Contract Refine, SMASH, per-ticket spend |
+| `specrails_rails` | Assign tickets to a rail, configure it, and launch the pipeline |
+| `specrails_jobs` | Inspect, stream, and stop pipeline jobs |
+| `specrails_chat` | Explore / sidebar chat conversations and turns |
+| `specrails_agents` | Agent profiles and the agents catalog (Claude-only features) |
+| `specrails_plugins` | The per-project plugin marketplace (install / verify / uninstall) |
+| `specrails_jira` | The Jira integration (connect, sync, outbox) |
+| `specrails_loops` | Saved loop workflows |
+| `specrails_code` | The read-only code explorer (tree, file, summaries, provenance) |
+| `specrails_setup` | Add-project setup wizard surface |
+| `specrails_analytics` | Per-project spending analytics + budget |
+| `specrails_settings` | App-level settings |
+| `specrails_watch` | Await the real result of an async (cost-incurring) action |
+| `specrails_guide` | Returns the platform guide — read this first |
+| `specrails_search` | Find the right tool/action for an intent |
+| `specrails_describe` | Full description + input schema for a named tool |
+| `specrails_select_project` | Set an active project so later calls can omit `projectId` |
+
+Almost every domain tool is **project-scoped** and takes a `projectId`. Calling
+`specrails_select_project` first lets later calls omit it.
+
+### Resources
+
+Read-only state is also exposed as MCP **resources** so a client can fetch it
+without a tool call:
+
+- `specrails://guide` — the platform guide (concepts, workflow, invariants).
+- `specrails://projects` — all registered projects.
+- `specrails://projects/{projectId}` — a single project.
+
+### Async results — `specrails_watch`
+
+Cost-incurring and streaming actions (launch a rail, generate a spec, send a
+chat turn, AI-edit, Contract Refine, SMASH) **return immediately** with a
+reference (a `jobId` / `requestId`) and emit their **real** result over the
+app's WebSocket bus. An agent gets the actual outcome by calling
+`specrails_watch` with that reference; it waits for the operation to settle and
+returns the final result. Don't assume success from the acceptance alone — this
+is spelled out in `specrails_guide`.
+
+## The four permission tiers
+
+Every tool declares one tier. The server refuses any tool whose tier is not
+enabled, and the refusal **names the tier the user must turn on** so the agent
+can relay it rather than retrying blindly. The tiers are **opt-in and
+cumulative** — read is always on, the rest are off until you enable them in
+**Settings ▸ MCP**:
+
+| Tier | Default | What it allows |
+|---|---|---|
+| **Read** | Always on | Queries + resources (list specs, read analytics, inspect jobs) |
+| **Write** | Off | Mutating but non-destructive, non-spawn: create/edit specs, change settings, configure a rail |
+| **AI-spawn** | Off | Actions that spawn an AI CLI and **cost money**: launch a rail, generate a spec, send a chat turn |
+| **Destructive** | Off | Delete data, kill processes, or mutate an external system (e.g. unregister a project, `smash_undo`, Jira writes) |
+
+The split is deliberate: a client you only half-trust can be left read-only;
+**destructive and cost-incurring actions are opt-in** and never happen by
+accident. A tool's tier is dynamic per action — e.g. `specrails_specs(list)` is
+read while `specrails_specs(delete)` is destructive — so the same tool exposes
+different actions at different trust levels.
+
+## Enabling it
+
+1. Open the app and go to **Settings ▸ MCP**.
+2. Toggle **Enable MCP**. This boots the embedded transport immediately — no
+   app restart. (Behind the scenes it persists `mcp_enabled` and starts serving
+   `/api/mcp`.)
+3. Enable the permission tiers you want (**Write** / **AI-spawn** /
+   **Destructive**). Leave them off to keep the agent read-only.
+4. Click **Copy client config** to grab a ready-to-paste configuration, or
+   **Copy token** if your client needs the raw token (for the direct-HTTP path
+   below).
+
+Toggling the enable switch off again tears down all open MCP sessions
+immediately.
+
+## Connecting a client
+
+There are two ways to connect, and **the stdio bridge is the recommended,
+universal one.**
+
+### Option A — the stdio bridge `specrails-mcp` (recommended)
+
+Most MCP clients (Claude Desktop, Claude Code, Cursor) speak MCP over **stdio**:
+they launch a command and talk to it on stdin/stdout. Specrails ships a tiny
+relay, **`specrails-mcp`**, bundled with the app. It transparently forwards MCP
+stdio from your client to the embedded HTTP server on loopback — and it reads
+the scoped token from `~/.specrails/mcp.token` **locally**, so the token never
+appears in your client's config file.
+
+A typical client config looks like:
+
+```json
+{
+  "mcpServers": {
+    "specrails": {
+      "command": "specrails-mcp"
+    }
+  }
+}
+```
+
+Use the exact command/path from the panel's **Copy client config** button — it
+fills in the path to the bundled bridge for your platform. No token, no URL, no
+port to manage; the bridge handles all of it. If the Specrails app isn't
+running, the bridge replies with a clear *"Specrails app is not running. Start
+the Specrails Desktop app, then retry."* rather than a cryptic connection error.
+
+### Option B — the direct HTTP URL (remote-HTTP clients)
+
+Clients that speak MCP's **streamable-HTTP** transport directly can skip the
+bridge and connect to:
+
+```
+http://127.0.0.1:4200/api/mcp
+```
+
+with the scoped token as a bearer header:
+
+```
+Authorization: Bearer <your mcp token>
+```
+
+Get the token from **Settings ▸ MCP ▸ Copy token** (or read
+`~/.specrails/mcp.token`). The endpoint is **loopback-only** — it rejects any
+request that doesn't originate from `127.0.0.1`, so this path is for local
+HTTP-capable clients, not for exposing Specrails on a network. (`4200` is the
+default app port; if you've changed it, the panel's config reflects the real
+one.)
+
+## Security model
+
+- **A scoped token, not the master token.** The MCP surface is authenticated by
+  its own token at `~/.specrails/mcp.token` (mode `0600`), completely separate
+  from the app's all-powerful master token (`~/.specrails/desktop.token`). The
+  master token grants terminals (shell), arbitrary AI-CLI spawns, and project
+  admin; handing that to a third-party MCP client would be a security smell. The
+  scoped token only reaches the four tiered surfaces above. You can rotate it
+  any time with **Regenerate token** in Settings — the old token stops working
+  immediately.
+- **Loopback only.** Both the transport (`/api/mcp`) and the admin control plane
+  (`/api/mcp-admin`) require the request to come from `127.0.0.1`. There is no
+  network ingress; an MCP client must run on the same machine.
+- **Tiers, not blanket access.** Even with a valid token, an agent can only do
+  what the enabled tiers allow (read by default). High-risk actions stay opt-in.
+- **The app must be running.** The MCP server is embedded in the desktop app's
+  process — there is no standalone daemon. The Tauri shell keeps it alive even
+  when you close the main window: closing the window **minimizes to the system
+  tray / menu bar** and leaves the embedded server running, so your MCP client
+  stays connected. The server stops only when you choose **Exit** from the tray
+  menu (or the OS truly quits the app). If the app isn't running, the bridge
+  tells you to start it.
+
+## v1 limitations — what is *not* exposed
+
+The tool catalog deliberately leaves the highest-risk execution vectors out of
+v1. None of these are reachable over MCP:
+
+- **Terminal shell execution.** The built-in terminal panel runs arbitrary
+  shell commands; the MCP surface does **not** expose it. An agent cannot run
+  shell on your machine through Specrails.
+- **Browser capture.** No browser navigation / screenshot / capture tool.
+- **In-app file write.** The code explorer is **read-only** over MCP — there is
+  no source-file overwrite tool (`code_write_file`). An agent can read files and
+  AI-generated summaries, but cannot edit your code directly through MCP. (AI
+  *rails* still write code — that's the pipeline, gated behind the AI-spawn
+  tier — but there is no direct file-overwrite tool.)
+- **The prerequisite installer.** The `uv`/remote-script prerequisite installer
+  is not exposed, so an agent cannot trigger remote-script installs.
+- The global Claude marketplace / `~/.claude/settings.json` mutation is also
+  out of scope.
+
+These boundaries are intentional and may be revisited in a later version.
+
+## Troubleshooting
+
+**My client can't connect / "app is not running"** — start the Specrails
+Desktop app. The MCP server is embedded in the app process; it isn't a separate
+daemon. If the window is hidden, the app is still running in the tray/menu bar —
+look for the Specrails icon there. Only the tray **Exit** stops the server.
+
+**Every tool is refused with a "permission tier" message** — the action needs a
+tier you haven't enabled. Open **Settings ▸ MCP** and turn on **Write** /
+**AI-spawn** / **Destructive** as appropriate. Read-only actions work with no
+extra tiers.
+
+**`401 Unauthorized: invalid MCP token`** (direct-HTTP path) — the bearer token
+is wrong or stale. Re-copy it from **Settings ▸ MCP ▸ Copy token**, or
+**Regenerate token** and update your client. The stdio bridge avoids this
+entirely (it reads the token locally).
+
+**The agent assumed a rail succeeded but it didn't** — cost-incurring actions
+return a reference, not a result. The agent must call `specrails_watch` with the
+returned `jobId`/`requestId` to get the real outcome. This is documented in
+`specrails_guide`; point the agent at it.
+
+**Connection refused on `:4200`** — that's the default app port. If you changed
+the port in Settings, use the URL from **Copy client config**, which reflects
+the real port. The bridge resolves the port automatically.
+
+## See also
+
+- [Running pipelines](running-pipelines.md) — what rails, jobs, and the
+  pipeline an MCP client drives actually do.
+- [Creating specs](creating-specs.md) — specs, drafts, SMASH, and Contract
+  Refine, all reachable via `specrails_specs`.
+- [Tracking cost](tracking-cost.md) — the analytics an agent reads via
+  `specrails_analytics`.
+- [Customising the app](customizing.md) — other settings, including the budget
+  the AI-spawn tier respects.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.16.0",
+  "version": "2.18.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -24,15 +24,16 @@
     "dev:server": "tsx watch server/index.ts",
     "dev:client": "cd client && npm run dev",
     "dev:desktop": "tauri dev",
-    "build:server": "node -e \"require('fs').rmSync('server/dist',{recursive:true,force:true})\" && tsc --project tsconfig.json",
+    "build:server": "node -e \"require('fs').rmSync('server/dist',{recursive:true,force:true})\" && tsc --project tsconfig.build.json --noCheck",
     "build:cli": "tsc --project tsconfig.cli.json",
     "build": "npm run build:server && cd client && npm run build && cd .. && npm run build:cli",
     "build:sidecar": "node scripts/build-sidecar.mjs",
-    "build:desktop": "npm run build:server && cd client && npm run build && cd .. && npm run build:sidecar && tauri build",
+    "build:mcp-bridge": "node scripts/build-mcp-bridge.mjs",
+    "build:desktop": "npm run build:server && cd client && npm run build && cd .. && npm run build:sidecar && npm run build:mcp-bridge && tauri build",
     "assemble-runtimes": "node scripts/assemble-runtimes-local.mjs",
     "build:desktop:local": "npm run assemble-runtimes && npm run build:desktop",
     "generate-icons": "tauri icon src-tauri/icons/icon.svg",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.cli.json --noEmit && cd client && tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.cli.json --noEmit && tsc -p mcp-bridge/tsconfig.json --noEmit && cd client && tsc --noEmit",
     "check-core-compat": "tsx scripts/check-core-compat.ts",
     "test": "vitest run && tsx scripts/check-core-compat.ts",
     "test:watch": "vitest",
@@ -42,6 +43,7 @@
     "ci": "npm run typecheck && npm run check-core-compat && npm run test:coverage && cd client && npm run test:coverage"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@tailwindcss/typography": "^0.5.19",
     "ajv": "^8.17.1",
     "better-sqlite3": "^12.8.0",
@@ -57,7 +59,8 @@
     "selfsigned": "^5.5.0",
     "tree-kill": "^1.2.2",
     "werift": "^0.23.0",
-    "ws": "^8.16.0"
+    "ws": "^8.16.0",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@tauri-apps/cli": "^2.0.0",