perplexity-notebooklm 0.2.2__tar.gz → 0.3.0__tar.gz

{perplexity_notebooklm-0.2.2 → perplexity_notebooklm-0.3.0}/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "perplexity-notebooklm",
       "description": "Integração dual Perplexity <-> NotebookLM (conta Pro, sem API key)",
-      "version": "0.2.2",
+      "version": "0.3.0",
       "source": "./",
       "author": {
         "name": "wgardim"

{perplexity_notebooklm-0.2.2 → perplexity_notebooklm-0.3.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "perplexity-notebooklm",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Integração dual Perplexity <-> NotebookLM (conta Pro, sem API key): pesquisa citada vira fonte no notebook e vice-versa.",
   "author": {
     "name": "wgardim"

{perplexity_notebooklm-0.2.2 → perplexity_notebooklm-0.3.0}/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com). Versionamento semântico.
 
+## [0.3.0] — 2026-06-27
+
+### Adicionado
+- **Fluxo dual como tools MCP first-class** (`perplexity_mcp/nlm_tools.py`): o server
+  `perplexity-pro` agora expõe 9 tools além das do Perplexity —
+  `notebooklm_list`, `notebooklm_read_summary`, `notebooklm_add_text/add_url/add_file`,
+  `notebooklm_generate`, `dual_research_to_notebook`, `dual_notebook_to_research`,
+  `dual_research_to_media`. O Claude chama tudo direto via MCP (não mais skill rodando Python).
+- **Annotations de segurança**: leitura = `readOnlyHint`; escrita = `destructiveHint`
+  (checkpoint humano = permission prompt do Claude Code).
+- **Registro condicional/gracioso**: as tools só sobem se o extra `notebooklm` estiver
+  instalado (`find_spec`); install Perplexity-only fica intacto. Erro real de registro
+  loga no stderr (não polui o protocolo stdio).
+
 ## [0.2.2] — 2026-06-27
 
 ### CI

{perplexity_notebooklm-0.2.2 → perplexity_notebooklm-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: perplexity-notebooklm
-Version: 0.2.2
+Version: 0.3.0
 Summary: Integração dual NotebookLM <-> Perplexity (conta Pro, sem API key) via MCP + skill
 Project-URL: Homepage, https://github.com/wgardim-hub/notebooklm2perplexity
 Project-URL: Repository, https://github.com/wgardim-hub/notebooklm2perplexity

perplexity_notebooklm-0.3.0/docs/superpowers/specs/2026-06-27-dual-mcp-tools-design.md

@@ -0,0 +1,69 @@
+# Spec: Fluxo dual como tools MCP first-class
+
+## Contexto
+Hoje o MCP `perplexity-pro` expõe só Perplexity (ask/search/reason/research/healthcheck).
+NotebookLM + o fluxo dual existem em `notebooklm_write/nlm_http.py` e `dual_flow.py`, mas
+são acessados pela **skill rodando Python via venv** — não como tools MCP. Resultado: o
+Claude não chama add_source/list/dual diretamente pela interface MCP. Esta feature expõe
+tudo como tools, uniformizando o produto pela camada MCP.
+
+## Objetivo
+Adicionar NotebookLM (primitivas) + dual como tools no **mesmo** server `perplexity-pro`,
+com registro condicional e annotations de segurança.
+
+## Não-objetivos
+- Não muda os helpers (`nlm_http`/`dual_flow`) — as tools são adaptadores finos.
+- Não remove o caminho da skill (continua válido); só passa a preferir as tools MCP.
+- Sem novas capacidades de NotebookLM além das já implementadas.
+
+## Arquitetura
+- **Novo `perplexity_mcp/nlm_tools.py`** com `register(mcp)`: define e registra as tools.
+  Imports de `nlm_http`/`dual_flow` são lazy (dentro das funções) → import do módulo não
+  quebra em install Perplexity-only.
+- **`server.py`**: em `main()`/`_register()`, chamar `nlm_tools.register(mcp)` dentro de
+  `try/except Exception` — se `notebooklm-py` ausente, loga e segue (Perplexity-only intacto).
+- **Annotations**: usar `ToolAnnotations`/`annotations` do FastMCP — `readOnlyHint=True` nas
+  de leitura; escrita marcada como destrutiva (`readOnlyHint=False`). Se a versão do FastMCP
+  instalada não suportar annotations, fallback: descrição explícita ("ESCREVE no notebook")
+  + permission prompt do Claude Code (checkpoint humano default).
+
+## Tools (retornam string/markdown human-readable)
+Leitura (readOnly):
+- `notebooklm_list()` — notebooks (id + título), via `nlm_http.list_notebooks_sync`.
+- `notebooklm_read_summary(notebook_id)` — resumo, via `read_summary_sync`.
+Escrita (destrutiva — checkpoint via permission prompt):
+- `notebooklm_add_text(notebook_id, title, content)` — `add_text_sync`.
+- `notebooklm_add_url(notebook_id, url)` — `add_url_sync` (web/YouTube auto).
+- `notebooklm_add_file(notebook_id, file_path)` — `add_file_sync`.
+- `notebooklm_generate(notebook_id, kind)` — `generate_artifact_sync` (audio|video|mind_map).
+Dual:
+- `dual_research_to_notebook(query, notebook_id, tool="research", verify=True, dedup=True)` (escrita).
+- `dual_notebook_to_research(notebook_id, tool="search")` (leitura+pesquisa; não escreve).
+- `dual_research_to_media(query, notebook_id, kind="mind_map", tool="search")` (escrita).
+
+## Fluxo de dados
+Claude → tool MCP → helper sync (`nlm_http`/`dual_flow`) → cited_search/notebooklm-py →
+resultado. Cada tool formata o resultado (`.ok`/`.detail`/source_id/answer) em string.
+
+## Erros
+Helpers já retornam objetos de resultado (não levantam em falha esperada). As tools
+formatam: Chrome fechado/cookie stale → mensagem clara ("abra Chrome :9222 logado").
+Exceções inesperadas → capturadas e retornadas como texto de erro (sem stacktrace cru).
+
+## Testes
+- Unit (offline): `register(mcp)` adiciona as 9 tools (`mcp.list_tools()`); sem notebooklm-py
+  → `register` é no-op gracioso; annotations de leitura/escrita corretas.
+- Live (Chrome :9222): `notebooklm_list` retorna notebooks; `dual_notebook_to_research` retorna
+  análise. (Camada fina; helpers já validados e2e em sessões anteriores.)
+
+## Arquivos
+- Criar: `perplexity_mcp/nlm_tools.py`.
+- Modificar: `perplexity_mcp/server.py` (registro condicional).
+- Docs: `skills/perplexity-notebooklm/SKILL.md` (usar `mcp__perplexity-pro__*` direto),
+  `README*.md`, `CHANGELOG.md`; bump `0.3.0` (pyproject + plugin + marketplace).
+
+## Verificação
+- `mcp.list_tools()` lista Perplexity + 9 novas tools.
+- Install Perplexity-only (sem extra notebooklm): server sobe, tools NotebookLM ausentes, sem erro.
+- 1 tool de leitura e 1 dual funcionam live com Chrome :9222.
+- Harness `evals/run.py` segue verde.

perplexity_notebooklm-0.3.0/perplexity_mcp/nlm_tools.py

@@ -0,0 +1,138 @@
+"""Tools MCP de NotebookLM + fluxo dual (registradas no server `perplexity-pro`).
+
+Adaptadores FINOS sobre os helpers já validados (`notebooklm_write.nlm_http` e
+`dual_flow`). `register(mcp)` é chamado pelo server dentro de try/except — se o extra
+`notebooklm` (notebooklm-py) não estiver instalado, o import falha e o server segue
+só com as tools do Perplexity (degradação graciosa).
+
+Annotations: leitura = readOnlyHint; escrita = destructiveHint (o cliente trata as de
+escrita com cautela; o checkpoint humano é o permission prompt do Claude Code).
+"""
+
+from __future__ import annotations
+
+from mcp.types import ToolAnnotations
+
+_RO = ToolAnnotations(readOnlyHint=True, destructiveHint=False)
+_WRITE = ToolAnnotations(readOnlyHint=False, destructiveHint=True)
+
+
+def _err(exc: Exception) -> str:
+    return f"erro: {type(exc).__name__}: {exc}"
+
+
+def register(mcp) -> None:
+    """Registra as 9 tools de NotebookLM/dual no server MCP. Import lazy dos helpers.
+
+    No-op se o extra `notebooklm` (notebooklm-py) não estiver instalado — Perplexity-only
+    não expõe tools que não conseguiriam rodar.
+    """
+    import importlib.util
+
+    if importlib.util.find_spec("notebooklm") is None:
+        return  # extra notebooklm ausente → não registra as tools
+
+    # ---- NotebookLM: leitura ----
+    def notebooklm_list() -> str:
+        """Lista os notebooks do NotebookLM da conta (id — título). Requer Chrome :9222 logado."""
+        try:
+            from notebooklm_write.nlm_http import list_notebooks_sync
+
+            nbs = list_notebooks_sync()
+            return "\n".join(f"{nb_id} — {title}" for nb_id, title in nbs) or "(nenhum notebook)"
+        except Exception as exc:
+            return _err(exc)
+
+    def notebooklm_read_summary(notebook_id: str) -> str:
+        """Lê o resumo de um notebook (texto). Útil p/ enriquecer/fact-check no Perplexity."""
+        try:
+            from notebooklm_write.nlm_http import read_summary_sync
+
+            return read_summary_sync(notebook_id) or "(resumo vazio)"
+        except Exception as exc:
+            return _err(exc)
+
+    # ---- NotebookLM: escrita (ESCREVE na conta — não-reversível) ----
+    def notebooklm_add_text(notebook_id: str, title: str, content: str) -> str:
+        """ESCREVE: adiciona uma fonte de texto ao notebook."""
+        try:
+            from notebooklm_write.nlm_http import add_text_sync
+
+            r = add_text_sync(notebook_id, title, content)
+            return f"ok={r.ok} source_id={r.source_id} | {r.detail}"
+        except Exception as exc:
+            return _err(exc)
+
+    def notebooklm_add_url(notebook_id: str, url: str) -> str:
+        """ESCREVE: adiciona fonte por URL (web ou YouTube, auto-detectado)."""
+        try:
+            from notebooklm_write.nlm_http import add_url_sync
+
+            r = add_url_sync(notebook_id, url)
+            return f"ok={r.ok} source_id={r.source_id} | {r.detail}"
+        except Exception as exc:
+            return _err(exc)
+
+    def notebooklm_add_file(notebook_id: str, file_path: str) -> str:
+        """ESCREVE: adiciona fonte por arquivo local (PDF/DOCX/MD/...)."""
+        try:
+            from notebooklm_write.nlm_http import add_file_sync
+
+            r = add_file_sync(notebook_id, file_path)
+            return f"ok={r.ok} source_id={r.source_id} | {r.detail}"
+        except Exception as exc:
+            return _err(exc)
+
+    def notebooklm_generate(notebook_id: str, kind: str) -> str:
+        """ESCREVE: gera artefato no notebook. kind: audio | video | mind_map (áudio/vídeo gastam cota)."""
+        try:
+            from notebooklm_write.nlm_http import generate_artifact_sync
+
+            r = generate_artifact_sync(notebook_id, kind)
+            return f"ok={r.ok} kind={r.kind} | {r.detail}"
+        except Exception as exc:
+            return _err(exc)
+
+    # ---- Dual ----
+    def dual_research_to_notebook(
+        query: str, notebook_id: str, tool: str = "research", verify: bool = True, dedup: bool = True
+    ) -> str:
+        """ESCREVE: pesquisa no Perplexity e injeta como fonte (verify filtra citações, dedup evita repetir). tool: research|search|reason."""
+        try:
+            from dual_flow import research_to_notebook
+
+            r = research_to_notebook(query, notebook_id, tool=tool, verify=verify, dedup=dedup)
+            return f"source_added={r.source_added} | {r.detail}"
+        except Exception as exc:
+            return _err(exc)
+
+    def dual_notebook_to_research(notebook_id: str, tool: str = "search") -> str:
+        """Lê o resumo do notebook e enriquece/fact-check no Perplexity (NÃO escreve). tool: search|reason|research."""
+        try:
+            from dual_flow import notebook_to_research
+
+            r = notebook_to_research(notebook_id, tool=tool)
+            return r.answer or "(sem resposta)"
+        except Exception as exc:
+            return _err(exc)
+
+    def dual_research_to_media(
+        query: str, notebook_id: str, kind: str = "mind_map", tool: str = "search"
+    ) -> str:
+        """ESCREVE: pesquisa → fonte no notebook → gera artefato (kind: audio|video|mind_map)."""
+        try:
+            from dual_flow import research_to_media
+
+            r = research_to_media(query, notebook_id, kind=kind, tool=tool)
+            return f"source_added={r.source_added} artifact_ok={r.artifact_ok} | {r.detail}"
+        except Exception as exc:
+            return _err(exc)
+
+    # Registro com annotations (leitura vs escrita).
+    for fn in (notebooklm_list, notebooklm_read_summary, dual_notebook_to_research):
+        mcp.tool(annotations=_RO)(fn)
+    for fn in (
+        notebooklm_add_text, notebooklm_add_url, notebooklm_add_file, notebooklm_generate,
+        dual_research_to_notebook, dual_research_to_media,
+    ):
+        mcp.tool(annotations=_WRITE)(fn)

{perplexity_notebooklm-0.2.2 → perplexity_notebooklm-0.3.0}/perplexity_mcp/server.py

@@ -13,6 +13,7 @@ autenticada — espelha o comportamento do upstream.
 from __future__ import annotations
 
 import os
+import sys
 
 from pathlib import Path
 
@@ -96,6 +97,16 @@ def _register() -> None:
         mcp.tool()(perplexity_reason)
         mcp.tool()(perplexity_research)
 
+    # NotebookLM + dual: só sobem se o extra `notebooklm` estiver instalado (gracioso).
+    # `register` já faz no-op se notebooklm-py ausente; aqui logamos qualquer erro REAL
+    # de registro no stderr (stdout é o protocolo MCP — não pode poluir) em vez de silenciar.
+    try:
+        from . import nlm_tools
+
+        nlm_tools.register(mcp)
+    except Exception as exc:
+        print(f"[perplexity-pro] aviso: tools NotebookLM/dual não registradas: {exc}", file=sys.stderr)
+
 
 def main() -> None:
     global BACKEND

{perplexity_notebooklm-0.2.2 → perplexity_notebooklm-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "perplexity-notebooklm"
-version = "0.2.2"
+version = "0.3.0"
 description = "Integração dual NotebookLM <-> Perplexity (conta Pro, sem API key) via MCP + skill"
 readme = "README.md"
 requires-python = ">=3.10,<3.14"  # 3.14 quebra wheels do curl_cffi; testado em 3.12/3.13

{perplexity_notebooklm-0.2.2 → perplexity_notebooklm-0.3.0}/skills/perplexity-notebooklm/SKILL.md

@@ -5,9 +5,13 @@ description: Use quando o usuário quiser pesquisar/enriquecer/fact-check com Pe
 
 # Perplexity ↔ NotebookLM (fluxo dual)
 
-Integra dois lados, ambos sem API key paga:
-- **Perplexity (conta Pro)** via MCP `perplexity-pro` (registrado, Connected). Tools: `healthcheck`, `perplexity_ask`, `perplexity_search`, `perplexity_reason`, `perplexity_research`. Auth = cookies em `.env`.
-- **NotebookLM** via `notebooklm_write.nlm_http` — **HTTP/RPC** (notebooklm-py), sem dirigir UI. Capaz de `add_text` (escrita), `list_notebooks`, `read_summary` (leitura). Fallback: `add_source` (Selenium) se o HTTP falhar.
+Integra dois lados, ambos sem API key paga. **Preferir as tools MCP** (v0.3.0+) — o Claude chama direto, sem rodar Python:
+- **Perplexity**: `mcp__perplexity-pro__perplexity_ask|search|reason|research`, `healthcheck`.
+- **NotebookLM**: `mcp__perplexity-pro__notebooklm_list|read_summary|add_text|add_url|add_file|generate`.
+- **Dual**: `mcp__perplexity-pro__dual_research_to_notebook` (PPLX→NLM, verify+dedup), `dual_notebook_to_research` (NLM→PPLX), `dual_research_to_media` (research→fonte→artefato).
+- Tools de escrita têm annotation destrutiva → o Claude Code pede aprovação (checkpoint humano). Os helpers Python (`dual_flow`, `nlm_http`) seguem válidos como fallback.
+
+Detalhes do backend: Perplexity por cookies no `.env`; NotebookLM por cookie-bridge (HTTP/RPC, fallback Selenium).
 
 ### Auth NotebookLM = cookie-bridge (uma vez)
 O Google bloqueia login sob automação. Solução: abrir um Chrome real logado com porta de debug; o `nlm_http` extrai os cookies dele e gera o `storage_state` (depois as chamadas são HTTP puras, sem browser, até o cookie expirar).