# EventPhotoFind — Context & Intelligence MCP Server

> **Cổng kết nối ngữ cảnh trung tâm (Single Source of Context Gateway) chuẩn Model Context Protocol (MCP) và OpenAPI dành cho dự án EventPhotoFind.**
> Cho phép các mô hình AI Cloud (**Google Gemini**, **ChatGPT / GPT-4o**, **Claude Desktop**, **Cursor**) kết nối trực tiếp qua giao thức HTTPS để nắm toàn bộ kiến trúc, sản phẩm, dữ liệu, luật bất biến E1–E13, marketing và trạng thái sống của dự án.

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Ftienlxepf%2Fepf-context-mcp)

👉 **Link Import 1-Click lên Vercel:** [https://vercel.com/new/import?s=https://github.com/tienlxepf/epf-context-mcp](https://vercel.com/new/import?s=https://github.com/tienlxepf/epf-context-mcp)


---

## 1. Mục Đích & Bối Cảnh

EventPhotoFind là nền tảng SaaS phức tạp với hơn 160+ tài liệu kế hoạch, nhật ký quyết định kỹ thuật `CONTEXT_LOG.md` (hơn 1.2MB), cơ sở dữ liệu PostgreSQL + pgvector (`halfvec(512)`), và hệ thống lưu trữ Cloudflare R2 với các quy tắc kỹ thuật cực kỳ nghiêm ngặt:
- **E1–E3**: Ảnh sự kiện lưu tại Cloudflare R2 (egress $0), hiển thị bằng `<img>` thuần, tuyệt đối không dùng `next/image` cho ảnh sự kiện.
- **E4**: Dữ liệu sinh trắc học (selfie của khách) **KHÔNG BAO GIỜ** được lưu trữ vào ổ cứng, database, S3 hay log. Nhận diện trong RAM, so khớp vector, và giải phóng ngay lập tức.
- **E6, E9, E10**: Phân vùng dữ liệu cô lập đa người thuê (`app`, `private`, `cms`). Mọi bảng nghiệp vụ mang `org_id`. RLS mặc định từ chối (`deny-by-default`).
- **Quota & Định giá**: Searchable Photos là dung lượng throughput theo chu kỳ tháng; Photo Storage là tổng byte ảnh gốc raw thực tế. Mọi nút mua phải qua cổng `checkoutReady`.

Khi làm việc với các nền tảng AI Cloud bên ngoài, việc nhồi nhét hàng megabyte tài liệu vào cửa sổ chat gây nghẽn token và khiến AI dễ ảo giác. **EPF Context MCP Server** giải quyết triệt để vấn đề này bằng cách cung cấp các API/Tools chuẩn để AI tự động tra cứu đúng dữ liệu cần thiết theo thời gian thực.

---

## 2. Các Địa Chỉ Kết Nối HTTPS (Live Endpoints)

Sau khi xuất bản lên Vercel, server cung cấp 4 endpoints chuẩn:

| Endpoint | Giao thức | Mục đích sử dụng |
|---|---|---|
| `https://<your-vercel-domain>/api/sse` | **MCP SSE** | Dùng cho **Gemini**, **Claude Desktop**, **Cursor IDE**, **ChatGPT Desktop**. |
| `https://<your-vercel-domain>/api/mcp` | **MCP JSON-RPC** | Dùng cho các client gửi trực tiếp POST JSON-RPC 2.0 (stateless, không lo rớt session). |
| `https://<your-vercel-domain>/api/openapi` | **OpenAPI 3.1** | Dùng cho **ChatGPT Web Custom GPTs** (nhập 1-click vào mục Actions). |
| `https://<your-vercel-domain>/api/health` | **REST Health** | Kiểm tra trạng thái máy chủ. |

---

## 3. Danh Mục 10 MCP Tools Tích Hợp Sẵn

1. **`epf_get_project_overview`**: Trả về tổng quan sứ mệnh, 4 product surfaces (Marketing, Dashboard, Public Page, Ops), domain và toàn bộ tech stack.
2. **`epf_get_hard_constraints`**: Trích xuất 13 quy tắc bất biến sống còn (E1–E13) và các lỗi cấm kỵ.
3. **`epf_get_product_and_pricing`**: Bảng giá 7 gói chuẩn (Pro, Ultra, Professional, Scale, Studio, Agency, Enterprise), giới hạn Demo (100 ảnh / 250MB), và cơ chế Add-ons.
4. **`epf_get_marketing_context`**: 4 nhóm chân dung khách hàng mục tiêu (**ICP 1–4**: Nhiếp ảnh gia, Agency, Doanh nghiệp, Trường học), giọng văn thương hiệu, từ khóa SEO và các điều cấm kỵ khi viết bài.
5. **`epf_get_database_schema`**: Cấu trúc các schema (`app`, `private`, `cms`), danh sách bảng cốt lõi, quan hệ khóa ngoại, RLS policies, và các hàm RPC trọng yếu.
6. **`epf_get_feature_spec`**: Đọc đặc tả chi tiết của từng tính năng (Onboarding `/start`, Photo Library, Page Photos, Modular Design Studio, Selfie Search, Billing, Analytics).
7. **`epf_query_context_log`**: Trích xuất thông minh các quyết định kỹ thuật và mốc bàn giao gần nhất từ `CONTEXT_LOG.md` theo tag (`UIUX`, `SECURITY`, `DEPLOY`, `STORAGE`).
8. **`epf_validate_proposal`**: **Công cụ kiểm toán AI tự động**: Phân tích bất kỳ đề xuất tính năng, đoạn code hay kế hoạch marketing nào, tự động phát hiện vi phạm E1–E13 và đưa ra cảnh báo kèm giải pháp thay thế chuẩn xác.
9. **`epf_get_design_tokens`**: Hệ thống token thẩm mỹ từ `DESIGN.md` (brand blue `#283DFD`, font Inter, chuẩn touch target 44px, Light-mode first).
10. **`epf_get_active_plans`**: Danh sách các kế hoạch đang chạy và trạng thái phát hành trên môi trường Production.

---

## 4. Hướng Dẫn Kết Nối Từng Nền Tảng

### 4.1. Google Gemini (qua Antigravity IDE hoặc Gemini CLI)
Thêm vào file cấu hình MCP (ví dụ `.agents/mcp_config.json`):
```json
{
  "mcpServers": {
    "epf-context": {
      "serverUrl": "https://<your-vercel-domain>/api/sse",
      "headers": {}
    }
  }
}
```

### 4.2. OpenAI ChatGPT
#### Cách A: ChatGPT Web / Mobile (Tạo Custom GPT - Khuyên dùng)
1. Mở ChatGPT, vào **Explore GPTs** > **Create a GPT**.
2. Tại tab **Configure**, kéo xuống chọn **Actions** > **Create new action**.
3. Bấm **Import from URL**, dán địa chỉ:
   ```text
   https://<your-vercel-domain>/api/openapi
   ```
4. Toàn bộ 10 tools sẽ được import tự động. ChatGPT từ nay có thể tra cứu toàn bộ dữ liệu dự án khi bạn trò chuyện!

#### Cách B: ChatGPT Desktop App (macOS / Windows)
Vào **Settings** > **Developer** > **MCP Servers**, thêm mới server với URL:
`https://<your-vercel-domain>/api/sse`.

### 4.3. Claude Desktop
Chỉnh sửa file cấu hình `%APPDATA%\Claude\claude_desktop_config.json` (Windows) hoặc `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac):
```json
{
  "mcpServers": {
    "epf-context": {
      "url": "https://<your-vercel-domain>/api/sse"
    }
  }
}
```

### 4.4. Cursor IDE / Windsurf
Thêm vào file `.cursor/mcp.json` trong dự án:
```json
{
  "mcpServers": {
    "epf-context": {
      "url": "https://<your-vercel-domain>/api/sse"
    }
  }
}
```

---

## 5. Quy Trình Cập Nhật Ngữ Cảnh Khi Dự Án Có Thay Đổi

Khi EventPhotoFind hoàn thành tính năng mới, cập nhật bảng giá, thay đổi schema hoặc bổ sung mốc quan trọng trong `CONTEXT_LOG.md`:

### Bước 1: Chạy lệnh đồng bộ ngữ cảnh
Từ thư mục plugin:
```bash
npm run sync:context
```
Script sẽ tự động đọc `CONTEXT_LOG.md`, `AGENTS.md`, `PRICING_PACKAGING.md` của dự án cha và cập nhật vào các file JSON trong `src/data/`.

### Bước 2: Commit và Push lên GitHub
```bash
git add -A
git commit -m "feat: sync latest epf context and milestones"
git push origin main
```

### Bước 3: Vercel tự động triển khai trong 30 giây
Vercel sẽ tự động build và xuất bản bản cập nhật mới nhất. Toàn bộ các AI Cloud (Gemini, ChatGPT, Claude) đang kết nối qua link MCP sẽ **ngay lập tức nhận được dữ liệu mới nhất mà không cần phải cài đặt hay đổi link kết nối lại**!

---

## 6. Chính Sách Bảo Mật (Zero-Secret Policy)

Tuân thủ nghiêm ngặt **Quy tắc bất biến E12**:
- Plugin này **KHÔNG** chứa bất kỳ API key, Service Role Key, Database password hay dữ liệu sinh trắc học nào.
- Chỉ lưu trữ các đặc tả kiến trúc, lược đồ bảng, chính sách sản phẩm, quy tắc thương hiệu và nhật ký phát triển công khai.
- Hoàn toàn an toàn để xuất bản công khai trên GitHub và Vercel.