OKF GDrive MCP Server (Second Brain)

OKF GDrive MCP Server là một Model Context Protocol (MCP) server được thiết kế để đóng vai trò như một "Bộ nhớ tập trung" (Centralized Memory) cho các AI Agents (như Cursor, Claude Code, Cline...). Dự án sử dụng Google Drive cá nhân của bạn (BYOD) làm nơi lưu trữ dữ liệu dưới dạng Open Knowledge Format (OKF) (Markdown + YAML Frontmatter), đảm bảo tính an toàn, bảo mật tuyệt đối và giúp AI hiểu ngữ cảnh dự án một cách đồng nhất.

🌟 Tính năng nổi bật

• Bring Your Own Drive (BYOD): Dữ liệu được lưu thẳng vào Google Drive cá nhân của bạn. Không đi qua bất kỳ server trung gian nào.
• Machine-actionable & Human-readable: Định dạng Markdown kết hợp YAML Frontmatter dễ dàng cho cả bạn đọc trực tiếp và cho AI truy xuất.
• Concurrency Control: Sử dụng ETag API của Google để khóa (lock) chống ghi đè khi nhiều Agent cùng thao tác trên 1 file.
• Graph Structure: Tự động quản lý cây mục lục (index.md) và nhật ký (log.md) ở từng thư mục để duy trì cấu trúc liên kết tri thức.

🚀 Hướng dẫn Cài đặt

Cài đặt qua NPM

Bạn có thể cài đặt toàn cục bằng lệnh:

npm install -g okf-gdrive-mcp

Sau đó, ứng dụng sẽ tự động gọi trình duyệt web lên để bạn uỷ quyền Google Drive với duy nhất 1 cú click chuột, vô cùng nhanh gọn!

🛠 Hướng dẫn Cấu hình cho AI Agents (Cursor, Antigravity, Claude, Cline...)

Có 3 cách để khai báo MCP Server tuỳ theo cách cài đặt của bạn:

⚠️ Lưu ý quan trọng: Nếu dùng node, bạn BẮT BUỘC phải dùng đường dẫn tuyệt đối (Absolute Path) tới file dist/index.js. Không dùng đường dẫn tương đối dist/index.js vì các AI Agent/IDE có thể chạy MCP từ thư mục gốc hệ thống làm phát sinh lỗi ngắt kết nối.

Cách 1: Sử dụng Lệnh Global (Đã cài npm install -g okf-gdrive-mcp) - Khuyên dùng

Áp dụng cho mọi Client:

{
  "mcpServers": {
    "okf-gdrive": {
      "command": "okf-gdrive"
    }
  }
}

Cách 2: Sử dụng npx (Không cần cài đặt trước)

Áp dụng cho mọi Client:

{
  "mcpServers": {
    "okf-gdrive": {
      "command": "npx",
      "args": ["-y", "okf-gdrive-mcp"]
    }
  }
}

Cách 3: Dành cho Developer (Chạy trực tiếp mã nguồn local)

{
  "mcpServers": {
    "okf-gdrive": {
      "command": "node",
      "args": [
        "C:/duong-dan-tuyet-doi-toi-du-an/dist/index.js"
      ]
    }
  }
}

Chi tiết vị trí file cấu hình trên từng công cụ:

• Cursor IDE: Vào Settings > Features > MCP Servers > Add New MCP Server (Name: okf-gdrive, Type: command, Command: okf-gdrive).
• Google Antigravity (AGY): Thêm vào file .agents/mcp_config.json trong thư mục dự án hoặc ~/.gemini/config/mcp_config.json toàn cục.
• Claude Desktop: Thêm vào file %APPDATA%\Claude\claude_desktop_config.json (Windows) hoặc ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).
• Cline (VS Code Extension): Thêm vào file cline_mcp_settings.json.

📦 Hướng dẫn Publish lên NPM (Dành cho Developer/Nhà phát triển)

Nếu bạn là chủ dự án (Nhà phát triển) muốn cấu hình package này để đưa lên mạng:

1. Xác minh Google Cloud (Bắt buộc):
   • Đảm bảo bạn đã mang dự án trên Google Cloud đi xin cấp phép Verification (Vì scope của Drive là quyền cao).
2. Hardcode Client ID:
   • Mở file src/index.ts và thay thế đoạn 'ĐIỀN_CLIENT_ID_CỦA_DEVELOPER_VÀO_ĐÂY' bằng thông tin thật của bạn.
3. Build dự án:

   npm run build

4. Publish:

   npm login
   npm publish --access public

Sau khi hoàn thành, bất kỳ ai cũng có thể dùng lệnh npx <tên-package-của-bạn> để chạy hệ thống này!

📝 Danh sách các MCP Tools được cung cấp

1. okf_read_node: Tải file Markdown, phân tách Metadata (JSON) và Nội dung (Text).
2. okf_update_frontmatter: Sửa Metadata trong YAML Frontmatter an toàn mà không làm hỏng văn bản bài viết.
3. okf_append_content: Viết nối nội dung mới vào phần Body (thường dùng cho Worklog, Audit log).
4. okf_create_node: Tạo mới hoàn toàn một file Markdown OKF (hỗ trợ tự động gắn link vào file index.md của thư mục cha để duy trì Graph Tree).