# `google-meet-mcp` — Multimodal Meeting Copilot & FastMCP Server

<div align="center">

[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/)
[![FastMCP Protocol](https://img.shields.io/badge/MCP-FastMCP%202024--11--05-brightgreen.svg)](https://modelcontextprotocol.io/)
[![Tests Passing](https://img.shields.io/badge/tests-495%20passed%20(100%25)-success.svg)](https://github.com/DuongNAD/google-meet-mcp)
[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED.svg?logo=docker&logoColor=white)](https://www.docker.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)]()
[![GitHub Repo](https://img.shields.io/badge/GitHub-DuongNAD%2Fgoogle--meet--mcp-181717.svg?logo=github)](https://github.com/DuongNAD/google-meet-mcp)

**Production-grade, zero-loss multimodal Google Meet copilot, 3-hour+ resilient session buffering, WebRTC audio & slide vision ingestion, interactive web dashboard, multi-channel alerts (Telegram & Zalo), and deep executive intelligence synthesis connecting Google Antigravity, Claude, and AI Agents with Google Meet.**

---

<h3>
  <a href="#-english">🇬🇧 English</a> &nbsp;&nbsp;•&nbsp;&nbsp; <a href="#-tiếng-việt">🇻🇳 Tiếng Việt</a>
</h3>

---

</div>

---

# 🇬🇧 English

## Table of Contents
- [1. Overview & Key Capabilities](#1-overview--key-capabilities)
- [2. Competitive Comparison Matrix](#2-competitive-comparison-matrix)
- [3. System Architecture & Data Flow](#3-system-architecture--data-flow)
- [4. Repository Directory Structure](#4-repository-directory-structure)
- [5. 1-Click Quickstart & Installation](#5-1-click-quickstart--installation)
  - [Option A: Local Python Installation](#option-a-local-python-installation-recommended-for-development)
  - [Option B: Turnkey Docker & Docker Compose](#option-b-turnkey-docker--docker-compose-recommended-for-production)
- [6. Client Ingestion Options](#6-client-ingestion-options)
  - [Method 1: Chrome Extension (Manifest V3)](#method-1-chrome-extension-manifest-v3---recommended)
  - [Method 2: Tampermonkey Userscript](#method-2-tampermonkey-userscript-lightweight-alternative)
- [7. CLI Command Reference](#7-cli-command-reference)
- [8. Interactive Web Dashboard](#8-interactive-web-dashboard)
- [9. Interactive Meeting Chat Assistant & Gemini Intelligence](#9-interactive-meeting-chat-assistant--gemini-intelligence)
- [10. Multi-Channel Alert Engine (Telegram & Zalo)](#10-multi-channel-alert-engine-telegram--zalo)
- [11. Complete RESTful API Specifications](#11-complete-restful-api-specifications)
- [12. FastMCP Tools for AI Agents](#12-fastmcp-tools-for-ai-agents-antigravity-claude-cursor)
- [13. Environment Variables Reference](#13-environment-variables-reference)
- [14. Troubleshooting Guide Matrix](#14-troubleshooting-guide-matrix)
- [15. Testing & Quality Assurance](#15-testing--quality-assurance)
- [16. Security & Privacy Guarantees](#16-security--privacy-guarantees)

---

## 1. Overview & Key Capabilities

Strategic executive, technical architecture, and board meetings routinely run for **2 to 3+ hours** (exceeding 25,000–45,000 spoken words). Traditional note-taking tools and single-modal AI bots suffer from critical vulnerabilities:
1. **Fragility & Catastrophic Data Loss**: Network drops, browser tab crashes, or token expirations wipe out hours of unsaved context.
2. **Context Window Overload & Hallucination**: Submitting raw 45,000-word transcripts directly into an LLM causes lost commitments, overlooked decision points, and superficial summaries.
3. **Missing Visual & Audio Evidence**: Presenters share slides with dense architecture charts, code snippets, financial tables, and QR codes that voice-only transcripts fail to capture.
4. **Scattered Multi-Account Environments**: Workspace domains support Google Meet REST API & Drive auto-transcripts, whereas personal Google accounts only support live closed captions.

**`google-meet-mcp`** is an enterprise-ready solution engineered to solve these challenges completely:
- 🛡️ **Zero-Loss Append-Only Buffer**: Writes every spoken utterance (`.utterances.jsonl`), slide screenshot (`.jpg`), and WebRTC Opus audio chunk (`.webm`) directly to durable disk storage (`~/.google_meet_mcp`).
- 👁️ **Multimodal Capture & Vision Engine**: Synchronizes live captions with speaker diarization, high-resolution slide captures on visual transitions, and embedded QR code/hyperlink extraction.
- 📊 **Interactive Web Dashboard**: Embedded SPA (served on `http://127.0.0.1:8765/dashboard`) providing a session history browser, slide carousel gallery, audio playback synchronized with captions, and multi-format minutes exports (Markdown, HTML, JSON).
- 💬 **Interactive Meeting Chat Assistant**: Natural-language conversational Q&A over the entire meeting transcript and slides powered by Gemini Multimodal API with offline heuristic fallback and interactive audio/slide citation pills.
- 🔔 **Multi-Channel Alert Engine**: Instant mention notifications dispatched via native **Telegram Bot** and **Zalo OA/Webhook** with direct links to the meeting dashboard.
- ⚡ **1-Click Packaging & Turnkey Docker**: Single-command startup (`google-meet-mcp start/companion/dashboard`) and unprivileged hardened Docker container with automated healthcheck.

---

## 2. Competitive Comparison Matrix

| Feature / Capability | Standard MCP Bots | Commercial Notetakers (Otter / Fireflies) | `google-meet-mcp` |
| :--- | :---: | :---: | :---: |
| **3-Hour+ Zero-Loss Disk Buffer** | ❌ Memory-only | ⚠️ Dependent on cloud stability | ✅ **Append-only `.jsonl` on durable disk** |
| **Multimodal Slide Vision & QR Capture** | ❌ Text only | ❌ Voice / Text only | ✅ **High-res slide capture + QR extraction** |
| **Synchronized Audio & Caption Player** | ❌ No audio playback | ⚠️ Proprietary cloud player | ✅ **Local WebM Opus player with timestamp seek** |
| **Offline / No-API-Key Synthesis** | ❌ Hard crash without API | ❌ Cloud only | ✅ **Heuristic fallback engine included** |
| **Multi-Channel Mentions (Telegram & Zalo)**| ❌ None | ⚠️ Slack / Email only | ✅ **Native Telegram Bot + Zalo OA / Webhook** |
| **Support Personal & Workspace Accounts** | ⚠️ Workspace API only | ⚠️ Requires bot joining call | ✅ **Dual support (Live captions + REST API)** |
| **FastMCP Protocol for AI Agents** | ⚠️ Basic tools | ❌ Closed proprietary SaaS | ✅ **Full FastMCP 2024-11-05 for Antigravity & Claude** |
| **Data Privacy & On-Premises Control** | ⚠️ Depends on host | ❌ Cloud vendor storage | ✅ **100% Local storage under `~/.google_meet_mcp`** |

---

## 3. System Architecture & Data Flow

### ASCII Architecture Overview

```text
+---------------------------------------------------------------------------------------+
|                               GOOGLE MEET (meet.google.com)                           |
+---------------------------------------------------------------------------------------+
        │ (Live Captions Scraper)   │ (Slide Vision Canvas)        │ (WebRTC Opus Audio)
        ▼                           ▼                              ▼
+---------------------------------------------------------------------------------------+
|                         CHROME EXTENSION (Manifest V3)                                |
|  - Floating Status Badge & Controls [🟢 Recording | 📊 Dashboard | ⚡ AI Synthesis]    |
|  - Background Service Worker (Proxy for Google Meet CSP connect-src)                  |
+---------------------------------------------------------------------------------------+
                                            │ HTTP POST (port 8765)
                                            ▼
+---------------------------------------------------------------------------------------+
|                       GOOGLE-MEET-MCP COMPANION HTTP SERVER                           |
|                                                                                       |
|  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────┐  |
|  │  POST /chunk     │  │  POST /snapshot  │  │  POST /audio     │  │ GET /health   │  |
|  │  (Live Captions) │  │  (Slide Vision)  │  │  (WebRTC Opus)   │  │ (Docker Probe)│  |
|  └─────────┬────────┘  └─────────┬────────┘  └─────────┬────────┘  └───────────────┘  |
|            │                     │                     │                              |
|            ▼                     ▼                     ▼                              |
|  ┌─────────────────────────────────────────────────────────────────────────────────┐  |
|  │             SessionManager (Append-Only Durable Storage: ~/.google_meet_mcp)    │  |
|  │             • .utterances.jsonl  • slides/*.jpg  • audio/*.webm  • .meta.json   │  |
|  └───────────────────────────────────────┬─────────────────────────────────────────┘  |
|                                          │                                            |
|       ┌──────────────────────────────────┴──────────────────────────────────┐         |
|       ▼                                                                     ▼         |
| ┌──────────────────────────────────────┐          ┌────────────────────────────────┐  |
| │  Interactive Web Dashboard (port 8765)│          │ Autonomous Synthesis & AI Chat │  |
| │  - Sessions Browser & Statistics     │          │ - Executive Summary            │  |
| │  - Slide Carousel & QR/Link Gallery  │          │ - Action Matrix & Decisions    │  |
| │  - Synchronized WebM Audio Player    │          │ - Gemini Multimodal Chat API   │  |
| │  - Multi-Channel Alerts Modal        │          │ - Multi-format Exporters:      │  |
| │    (Telegram Bot + Zalo Webhook/OA)  │          │   • Markdown • HTML • JSON     │  |
| └──────────────────────────────────────┘          └────────────────────────────────┘  |
+---------------------------------------------------------------------------------------+
                                            │ FastMCP stdio (JSON-RPC 2.0)
                                            ▼
+---------------------------------------------------------------------------------------+
|                     AI AGENT ECOSYSTEM (Google Antigravity / Claude)                  |
|                 Tools: meet_start_session, meet_synthesize_meeting, ...               |
+---------------------------------------------------------------------------------------+
```

### Mermaid Architecture Diagram

```mermaid
flowchart TD
    subgraph Client["Browser: meet.google.com"]
        GM[Google Meet Meeting Room]
        EXT["Chrome Extension MV3<br/>(Floating Badge & Service Worker)"]
        SCRIPT["Tampermonkey Userscript<br/>(Alternative Ingestion)"]
        GM -->|Captions, Slides & Audio| EXT
        GM -.->|Captions only| SCRIPT
    end

    subgraph Server["google-meet-mcp Companion Server (Port 8765)"]
        HTTP["HTTP Endpoints<br/>/chunk, /snapshot, /audio, /health"]
        SM["SessionManager<br/>(Append-Only Buffer)"]
        SYN["MeetingSynthesizer<br/>(Executive Summary, Action Matrix)"]
        CHAT["AI Chat Engine<br/>(Gemini Multimodal API)"]
        ALERT["Alert Dispatcher<br/>(Telegram Bot + Zalo OA)"]
        DASH["Web Dashboard SPA<br/>(/dashboard)"]
    end

    subgraph Storage["Durable Storage (~/.google_meet_mcp)"]
        DISK["Session Store<br/>• .utterances.jsonl<br/>• slides/*.jpg<br/>• audio/*.webm<br/>• exports/"]
    end

    subgraph Consumers["Downstream Consumers"]
        USER["User via Web Browser"]
        TELEGRAM["Telegram Messenger"]
        ZALO["Zalo Notification"]
        MCP["Google Antigravity / Claude (FastMCP stdio)"]
    end

    EXT -->|HTTP POST| HTTP
    SCRIPT -.->|HTTP POST /chunk| HTTP
    HTTP --> SM
    SM <--> DISK
    SM --> SYN
    SM --> CHAT
    SM --> ALERT
    HTTP --> DASH
    DASH <--> USER
    ALERT --> TELEGRAM
    ALERT --> ZALO
    Server -->|FastMCP stdio| MCP
```

---

## 4. Repository Directory Structure

```text
google-meet-mcp/
├── .dockerignore
├── .gitignore
├── Dockerfile                  # Hardened, non-root (UID 10001) production image
├── docker-compose.yml          # Turnkey 1-command container orchestration
├── pyproject.toml              # Build & dependency declarations (FastMCP, Pydantic, etc.)
├── uv.lock                     # Deterministic dependency lockfile
├── LICENSE                     # MIT License
├── README.md                   # Complete bilingual documentation
│
├── extension/                  # Chrome Extension (Manifest V3)
│   ├── manifest.json           # MV3 extension manifest
│   ├── background.js           # Service worker proxy (bypasses Google Meet CSP)
│   ├── content.js              # DOM caption observer, slide capturer, tab audio recorder
│   ├── popup.html / popup.js   # Extension settings & quick status popup
│   └── icons/                  # High-resolution extension icons
│
├── src/google_meet_mcp/        # Core Python Application
│   ├── __init__.py
│   ├── __main__.py             # Direct execution entrypoint
│   ├── cli.py                  # Rich CLI commands (start, dashboard, companion, etc.)
│   ├── config.py               # Central environment and path configurations
│   ├── server.py               # FastMCP standard server (stdio)
│   │
│   ├── auth/                   # Google OAuth2 Authentication Engine
│   │   └── google_auth.py      # Browser-based OAuth2 workflow with local callback
│   │
│   ├── capture/                # Ingestion Server & Web Dashboard
│   │   ├── companion_server.py # aiohttp HTTP server handling /chunk, /audio, /snapshot, /chat
│   │   ├── meet_captions.user.js # Tampermonkey userscript alternative
│   │   └── templates/
│   │       └── dashboard.html  # Embedded single-page application (Vue/Alpine-like UI)
│   │
│   ├── engine/                 # Intelligence & Synthesis Engine
│   │   ├── prompts.py          # Multimodal & executive synthesis system prompts
│   │   └── synthesizer.py      # Map-Reduce & sliding window synthesis pipeline
│   │
│   ├── google_client/          # Google API Clients
│   │   ├── meet_api.py         # Google Meet REST API v2 client
│   │   └── drive_api.py        # Google Drive API v3 transcript parser
│   │
│   ├── notifications/          # Real-time Alerting System
│   │   ├── alert_detector.py   # Mention & keyword detector with Vietnamese diacritic normalization
│   │   ├── telegram.py         # Telegram Bot native HTTP dispatcher
│   │   └── zalo.py             # Zalo Webhook & Zalo OA OpenAPI v3.0 dispatcher
│   │
│   └── session/                # Data Models & Storage
│       ├── models.py           # Pydantic v2 domain schemas (Utterance, Slide, Audio, Synthesis)
│       ├── session_manager.py  # Durable append-only storage manager
│       └── chat.py             # Interactive AI meeting assistant engine
│
└── tests/                      # Automated Test Suite (495 tests)
    ├── conftest.py             # Fixtures, mocks, and test utilities
    ├── e2e/                    # End-to-end multi-tier test scenarios
    │   ├── test_tier1_features.py
    │   ├── test_tier2_boundaries.py
    │   ├── test_tier3_interactions.py
    │   └── test_tier4_workloads.py
    └── test_*.py               # Comprehensive unit & integration tests
```

---

## 5. 1-Click Quickstart & Installation

### Option A: Local Python Installation (Recommended for Development)

Requires Python 3.10+ (Python 3.11 recommended).

```bash
# 1. Clone repository
git clone https://github.com/DuongNAD/google-meet-mcp.git
cd google-meet-mcp

# 2. Setup virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3. Install dependencies in editable mode
pip install -e ".[dev]"

# 4. Launch 1-Click Web Dashboard & Companion Server
google-meet-mcp dashboard
```

The Web Dashboard will automatically launch in your default web browser at `http://127.0.0.1:8765/dashboard`.

### Option B: Turnkey Docker & Docker Compose (Recommended for Production)

Run the hardened, unprivileged container with built-in healthcheck:

```bash
# 1. (Optional) Set API keys in your shell
export GEMINI_API_KEY="your-gemini-api-key"
export TELEGRAM_BOT_TOKEN="your-bot-token"
export TELEGRAM_CHAT_ID="your-chat-id"

# 2. Launch container in background
docker compose up -d

# 3. Verify health status
docker compose ps
curl -s http://localhost:8765/health

# 4. Open dashboard in browser
open http://localhost:8765/dashboard  # macOS
# xdg-open http://localhost:8765/dashboard  # Linux
```

---

## 6. Client Ingestion Options

You can capture Google Meet sessions using either the Chrome Extension or the Userscript:

### Method 1: Chrome Extension (Manifest V3) — Recommended

Full multimodal support: Live Captions, High-Resolution Slides, and WebRTC Tab Audio.

1. Open Chrome and navigate to `chrome://extensions/`.
2. Toggle on **Developer mode** (top-right corner).
3. Click **Load unpacked** and select the `extension/` folder in this repository.
4. Join any Google Meet call (`https://meet.google.com/*-*-*`).
5. Turn on closed captions in Google Meet (press `c`).
6. The **Floating Status Badge** will appear at the bottom-left of your meeting screen:
   - 🟢 **Green badge**: Connected to companion server (`http://127.0.0.1:8765`).
   - 🔴 **Red badge**: Server offline (check `google-meet-mcp companion`).
   - **Counter**: Displays live count of captured utterances, slides, and audio chunks.
   - **Quick Actions**: "Dashboard" button, "Synthesize" button, and "Audio" toggle.

### Method 2: Tampermonkey Userscript (Lightweight Alternative)

Captures live captions directly without loading an unpacked extension.

1. Install [Tampermonkey](https://www.tampermonkey.net/) in your browser.
2. Create a new script and paste the content of [`src/google_meet_mcp/capture/meet_captions.user.js`](src/google_meet_mcp/capture/meet_captions.user.js).
3. Save the script and join your Google Meet meeting.
4. Enable captions in Google Meet (`c`). Utterances stream automatically to port 8765.

---

## 7. CLI Command Reference

The `google-meet-mcp` CLI provides rich terminal commands powered by `rich`:

| Command | Syntax | Description |
| :--- | :--- | :--- |
| **`start`** | `google-meet-mcp start [--mode companion\|stdio\|all] [--host HOST] [--port PORT] [--open-browser]` | 1-Click production service launcher. In `all` mode, runs both HTTP companion and FastMCP stdio simultaneously. |
| **`dashboard`** | `google-meet-mcp dashboard [--host HOST] [--port PORT] [--no-browser]` | 1-Click launcher that starts the companion server and automatically opens the Web Dashboard in the browser. |
| **`companion`** | `google-meet-mcp companion [--host HOST] [--port PORT]` | Starts HTTP live ingestion server and hosts the Web Dashboard on port 8765. |
| **`stdio`** | `google-meet-mcp stdio` | Executes the FastMCP server over standard I/O (stdio) for Google Antigravity and Claude Desktop. |
| **`status`** | `google-meet-mcp status` | Displays Google OAuth credential status and prints a rich summary table of all stored sessions. |
| **`auth`** | `google-meet-mcp auth [--no-browser]` | Runs Google OAuth2 browser authentication flow for Google Meet and Drive APIs. |
| **`synthesize`** | `google-meet-mcp synthesize <SESSION_ID> [--export]` | Synthesizes a meeting session and prints executive summary, action items, and decisions. |

---

## 8. Interactive Web Dashboard

The embedded Web Dashboard at `http://127.0.0.1:8765/dashboard` provides an all-in-one executive workstation:

- 🗂️ **Session Explorer**: Browse past and ongoing meetings, view total duration, active participant list, word count, and speech volume.
- 🎵 **Synchronized Audio Player**: Play back recorded WebM Opus audio chunks with sub-second timeline seeking linked to utterance timestamps.
- 🖼️ **Slide Carousel & Gallery**: Browse high-definition presentation slides captured at visual transition points, view extracted QR codes, and click detected URLs.
- 📝 **Multi-Format Minutes Exporter**: 1-click download of executive minutes in:
  - **Markdown (`.md`)**: Ready for Obsidian, Notion, or GitHub.
  - **Printable HTML (`.html`)**: Beautiful executive typography formatted for PDF printing.
  - **JSON (`.json`)**: Raw structured data for enterprise pipelines.
- ⚙️ **Multi-Channel Alert Modal**: Live configuration of Telegram Bot and Zalo notifications with built-in test buttons.

---

## 9. Interactive Meeting Chat Assistant & Gemini Intelligence

The dashboard includes a real-time conversational AI panel:
- Ask natural-language questions about the meeting:
  - *"What was decided regarding the database migration?"*
  - *"Who was assigned the Q3 roadmap deliverables?"*
  - *"Explain the system architecture shown on slide 3."*
- **Powered by Gemini Multimodal API**: Integrates both transcript text and slide images for context-aware answers.
- **Interactive Citation Pills**:
  - `[MM:SS]` (e.g., `[04:15]`): Instantly seeks the audio player to the exact second.
  - `[Slide #N]` (e.g., `[Slide #2]`): Navigates the slide gallery to the referenced visual.
- **Offline Heuristic Fallback**: Operates deterministically without an API key using local text mining and decision extraction algorithms.

---

## 10. Multi-Channel Alert Engine (Telegram & Zalo)

Stay informed even when stepping away from long meetings:
- ✈️ **Telegram Bot Native**: Sends real-time notifications with speaker attribution, transcript snippet, and an inline button linking directly to the Web Dashboard.
- 💬 **Zalo Integration**: Supports both Zalo Webhooks (for custom gateways / n8n) and Zalo Official Account (OA) OpenAPI v3.0.
- 🎯 **Smart Mention Matching**:
  - Diacritic normalization (`strip_accents`) handles Vietnamese names accurately (e.g., `Dương`, `Duong`, `duongnad`).
  - Urgent keyword detection (`deadline`, `gấp`, `hỏi`, `ơi`, `nhờ`, `urgent`).
  - Cooldown suppression prevents alert storms when a name is repeated multiple times.

---

## 11. Complete RESTful API Specifications

The Companion Server exposes 14+ standardized RESTful endpoints:

| Method | Endpoint | Description | Payload / Parameters | Response |
| :--- | :--- | :--- | :--- | :--- |
| `GET` | `/health` | Liveness and Docker health probe | None | `{"status": "ok", "service": "google-meet-mcp-companion"}` |
| `GET` | `/dashboard` | Serves Interactive Web Dashboard SPA | None | HTML Web Application |
| `GET` | `/` | Redirects to Dashboard | None | HTTP 302 to `/dashboard` |
| `POST` | `/chunk` | Ingest captions with speaker diarization | `{"meeting_code": str, "speaker": str, "text": str, "timestamp": str}` | `{"status": "ok", "session_id": str, "utterances_count": int}` |
| `POST` | `/snapshot` | Ingest slide image with QR/links | `{"meeting_code": str, "image_base64": str, "qr_codes": [], "links": []}` | `{"status": "ok", "session_id": str, "slide_index": int}` |
| `POST` | `/audio` | Ingest WebRTC Opus audio chunk | `{"meeting_code": str, "audio_base64": str, "duration_seconds": float}` | `{"status": "ok", "session_id": str, "chunk_index": int}` |
| `POST` | `/session/start` | Explicitly start named session | `{"title": str, "meeting_code": str, "session_id": Optional[str]}` | `MeetingSession` JSON object |
| `POST` | `/session/end` | End session and trigger synthesis | `{"session_id": str}` | `{"status": "ended", "session_id": str}` |
| `GET` | `/api/sessions` | List recorded sessions | `?limit=20` | `List[SessionSummary]` JSON |
| `GET` | `/api/session/{id}` | Detailed session payload | Path `{id}` | `SessionDetail` (utterances, slides, audio) |
| `GET` | `/api/session/{id}/slides/{file}` | Serve high-res slide JPEG | Path `{id}`, `{file}` | Binary `image/jpeg` |
| `GET` | `/api/session/{id}/audio/{file}` | Stream WebM Opus chunk (RFC 7233 Range) | Path `{id}`, `{file}`, `Range` header | Binary `audio/webm` (HTTP 200 or 206) |
| `GET` | `/api/session/{id}/export` | Download formatted minutes | `?format=markdown\|html\|json` | File attachment download |
| `POST` | `/api/session/{id}/chat` | Meeting Chat Assistant Q&A | `{"question": str, "stream": bool}` | SSE stream or JSON answer with citations |
| `GET` | `/api/alerts/config` | Read current alert configuration | None | `AlertConfig` JSON |
| `POST` | `/api/alerts/config` | Update alert configuration | `AlertConfig` JSON | `{"status": "ok", "config": ...}` |
| `POST` | `/api/alerts/test` | Dispatch test alert (Telegram/Zalo) | `{"channel": "telegram"\|"zalo", ...}` | `{"status": "ok"\|"error", "message": ...}` |
| `POST` | `/session/synthesize` | Trigger AI meeting synthesis | `{"session_id": str}` | `{"status": "ok", "exports": {...}}` |

---

## 12. FastMCP Tools for AI Agents (Antigravity, Claude, Cursor)

Connect `google-meet-mcp` to autonomous AI coding and workflow agents:

### 1. Google Antigravity (`~/.gemini/config/mcp_config.json`)
```json
{
  "mcpServers": {
    "google-meet": {
      "command": "/path/to/google-meet-mcp/.venv/bin/python",
      "args": ["-m", "google_meet_mcp.cli", "stdio"],
      "env": {
        "GOOGLE_MEET_MCP_DATA_DIR": "/Users/duongnad/.google_meet_mcp",
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}
```

### 2. Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "google-meet": {
      "command": "/path/to/google-meet-mcp/.venv/bin/python",
      "args": ["-m", "google_meet_mcp.cli", "stdio"]
    }
  }
}
```

### 3. Cursor IDE (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "google-meet": {
      "command": "google-meet-mcp",
      "args": ["stdio"]
    }
  }
}
```

### Available FastMCP Tools:
1. `meet_start_session`: Initialize a durable session for multi-hour live recording.
2. `meet_ingest_chunk`: Append a spoken utterance line directly to the disk buffer.
3. `meet_get_live_status`: Real-time session inspection (active speakers, word counts, duration).
4. `meet_list_sessions`: List all historical sessions recorded on disk.
5. `meet_fetch_google_transcript`: Retrieve Google Meet API v2 transcripts.
6. `meet_fetch_drive_transcript`: Query and parse auto-saved transcript docs from Google Drive.
7. `meet_list_recent_conferences`: List recent Google Meet conferences via Google Calendar API.
8. `meet_synthesize_meeting`: Execute deep AI synthesis (Executive Summary, Action Matrix, Decision Log, Timeline).
9. `meet_export_minutes`: Export comprehensive minutes to Markdown, HTML, or JSON.
10. `meet_check_auth` / `meet_setup_auth`: Inspect and initiate Google OAuth2 workflow.

---

## 13. Environment Variables Reference

| Variable | Default | Description |
| :--- | :--- | :--- |
| `GOOGLE_MEET_MCP_DATA_DIR` | `~/.google_meet_mcp` | Root directory for sessions, slides, audio, and exports |
| `GOOGLE_MEET_COMPANION_HOST` | `127.0.0.1` | Bind host for the companion HTTP server & dashboard |
| `GOOGLE_MEET_COMPANION_PORT` | `8765` | Port for the companion HTTP server & dashboard |
| `GEMINI_API_KEY` | *(None)* | Google Gemini API key for multimodal chat and synthesis |
| `TELEGRAM_BOT_TOKEN` | *(None)* | Telegram Bot token created via `@BotFather` |
| `TELEGRAM_CHAT_ID` | *(None)* | Telegram user or group chat ID for alerts |
| `ZALO_WEBHOOK_URL` | *(None)* | Webhook endpoint for forwarding Zalo alerts |
| `ZALO_OA_ACCESS_TOKEN` | *(None)* | Official Account access token for Zalo OpenAPI v3.0 |
| `ZALO_USER_ID` | *(None)* | Target Zalo user ID to receive direct messages |
| `GOOGLE_MEET_CREDENTIALS_FILE` | `~/.google_meet_mcp/credentials.json` | Path to Google OAuth2 client credentials JSON |
| `GOOGLE_MEET_TOKEN_FILE` | `~/.google_meet_mcp/token.json` | Path to saved Google OAuth2 user token JSON |

---

## 14. Troubleshooting Guide Matrix

| Issue / Symptom | Root Cause | Resolution Steps |
| :--- | :--- | :--- |
| **Port 8765 Conflict** (`Address already in use`) | Another companion instance or process occupies port 8765. | Identify PID with `lsof -i :8765` and terminate it, or specify an alternative port: `google-meet-mcp companion --port 8766`. |
| **Extension Connection Failed** (`Failed to fetch`) | Companion server is offline or blocked by firewall. | Run `google-meet-mcp companion` or `docker compose up -d`. Verify via `curl -s http://127.0.0.1:8765/health`. |
| **Google Meet CSP Error** (`Refused connect-src`) | Google Meet CSP blocks direct third-party fetch calls. | Use the updated Chrome Extension which routes all requests through the background Service Worker. |
| **No Audio Captured** | Browser tab audio capture permission not granted. | When starting screen/tab sharing in Chrome, ensure the **"Share tab audio"** checkbox is checked. |
| **Docker Permission Denied** on `~/.google_meet_mcp` | Host volume owned by root instead of non-root UID 10001. | Run `sudo chown -R 10001:10001 ~/.google_meet_mcp` on host system before starting Docker container. |
| **Gemini AI Chat Fails** | Missing or invalid Gemini API key. | Set `export GEMINI_API_KEY="your-key"` or enter key directly in Dashboard Settings Modal. Offline heuristic fallback will be used automatically if omitted. |
| **Telegram Alert Not Received** | Invalid Bot Token or user has not messaged the bot. | Verify token via `curl -s https://api.telegram.org/bot<TOKEN>/getMe`. Ensure you clicked `/start` in your bot's chat. |

---

## 15. Testing & Quality Assurance

The codebase includes an exhaustive **495-test** suite spanning 4 rigorous validation tiers:
- **Tier 1 (Core Features)**: Unit tests for SessionManager, Synthesizer, Chat Assistant, and Alert Detectors.
- **Tier 2 (Boundaries & Edge Cases)**: Multi-hour rollover tests, malformed inputs, missing headers, and partial audio chunks.
- **Tier 3 (Interactions & Endpoints)**: REST API contract tests, Range streaming header validation, and WebSocket fallbacks.
- **Tier 4 (Workloads & Stress)**: 3-hour meeting simulation with 45,000+ utterances, concurrent writes, and eviction stability.

```bash
# Run complete test suite (495 tests)
.venv/bin/pytest tests/ -v

# Run with coverage report
.venv/bin/pytest tests/ --cov=google_meet_mcp --cov-report=term-missing
```

---

## 16. Security & Privacy Guarantees

- 🔒 **Local-First Processing**: All transcripts, slide captures, and audio chunks reside exclusively on your local machine (`~/.google_meet_mcp`). No meeting data is uploaded to third-party servers unless you configure an external LLM API key.
- 🛡️ **Hardened Docker Container**: Runs under an unprivileged user (`appuser`, UID 10001) with `no-new-privileges:true` and automated container healthcheck.
- 🔑 **Safe Credential Management**: OAuth tokens and API keys are stored in user-restricted paths and ignored by git (`.gitignore`).

---

<br/>
<br/>

---

# 🇻🇳 Tiếng Việt

## Mục Lục
- [1. Tổng quan & Vấn đề giải quyết](#1-tổng-quan--vấn-đề-giải-quyết)
- [2. Ma trận So sánh Tính năng Cạnh tranh](#2-ma-trận-so-sánh-tính-năng-cạnh-tranh)
- [3. Sơ đồ Kiến trúc & Luồng Dữ liệu](#3-sơ-đồ-kiến-trúc--luồng-dữ-liệu)
- [4. Cấu trúc Thư mục Dự án](#4-cấu-trúc-thư-mục-dự-án)
- [5. Hướng dẫn Cài đặt & Khởi động 1-Chạm](#5-hướng-dẫn-cài-đặt--khởi-động-1-chạm)
  - [Cách 1: Chạy Cục bộ với Python](#cách-1-chạy-cục-bộ-với-python-khuyên-dùng-khi-phát-triển)
  - [Cách 2: Triển khai Nhanh với Docker & Docker Compose](#cách-2-triển-khai-nhanh-với-docker--docker-compose-khuyên-dùng-cho-production)
- [6. Tùy chọn Thu thập Dữ liệu Cuộc họp](#6-tùy-chọn-thu-thập-dữ-liệu-cuộc-họp)
  - [Cách 1: Chrome Extension (Manifest V3)](#cách-1-chrome-extension-manifest-v3---khuyến-nghị)
  - [Cách 2: Tampermonkey Userscript](#cách-2-tampermonkey-userscript-nhẹ--nhanh)
- [7. Bảng Lệnh CLI Chi tiết](#7-bảng-lệnh-cli-chi-tiết)
- [8. Giao diện Web Dashboard Tương tác](#8-giao-diện-web-dashboard-tương-tác)
- [9. Trợ lý Hỏi đáp Cuộc họp AI & Trí tuệ Gemini](#9-trợ-lý-hỏi-đáp-cuộc-họp-ai--trí-tuệ-gemini)
- [10. Động cơ Cảnh báo Đa kênh (Telegram & Zalo)](#10-động-cơ-cảnh-báo-đa-kênh-telegram--zalo)
- [11. Đặc tả Toàn diện API RESTful](#11-đặc-tả-toàn-diện-api-restful)
- [12. Danh mục Công cụ FastMCP cho AI Agent](#12-danh-mục-công-cụ-fastmcp-cho-ai-agent-antigravity-claude-cursor)
- [13. Bảng Tham chiếu Biến Môi trường](#13-bảng-tham-chiếu-biến-môi-trường)
- [14. Cẩm nang Xử lý Sự cố & Thắc mắc](#14-cẩm-nang-xử-lý-sự-cố--thắc-mắc)
- [15. Kiểm thử & Đảm bảo Chất lượng](#15-kiểm-thử--đảm-bảo-chất-lượng)
- [16. Cam kết An toàn & Bảo mật Dữ liệu](#16-cam-kết-an-toàn--bảo-mật-dữ-liệu)

---

## 1. Tổng quan & Vấn đề giải quyết

Các cuộc họp điều hành chiến lược, kiến trúc kỹ thuật hoặc đại hội cổ đông thường kéo dài **từ 2 đến 3 tiếng hoặc lâu hơn** (tương đương 25,000 – 45,000 từ thoại). Các công cụ ghi chú thông thường và bot phiên âm truyền thống bộc lộ những hạn chế chí mạng:
1. **Rủi ro mất trắng dữ liệu (Data Loss)**: Mất mạng, sập nguồn hoặc vô tình đóng tab trình duyệt khiến toàn bộ biên bản ghi trước đó biến mất.
2. **Quá tải ngữ cảnh (Context Window Overload)**: Nạp toàn bộ 45,000 từ thô vào LLM khiến AI tóm tắt qua loa, bỏ sót cam kết hành động (Action Items) và quyết định chốt ở giữa buổi họp.
3. **Thiếu hụt hình ảnh & âm thanh minh chứng**: Diễn giả trình chiếu slide kiến trúc, sơ đồ kỹ thuật, bảng tài chính hoặc mã QR tài liệu nhưng công cụ âm thanh không ghi nhận được.
4. **Môi trường tài khoản phân tán**: Google Workspace hỗ trợ Meet API/Drive, trong khi tài khoản cá nhân thông thường chỉ hiển thị phụ đề trực tiếp (Live Captions).

**`google-meet-mcp`** giải quyết triệt để toàn bộ vấn đề trên:
- 🛡️ **Bộ đệm Append-Only Chống Mất Dữ Liệu**: Ghi tức thì từng câu thoại (`.utterances.jsonl`), ảnh slide (`.jpg`) và khối âm thanh Opus (`.webm`) xuống ổ cứng cục bộ (`~/.google_meet_mcp`).
- 👁️ **Thu thập Đa phương thức & Thị giác AI**: Đồng bộ hóa phụ đề (phân tách người nói), tự động chụp slide độ nét cao khi diễn giả chuyển trang và bóc tách mã QR/liên kết đính kèm.
- 📊 **Web Dashboard Quản lý Tương tác**: Ứng dụng Web trực quan (`http://127.0.0.1:8765/dashboard`) duyệt lịch sử họp, trình chiếu slide gallery, phát âm thanh WebM khớp với phụ đề và xuất biên bản Markdown/HTML/JSON.
- 💬 **Trợ lý Hỏi đáp Cuộc họp AI (Meeting Chat)**: Chat tự do hỏi đáp mọi nội dung cuộc họp hỗ trợ bởi Gemini Multimodal API, đính kèm nút trích dẫn `[MM:SS]` phát lại âm thanh và `[Slide #X]` mở trực tiếp trang slide.
- 🔔 **Cảnh báo Đa kênh Tức thì (Telegram + Zalo)**: Gửi tin nhắn cảnh báo khi bạn được gọi tên qua bot Telegram chính chủ hoặc Zalo OA/Webhook kèm liên kết mở Dashboard.
- ⚡ **Đóng gói 1-Chạm & Docker Tiện lợi**: Khởi động tức thì bằng lệnh CLI (`google-meet-mcp dashboard`) hoặc triển khai container Docker bảo mật chạy không dùng quyền root.

---

## 2. Ma trận So sánh Tính năng Cạnh tranh

| Tính năng / Năng lực | Bot MCP Thông thường | Công cụ Thương mại (Otter / Fireflies) | `google-meet-mcp` |
| :--- | :---: | :---: | :---: |
| **Ghi đệm 3h+ Chống mất dữ liệu** | ❌ Chỉ lưu trên RAM | ⚠️ Phụ thuộc độ ổn định mạng cloud | ✅ **Ghi nối tiếp `.jsonl` vào ổ cứng** |
| **Bắt ảnh Slide & Bóc tách mã QR** | ❌ Chỉ xử lý văn bản | ❌ Chỉ xử lý giọng nói | ✅ **Chụp slide HD + nhận diện QR/link** |
| **Phát lại Audio đồng bộ với Phụ đề** | ❌ Không lưu audio | ⚠️ Player đóng trên cloud | ✅ **Phát WebM Opus tua chuẩn mốc giây** |
| **Tổng hợp Ngoại tuyến (Không cần API Key)** | ❌ Lỗi nếu thiếu API | ❌ Hoàn toàn dùng cloud | ✅ **Tích hợp thuật toán heuristic cục bộ** |
| **Cảnh báo Gọi tên (Telegram & Zalo)** | ❌ Không có | ⚠️ Chỉ có Slack / Email | ✅ **Gửi Telegram Bot + Zalo OA / Webhook** |
| **Hỗ trợ cả Tài khoản Cá nhân & Workspace** | ⚠️ Chỉ chạy với Workspace API | ⚠️ Bắt buộc thêm bot vào phòng họp | ✅ **Đa cơ chế (Phụ đề sống + REST API)** |
| **Giao thức FastMCP cho AI Agent** | ⚠️ Công cụ cơ bản | ❌ Hệ thống đóng SaaS | ✅ **Chuẩn FastMCP 2024-11-05 cho Antigravity & Claude** |
| **Bảo mật & Tự chủ Dữ liệu 100%** | ⚠️ Phụ thuộc máy host | ❌ Dữ liệu lưu máy chủ bên thứ ba | ✅ **Lưu cục bộ tại `~/.google_meet_mcp`** |

---

## 3. Sơ đồ Kiến trúc & Luồng Dữ liệu

### Sơ đồ Khối ASCII

```text
+---------------------------------------------------------------------------------------+
|                               GOOGLE MEET (meet.google.com)                           |
+---------------------------------------------------------------------------------------+
        │ (Thu thập Phụ đề)         │ (Chụp Slide Trình chiếu)     │ (Luồng Âm thanh Opus)
        ▼                           ▼                              ▼
+---------------------------------------------------------------------------------------+
|                         CHROME EXTENSION (Manifest V3)                                |
|  - Huy hiệu Nổi & Nút Điều khiển [🟢 Đang ghi | 📊 Dashboard | ⚡ Tổng hợp AI]         |
|  - Service Worker (Vượt rào CSP connect-src của Google Meet an toàn)                 |
+---------------------------------------------------------------------------------------+
                                            │ HTTP POST (cổng 8765)
                                            ▼
+---------------------------------------------------------------------------------------+
|                       GOOGLE-MEET-MCP COMPANION HTTP SERVER                           |
|                                                                                       |
|  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────┐  |
|  │  POST /chunk     │  │  POST /snapshot  │  │  POST /audio     │  │ GET /health   │  |
|  │  (Phụ đề Thoại)  │  │  (Ảnh Slide HD)  │  │  (WebRTC Opus)   │  │ (Kiểm tra Sống│  |
|  └─────────┬────────┘  └─────────┬────────┘  └─────────┬────────┘  └───────────────┘  |
|            │                     │                     │                              |
|            ▼                     ▼                     ▼                              |
|  ┌─────────────────────────────────────────────────────────────────────────────────┐  |
|  │             SessionManager (Lưu trữ Bền vững Cục bộ: ~/.google_meet_mcp)        │  |
|  │             • .utterances.jsonl  • slides/*.jpg  • audio/*.webm  • .meta.json   │  |
|  └───────────────────────────────────────┬─────────────────────────────────────────┘  |
|                                          │                                            |
|       ┌──────────────────────────────────┴──────────────────────────────────┐         |
|       ▼                                                                     ▼         |
| ┌──────────────────────────────────────┐          ┌────────────────────────────────┐  |
| │  Web Dashboard Trực quan (cổng 8765) │          │ Động cơ Tổng hợp & Trợ lý Chat │  |
| │  - Danh sách Cuộc họp & Thống kê     │          │ - Tóm tắt Điều hành            │  |
| │  - Trình duyệt Slide & Thư viện QR   │          │ - Ma trận Quyết định & Việc cần│  |
| │  - Trình phát Audio WebM Đồng bộ     │          │ - API Chat Gemini Multimodal   │  |
| │  - Hộp thoại Cài đặt Cảnh báo        │          │ - Xuất Biên bản Đa định dạng:  │  |
| │    (Telegram Bot + Zalo Webhook/OA)  │          │   • Markdown • HTML In • JSON  │  |
| └──────────────────────────────────────┘          └────────────────────────────────┘  |
+---------------------------------------------------------------------------------------+
                                            │ FastMCP stdio (JSON-RPC 2.0)
                                            ▼
+---------------------------------------------------------------------------------------+
|                     HỆ SINH THÁI AI AGENT (Google Antigravity / Claude)               |
|                 Công cụ: meet_start_session, meet_synthesize_meeting, ...             |
+---------------------------------------------------------------------------------------+
```

### Sơ đồ Luồng Dữ liệu Mermaid

```mermaid
flowchart TD
    subgraph Browser["Trình duyệt: meet.google.com"]
        GM[Phòng họp Google Meet]
        EXT["Chrome Extension MV3<br/>(Huy hiệu Nổi & Service Worker)"]
        SCRIPT["Tampermonkey Userscript<br/>(Thu thập Nhẹ)"]
        GM -->|Phụ đề, Slide & Audio| EXT
        GM -.->|Chỉ phụ đề| SCRIPT
    end

    subgraph Server["Máy chủ Companion (Cổng 8765)"]
        HTTP["HTTP Endpoints<br/>/chunk, /snapshot, /audio, /health"]
        SM["SessionManager<br/>(Bộ đệm Append-Only)"]
        SYN["MeetingSynthesizer<br/>(Tóm tắt, Ma trận Việc cần làm)"]
        CHAT["Động cơ Chat AI<br/>(Gemini Multimodal API)"]
        ALERT["Bộ phát Cảnh báo<br/>(Telegram Bot + Zalo OA)"]
        DASH["Giao diện Web Dashboard<br/>(/dashboard)"]
    end

    subgraph Storage["Lưu trữ Bền vững (~/.google_meet_mcp)"]
        DISK["Thư mục Phiên họp<br/>• .utterances.jsonl<br/>• slides/*.jpg<br/>• audio/*.webm<br/>• exports/"]
    end

    subgraph Consumers["Người dùng & Tác tử AI"]
        USER["Người dùng qua Trình duyệt"]
        TELEGRAM["Kênh / Chat Telegram"]
        ZALO["Ứng dụng Zalo"]
        MCP["Google Antigravity / Claude (FastMCP stdio)"]
    end

    EXT -->|HTTP POST| HTTP
    SCRIPT -.->|HTTP POST /chunk| HTTP
    HTTP --> SM
    SM <--> DISK
    SM --> SYN
    SM --> CHAT
    SM --> ALERT
    HTTP --> DASH
    DASH <--> USER
    ALERT --> TELEGRAM
    ALERT --> ZALO
    Server -->|FastMCP stdio| MCP
```

---

## 4. Cấu trúc Thư mục Dự án

```text
google-meet-mcp/
├── .dockerignore
├── .gitignore
├── Dockerfile                  # Docker image bảo mật không dùng quyền root (UID 10001)
├── docker-compose.yml          # Triển khai trọn gói tiện lợi 1 câu lệnh
├── pyproject.toml              # Khai báo gói cài đặt và thư viện phụ thuộc
├── uv.lock                     # Khóa phiên bản gói xác định
├── LICENSE                     # Giấy phép nguồn mở MIT
├── README.md                   # Tài liệu hướng dẫn song ngữ hoàn chỉnh
│
├── extension/                  # Tiện ích mở rộng Chrome Extension (Manifest V3)
│   ├── manifest.json           # Khai báo quyền hạn và tài nguyên tiện ích
│   ├── background.js           # Service worker vượt rào CSP Google Meet
│   ├── content.js              # Lắng nghe DOM phụ đề, chụp slide, thu âm tab
│   ├── popup.html / popup.js   # Giao diện bật popup kiểm tra trạng thái
│   └── icons/                  # Bộ icon độ phân giải cao
│
├── src/google_meet_mcp/        # Mã nguồn cốt lõi Python
│   ├── __init__.py
│   ├── __main__.py             # Điểm chạy thực thi trực tiếp
│   ├── cli.py                  # Giao diện dòng lệnh CLI tương tác Rich
│   ├── config.py               # Quản lý đường dẫn và biến môi trường
│   ├── server.py               # Máy chủ FastMCP stdio chuẩn MCP
│   │
│   ├── auth/                   # Luồng xác thực Google OAuth2
│   │   └── google_auth.py      # Mở trình duyệt xác thực và nhận mã callback
│   │
│   ├── capture/                # Máy chủ Ingestion & Giao diện Dashboard
│   │   ├── companion_server.py # Máy chủ aiohttp xử lý /chunk, /audio, /snapshot, /chat
│   │   ├── meet_captions.user.js # Userscript Tampermonkey thay thế
│   │   └── templates/
│   │       └── dashboard.html  # Ứng dụng Web SPA hiện đại
│   │
│   ├── engine/                 # Động cơ Trí tuệ Nhân tạo & Tổng hợp Cuộc họp
│   │   ├── prompts.py          # Tập hợp câu lệnh định hình phong cách tóm tắt
│   │   └── synthesizer.py      # Kỹ thuật Map-Reduce & cửa sổ trượt tổng hợp
│   │
│   ├── google_client/          # Tương tác API Google
│   │   ├── meet_api.py         # Google Meet REST API v2
│   │   └── drive_api.py        # Bóc tách transcript Google Drive v3
│   │
│   ├── notifications/          # Hệ thống Cảnh báo Đa kênh
│   │   ├── alert_detector.py   # Nhận diện gọi tên và chuẩn hóa tiếng Việt không dấu
│   │   ├── telegram.py         # Gửi tin nhắn Telegram Bot native
│   │   └── zalo.py             # Gửi tin nhắn Zalo Webhook & Zalo OA OpenAPI v3.0
│   │
│   └── session/                # Quản lý Dữ liệu & Lưu trữ Bền vững
│       ├── models.py           # Mô hình dữ liệu Pydantic v2 chuẩn hóa
│       ├── session_manager.py  # Bộ đệm append-only ghi trực tiếp ổ cứng
│       └── chat.py             # Động cơ trợ lý trò chuyện hỏi đáp cuộc họp
│
└── tests/                      # Bộ kiểm thử tự động toàn diện (495 tests)
    ├── conftest.py             # Bộ dữ liệu mẫu và mock
    ├── e2e/                    # Các kịch bản kiểm thử tích hợp 4 tầng
    │   ├── test_tier1_features.py
    │   ├── test_tier2_boundaries.py
    │   ├── test_tier3_interactions.py
    │   └── test_tier4_workloads.py
    └── test_*.py               # Các bài kiểm thử đơn vị & tích hợp chi tiết
```

---

## 5. Hướng dẫn Cài đặt & Khởi động 1-Chạm

### Cách 1: Chạy Cục bộ với Python (Khuyên dùng khi Phát triển)

Yêu cầu máy tính cài đặt Python 3.10 trở lên (khuyến nghị 3.11).

```bash
# 1. Tải mã nguồn về máy
git clone https://github.com/DuongNAD/google-meet-mcp.git
cd google-meet-mcp

# 2. Khởi tạo và kích hoạt môi trường ảo
python3 -m venv .venv
source .venv/bin/activate

# 3. Cài đặt các thư viện cần thiết
pip install -e ".[dev]"

# 4. Khởi động Web Dashboard & Companion Server 1-chạm
google-meet-mcp dashboard
```

Trình duyệt của bạn sẽ tự động mở giao diện Dashboard tại `http://127.0.0.1:8765/dashboard`.

### Cách 2: Triển khai Nhanh với Docker & Docker Compose (Khuyên dùng cho Production)

Triển khai container an toàn chạy bằng tài khoản thường `appuser` (UID 10001, không quyền root, có cơ chế healthcheck):

```bash
# 1. (Tùy chọn) Khai báo khóa API vào môi trường
export GEMINI_API_KEY="khoa-gemini-cua-ban"
export TELEGRAM_BOT_TOKEN="token-bot-telegram"
export TELEGRAM_CHAT_ID="id-chat-telegram"

# 2. Bật dịch vụ chạy ngầm với Docker Compose
docker compose up -d

# 3. Kiểm tra trạng thái hoạt động
docker compose ps
curl -s http://localhost:8765/health

# 4. Mở Dashboard trên trình duyệt
open http://localhost:8765/dashboard
```

---

## 6. Tùy chọn Thu thập Dữ liệu Cuộc họp

Bạn có thể lựa chọn thu thập dữ liệu bằng Chrome Extension hoặc Userscript:

### Cách 1: Chrome Extension (Manifest V3) — Khuyến nghị

Thu thập đầy đủ đa phương thức: Phụ đề, Ảnh chụp Slide HD và Luồng Âm thanh Tab WebRTC.

1. Mở trình duyệt Chrome và truy cập: `chrome://extensions/`.
2. Bật công tắc **Developer mode** ở góc trên cùng bên phải.
3. Nhấp vào nút **Load unpacked** và chọn thư mục `extension/` trong dự án này.
4. Tham gia bất kỳ phòng họp Google Meet nào (`https://meet.google.com/*-*-*`).
5. Bật phụ đề trực tiếp trong Meet (phím tắt `c`).
6. **Huy hiệu Trạng thái Nổi** sẽ xuất hiện ở góc dưới bên trái màn hình cuộc họp:
   - 🟢 **Chấm xanh**: Đã kết nối thành công với máy chủ companion (`http://127.0.0.1:8765`).
   - 🔴 **Chấm đỏ**: Máy chủ chưa chạy (kiểm tra lại `google-meet-mcp companion`).
   - **Bộ đếm**: Thống kê số câu thoại, số slide và khối âm thanh đã thu thập theo thời gian thực.
   - **Thao tác nhanh**: Nút mở "Dashboard", nút kích hoạt "Tổng hợp AI", nút bật "Audio".

### Cách 2: Tampermonkey Userscript (Nhẹ & Nhanh)

Thu thập phụ đề trực tiếp mà không cần cài extension dạng unpacked.

1. Cài đặt tiện ích [Tampermonkey](https://www.tampermonkey.net/) trên trình duyệt của bạn.
2. Tạo mới một script và dán toàn bộ nội dung tệp [`src/google_meet_mcp/capture/meet_captions.user.js`](src/google_meet_mcp/capture/meet_captions.user.js).
3. Lưu lại và tham gia phòng họp Google Meet. Bật phụ đề (`c`), câu thoại sẽ tự động truyền về cổng 8765.

---

## 7. Bảng Lệnh CLI Chi tiết

Bộ công cụ `google-meet-mcp` cung cấp các lệnh trực quan:

| Lệnh | Cú pháp | Ý nghĩa & Mô tả |
| :--- | :--- | :--- |
| **`start`** | `google-meet-mcp start [--mode companion\|stdio\|all] [--host HOST] [--port PORT] [--open-browser]` | Khởi động toàn diện hệ thống. Mặc định chạy `companion`. Ở chế độ `all`, chạy song song cả Companion HTTP và FastMCP stdio. |
| **`dashboard`** | `google-meet-mcp dashboard [--host HOST] [--port PORT] [--no-browser]` | Khởi động máy chủ companion và tự động bật Web Dashboard trên trình duyệt mặc định. |
| **`companion`** | `google-meet-mcp companion [--host HOST] [--port PORT]` | Khởi động máy chủ nạp phụ đề HTTP và phục vụ Web Dashboard tại cổng 8765. |
| **`stdio`** | `google-meet-mcp stdio` | Chạy máy chủ FastMCP qua luồng nhập/xuất chuẩn (stdio) dành cho Google Antigravity và Claude Desktop. |
| **`status`** | `google-meet-mcp status` | Kiểm tra tình trạng OAuth Google và in danh sách các phiên họp đã lưu trữ dưới dạng bảng Rich. |
| **`auth`** | `google-meet-mcp auth [--no-browser]` | Mở trình duyệt thực hiện cấp quyền Google OAuth2 cho Meet API và Drive API. |
| **`synthesize`** | `google-meet-mcp synthesize <SESSION_ID> [--export]` | Tổng hợp phiên họp ngay từ dòng lệnh và in tóm tắt điều hành, tùy chọn xuất ra Markdown. |

---

## 8. Giao diện Web Dashboard Tương tác

Truy cập Dashboard tại `http://127.0.0.1:8765/dashboard` để sử dụng đầy đủ các tiện ích:

- 🗂️ **Quản lý Phiên họp**: Xem danh sách các cuộc gọi, thống kê số người tham gia, tổng số câu nói, số từ và thời lượng cuộc họp.
- 🎵 **Trình phát Âm thanh Đồng bộ**: Nghe lại các đoạn ghi âm WebM Opus, bấm tua trực tiếp đến mốc thời gian của từng câu thoại.
- 🖼️ **Thư viện Slide & Ảnh minh chứng**: Duyệt các slide trình chiếu chất lượng cao, nhấp mở trực tiếp các mã QR và liên kết tài liệu được bóc tách tự động.
- 📝 **Tải Biên bản Đa định dạng**: Xuất biên bản tức thì dưới dạng:
  - **Markdown (`.md`)**: Phù hợp chép vào Obsidian, Notion, GitHub.
  - **HTML In ấn (`.html`)**: Trình bày chuyên nghiệp theo chuẩn tài liệu điều hành, sẵn sàng in ra PDF.
  - **JSON (`.json`)**: Dữ liệu có cấu trúc cho các hệ thống phần mềm khác.
- ⚙️ **Cài đặt Cảnh báo Trực quan**: Hộp thoại cấu hình và kiểm tra kết nối gửi tin nhắn đến Telegram và Zalo.

---

## 9. Trợ lý Hỏi đáp Cuộc họp AI & Trí tuệ Gemini

Khung chat tương tác trực tiếp trên Web Dashboard:
- Đặt câu hỏi tự nhiên về bất kỳ nội dung nào trong cuộc họp:
  - *"Ai được giao phụ trách chuẩn bị hạ tầng cơ sở dữ liệu?"*
  - *"Quyết định chốt về ngân sách quý 4 là bao nhiêu?"*
  - *"Giải thích sơ đồ kiến trúc xuất hiện ở slide số 3."*
- **Tích hợp Gemini Multimodal API**: AI đọc hiểu đồng thời cả văn bản phụ đề và nội dung hình ảnh trong slide trình chiếu.
- **Nút Trích dẫn Tương tác**:
  - Nút `[MM:SS]` (ví dụ `[04:15]`): Nhấp vào để tua trình phát âm thanh đến đúng giây diễn giả phát biểu.
  - Nút `[Slide #X]` (ví dụ `[Slide #2]`): Nhấp vào để trượt slide gallery đến đúng trang tài liệu liên quan.
- **Chế độ Ngoại tuyến Tự hành (Heuristic Fallback)**: Hoạt động trơn tru ngay cả khi không có Internet hoặc chưa nhập khóa API nhờ động cơ bóc tách ngữ nghĩa cục bộ.

---

## 10. Động cơ Cảnh báo Đa kênh (Telegram & Zalo)

Không bao giờ bỏ lỡ các thông tin quan trọng khi đang bận việc khác:
- ✈️ **Kênh Telegram Bot Native**: Nhận tin nhắn cảnh báo tức thì kèm tên người gọi, nội dung thoại và nút bấm trực tiếp mở Dashboard.
- 💬 **Kênh Zalo**: Hỗ trợ cả Zalo Webhook (cho hệ thống n8n / bot riêng) và Zalo Official Account (OA) OpenAPI v3.0.
- 🎯 **Nhận diện Thông minh & Chuẩn hóa Tiếng Việt**:
  - Tự động bỏ dấu (`strip_accents`) nhận diện chuẩn xác các cách viết tên (ví dụ: `Dương`, `Duong`, `duongnad`).
  - Lọc các từ khóa cấp bách (`deadline`, `gấp`, `hỏi`, `ơi`, `nhờ`, `urgent`).
  - Cơ chế chống spam (cooldown) tránh gửi lặp tin nhắn khi tên được nhắc liên tục trong thời gian ngắn.

---

## 11. Đặc tả Toàn diện API RESTful

Máy chủ Companion phục vụ 14+ endpoint chuẩn RESTful:

| Phương thức | Endpoint | Chức năng | Tham số / Body | Cấu trúc Dữ liệu Trả về |
| :--- | :--- | :--- | :--- | :--- |
| `GET` | `/health` | Kiểm tra trạng thái hoạt động (Docker Healthcheck) | Không | `{"status": "ok", "service": "google-meet-mcp-companion"}` |
| `GET` | `/dashboard` | Giao diện Web Dashboard tương tác | Không | Ứng dụng HTML Web SPA |
| `GET` | `/` | Điều hướng trang chủ | Không | Chuyển hướng HTTP 302 về `/dashboard` |
| `POST` | `/chunk` | Nạp câu thoại phụ đề trực tiếp | `{"meeting_code": str, "speaker": str, "text": str, "timestamp": str}` | `{"status": "ok", "session_id": str, "utterances_count": int}` |
| `POST` | `/snapshot` | Nạp ảnh chụp slide và mã QR/link | `{"meeting_code": str, "image_base64": str, "qr_codes": [], "links": []}` | `{"status": "ok", "session_id": str, "slide_index": int}` |
| `POST` | `/audio` | Nạp đoạn âm thanh Opus WebRTC | `{"meeting_code": str, "audio_base64": str, "duration_seconds": float}` | `{"status": "ok", "session_id": str, "chunk_index": int}` |
| `POST` | `/session/start` | Khởi tạo phiên họp mới | `{"title": str, "meeting_code": str, "session_id": Optional[str]}` | Đối tượng JSON `MeetingSession` |
| `POST` | `/session/end` | Kết thúc phiên và kích hoạt tổng hợp | `{"session_id": str}` | `{"status": "ended", "session_id": str}` |
| `GET` | `/api/sessions` | Lấy danh sách các phiên họp đã lưu | `?limit=20` | Mảng JSON `List[SessionSummary]` |
| `GET` | `/api/session/{id}` | Lấy chi tiết phiên họp | Đường dẫn `{id}` | Đối tượng `SessionDetail` (thoại, slide, audio) |
| `GET` | `/api/session/{id}/slides/{file}` | Phục vụ tệp ảnh slide chất lượng cao | Đường dẫn `{id}`, `{file}` | Nhị phân `image/jpeg` |
| `GET` | `/api/session/{id}/audio/{file}` | Phát luồng âm thanh WebM Opus (hỗ trợ RFC 7233 Range) | Đường dẫn `{id}`, `{file}`, Header `Range` | Nhị phân `audio/webm` (HTTP 200 hoặc 206) |
| `GET` | `/api/session/{id}/export` | Tải xuống biên bản cuộc họp | `?format=markdown\|html\|json` | Tệp đính kèm tải về |
| `POST` | `/api/session/{id}/chat` | Trợ lý Chat AI hỏi đáp cuộc họp | `{"question": str, "stream": bool}` | Luồng SSE hoặc JSON câu trả lời kèm trích dẫn |
| `GET` | `/api/alerts/config` | Đọc cấu hình cảnh báo hiện tại | Không | Đối tượng JSON `AlertConfig` |
| `POST` | `/api/alerts/config` | Cập nhật cấu hình cảnh báo | Dữ liệu JSON `AlertConfig` | `{"status": "ok", "config": ...}` |
| `POST` | `/api/alerts/test` | Thử nghiệm gửi tin cảnh báo (Telegram/Zalo) | `{"channel": "telegram"\|"zalo", ...}` | `{"status": "ok"\|"error", "message": ...}` |
| `POST` | `/session/synthesize` | Kích hoạt AI tổng hợp cuộc họp | `{"session_id": str}` | `{"status": "ok", "exports": {...}}` |

---

## 12. Danh mục Công cụ FastMCP cho AI Agent (Antigravity, Claude, Cursor)

Tích hợp `google-meet-mcp` vào các tác tử AI lập trình:

### 1. Google Antigravity (`~/.gemini/config/mcp_config.json`)
```json
{
  "mcpServers": {
    "google-meet": {
      "command": "/duong-dan/google-meet-mcp/.venv/bin/python",
      "args": ["-m", "google_meet_mcp.cli", "stdio"],
      "env": {
        "GOOGLE_MEET_MCP_DATA_DIR": "/Users/tenban/.google_meet_mcp",
        "GEMINI_API_KEY": "khoa-gemini-cua-ban"
      }
    }
  }
}
```

### 2. Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "google-meet": {
      "command": "/duong-dan/google-meet-mcp/.venv/bin/python",
      "args": ["-m", "google_meet_mcp.cli", "stdio"]
    }
  }
}
```

### 3. Cursor IDE (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "google-meet": {
      "command": "google-meet-mcp",
      "args": ["stdio"]
    }
  }
}
```

### Danh sách Công cụ FastMCP:
1. `meet_start_session`: Bắt đầu phiên họp mới với bộ đệm an toàn hỗ trợ họp 3 tiếng+.
2. `meet_ingest_chunk`: Ghi nhận trực tiếp từng câu nói vào bộ đệm ổ cứng.
3. `meet_get_live_status`: Xem nhanh trạng thái trực tiếp (thời lượng, số từ, người nói).
4. `meet_list_sessions`: Xem danh sách các phiên họp đã lưu trên ổ cứng.
5. `meet_fetch_google_transcript`: Tải toàn bộ transcript qua Google Meet REST API v2.
6. `meet_fetch_drive_transcript`: Phân tích tệp transcript tự động lưu trên Google Drive.
7. `meet_list_recent_conferences`: Liệt kê các cuộc họp Google Meet gần nhất.
8. `meet_synthesize_meeting`: Tổng hợp sâu toàn diện: Tóm tắt điều hành, Ma trận nhiệm vụ, Bảng quyết định.
9. `meet_export_minutes`: Xuất biên bản họp hoàn chỉnh ra Markdown, HTML hoặc JSON.
10. `meet_check_auth` / `meet_setup_auth`: Kiểm tra và khởi động luồng xác thực Google OAuth2.

---

## 13. Bảng Tham chiếu Biến Môi trường

| Biến môi trường | Mặc định | Ý nghĩa & Mô tả |
| :--- | :--- | :--- |
| `GOOGLE_MEET_MCP_DATA_DIR` | `~/.google_meet_mcp` | Thư mục gốc lưu trữ các phiên họp, slide, audio và xuất dữ liệu |
| `GOOGLE_MEET_COMPANION_HOST` | `127.0.0.1` | Địa chỉ IP máy chủ companion và Web Dashboard lắng nghe |
| `GOOGLE_MEET_COMPANION_PORT` | `8765` | Cổng mạng máy chủ companion và Web Dashboard phục vụ |
| `GEMINI_API_KEY` | *(Không có)* | Khóa API Google Gemini phục vụ chat hỏi đáp và tổng hợp thông minh |
| `TELEGRAM_BOT_TOKEN` | *(Không có)* | Token bot Telegram tạo qua `@BotFather` |
| `TELEGRAM_CHAT_ID` | *(Không có)* | ID cuộc trò chuyện hoặc nhóm nhận thông báo Telegram |
| `ZALO_WEBHOOK_URL` | *(Không có)* | Đường dẫn webhook chuyển tiếp thông báo Zalo |
| `ZALO_OA_ACCESS_TOKEN` | *(Không có)* | Access token của Zalo Official Account v3.0 |
| `ZALO_USER_ID` | *(Không có)* | ID người dùng Zalo đích để nhận tin nhắn riêng |
| `GOOGLE_MEET_CREDENTIALS_FILE` | `~/.google_meet_mcp/credentials.json` | Đường dẫn tệp client credentials Google OAuth2 |
| `GOOGLE_MEET_TOKEN_FILE` | `~/.google_meet_mcp/token.json` | Đường dẫn tệp token người dùng Google OAuth2 |

---

## 14. Cẩm nang Xử lý Sự cố & Thắc mắc

| Sự cố thường gặp | Nguyên nhân gốc rễ | Hướng dẫn khắc phục từng bước |
| :--- | :--- | :--- |
| **Xung đột Cổng 8765** (`Address already in use`) | Có một tiến trình hoặc máy chủ khác đang chiếm dụng cổng 8765. | Tìm mã PID qua lệnh `lsof -i :8765` và tắt nó, hoặc đổi cổng khác: `google-meet-mcp companion --port 8766`. |
| **Extension Báo Lỗi Kết Nối** (`Failed to fetch`) | Máy chủ companion chưa chạy hoặc bị tường lửa chặn. | Chạy lệnh `google-meet-mcp companion` hoặc `docker compose up -d`. Kiểm tra bằng lệnh `curl -s http://127.0.0.1:8765/health`. |
| **Lỗi CSP Google Meet** (`Refused connect-src`) | Chính sách bảo mật của Google Meet chặn kết nối fetch từ nội dung trang. | Sử dụng bản Chrome Extension mới nhất đã điều hướng toàn bộ request qua Service Worker ngầm. |
| **Không Thu được Âm thanh** | Chưa cấp quyền thu âm thanh tab cho trình duyệt. | Khi chọn chia sẻ màn hình/tab trong Meet, nhớ tích chọn vào ô **"Share tab audio"** (Chia sẻ âm thanh tab). |
| **Docker Báo Lỗi Phân quyền** `~/.google_meet_mcp` | Thư mục trên máy host thuộc sở hữu của root thay vì UID 10001. | Chạy lệnh `sudo chown -R 10001:10001 ~/.google_meet_mcp` trên máy host trước khi bật docker. |
| **Lỗi Chat AI Gemini** | Chưa cấu hình hoặc sai khóa API Gemini. | Thiết lập biến môi trường `export GEMINI_API_KEY="khoa-cua-ban"` hoặc nhập trực tiếp trong Cài đặt Dashboard. Nếu không có key, hệ thống tự động dùng thuật toán phân tích cục bộ. |
| **Không Nhận được Tin Telegram** | Sai Bot Token/Chat ID hoặc chưa từng nhắn tin cho Bot. | Kiểm tra token qua `curl -s https://api.telegram.org/bot<TOKEN>/getMe`. Hãy chắc chắn bạn đã bấm `/start` với bot trong Telegram. |

---

## 15. Kiểm thử & Đảm bảo Chất lượng

Hệ thống được bảo vệ bởi **495 bài kiểm thử tự động** chạy qua 4 tầng kiểm định:
- **Tầng 1 (Chức năng cốt lõi)**: Kiểm thử SessionManager, Synthesizer, Chat Assistant, và bộ phát hiện nhắc tên.
- **Tầng 2 (Biên giới hạn & Ngoại lệ)**: Mô phỏng họp nhiều giờ liên tục, dữ liệu đầu vào khiếm khuyết, audio ngắt quãng.
- **Tầng 3 (Tương tác & Endpoints)**: Kiểm tra chuẩn hợp đồng 14+ REST API, phát audio Range RFC 7233 và WebSocket.
- **Tầng 4 (Tải trọng & Ứng suất cao)**: Mô phỏng tải 45,000+ câu thoại, ghi đệm đồng thời và kiểm tra dọn dẹp bộ nhớ đệm an toàn.

```bash
# Chạy bộ test tự động (495 tests)
.venv/bin/pytest tests/ -v

# Chạy kèm báo cáo độ phủ mã nguồn (Coverage)
.venv/bin/pytest tests/ --cov=google_meet_mcp --cov-report=term-missing
```

---

## 16. Cam kết An toàn & Bảo mật Dữ liệu

- 🔒 **Xử lý Cục bộ Tuyệt đối**: Toàn bộ phụ đề, ảnh chụp slide và file ghi âm chỉ lưu trữ trực tiếp trên máy của bạn (`~/.google_meet_mcp`). Không có bất kỳ dữ liệu nào bị tải lên máy chủ của bên thứ ba nếu bạn không chủ động cấu hình khóa API LLM bên ngoài.
- 🛡️ **Container Docker Chuẩn Doanh nghiệp**: Chạy dưới quyền người dùng thông thường (`appuser`, UID 10001), kích hoạt chính sách `no-new-privileges:true` và kiểm tra sức khỏe container định kỳ.
- 🔑 **Bảo vệ Thông tin Nhạy cảm**: Token OAuth và API Key được lưu tại thư mục hạn chế quyền truy cập và tự động được loại trừ khỏi git qua `.gitignore`.

---

## 📜 Giấy phép Nguồn mở (License)

Dự án được phát hành theo giấy phép mã nguồn mở [MIT License](LICENSE).  
Bản quyền © 2026 thuộc về **[DuongNAD](https://github.com/DuongNAD)**.