# MCP Bỏ Túi

Đưa file và đoạn chat WhatsApp từ điện thoại vào Claude, qua một trạm MCP chạy trong tài khoản Cloudflare miễn phí **của chính bạn**.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cathophile/mcp-bo-tui)

- **Chia sẻ là xong:** trong WhatsApp, chọn *Export chat* hoặc *Chia sẻ* một file, rồi chọn **MCP Bỏ Túi** (Android).
- **Claude đọc được ngay:** tìm tin nhắn (không cần gõ dấu), đọc lại đoạn hội thoại, mở PDF, Word, ảnh.
- **Dữ liệu là của bạn:** nằm trong Cloudflare của bạn, chỉ đọc qua 6 công cụ, có nhật ký truy cập, tự xóa sau 30 ngày.

> Bản dùng thử. Nhận file từ menu Chia sẻ chỉ có trên **Android (Chrome)**. Trên iPhone, dùng nút “Thêm file” trong app.

---

## Cài đặt trong khoảng 10 phút, chỉ cần điện thoại

### 1. Deploy trạm lên Cloudflare

1. Bấm nút **Deploy to Cloudflare** ở trên, rồi đăng nhập Cloudflare. Chưa có tài khoản thì tạo mới, miễn phí và không cần thẻ.
2. Kết nối GitHub khi được hỏi. Cloudflare sẽ tạo một bản sao của repo này trong tài khoản GitHub của bạn.
3. Ở mục **APP_PASSWORD**, nhập một mật khẩu dài (ít nhất 8 ký tự). Đây là **mật khẩu chủ**: dùng để đăng nhập app và cho phép Claude kết nối.
4. Bấm **Deploy**. Cloudflare tự tạo database D1 và vùng KV, không cần làm gì thêm.
5. Khi xong, bạn có địa chỉ dạng `https://mcp-bo-tui.<tên-của-bạn>.workers.dev`.

<details>
<summary>Cách khác: đã có repo này trong GitHub của bạn</summary>

1. dash.cloudflare.com → **Workers & Pages** → **Create** → **Import a repository** → chọn repo `mcp-bo-tui` → **Deploy**.
2. Vào Worker vừa tạo → **Settings** → **Variables and Secrets** → **Add**: loại *Secret*, tên `APP_PASSWORD`, giá trị là mật khẩu chủ → **Deploy**.

</details>

### 2. Cài app lên điện thoại

1. Mở địa chỉ `https://mcp-bo-tui.<tên-của-bạn>.workers.dev` bằng **Chrome trên Android**, rồi đăng nhập bằng mật khẩu chủ.
2. Bấm **⋮** → **Cài đặt ứng dụng** (*Install app*) hoặc **Thêm vào màn hình chính** (*Add to Home screen*).
3. Sau khi cài, **MCP Bỏ Túi** sẽ xuất hiện trong menu **Chia sẻ** của điện thoại.

### 3. Kết nối với Claude (làm một lần)

1. Mở **claude.ai** trong trình duyệt → **Customize** → **Connectors** → **+** → **Add custom connector**.
2. Đặt tên `MCP Bỏ Túi`. URL là địa chỉ ở tab **Kết nối** của app, dạng `https://mcp-bo-tui.<tên-của-bạn>.workers.dev/mcp`. Bấm **Add**, rồi **Connect**.
3. Trang xin quyền của MCP Bỏ Túi hiện ra: nhập mật khẩu chủ và bấm **Cho phép**.
4. Connector tự có trong app Claude trên điện thoại. Khi trò chuyện, bấm **+** → **Connectors** → bật **MCP Bỏ Túi**.

### 4. Dùng thử

- WhatsApp → mở một đoạn chat → **⋮** → **Thêm** (*More*) → **Xuất đoạn chat** (*Export chat*) → chọn kèm tệp phương tiện hoặc không → chọn **MCP Bỏ Túi** → **Nhập vào kho**.
- Hỏi Claude, ví dụ:
  - “Trong kho MCP Bỏ Túi có gì?”
  - “Trong nhóm Gia đình, tuần này ai nhắc tới tiền điện?”
  - “Tóm tắt hợp đồng PDF chị Lan gửi.”
  - “Soạn câu trả lời cho Lan, nói anh đọc hợp đồng rồi.”

---

## Claude dùng được những công cụ nào

| Công cụ | Claude dùng để | Quyền |
| --- | --- | --- |
| `list_sources` | Xem tổng quan: số đoạn chat, tin nhắn, file, mục mới nhất | Đọc |
| `list_items` | Liệt kê đoạn chat và file, tìm theo tên hoặc nội dung tài liệu | Đọc |
| `search_messages` | Tìm tin nhắn theo từ khóa (không cần dấu), người gửi, chat, khoảng ngày | Đọc |
| `get_chat_messages` | Đọc một đoạn chat theo thứ tự, hoặc đọc quanh một tin tìm được | Đọc |
| `get_file` | Mở file: chữ của PDF, Word, văn bản (chia phần), hoặc ảnh đã thu nhỏ | Đọc |
| `draft_whatsapp_reply` | Soạn sẵn tin nhắn và trả về link `wa.me`; bạn tự bấm Gửi | Chỉ soạn |

Claude **không thể** gửi tin nhắn, xóa hay sửa gì trong kho.

## Cách hoạt động

```
WhatsApp ──Chia sẻ──▶ App MCP Bỏ Túi (trên điện thoại)
                        │  đọc chữ trong PDF/Word, thu nhỏ ảnh, tách tin nhắn
                        ▼
              Trạm trên Cloudflare Workers (của bạn)
              ├─ D1: tin nhắn, chữ trong file, ảnh thu nhỏ, nhật ký
              ├─ /mcp: 6 công cụ MCP (Streamable HTTP)
              └─ OAuth: Claude đăng ký tự động (DCR), bạn duyệt bằng mật khẩu chủ
                        ▲
Claude (app, web) ──gọi công cụ──┘
```

Phần xử lý nặng (giải nén, đọc PDF, nén ảnh) chạy ngay trên điện thoại, nên trạm nằm gọn trong giới hạn CPU của gói Workers miễn phí.

## Bảo mật và quyền riêng tư

- Dữ liệu nằm trong tài khoản Cloudflare của bạn, không đi qua máy chủ nào khác.
- Đăng nhập app và cho phép Claude đều cần mật khẩu chủ. Sau 10 lần nhập sai, trạm khóa thêm 15 phút.
- Token OAuth chỉ lưu dạng băm trong KV. Một connector đã kết nối sẽ tự hết hạn nếu không dùng trong 60 ngày.
- Mỗi lần Claude gọi công cụ đều được ghi vào tab **Nhật ký**.
- Dữ liệu tự xóa sau 30 ngày (đổi được trong tab **Cài đặt**: 7, 30, 90, 365 ngày hoặc giữ mãi). Có nút xóa toàn bộ.
- Nội dung trong tin nhắn và file là dữ liệu do người khác viết. Trạm nhắc Claude không làm theo chỉ dẫn nằm trong đó.
- Đoạn chat có tin nhắn của người khác. Chỉ nhập những gì bạn được phép chia sẻ.

## Giới hạn của bản dùng thử

- **iPhone:** Safari không cho web app nhận file từ menu Chia sẻ. Hãy lưu file vào máy rồi dùng nút **Thêm file**.
- **Tin nhắn mới không tự động vào kho.** Muốn cập nhật, hãy xuất lại đoạn chat. Việc đọc thông báo Android cần app native, nằm trong kế hoạch sau.
- **Tin nhắn thoại, video:** chỉ lưu tên file, Claude không nghe hay xem được.
- **PDF dạng ảnh scan:** chỉ lưu ảnh trang đầu để Claude nhìn.
- **Gói miễn phí của Cloudflare:** D1 cho ghi 100.000 dòng mỗi ngày (một đoạn chat chừng 30.000 tin nhắn là gần chạm mức này), 5 GB dung lượng và tối đa 500 MB cho mỗi database. Xem [Cloudflare D1 pricing](https://developers.cloudflare.com/d1/platform/pricing/).
- WhatsApp chỉ đính kèm những file gửi gần đây nhất khi xuất đoạn chat dài.

## Phát triển trên máy

```bash
npm install
cp .dev.vars.example .dev.vars      # rồi đổi APP_PASSWORD
npm run dev                          # http://localhost:8787

npm run check                        # kiểm tra kiểu TypeScript
npm run test:parser                  # bộ tách đoạn chat WhatsApp
npm run test:mcp -- http://localhost:8787 <mật-khẩu>   # OAuth + 6 công cụ MCP
npm run test:ui  -- http://localhost:8787 <mật-khẩu>   # chạy thử app trên khung điện thoại (cần playwright)
```

Thử nhanh công cụ MCP bằng [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector): `npx @modelcontextprotocol/inspector`, chọn *Streamable HTTP*, URL `http://localhost:8787/mcp`.

### Cấu trúc

```
src/index.ts       OAuthProvider bọc toàn bộ Worker, định tuyến, cron dọn dẹp
src/authorize.ts   trang xin quyền (mật khẩu chủ + consent)
src/mcp.ts         6 công cụ MCP, chạy stateless, trả JSON
src/api.ts         API cho web app (đăng nhập, nhập chat, file, nhật ký, cài đặt)
src/db.ts          lược đồ D1 tự tạo lần đầu, tìm kiếm FTS5 không dấu
public/            web app (PWA): giao diện, service worker nhận file từ Share, manifest
public/js/whatsapp.js  bộ tách file Export chat (Android, iPhone, nhiều ngôn ngữ)
public/js/process.js   đọc PDF (PDF.js), Word, giải nén zip, thu nhỏ ảnh
test/              kiểm thử parser, MCP end-to-end, giao diện
```

## Giấy phép

MIT. Thư viện đi kèm trong `public/vendor/`: PDF.js (Apache 2.0) và fflate (MIT), xem `public/vendor/LICENSES.txt`.