# PITO Data MCP

> Kết nối trợ lý AI (Claude, ChatGPT, Cursor, VS Code…) với dữ liệu vận hành PITO: tra cứu đơn, khách, đối tác, công nợ
> và hỏi số liệu tổng hợp — theo đúng quyền tài khoản vận hành (fe-operator) của người dùng.

## Thông tin kết nối

- MCP server URL: https://mcp.pito.vn/mcp
- Transport: Streamable HTTP (MCP remote server)
- Xác thực: OAuth 2.1 với đăng ký client động (RFC 7591) và PKCE. Không cần API key, Client ID hay Client Secret.
- Đăng nhập: trang "Đăng nhập PITO Data" mở ra khi kết nối; dùng email và mật khẩu fe-operator.
- Môi trường: Chính thức (production)
- Server: pito-data 0.1.0

## Dành cho AI agent

Nếu bạn là AI agent được nhờ cài đặt kết nối này:

1. Chọn đúng hướng dẫn cho client bạn đang chạy ở mục bên dưới và thực hiện bước cấu hình (lệnh hoặc file JSON).
2. Bước đăng nhập luôn do người dùng tự làm trên trình duyệt: không hỏi, không nhận, không lưu mật khẩu của người dùng.
3. Sau khi kết nối, gọi tool `server_info` để xác nhận tài khoản và role, rồi `get_glossary` trước khi trả lời câu hỏi số liệu.
4. Với client web (Claude, ChatGPT) bạn không tự thêm connector được: hãy hướng dẫn người dùng làm theo các bước tương ứng.

## Hướng dẫn theo từng client

### Claude Code (AI agent tự cài được)

1. Chạy lệnh bên dưới trong terminal.
2. Gõ /mcp, chọn pito-data, đăng nhập bằng tài khoản vận hành.

```
claude mcp add --transport http pito-data https://mcp.pito.vn/mcp
```

### Cursor (AI agent tự cài được)

1. Thêm vào file ~/.cursor/mcp.json (tạo mới nếu chưa có).
2. Mở Settings → MCP, bấm Connect ở pito-data và đăng nhập.

```
{
  "mcpServers": {
    "pito-data": {
      "url": "https://mcp.pito.vn/mcp"
    }
  }
}
```

### VS Code (Copilot Chat) (AI agent tự cài được)

1. Thêm vào file .vscode/mcp.json của workspace (hoặc cấu hình user).
2. Bấm Start trên pito-data và đăng nhập.

```
{
  "servers": {
    "pito-data": {
      "type": "http",
      "url": "https://mcp.pito.vn/mcp"
    }
  }
}
```

### Claude (web, desktop, mobile) (người dùng tự bấm)

1. Mở Settings → Connectors → Add custom connector.
2. Name: PITO Data. Remote MCP server URL: https://mcp.pito.vn/mcp. Không cần điền OAuth Client ID/Secret.
3. Bấm Connect, đăng nhập bằng tài khoản vận hành ở trang "Đăng nhập PITO Data".
4. Gói Team/Enterprise: chủ tổ chức có thể phải thêm connector trong Organization settings trước.

### ChatGPT (người dùng tự bấm)

1. Mở Settings → Apps & Connectors, bật Developer mode nếu cần (tuỳ gói và phiên bản; tên mục có thể khác).
2. Tạo connector mới: URL https://mcp.pito.vn/mcp, Authentication: OAuth.
3. Đăng nhập bằng tài khoản vận hành, rồi bật connector trong cuộc trò chuyện.

### Client chỉ hỗ trợ MCP qua stdio (AI agent tự cài được)

1. Dùng cầu nối mcp-remote (cần Node.js); lần đầu chạy sẽ mở trình duyệt để đăng nhập.

```
{
  "mcpServers": {
    "pito-data": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.pito.vn/mcp"
      ]
    }
  }
}
```

## Câu hỏi mẫu

- **Kiểm tra kết nối:** Gọi server_info cho tôi xem tôi đang đăng nhập bằng tài khoản nào.
- **Vận hành:** Tháng 9 có bao nhiêu đơn tiệc hiệu lực, chia theo loại đơn?
- **Vận hành:** Tra đơn PT… : món, cửa hàng, trạng thái và nhật ký thay đổi.
- **Kinh doanh:** Quý 3 có bao nhiêu doanh nghiệp đặt đơn lần đầu? Liệt kê 10 doanh nghiệp có giá trị đơn cao nhất.
- **Tài chính:** Các đơn quá hạn thanh toán mà chưa thu đủ, sắp theo số còn nợ.
- **Đối tác:** Có bao nhiêu đối tác đang có menu online? Giá trung bình mỗi khách là bao nhiêu?

## Giới hạn hiện tại

- Chỉ đọc: chưa thao tác ghi (tạo/sửa đơn, ghi nhận thanh toán) qua AI.
- Dữ liệu và tool theo đúng role của tài khoản; tài khoản bị khoá hoặc gỡ quyền sẽ mất kết nối trong khoảng 1 phút.
- "Doanh thu" chưa có định nghĩa chính thức; AI sẽ báo giá trị đơn hiệu lực và ghi rõ điều này.
- Tối đa 120 yêu cầu mỗi phút cho mỗi người; câu hỏi số liệu tối đa 10 giây và 1.000 dòng.
- Không dán dữ liệu khách hàng ra ngoài hệ thống AI được công ty cho phép.

## Thu hồi kết nối

Xoá connector PITO Data trong ứng dụng AI. Nếu nghi lộ tài khoản, đổi mật khẩu fe-operator: mọi kết nối cũ sẽ hết hiệu lực khi phiên đăng nhập hết hạn.