@rafaelsouza-ai/agent-buzz 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# @rafaelsouza-ai/agent-buzz
+
+MCP server que envia notificações push em tempo real para o seu celular.
+Quando o agente (Claude Code, Codex, etc.) termina uma task, precisa de
+aprovação ou dá erro — o celular toca.
+
+## Como funciona
+- PWA (Docker + Express) roda atrás do seu Cloudflare Tunnel (HTTPS).
+- O celular registra a subscription Web Push num volume compartilhado.
+- O MCP server (stdio) lê a subscription e faz POST na Web Push API
+  (`web-push`, VAPID self-managed).
+
+## Setup
+1. `docker compose up -d` — sobe a PWA na porta 8080.
+2. Aponte seu Cloudflare Tunnel para `localhost:8080`.
+3. Abra a URL do tunnel no celular → "Adicionar à tela inicial" → "Ativar push".
+4. Configure o MCP no Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "agent-buzz": {
+      "command": "npx",
+      "args": ["@rafaelsouza-ai/agent-buzz"],
+      "env": { "AGENT_BUZZ_DATA": "./data" }
+    }
+  }
+}
+```
+
+> **Importante:** `AGENT_BUZZ_DATA` deve apontar para a pasta `./data` do projeto — a mesma que o `docker-compose.yml` monta em `/data` dentro do container. Se os caminhos divergirem, o MCP server não encontra a subscription e a `notify()` falha silenciosamente.
+
+5. O agente chama `notify(title, body, priority)`.
+
+## Priority
+- `low` — silencioso + badge
+- `normal` — som + badge
+- `high` — som + badge + vibração + requireInteraction
+
+## Limitações (v1)
+- 1 dev / 1 celular (múltiplos dispositivos = v2).
+- A PWA deve permanecer em foreground no celular (Web Push em background no iOS é limitado).
+- Requer secure context (HTTPS via Cloudflare Tunnel).
+- **Segurança do token:** o endpoint `GET /token` não é autenticado. A URL do Cloudflare Tunnel é efêmera (muda a cada `cloudflared` restart), o que mitiga o risco. Para uso em rede pública persistente, considere adicionar um reverse proxy com auth ou injetar o token via env no container.
+
+## Publish
+`npm publish --access=public` (pacote scoped, free tier).

package/bin/agent-buzz.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Entry point stdio. Importa e sobe o MCP server (implementado no Task 5).
+import { startServer } from "../src/server.js";
+startServer();

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@rafaelsouza-ai/agent-buzz",
+  "version": "0.1.0",
+  "description": "MCP server that sends real-time Web Push notifications to your phone",
+  "type": "module",
+  "bin": { "agent-buzz": "bin/agent-buzz.js" },
+  "main": "src/server.js",
+  "files": ["bin", "src"],
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "test": "node --test tests/",
+    "start": "node bin/agent-buzz.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "web-push": "^3.6.0"
+  }
+}

package/src/push.js

@@ -0,0 +1,23 @@
+import webpush from "web-push";
+import { readSubscriptions } from "./storage.js";
+import { loadVapid } from "./vapid.js";
+
+export function sendNotification({ title, body, priority, dataPath }) {
+  const { subscriptions } = readSubscriptions(dataPath);
+  if (!subscriptions.length) {
+    return Promise.reject(new Error("No subscription registered"));
+  }
+  const vapid = loadVapid(dataPath);
+  const payload = JSON.stringify({ title, body, priority });
+  const urgency = priority === "high" ? "high" : "normal";
+  const vapidKeys = {
+    publicKey: vapid.publicKey,
+    privateKey: vapid.privateKey,
+    subject: "mailto:agent-buzz@local",
+  };
+  return Promise.all(
+    subscriptions.map((sub) =>
+      webpush.sendNotification(sub, payload, { TTL: 60, headers: { Urgency: urgency }, vapidKeys })
+    )
+  );
+}

package/src/server.js

@@ -0,0 +1,44 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { sendNotification } from "./push.js";
+import { join } from "node:path";
+
+const DATA_PATH = process.env.AGENT_BUZZ_DATA || join(process.cwd(), "data");
+
+export function buildServer(dataPath = DATA_PATH) {
+  const server = new McpServer({ name: "agent-buzz", version: "0.1.0" });
+
+  server.registerTool(
+    "notify",
+    {
+      title: "Notify phone",
+      description: "Envia uma notificação push em tempo real para o celular do usuário.",
+      inputSchema: {
+        title: z.string().describe("Título da notificação"),
+        body: z.string().describe("Corpo da notificação"),
+        priority: z.enum(["low", "normal", "high"]).default("normal")
+          .describe("low=silencioso+badge, normal=som+badge, high=som+badge+vibração+requireInteraction"),
+      },
+    },
+    async ({ title, body, priority }) => {
+      try {
+        await sendNotification({ title, body, priority, dataPath });
+        return { content: [{ type: "text", text: `Notificação enviada: ${title}` }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: `Falha ao notificar: ${err.message}` }], isError: true };
+      }
+    }
+  );
+
+  return { server, mcp: server };
+}
+
+export function startServer() {
+  const { mcp } = buildServer();
+  const transport = new StdioServerTransport();
+  mcp.connect(transport).catch((err) => {
+    console.error("agent-buzz: falha ao conectar stdio", err);
+    process.exit(1);
+  });
+}

package/src/storage.js

@@ -0,0 +1,9 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+export function readSubscriptions(dataPath) {
+  const file = join(dataPath, "subscriptions.json");
+  if (!existsSync(file)) return { subscriptions: [] };
+  const raw = JSON.parse(readFileSync(file, "utf8"));
+  return { subscriptions: raw.subscriptions ?? [] };
+}

package/src/vapid.js

@@ -0,0 +1,14 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import webpush from "web-push";
+
+export function loadVapid(dataPath) {
+  const file = join(dataPath, "vapid.json");
+  if (existsSync(file)) {
+    return JSON.parse(readFileSync(file, "utf8"));
+  }
+  const keys = webpush.generateVAPIDKeys();
+  mkdirSync(dataPath, { recursive: true });
+  writeFileSync(file, JSON.stringify(keys, null, 2));
+  return keys;
+}