@danhachuel/thunderbolt 0.2.26 → 0.2.27

package/MANUAL-INSTALACAO.md

@@ -2,7 +2,7 @@
 
 Este manual descreve a instalação local da UI Thunderbolt, baseada no MoneyPrinterTurbo, utilizando o pacote npm `@danhachuel/thunderbolt`. O fluxo recomendado instala automaticamente o ambiente Python, as dependências da aplicação, as dependências do MoneyPrinterTurbo, o Streamlit e o suporte FFmpeg através de `imageio-ffmpeg`.
 
-> **Versão deste manual:** 0.2.26
+> **Versão deste manual:** 0.2.27
 > **Pacote npm:** `@danhachuel/thunderbolt`
 > **Porta padrão da UI:** `localhost:3030`  
 > **Repositório:** [github.com/DanHachuel/thunderbolt](https://github.com/DanHachuel/thunderbolt)
@@ -100,13 +100,13 @@ Execute:
 Windows PowerShell ou MobaXterm:
 
 ```powershell
-npx.cmd --yes @danhachuel/thunderbolt@0.2.26 install
+npx.cmd --yes @danhachuel/thunderbolt@0.2.27 install
 ```
 
 Linux/macOS:
 
 ```bash
-npx --yes @danhachuel/thunderbolt@0.2.26 install
+npx --yes @danhachuel/thunderbolt@0.2.27 install
 ```
 
 A instalação normal é **segura para actualizações**: preserva `storage`, Blueprints, Brandings, configurações e artefactos do utilizador. Remove apenas `.venv`, o clone técnico do MoneyPrinterTurbo e dependências que serão recriadas. Uma pasta antiga sem dados do utilizador, como `C:\Users\<utilizador>\AppData\Local\hermes` da tentativa incompleta, pode ser removida; uma pasta antiga que contenha Blueprints, Brandings ou storage é preservada e apenas avisada no terminal. Feche processos Python, Node, Streamlit e MobaXterm que estejam a usar as pastas antes de executar.
@@ -371,8 +371,9 @@ Após iniciar a aplicação, valide o seguinte percurso:
 11. **Automação:** no cartão de cada canal, escolha o **Blueprint padrão** e a **Voz padrão**, clique em `Guardar` e confirme que o resumo do cartão se actualiza. Configure também **Automação ON** e um horário `HH:MM`; confirme a lista de vídeos cadastrados. Os mesmos defaults aparecem em **Canais** e são usados em novas tarefas. A UI não inicia jobs em segundo plano nesta entrega.
 12. **Teste de vozes:** em Configurações, teste Edge/Azure ou provider configurado e confirme reprodução/download sem criação de tarefa.
 13. **Upload directo:** configure manualmente cookies, sessionInfo e INNERTUBE_API_KEY, atribua o `DELEGATED_SESSION_ID` no canal e teste apenas com um vídeo de validação. O método envia chunks de 256 KiB e não extrai cookies do navegador.
-14. **MCP:** confirme que Short Video Maker, AutoVio, OpenMontage e OpenCut aparecem com as portas padrão editáveis. O estado **Activo** é apenas uma preferência local; a detecção deve indicar **Não detectado** quando os serviços externos não estiverem instalados ou iniciados.
-15. **Skill MCP:** clique em **Guardar skill localmente** e confirme o ficheiro em `storage/skills/moneyprinterturbo-video.md`; opcionalmente use **Descarregar skill .md** para obter a cópia através do navegador.
+14. **MCP — Client MCP:** confirme que Short Video Maker, AutoVio, OpenMontage e OpenCut aparecem com as portas padrão editáveis. O estado **Activo** é uma preferência local; a detecção deve indicar **Não detectado** quando os serviços externos não estiverem instalados ou iniciados.
+15. **MCP — Servidor MCP:** abra a subaba, mantenha o host `127.0.0.1`, active **Servidor MCP ON** e clique em **Guardar e iniciar Servidor MCP**. Confirme o endpoint `/mcp` e o health endpoint `/health`. Mantenha **Permitir ferramentas de escrita** desactivado até precisar que um agente crie lotes.
+16. **MCP — Skill:** clique em **Guardar skill localmente** e confirme o ficheiro em `storage/skills/moneyprinterturbo-video.md`; opcionalmente use **Descarregar skill .md** para obter a cópia através do navegador.
 
 ## Novo vídeo, Automação e música
 
@@ -388,9 +389,11 @@ A subaba **Upload directo** adapta o [YouTube-Video-Upload-Frontend-Api](https:/
 
 ## MCP e integrações externas
 
-A aba **MCP** é um configurador local de quatro serviços opcionais. As portas iniciais são `3123` para Short Video Maker, `3001` para AutoVio, `8000` como referência editável para OpenMontage e `8787` para a API do OpenCut. A página consulta apenas `http://127.0.0.1:<porta>/` com timeout curto; não clona, instala ou inicia processos externos.
+A subaba **Client MCP** é um configurador local de quatro serviços opcionais. As portas iniciais são `3123` para Short Video Maker, `3001` para AutoVio, `8000` como referência editável para OpenMontage e `8787` para a API do OpenCut. A página consulta apenas `http://127.0.0.1:<porta>/` com timeout curto; não clona, instala ou inicia processos externos.
 
-O botão **Guardar skill localmente** copia a skill anexada para `storage/skills/`. Esta pasta fica fora dos estados JSON e é criada pelo instalador e pelo launcher. Os quatro repositórios continuam fora do pacote npm.
+A subaba **Servidor MCP** disponibiliza, após activação explícita, `http://127.0.0.1:3031/mcp` por JSON-RPC sobre HTTP POST. Para configurar um agente compatível, use esse URL como endpoint MCP. Se o host for alterado para uma interface externa, preencha primeiro um token e trate-o como segredo. O servidor disponibiliza ferramentas de leitura por padrão; a criação de lotes só é exposta quando **Permitir ferramentas de escrita** está activado.
+
+A subaba **Skill** contém as acções para guardar a skill anexada em `storage/skills/` ou descarregá-la como Markdown. Esta pasta fica fora dos estados JSON e é criada pelo instalador e pelo launcher. Os quatro repositórios continuam fora do pacote npm.
 
 ## 12. Limpador de metadado
 

package/README.md

@@ -104,9 +104,9 @@ thunderbolt
 No Windows PowerShell, se `npx` for bloqueado por `npx.ps1`, use directamente `npx.cmd`:
 
 ```powershell
-npx.cmd --yes @danhachuel/thunderbolt@0.2.26 install
-npx.cmd --yes @danhachuel/thunderbolt@0.2.26 doctor
-npx.cmd --yes @danhachuel/thunderbolt@0.2.26
+npx.cmd --yes @danhachuel/thunderbolt@0.2.27 install
+npx.cmd --yes @danhachuel/thunderbolt@0.2.27 doctor
+npx.cmd --yes @danhachuel/thunderbolt@0.2.27
 ```
 
 Como alternativa, pode permitir scripts para o seu utilizador:
@@ -193,11 +193,14 @@ A área **Configurações > Teste de vozes** é isolada da pipeline. Permite esc
 
 ## MCP e integrações externas opcionais
 
-A aba **MCP** funciona como um catálogo local de clientes externos. Ela lista **Short Video Maker**, **AutoVio**, **OpenMontage** e **OpenCut** com os respectivos links oficiais, protocolo/capacidade conhecida, porta local editável e toggle **Activo**. Os repositórios não são clonados, instalados ou incluídos no pacote npm do Thunderbolt.
+A aba **MCP** está organizada em três subabas independentes. **Client MCP** lista **Short Video Maker**, **AutoVio**, **OpenMontage** e **OpenCut** com links oficiais, protocolo/capacidade conhecida, porta local editável, detecção passiva e toggle **Activo**. Os repositórios externos não são clonados, instalados ou incluídos no pacote npm do Thunderbolt.
 
-As portas iniciais são `3123` para Short Video Maker, `3001` para a API backend do AutoVio, `8000` como referência editável para OpenMontage — que não documenta uma porta HTTP padrão — e `8787` para a API do OpenCut, cujo frontend de desenvolvimento usa `5173`. A detecção é passiva: apenas consulta `localhost` e nunca inicia processos externos. Activar uma integração guarda a preferência local; não substitui a instalação/configuração do serviço externo.
+As portas iniciais são `3123` para Short Video Maker, `3001` para a API backend do AutoVio, `8000` como referência editável para OpenMontage — que não documenta uma porta HTTP padrão — e `8787` para a API do OpenCut, cujo frontend de desenvolvimento usa `5173`. A detecção do Client MCP apenas consulta `localhost` e nunca inicia processos externos.
+
+**Servidor MCP** activa, mediante confirmação explícita na UI, um endpoint local em `http://127.0.0.1:3031/mcp`. O endpoint usa JSON-RPC sobre HTTP POST, disponibiliza ferramentas de leitura para estado da pipeline, canais, vídeos e Blueprints e exige um token quando o host é exposto fora do computador local. As ferramentas de escrita ficam desactivadas por padrão; quando o utilizador as activa, o agente pode criar lotes de vídeos através de uma ferramenta controlada. O endpoint `/health` serve apenas para verificação de disponibilidade.
+
+**Skill** contém exclusivamente os botões para guardar localmente ou descarregar `moneyprinterturbo-video.md`. A skill é guardada em `storage/skills/` e não é misturada com o catálogo de clientes MCP.
 
-A mesma aba permite **Guardar skill localmente**, copiando `moneyprinterturbo-video.md` para `storage/skills/`, e **Descarregar skill .md** através do navegador. A skill é um recurso separado dos quatro repositórios externos.
 
 ## TikTok
 

package/app/main.py

@@ -20,7 +20,8 @@ from hermes_ui.domain import STAGES, create_batch, create_channel, create_tasks_
 from hermes_ui.storage import BLUEPRINTS, ensure_storage, list_blueprint_files, load_blueprint_file, now, read_json, write_json
 from hermes_ui.blueprints import create_blueprint_from_link, list_branding_files, save_generated_blueprint
 from hermes_ui.metadata_cleaner import build_description, clean_video_metadata, list_edit_records, metadata_manifest, normalize_tags, save_edit_record, store_external_video
-from hermes_ui.mcp import detect_local_service, install_skill_locally, load_integrations, read_packaged_skill, update_integration
+from hermes_ui.mcp import detect_local_service, install_skill_locally, load_integrations, load_server_config, read_packaged_skill, save_server_config, update_integration
+from hermes_ui.mcp_server import server_status, start_server, stop_server
 from hermes_ui.music import list_music_files, materialize_suno_audio, request_suno_generation, store_music_file
 from hermes_ui.voice_preview import DEFAULT_SAMPLE, load_preview_file, synthesize_preview
 from integrations.platforms import IntegrationResult, TikTokAdapter, YouTubeAdapter
@@ -1077,73 +1078,141 @@ def render_settings():
 
 def render_mcp():
     st.title("MCP")
-    st.caption("Clientes opcionais para serviços externos. Os repositórios não são instalados nem incluídos no pacote Thunderbolt.")
-    st.info("Activar uma integração guarda apenas a preferência local. O Thunderbolt não inicia processos externos automaticamente; a detecção verifica passivamente se existe um serviço já disponível na porta configurada.")
+    st.caption("Clientes externos, servidor MCP do Thunderbolt e a skill local ficam separados para evitar confundir funções diferentes.")
+
+    client_tab, server_tab, skill_tab = st.tabs(["Client MCP", "Servidor MCP", "Skill"])
+
+    with client_tab:
+        st.subheader("Client MCP")
+        st.info("Configure aqui os serviços MCP externos que o Thunderbolt pode detectar passivamente. Activar uma integração guarda apenas a preferência; não instala nem inicia processos externos.")
+        integrations = load_integrations()
+        for integration in integrations:
+            integration_id = integration["id"]
+            with st.container(border=True):
+                header_cols = st.columns([2.6, 1.15, 1.65, 1.2])
+                with header_cols[0]:
+                    st.write(f"**{integration['name']}**")
+                    st.caption(f"{integration['protocol']} · {integration['description']}")
+                    st.markdown(f"[Abrir repositório oficial]({integration['repository']})")
+                with header_cols[1]:
+                    port = st.number_input(
+                        "Porta",
+                        min_value=1,
+                        max_value=65535,
+                        value=int(integration.get("port", 8000)),
+                        step=1,
+                        key=f"mcp_port_{integration_id}",
+                    )
+                with header_cols[2]:
+                    status = detect_local_service({**integration, "port": port})
+                    if status["available"]:
+                        st.success("Disponível")
+                    else:
+                        st.caption("Não detectado")
+                    st.caption(status["message"])
+                with header_cols[3]:
+                    active = st.toggle("Activo", value=bool(integration.get("active", False)), key=f"mcp_active_{integration_id}")
+                    if active != bool(integration.get("active", False)):
+                        update_integration(integration_id, active=active)
+                        st.rerun()
 
-    integrations = load_integrations()
-    for integration in integrations:
-        integration_id = integration["id"]
-        with st.container(border=True):
-            header_cols = st.columns([2.6, 1.15, 1.65, 1.2])
-            with header_cols[0]:
-                st.write(f"**{integration['name']}**")
-                st.caption(f"{integration['protocol']} · {integration['description']}")
-                st.markdown(f"[Abrir repositório oficial]({integration['repository']})")
-            with header_cols[1]:
-                port = st.number_input(
-                    "Porta",
-                    min_value=1,
-                    max_value=65535,
-                    value=int(integration.get("port", 8000)),
-                    step=1,
-                    key=f"mcp_port_{integration_id}",
-                )
-            with header_cols[2]:
-                status = detect_local_service({**integration, "port": port})
-                if status["available"]:
-                    st.success("Disponível")
-                else:
-                    st.caption("Não detectado")
-                st.caption(status["message"])
-            with header_cols[3]:
-                active = st.toggle("Activo", value=bool(integration.get("active", False)), key=f"mcp_active_{integration_id}")
-                if active != bool(integration.get("active", False)):
-                    update_integration(integration_id, active=active)
+                st.caption(integration.get("endpoint_note", "Porta editável para o serviço local."))
+                if st.button("Guardar porta", key=f"mcp_save_port_{integration_id}", use_container_width=True):
+                    update_integration(integration_id, port=int(port))
+                    st.success(f"Porta de {integration['name']} guardada: {int(port)}")
                     st.rerun()
 
-            st.caption(integration.get("endpoint_note", "Porta editável para o serviço local."))
-            if st.button("Guardar porta", key=f"mcp_save_port_{integration_id}", use_container_width=True):
-                update_integration(integration_id, port=int(port))
-                st.success(f"Porta de {integration['name']} guardada: {int(port)}")
-                st.rerun()
-
-    st.divider()
-    st.subheader("Skill MoneyPrinterTurbo")
-    st.caption("A skill anexada pode ser guardada na pasta local do Thunderbolt ou descarregada como ficheiro Markdown. Nenhum dos quatro repositórios externos é copiado para o pacote.")
-    skill_cols = st.columns(2)
-    with skill_cols[0]:
-        if st.button("Guardar skill localmente", type="primary", use_container_width=True, key="mcp_install_mpt_skill"):
+    with server_tab:
+        st.subheader("Servidor MCP")
+        st.caption("Servidor local do Thunderbolt para ser descoberto por um agente compatível com MCP. O endpoint usa JSON-RPC sobre HTTP POST em `/mcp`.")
+        st.warning("Por segurança, o servidor inicia apenas quando o activar explicitamente. Por padrão fica acessível somente neste computador em 127.0.0.1:3031.")
+        server_config = load_server_config()
+        if server_config.get("enabled") and not server_status().get("running"):
             try:
-                destination = install_skill_locally()
-                st.success(f"Skill guardada em `{destination}`")
-            except (FileNotFoundError, OSError) as exc:
-                st.error(f"Não foi possível guardar a skill: {exc}")
-    with skill_cols[1]:
-        try:
-            skill_data = read_packaged_skill()
-        except FileNotFoundError:
-            skill_data = None
-        if skill_data is not None:
-            st.download_button(
-                "Descarregar skill .md",
-                data=skill_data,
-                file_name="moneyprinterturbo-video.md",
-                mime="text/markdown",
-                use_container_width=True,
-                key="mcp_download_mpt_skill",
+                start_server(
+                    str(server_config.get("host", "127.0.0.1")),
+                    int(server_config.get("port", 3031)),
+                    str(server_config.get("auth_token", "")),
+                    bool(server_config.get("write_enabled", False)),
+                )
+            except Exception as exc:
+                st.error(f"Não foi possível iniciar o Servidor MCP guardado: {exc}")
+
+        server_cols = st.columns([1.3, 1.4, 1.4])
+        with server_cols[0]:
+            server_enabled = st.checkbox("Servidor MCP ON", value=bool(server_config.get("enabled", False)), key="mcp_server_enabled")
+        with server_cols[1]:
+            server_host = st.text_input("Host", value=str(server_config.get("host", "127.0.0.1")), key="mcp_server_host", help="Use 127.0.0.1 para acesso local. Um host externo exige token.")
+        with server_cols[2]:
+            server_port = st.number_input("Porta do servidor", min_value=1, max_value=65535, value=int(server_config.get("port", 3031)), step=1, key="mcp_server_port")
+        server_token = st.text_input("Token de acesso MCP (opcional no localhost)", value=str(server_config.get("auth_token", "")), type="password", key="mcp_server_token")
+        write_enabled = st.checkbox("Permitir ferramentas de escrita", value=bool(server_config.get("write_enabled", False)), key="mcp_server_write", help="Desactivado por padrão. Quando activo, o agente pode criar lotes de vídeos através de uma ferramenta MCP; leituras continuam disponíveis sem esta opção.")
+        if str(server_host).strip() not in {"127.0.0.1", "localhost", "::1"} and not str(server_token).strip():
+            st.error("Para expor o servidor fora do computador local, defina um token de acesso MCP.")
+
+        action_label = "Guardar e iniciar Servidor MCP" if server_enabled else "Guardar e parar Servidor MCP"
+        if st.button(action_label, type="primary", key="mcp_server_save", use_container_width=True):
+            try:
+                saved = save_server_config(enabled=server_enabled, host=server_host, port=int(server_port), auth_token=server_token, write_enabled=write_enabled)
+                if saved["enabled"]:
+                    status = start_server(saved["host"], saved["port"], saved["auth_token"], saved["write_enabled"])
+                    st.success(f"Servidor MCP activo em `{status['endpoint']}`")
+                else:
+                    stop_server()
+                    st.success("Servidor MCP parado.")
+                st.rerun()
+            except Exception as exc:
+                st.error(f"Não foi possível guardar/iniciar o Servidor MCP: {exc}")
+
+        runtime = server_status()
+        if runtime.get("running"):
+            st.success(f"Servidor MCP activo: `{runtime['endpoint']}`")
+            st.code(
+                json.dumps(
+                    {
+                        "endpoint": runtime["endpoint"],
+                        "health": runtime["health_endpoint"],
+                        "transport": "Streamable HTTP / JSON-RPC POST",
+                        "write_tools": runtime["write_enabled"],
+                    },
+                    ensure_ascii=False,
+                    indent=2,
+                ),
+                language="json",
             )
+            st.caption("Use o endpoint `/mcp` na configuração do agente. O endpoint `/health` serve apenas para verificar se o servidor está activo. Não partilhe o token.")
         else:
-            st.warning("A skill ainda não está disponível nesta instalação.")
+            st.info("Servidor MCP parado. As configurações ficam guardadas localmente e só são usadas depois de clicar em Guardar e iniciar.")
+        st.markdown("**Ferramentas disponibilizadas**")
+        st.write("Leitura: estado da pipeline, canais, vídeos e Blueprints. Ferramentas de escrita: criação de lotes de vídeos, apenas quando a opção de escrita estiver activada pelo utilizador.")
+
+    with skill_tab:
+        st.subheader("Skill")
+        st.caption("A skill anexada pode ser guardada na pasta local do Thunderbolt ou descarregada como ficheiro Markdown. Nenhum dos quatro repositórios externos é copiado para o pacote.")
+        skill_cols = st.columns(2)
+        with skill_cols[0]:
+            if st.button("Guardar skill localmente", type="primary", use_container_width=True, key="mcp_install_mpt_skill"):
+                try:
+                    destination = install_skill_locally()
+                    st.success(f"Skill guardada em `{destination}`")
+                except (FileNotFoundError, OSError) as exc:
+                    st.error(f"Não foi possível guardar a skill: {exc}")
+        with skill_cols[1]:
+            try:
+                skill_data = read_packaged_skill()
+            except FileNotFoundError:
+                skill_data = None
+            if skill_data is not None:
+                st.download_button(
+                    "Descarregar skill .md",
+                    data=skill_data,
+                    file_name="moneyprinterturbo-video.md",
+                    mime="text/markdown",
+                    use_container_width=True,
+                    key="mcp_download_mpt_skill",
+                )
+            else:
+                st.warning("A skill ainda não está disponível nesta instalação.")
 
 
 def render_metadata_cleaner():

package/hermes_ui/mcp.py

@@ -9,6 +9,13 @@ from . import storage
 
 
 SKILL_FILENAME = "moneyprinterturbo-video.md"
+MCP_SERVER_DEFAULTS: dict[str, Any] = {
+    "enabled": False,
+    "host": "127.0.0.1",
+    "port": 3031,
+    "auth_token": "",
+    "write_enabled": False,
+}
 
 MCP_DEFAULTS: list[dict[str, Any]] = [
     {
@@ -72,6 +79,36 @@ def _merge_defaults(saved: Any) -> list[dict[str, Any]]:
     return merged
 
 
+def load_server_config() -> dict[str, Any]:
+    saved = storage.read_json("mcp_server.json", MCP_SERVER_DEFAULTS)
+    config = {**MCP_SERVER_DEFAULTS, **(saved if isinstance(saved, dict) else {})}
+    config["enabled"] = bool(config.get("enabled", False))
+    config["write_enabled"] = bool(config.get("write_enabled", False))
+    config["host"] = str(config.get("host", "127.0.0.1") or "127.0.0.1").strip()
+    config["auth_token"] = str(config.get("auth_token", "") or "").strip()
+    try:
+        config["port"] = max(1, min(65535, int(config.get("port", 3031))))
+    except (TypeError, ValueError):
+        config["port"] = 3031
+    return config
+
+
+def save_server_config(**updates: Any) -> dict[str, Any]:
+    config = load_server_config()
+    config.update(updates)
+    config = {**MCP_SERVER_DEFAULTS, **config}
+    config["enabled"] = bool(config.get("enabled", False))
+    config["write_enabled"] = bool(config.get("write_enabled", False))
+    config["host"] = str(config.get("host", "127.0.0.1") or "127.0.0.1").strip()
+    config["auth_token"] = str(config.get("auth_token", "") or "").strip()
+    try:
+        config["port"] = max(1, min(65535, int(config.get("port", 3031))))
+    except (TypeError, ValueError):
+        config["port"] = 3031
+    storage.write_json("mcp_server.json", config)
+    return config
+
+
 def load_integrations() -> list[dict[str, Any]]:
     return _merge_defaults(storage.read_json("mcp_integrations.json", MCP_DEFAULTS))
 

package/hermes_ui/mcp_server.py

@@ -0,0 +1,400 @@
+from __future__ import annotations
+
+import atexit
+import json
+import logging
+import threading
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+from . import storage
+from .domain import create_batch, create_tasks_for_batch, pipeline_summary
+
+LOGGER = logging.getLogger(__name__)
+MCP_ENDPOINT_PATH = "/mcp"
+MCP_HEALTH_PATH = "/health"
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 3031
+DEFAULT_PROTOCOL_VERSION = "2025-06-18"
+
+
+def _version() -> str:
+    try:
+        package = json.loads((Path(__file__).resolve().parents[1] / "package.json").read_text(encoding="utf-8"))
+        return str(package.get("version") or "")
+    except (OSError, json.JSONDecodeError):
+        return ""
+
+
+def _json_text(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, indent=2, default=str)
+
+
+def _channel_public(channel: dict[str, Any]) -> dict[str, Any]:
+    allowed = (
+        "id", "name", "url", "handle", "description", "thumbnail_url", "subscriber_count",
+        "video_count", "view_count", "metrics_source", "last_youtube_sync", "language",
+        "blueprint_id", "default_blueprint_id", "style_wide", "voice", "default_voice",
+        "automation_on", "automation_time", "active", "daily_limit", "backlog_total",
+        "created_at", "updated_at",
+    )
+    return {key: channel.get(key) for key in allowed if key in channel}
+
+
+def _task_public(task: dict[str, Any]) -> dict[str, Any]:
+    allowed = (
+        "id", "batch_id", "creation_mode", "channel_id", "channel_name", "topic", "language",
+        "format", "style_wide", "style_ia", "music_mode", "music_source", "background_mode",
+        "blueprint_id", "voice", "automation_on", "automation_time", "stage", "state",
+        "progress", "error", "created_at", "updated_at",
+    )
+    return {key: task.get(key) for key in allowed if key in task}
+
+
+def _list_blueprints() -> list[dict[str, Any]]:
+    storage.ensure_storage()
+    files = sorted(storage.BLUEPRINTS.rglob("*.json"))
+    return [
+        {
+            "id": path.stem,
+            "name": path.stem,
+            "filename": path.name,
+            "category": path.parent.name,
+        }
+        for path in files
+    ]
+
+
+def _tool_definitions(write_enabled: bool) -> list[dict[str, Any]]:
+    tools = [
+        {
+            "name": "thunderbolt_get_status",
+            "title": "Thunderbolt — estado da pipeline",
+            "description": "Obtém o resumo actual de canais e tarefas do Thunderbolt.",
+            "inputSchema": {"type": "object", "additionalProperties": False},
+        },
+        {
+            "name": "thunderbolt_list_channels",
+            "title": "Thunderbolt — listar canais",
+            "description": "Lista os canais registados sem devolver cookies, tokens ou outros segredos.",
+            "inputSchema": {"type": "object", "additionalProperties": False},
+        },
+        {
+            "name": "thunderbolt_list_videos",
+            "title": "Thunderbolt — listar vídeos",
+            "description": "Lista tarefas de vídeo com filtros opcionais por canal e estado.",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "channel_id": {"type": "string", "description": "ID do canal opcional."},
+                    "state": {"type": "string", "description": "Estado opcional: to_do, doing, blocked, done, failed ou cancelled."},
+                    "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50},
+                },
+                "additionalProperties": False,
+            },
+        },
+        {
+            "name": "thunderbolt_list_blueprints",
+            "title": "Thunderbolt — listar Blueprints",
+            "description": "Lista os Blueprints JSON disponíveis na biblioteca local, sem expor caminhos absolutos.",
+            "inputSchema": {"type": "object", "additionalProperties": False},
+        },
+    ]
+    if write_enabled:
+        tools.append(
+            {
+                "name": "thunderbolt_create_video_batch",
+                "title": "Thunderbolt — criar lote de vídeos",
+                "description": "Cria um lote e as respectivas tarefas. Só aparece quando o utilizador activa ferramentas de escrita na UI.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "mode": {"type": "string", "enum": ["single", "batch", "general"]},
+                        "channel_ids": {"type": "array", "items": {"type": "string"}, "minItems": 1},
+                        "topic": {"type": "string", "minLength": 1},
+                        "quantity": {"type": "integer", "minimum": 1, "maximum": 50},
+                        "language": {"type": "string"},
+                        "format": {"type": "string"},
+                        "style_wide": {"type": "string"},
+                        "style_ia": {"type": "string"},
+                        "music_mode": {"type": "boolean"},
+                        "background_mode": {"type": "string"},
+                    },
+                    "required": ["mode", "channel_ids", "topic", "quantity"],
+                    "additionalProperties": False,
+                },
+            }
+        )
+    return tools
+
+
+def _tool_call(name: str, arguments: dict[str, Any], write_enabled: bool) -> Any:
+    if name == "thunderbolt_get_status":
+        return pipeline_summary()
+    if name == "thunderbolt_list_channels":
+        channels = storage.read_json("channels.json", [])
+        return [_channel_public(channel) for channel in channels if isinstance(channel, dict)]
+    if name == "thunderbolt_list_videos":
+        channel_id = str(arguments.get("channel_id", "") or "").strip()
+        state = str(arguments.get("state", "") or "").strip()
+        limit = int(arguments.get("limit", 50) or 50)
+        if limit < 1 or limit > 100:
+            raise ValueError("limit deve estar entre 1 e 100.")
+        valid_states = {"to_do", "doing", "blocked", "done", "failed", "cancelled"}
+        if state and state not in valid_states:
+            raise ValueError(f"state inválido: {state}.")
+        tasks = storage.read_json("tasks.json", [])
+        filtered = [
+            task for task in tasks
+            if isinstance(task, dict)
+            and (not channel_id or task.get("channel_id") == channel_id)
+            and (not state or task.get("state") == state)
+        ]
+        return [_task_public(task) for task in filtered[:limit]]
+    if name == "thunderbolt_list_blueprints":
+        return _list_blueprints()
+    if name == "thunderbolt_create_video_batch":
+        if not write_enabled:
+            raise PermissionError("Ferramentas de escrita estão desactivadas no Servidor MCP.")
+        mode = str(arguments.get("mode", "")).strip()
+        if mode not in {"single", "batch", "general"}:
+            raise ValueError("mode deve ser single, batch ou general.")
+        channel_ids = arguments.get("channel_ids")
+        if not isinstance(channel_ids, list) or not channel_ids or not all(isinstance(item, str) and item.strip() for item in channel_ids):
+            raise ValueError("channel_ids deve conter pelo menos um ID de canal válido.")
+        topic = str(arguments.get("topic", "") or "").strip()
+        if not topic:
+            raise ValueError("topic é obrigatório.")
+        quantity = int(arguments.get("quantity", 1) or 1)
+        if quantity < 1 or quantity > 50:
+            raise ValueError("quantity deve estar entre 1 e 50.")
+        options = {
+            "language": str(arguments.get("language", "") or ""),
+            "format": str(arguments.get("format", "wide") or "wide"),
+            "style_wide": str(arguments.get("style_wide", "pexels") or "pexels"),
+            "style_ia": str(arguments.get("style_ia", "") or ""),
+            "music_mode": bool(arguments.get("music_mode", False)),
+            "background_mode": str(arguments.get("background_mode", "stock") or "stock"),
+        }
+        batch = create_batch(mode, [item.strip() for item in channel_ids], topic, quantity, options)
+        tasks = create_tasks_for_batch(batch)
+        return {"batch_id": batch["id"], "task_ids": [task["id"] for task in tasks], "created": len(tasks)}
+    raise KeyError(f"Ferramenta desconhecida: {name}")
+
+
+def _rpc_error(request_id: Any, code: int, message: str) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": request_id, "error": {"code": code, "message": message}}
+
+
+def _tool_result(value: Any, *, is_error: bool = False) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "content": [{"type": "text", "text": _json_text(value)}],
+        "isError": is_error,
+    }
+    if not is_error:
+        result["structuredContent"] = value
+    return result
+
+
+class _MCPDispatcher:
+    def __init__(self, auth_token: str = "", write_enabled: bool = False):
+        self.auth_token = auth_token.strip()
+        self.write_enabled = bool(write_enabled)
+
+    def handle(self, request: dict[str, Any]) -> dict[str, Any] | None:
+        request_id = request.get("id")
+        if request.get("jsonrpc") != "2.0":
+            return _rpc_error(request_id, -32600, "Pedido JSON-RPC inválido.")
+        method = request.get("method")
+        params = request.get("params") or {}
+        if not isinstance(method, str) or not isinstance(params, dict):
+            return _rpc_error(request_id, -32600, "method e params inválidos.")
+        if method in {"notifications/initialized", "notifications/cancelled", "notifications/progress"} or "id" not in request:
+            return None
+        if method == "initialize":
+            requested = params.get("protocolVersion")
+            protocol_version = requested if isinstance(requested, str) and requested else DEFAULT_PROTOCOL_VERSION
+            return {
+                "jsonrpc": "2.0",
+                "id": request_id,
+                "result": {
+                    "protocolVersion": protocol_version,
+                    "capabilities": {"tools": {"listChanged": False}},
+                    "serverInfo": {"name": "Thunderbolt MCP Server", "version": _version()},
+                    "instructions": "Use tools/list para descobrir as ferramentas disponíveis. Ferramentas de escrita só aparecem quando autorizadas pelo utilizador na UI.",
+                },
+            }
+        if method == "ping":
+            return {"jsonrpc": "2.0", "id": request_id, "result": {}}
+        if method == "tools/list":
+            return {"jsonrpc": "2.0", "id": request_id, "result": {"tools": _tool_definitions(self.write_enabled)}}
+        if method == "tools/call":
+            name = params.get("name")
+            arguments = params.get("arguments") or {}
+            if not isinstance(name, str) or not isinstance(arguments, dict):
+                return _rpc_error(request_id, -32602, "name e arguments são obrigatórios em tools/call.")
+            try:
+                value = _tool_call(name, arguments, self.write_enabled)
+                return {"jsonrpc": "2.0", "id": request_id, "result": _tool_result(value)}
+            except KeyError as exc:
+                return _rpc_error(request_id, -32602, str(exc))
+            except (ValueError, PermissionError) as exc:
+                return {"jsonrpc": "2.0", "id": request_id, "result": _tool_result(str(exc), is_error=True)}
+            except Exception:
+                LOGGER.exception("Falha ao executar ferramenta MCP %s", name)
+                return {"jsonrpc": "2.0", "id": request_id, "result": _tool_result("Erro interno ao executar a ferramenta.", is_error=True)}
+        return _rpc_error(request_id, -32601, f"Método não suportado: {method}")
+
+
+class _HTTPServer(ThreadingHTTPServer):
+    daemon_threads = True
+    allow_reuse_address = True
+
+
+class _RequestHandler(BaseHTTPRequestHandler):
+    server: _HTTPServer
+
+    def log_message(self, format: str, *args: Any) -> None:
+        LOGGER.info("MCP HTTP %s", format % args)
+
+    def _send_json(self, payload: Any, status: int = HTTPStatus.OK) -> None:
+        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _authorized(self) -> bool:
+        token = self.server.dispatcher.auth_token
+        if not token:
+            return True
+        return self.headers.get("Authorization", "") == f"Bearer {token}" or self.headers.get("X-Thunderbolt-MCP-Token", "") == token
+
+    def do_GET(self) -> None:
+        path = urlparse(self.path).path
+        if path == MCP_HEALTH_PATH:
+            self._send_json({"ok": True, "server": "Thunderbolt MCP Server", "endpoint": MCP_ENDPOINT_PATH, "version": _version()})
+            return
+        if path == MCP_ENDPOINT_PATH:
+            self.send_response(HTTPStatus.METHOD_NOT_ALLOWED)
+            self.send_header("Allow", "POST")
+            self.end_headers()
+            return
+        self._send_json({"error": "Not found"}, HTTPStatus.NOT_FOUND)
+
+    def do_POST(self) -> None:
+        path = urlparse(self.path).path
+        if path != MCP_ENDPOINT_PATH:
+            self._send_json({"error": "Not found"}, HTTPStatus.NOT_FOUND)
+            return
+        if not self._authorized():
+            self._send_json({"error": "Unauthorized"}, HTTPStatus.UNAUTHORIZED)
+            return
+        try:
+            length = int(self.headers.get("Content-Length", "0"))
+            if length < 1 or length > 1_000_000:
+                raise ValueError("Corpo JSON inválido ou demasiado grande.")
+            payload = json.loads(self.rfile.read(length).decode("utf-8"))
+        except (ValueError, json.JSONDecodeError, UnicodeDecodeError) as exc:
+            self._send_json(_rpc_error(None, -32700, f"JSON inválido: {exc}"), HTTPStatus.BAD_REQUEST)
+            return
+        if isinstance(payload, list):
+            responses = [self.server.dispatcher.handle(item) for item in payload if isinstance(item, dict)]
+            responses = [item for item in responses if item is not None]
+            if responses:
+                self._send_json(responses)
+            else:
+                self.send_response(HTTPStatus.ACCEPTED)
+                self.end_headers()
+            return
+        if not isinstance(payload, dict):
+            self._send_json(_rpc_error(None, -32600, "O pedido MCP deve ser um objecto JSON-RPC."), HTTPStatus.BAD_REQUEST)
+            return
+        response = self.server.dispatcher.handle(payload)
+        if response is None:
+            self.send_response(HTTPStatus.ACCEPTED)
+            self.end_headers()
+            return
+        self._send_json(response)
+
+
+class _Runtime:
+    def __init__(self) -> None:
+        self.lock = threading.RLock()
+        self.http_server: _HTTPServer | None = None
+        self.thread: threading.Thread | None = None
+        self.host = ""
+        self.port = 0
+        self.write_enabled = False
+
+    def start(self, host: str, port: int, auth_token: str = "", write_enabled: bool = False) -> dict[str, Any]:
+        host = (host or DEFAULT_HOST).strip()
+        port = int(port)
+        if not 1 <= port <= 65535:
+            raise ValueError("A porta MCP deve estar entre 1 e 65535.")
+        if host not in {"127.0.0.1", "localhost", "::1"} and not auth_token.strip():
+            raise ValueError("Defina um token MCP antes de expor o servidor fora do computador local.")
+        with self.lock:
+            if self.http_server and self.thread and self.thread.is_alive() and (self.host, self.port) == (host, port):
+                self.write_enabled = bool(write_enabled)
+                self.http_server.dispatcher.write_enabled = bool(write_enabled)
+                self.http_server.dispatcher.auth_token = auth_token.strip()
+                return self.status()
+            self.stop()
+            server = _HTTPServer((host, port), _RequestHandler)
+            server.dispatcher = _MCPDispatcher(auth_token, write_enabled)
+            thread = threading.Thread(target=server.serve_forever, name="thunderbolt-mcp", daemon=True)
+            thread.start()
+            self.http_server = server
+            self.thread = thread
+            self.host = host
+            self.port = port
+            self.write_enabled = bool(write_enabled)
+            return self.status()
+
+    def stop(self) -> None:
+        with self.lock:
+            if self.http_server:
+                self.http_server.shutdown()
+                self.http_server.server_close()
+            self.http_server = None
+            self.thread = None
+            self.host = ""
+            self.port = 0
+            self.write_enabled = False
+
+    def status(self) -> dict[str, Any]:
+        running = bool(self.http_server and self.thread and self.thread.is_alive())
+        return {
+            "running": running,
+            "host": self.host if running else "",
+            "port": self.port if running else 0,
+            "endpoint": f"http://{self.host}:{self.port}{MCP_ENDPOINT_PATH}" if running else "",
+            "health_endpoint": f"http://{self.host}:{self.port}{MCP_HEALTH_PATH}" if running else "",
+            "write_enabled": self.write_enabled if running else False,
+        }
+
+
+_RUNTIME = _Runtime()
+atexit.register(_RUNTIME.stop)
+
+
+def start_server(host: str = DEFAULT_HOST, port: int = DEFAULT_PORT, auth_token: str = "", write_enabled: bool = False) -> dict[str, Any]:
+    return _RUNTIME.start(host, port, auth_token, write_enabled)
+
+
+def stop_server() -> None:
+    _RUNTIME.stop()
+
+
+def server_status() -> dict[str, Any]:
+    return _RUNTIME.status()
+
+
+def tool_definitions(write_enabled: bool = False) -> list[dict[str, Any]]:
+    return _tool_definitions(write_enabled)

package/hermes_ui/storage.py

@@ -21,6 +21,13 @@ DEFAULTS: dict[str, Any] = {
     "batches.json": [],
     "uploads.json": [],
     "metadata_edits.json": [],
+    "mcp_server.json": {
+        "enabled": False,
+        "host": "127.0.0.1",
+        "port": 3031,
+        "auth_token": "",
+        "write_enabled": False,
+    },
     "mcp_integrations.json": [
         {
             "id": "short-video-maker",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danhachuel/thunderbolt",
-  "version": "0.2.26",
+  "version": "0.2.27",
   "description": "Thunderbolt — interface local para operação de canais faceless e motor MoneyPrinterTurbo",
   "main": "scripts/cli.mjs",
   "type": "module",