tautau-mcp 0.1.0 → 0.3.0

package/README.md

@@ -99,6 +99,26 @@ Example: *"Transcribe the voice memo at /Users/me/recordings/idea.m4a"*
 
 No arguments. Returns the current quota snapshot for your IP: plan, used/limit, remaining, and reset time.
 
+### `get_scan`
+
+Fetch a page-scan debug bundle by its trace id.
+
+| Argument | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `scanId` | string | when signed out | The 32-char hex trace id the extension popup shows after **Scan this page**; omit when signed in to get your latest scan |
+
+Returns the scan meta (page, status, bundle size, timings), the **service-side RPC trace** (every API call the extension made while the scan ran, with latencies), and a digest of the captured bundle: console errors, failed network requests (with error response bodies), pinned elements, voice/agent actions, the page outline, and the extension's own log. Signed out, the scan id is a capability — anyone holding it can read the scan. Signed in (`auth_login`), reads go through the owner API.
+
+Example: *"Fetch tautau scan 9f2c… and tell me why the voice command didn't click the button"*
+
+### `auth_login` / `auth_status` / `auth_logout`
+
+`auth_login` opens your browser for Google/email sign-in (same Firebase auth as the web app). The page hands the tokens to a **loopback callback** the MCP server is listening on — tokens never leave your machine. The session is stored at `~/.config/tautau/auth.json` (mode 0600) and auto-refreshes. `auth_status` shows who you're signed in as; `auth_logout` deletes the session.
+
+### `list_scans`
+
+Requires `auth_login`. Lists your page scans, newest first (id, status, time, size, page). Pair with `get_scan` to debug: *"List my tautau scans and pull the latest one — why did the page command fail?"*
+
 ## Quotas & anonymity
 
 - The server sends no credentials; tautau tracks anonymous usage by client IP.

package/install.sh

@@ -112,4 +112,4 @@ fi
 
 bold "Done."
 info "Verify any client with: npx -y tautau-mcp (Ctrl-C to stop; it speaks MCP on stdio)."
-info "Tools: transcribe_url, transcribe_audio, get_quota — anonymous quota is tracked per IP."
+info "Tools: transcribe_url, transcribe_audio, get_quota, get_scan, list_scans + auth_login/status/logout — anonymous quota is tracked per IP; auth_login unlocks owner scans."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tautau-mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "MCP server for tautau — transcribe YouTube links, podcast/audio URLs, and local audio files to text from any MCP client",
   "keywords": ["mcp", "model-context-protocol", "transcription", "speech-to-text", "youtube-transcript", "podcast-transcript", "tautau"],
   "homepage": "https://tautau.xyz",

package/src/index.js

@@ -7,10 +7,15 @@
  *   GET  /api/transcribe-url?id=<jobId>                  → poll a pending job
  *   POST /api/transcribe      multipart: file, language, cleanup=true
  *   GET  /api/user/status                                → quota snapshot
+ *   GET  /api/scan/<id>                                  → page-scan debug bundle (trace id = capability)
+ *   GET  /api/scans + /api/scans/<id>                    → owner scan list/read (Firebase bearer)
  *
- * No auth: usage is anonymous and IP-tracked by the tautau service
- * (5 lifetime URL transcripts / 5 lifetime dictations). Quota walls
- * come back as HTTP 429 with a {plan, used, limit, unit, resetsAt} body.
+ * Transcription needs no auth: usage is anonymous and IP-tracked by the
+ * tautau service (5 lifetime URL transcripts / 5 lifetime dictations). Quota
+ * walls come back as HTTP 429 with a {plan, used, limit, unit, resetsAt} body.
+ * Owner-level scan tools use auth_login: a browser sign-in against
+ * /cli-auth hands tokens to a loopback callback; the session is stored at
+ * ~/.config/tautau/auth.json and auto-refreshes.
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -18,8 +23,11 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
-import { readFile, stat } from 'node:fs/promises';
-import { basename, extname } from 'node:path';
+import { readFile, stat, writeFile, mkdir, rm } from 'node:fs/promises';
+import { basename, extname, join } from 'node:path';
+import http from 'node:http';
+import os from 'node:os';
+import { exec } from 'node:child_process';
 
 const API_BASE = (process.env.TAUTAU_API_BASE || 'https://tautau.xyz').replace(/\/+$/, '');
 const LOGIN_URL = `${API_BASE}/login`;
@@ -247,6 +255,299 @@ async function getQuota() {
   return ok(lines.join('\n'));
 }
 
+// ── auth: Firebase session via the /cli-auth loopback callback ──────────
+//
+// auth_login starts a loopback listener and opens ${API_BASE}/cli-auth in the
+// system browser; after Firebase sign-in the page bounces the tokens to the
+// loopback callback (query string — a fragment never reaches an HTTP server).
+// The session lives at ~/.config/tautau/auth.json (0600) and idTokens refresh
+// via securetoken.googleapis.com, same as the Chrome extension.
+
+const SESSION_PATH = join(os.homedir(), '.config', 'tautau', 'auth.json');
+const LOGIN_TIMEOUT_MS = 3 * 60_000;
+
+async function loadSession() {
+  try {
+    const s = JSON.parse(await readFile(SESSION_PATH, 'utf8'));
+    return s && s.refreshToken ? s : null;
+  } catch {
+    return null;
+  }
+}
+
+async function saveSession(s) {
+  await mkdir(join(SESSION_PATH, '..'), { recursive: true });
+  await writeFile(SESSION_PATH, JSON.stringify(s, null, 2), { mode: 0o600 });
+}
+
+/** A live Firebase idToken, refreshing via the refresh token when near expiry. Null = signed out. */
+async function getValidToken() {
+  const s = await loadSession();
+  if (!s) return null;
+  if (Date.now() < (s.expiresAt || 0) - 60_000) return s.idToken;
+  try {
+    const res = await fetch(`https://securetoken.googleapis.com/v1/token?key=${encodeURIComponent(s.apiKey)}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: `grant_type=refresh_token&refresh_token=${encodeURIComponent(s.refreshToken)}`,
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) return null; // refresh revoked/expired — force re-login
+    const data = await res.json();
+    const next = {
+      ...s,
+      idToken: data.id_token,
+      refreshToken: data.refresh_token || s.refreshToken,
+      expiresAt: Date.now() + Number(data.expires_in || 3600) * 1000,
+    };
+    await saveSession(next);
+    return next.idToken;
+  } catch {
+    return null;
+  }
+}
+
+function openBrowser(url) {
+  const quoted = `"${url.replace(/"/g, '\\"')}"`;
+  const cmd = process.platform === 'darwin' ? `open ${quoted}` : process.platform === 'win32' ? `start "" ${quoted}` : `xdg-open ${quoted}`;
+  exec(cmd, () => { /* a failed open still leaves the URL in the tool output */ });
+}
+
+async function authLogin() {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (result) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      server.close();
+      resolve(result);
+    };
+    const server = http.createServer((req, res) => {
+      const u = new URL(req.url || '/', 'http://127.0.0.1');
+      if (u.pathname !== '/callback') {
+        res.writeHead(404).end();
+        return;
+      }
+      const idToken = u.searchParams.get('idToken') || '';
+      if (!idToken) {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end('<h2>tautau CLI sign-in failed — no token received. You can close this tab.</h2>');
+        return;
+      }
+      const session = {
+        idToken,
+        refreshToken: u.searchParams.get('refreshToken') || '',
+        expiresAt: Number(u.searchParams.get('expiresAt')) || Date.now() + 3500e3,
+        email: u.searchParams.get('email') || '',
+        apiKey: u.searchParams.get('apiKey') || '',
+      };
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(
+        '<div style="font-family:system-ui;text-align:center;margin-top:80px">' +
+          '<h2>tautau CLI connected</h2><p>Signed in as <b>' +
+          (session.email || 'your account') +
+          '</b>. You can close this tab and return to your agent.</p></div>'
+      );
+      saveSession(session)
+        .then(() => finish(ok(`Signed in as ${session.email || '(unknown account)'}. Session saved to ${SESSION_PATH} — owner-level tools (list_scans, authed get_scan) are now active.`)))
+        .catch((err) => finish(fail(`Token received but could not save the session: ${err.message}`)));
+    });
+    const timer = setTimeout(() => {
+      finish(fail(`Sign-in timed out after 3 minutes — run auth_login again.`));
+    }, LOGIN_TIMEOUT_MS);
+    server.listen(0, '127.0.0.1', () => {
+      const port = server.address().port;
+      const authUrl = `${API_BASE}/cli-auth?redirect_uri=${encodeURIComponent(`http://127.0.0.1:${port}/callback`)}`;
+      openBrowser(authUrl);
+      console.error(`[tautau-mcp] waiting for sign-in: ${authUrl}`);
+    });
+    server.on('error', (err) => finish(fail(`Could not start the loopback listener: ${err.message}`)));
+  });
+}
+
+async function authStatus() {
+  const s = await loadSession();
+  if (!s) return ok('Not signed in. Run auth_login to connect your tautau account.');
+  const token = await getValidToken();
+  if (!token) return ok(`Session for ${s.email || '(unknown)'} exists but the token could not be refreshed — run auth_login again.`);
+  return ok(`Signed in as ${s.email || '(unknown account)'} · idToken valid until ${new Date(s.expiresAt || 0).toISOString()} (auto-refreshes).`);
+}
+
+async function authLogout() {
+  await rm(SESSION_PATH, { force: true });
+  return ok('Signed out — the saved tautau session was deleted.');
+}
+
+/** Fetch helper with the Firebase bearer when signed in; null when signed out. */
+async function authedFetch(path) {
+  const token = await getValidToken();
+  if (!token) return null;
+  return fetch(`${API_BASE}${path}`, {
+    headers: { Authorization: `Bearer ${token}` },
+    signal: AbortSignal.timeout(15_000),
+  });
+}
+
+async function listScans() {
+  const s = await loadSession();
+  if (!s) return fail('Not signed in — run auth_login first (opens a browser sign-in, tokens stay on this machine).');
+  let res;
+  try {
+    res = await authedFetch('/api/scans');
+  } catch (err) {
+    return fail(`Could not reach ${API_BASE}: ${err.message}`);
+  }
+  if (!res) return fail('Session expired — run auth_login again.');
+  if (!res.ok) return httpError(res);
+  const scans = await res.json().catch(() => []);
+  if (!Array.isArray(scans) || !scans.length) {
+    return ok('No page scans yet. In the extension popup, use "Scan this page" — scans appear here.');
+  }
+  const lines = [`tautau page scans (${scans.length}, newest first):`];
+  scans.slice(0, 25).forEach((sc) => {
+    lines.push(
+      `  ${sc.id} · ${sc.status || '?'} · ${sc.startedAt || '?'} · ${sc.bytes ? `${(Number(sc.bytes) / 1024).toFixed(1)}KB` : '—'} · ${sc.title || sc.url || '(untitled)'}`
+    );
+  });
+  if (scans.length > 25) lines.push(`  … and ${scans.length - 25} more`);
+  lines.push('\nUse get_scan with one of these ids for the full trace + bundle digest.');
+  return ok(lines.join('\n'));
+}
+
+
+// ── get_scan: pull a page-scan debug bundle by its trace id ──────────────
+
+const MAX_DIGEST_ITEMS = 15;
+
+function fmtBundleTime(t) {
+  return typeof t === 'number' ? `+${t}ms` : '+?ms';
+}
+
+/** One line per event, capped — the digest is for an LLM context window. */
+function digestEvents(events, predicate, format) {
+  const matched = (events || []).filter(predicate);
+  const shown = matched.slice(0, MAX_DIGEST_ITEMS).map(format);
+  if (matched.length > MAX_DIGEST_ITEMS) shown.push(`… and ${matched.length - MAX_DIGEST_ITEMS} more`);
+  return shown;
+}
+
+async function getScan({ scanId }) {
+  // Signed in → owner read (sees collecting scans, no IP throttle); the scan
+  // id defaults to your latest scan. Signed out → public capability read
+  // (the id IS the credential) and the id is required.
+  let id = scanId;
+  let res = null;
+  const token = await getValidToken();
+  if (token && !id) {
+    try {
+      const list = await authedFetch('/api/scans');
+      const scans = list && list.ok ? await list.json().catch(() => []) : [];
+      if (Array.isArray(scans) && scans.length) id = scans[0].id;
+    } catch { /* fall through to the missing-id error */ }
+    if (!id) return fail('No scans on your account yet — run one from the extension popup ("Scan this page").');
+  }
+  if (!id) return fail('Missing required argument: scanId (or run auth_login — get_scan then defaults to your latest scan).');
+  if (token) {
+    try {
+      const r = await authedFetch(`/api/scans/${encodeURIComponent(id)}`);
+      if (r && r.ok) res = r;
+    } catch { /* fall back to the public read below */ }
+  }
+  if (!res) {
+    try {
+      res = await fetch(`${API_BASE}/api/scan/${encodeURIComponent(id)}`, {
+        signal: AbortSignal.timeout(15_000),
+      });
+    } catch (err) {
+      return fail(`Could not reach ${API_BASE}: ${err.message}`);
+    }
+  }
+  if (!res.ok) return httpError(res);
+  const meta = await res.json().catch(() => ({}));
+
+  // The scan meta carries a 1h signed GET for the bundle — fetch it direct
+  // from GCS (can be up to 5MB, so it never proxies through the web app).
+  let bundle = null;
+  if (meta.sessionUrl) {
+    try {
+      const bres = await fetch(meta.sessionUrl, { signal: AbortSignal.timeout(30_000) });
+      if (bres.ok) bundle = await bres.json();
+    } catch { /* digest still carries meta + trace without the bundle */ }
+  }
+
+  const out = [];
+  out.push(`tautau page scan ${meta.id || id}`);
+  out.push(
+    `Status: ${meta.status || 'unknown'} · ${meta.bytes ? `${(Number(meta.bytes) / 1024).toFixed(1)}KB bundle` : 'no bundle'} · ` +
+      `${meta.startedAt || '?'} → ${meta.finishedAt || '…'}`
+  );
+  if (meta.url || meta.title) out.push(`Page: ${meta.title || '(untitled)'} — ${meta.url || ''}`);
+
+  const trace = Array.isArray(meta.trace) ? meta.trace : [];
+  out.push(`\nService trace (${trace.length} lines — RPCs the extension made while the scan ran):`);
+  out.push(trace.length ? trace.map((l) => `  ${l}`).join('\n') : '  (none — no traced API calls during this scan)');
+
+  if (bundle) {
+    const events = Array.isArray(bundle.events) ? bundle.events : [];
+    const s = bundle.summary || {};
+    out.push(
+      `\nBundle summary: ${s.consoleErrors ?? 0} console errors · ${s.consoleWarns ?? 0} warns · ` +
+        `${s.networkRequests ?? 0} requests (${s.networkFailures ?? 0} failed) · ${s.clicks ?? 0} clicks · ` +
+        `${s.pins ?? 0} pins · ${s.agentActions ?? 0} agent actions`
+    );
+
+    const consoleErrors = digestEvents(
+      events,
+      (e) => e.kind === 'console' && e.level === 'error',
+      (e) => `  ${fmtBundleTime(e.t)} ${e.text || ''}`
+    );
+    if (consoleErrors.length) out.push(`\nConsole errors:\n${consoleErrors.join('\n')}`);
+
+    const netFails = digestEvents(
+      events,
+      (e) => e.kind === 'network' && (e.status >= 400 || e.status === 0),
+      (e) =>
+        `  ${fmtBundleTime(e.t)} ${e.method || 'GET'} ${e.url || ''} → ${e.status || e.error || '?'}` +
+        (e.body ? `\n    body: ${String(e.body).slice(0, 300)}` : '')
+    );
+    if (netFails.length) out.push(`\nNetwork failures:\n${netFails.join('\n')}`);
+
+    const pins = digestEvents(
+      events,
+      (e) => e.kind === 'element_pin',
+      (e) => `  ${fmtBundleTime(e.t)} <${e.tag || '?'}> ${e.selector || ''} — "${(e.text || '').slice(0, 120)}"`
+    );
+    if (pins.length) out.push(`\nPinned elements:\n${pins.join('\n')}`);
+
+    const agent = digestEvents(
+      events,
+      (e) => e.kind === 'agent',
+      (e) =>
+        `  ${fmtBundleTime(e.t)} "${e.command || ''}" → ${e.action || '?'}${e.index >= 0 ? ` [${e.index}]` : ''} ` +
+        `${e.ok ? 'ok' : 'FAILED'}${e.reason ? ` (${e.reason})` : ''}${e.selector ? ` on ${e.selector}` : ''}`
+    );
+    if (agent.length) out.push(`\nVoice/agent actions:\n${agent.join('\n')}`);
+
+    const snaps = Array.isArray(bundle.snapshots) ? bundle.snapshots : [];
+    if (snaps.length && snaps[0].outline) {
+      const o = snaps[0].outline;
+      const headings = (o.headings || []).slice(0, 10).map((h) => `  ${'#'.repeat(Math.min(h.level || 1, 6))} ${h.text || ''}`);
+      out.push(
+        `\nPage outline: ${(o.interactive || []).length} interactive elements, ` +
+          `${(snaps[0].assets || []).length} assets loaded${headings.length ? `\n${headings.join('\n')}` : ''}`
+      );
+    }
+
+    const extLog = Array.isArray(bundle.extensionLog) ? bundle.extensionLog : [];
+    if (extLog.length) out.push(`\nExtension log:\n${extLog.map((l) => `  ${l}`).join('\n')}`);
+  } else {
+    out.push('\n(Bundle could not be fetched — meta + service trace above are still authoritative.)');
+  }
+
+  return ok(out.join('\n'));
+}
+
 const TOOLS = [
   {
     name: 'transcribe_url',
@@ -290,10 +591,50 @@ const TOOLS = [
     description: 'Check the current tautau transcription quota (anonymous usage is tracked per IP).',
     inputSchema: { type: 'object', properties: {} },
   },
+  {
+    name: 'get_scan',
+    description:
+      'Fetch a tautau page-scan debug bundle by its trace id (from the extension popup "Scan this page"). ' +
+      'Returns the scan meta, the service-side RPC trace, and a digest of the captured bundle: console errors, ' +
+      'failed requests (with response bodies), pinned elements, voice/agent actions, page outline, and the extension log. ' +
+      'Signed in (auth_login): owner read — omit scanId to get your latest scan. ' +
+      'Signed out: the scan id is required and works as a capability — anyone holding it can read the scan.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        scanId: { type: 'string', description: 'The 32-char hex scan/trace id. Optional when signed in — defaults to your latest scan.' },
+      },
+    },
+  },
+  {
+    name: 'auth_login',
+    description:
+      'Sign the MCP server into a tautau account: opens a browser window for Google/email sign-in and stores ' +
+      'the session locally (~/.config/tautau/auth.json, tokens never leave the machine). Unlocks owner-level ' +
+      'tools (list_scans, authed get_scan).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'auth_status',
+    description: 'Show which tautau account the MCP server is signed in as (and whether the token refreshes).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'auth_logout',
+    description: 'Sign the MCP server out and delete the locally stored tautau session.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'list_scans',
+    description:
+      'List your tautau page scans (newest first: id, status, time, size, page). Requires auth_login. ' +
+      'Use get_scan with one of the ids for the full trace + bundle digest.',
+    inputSchema: { type: 'object', properties: {} },
+  },
 ];
 
 const server = new Server(
-  { name: 'tautau-mcp', version: '0.1.0' },
+  { name: 'tautau-mcp', version: '0.3.0' },
   { capabilities: { tools: {} } }
 );
 
@@ -312,6 +653,18 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         return await transcribeAudio(args);
       case 'get_quota':
         return await getQuota();
+      case 'get_scan':
+        if (args.scanId !== undefined && typeof args.scanId !== 'string')
+          return fail('scanId must be a string');
+        return await getScan(args);
+      case 'auth_login':
+        return await authLogin();
+      case 'auth_status':
+        return await authStatus();
+      case 'auth_logout':
+        return await authLogout();
+      case 'list_scans':
+        return await listScans();
       default:
         return fail(`Unknown tool: ${name}`);
     }