# Base.vn FastMCP Server (Python)

[![FastMCP](https://img.shields.io/badge/MCP-FastMCP%20Python-blue.svg)](https://github.com/jlowin/fastmcp)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-green.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Base.vn FastMCP Server** cung cấp đầy đủ các công cụ MCP chuẩn hóa để tích hợp các **AI Agent (Hermes Agent, Claude Desktop, Cursor, Antigravity, AutoGen, CrewAI, LangChain)** vào hệ sinh thái **Base.vn (Base Account & Base Wework)**.

---

## ✨ Tính năng nổi bật

- ⚡ **Xây dựng trên nền tảng FastMCP (Python)**: Tốc độ cao, tối ưu chuẩn giao thức MCP, hỗ trợ cả **Stdio** và **SSE / HTTP Streaming**.
- 👥 **Base Account API (v1)**:
  - Tra cứu danh bạ nhân sự, tìm kiếm dev theo Username / Email.
  - Quản lý phòng ban, nhóm làm việc (Units / Groups).
  - Tự động Onboarding / Offboarding tài khoản nhân viên.
- 📋 **Base Wework API (v3)**:
  - Quản lý Dự án (Projects), Team làm việc, phân quyền thành viên.
  - Tạo, giao việc, cập nhật task, gắn tag, set deadline, mức độ khẩn cấp (urgent), custom fields.
  - Đánh dấu hoàn thành task (`mark done`).
  - Quản lý danh sách công việc (Tasklists), thảo luận (Topics).
  - Báo cáo công việc cá nhân (`user_tasks`, `user_activities`, `user_overview`).
- 🤖 **Dynamic Resources & Prompts**:
  - `base://account/users`: Danh bạ 65+ nhân viên công ty theo thời gian thực.
  - `base://wework/projects`: Danh sách dự án đang chạy trên Wework.
  - `base://wework/departments`: Danh sách phòng ban.
  - `base://wework/members`: Danh sách thành viên / dev để phân công công việc.
  - Prompt tạo Daily Standup tự động cho dev team (`daily_standup_summary`).
  - Prompt phân rã Requirement thành Task trên Base Wework (`create_sprint_tasks`).

## Mô hình phát hành

Repository này được build thành image riêng và được backend BIDU tham chiếu qua `BASE_MCP_IMAGE`; không copy source hoặc `.env` vào repository backend. Runtime production của BIDU là một dịch vụ private, chỉ đăng ký hai tool đọc chuẩn hóa `base_sync_list_employees` và `base_sync_list_project_tasks`. Các tool agent cũ, bao gồm tool ghi Base, chỉ được đăng ký trong môi trường `development`/stdio và không nằm trên bearer production.

---

## 📂 Cấu trúc mã nguồn

```
BaseMCP/
├── base_mcp/
│   ├── clients/
│   │   ├── base_client.py       # Async HTTP client (httpx)
│   │   ├── account_client.py    # Base Account API Client
│   │   └── wework_client.py     # Base Wework API Client
│   ├── tools/
│   │   ├── account_tools.py     # Account MCP Tools
│   │   └── wework_tools.py      # Wework MCP Tools
│   ├── resources/
│   │   └── resources.py         # MCP Dynamic Resources
│   ├── prompts/
│   │   └── prompts.py           # MCP Prompts
│   ├── utils/
│   │   ├── date_helpers.py      # Format ngày dd/mm/YYYY, giờ HH:mm
│   │   ├── username_helpers.py  # Xử lý prefix @username
│   │   ├── custom_fields.py     # Custom fields mapper (custom_{key})
│   │   └── error_handler.py     # Xử lý phản hồi Base API
│   ├── config.py                # Environment configuration loader
│   ├── server.py                # FastMCP Server definition
│   └── __init__.py
├── main.py                      # Server entrypoint (Stdio / SSE)
├── tests/                       # Isolated pytest suite; không gọi Base thật
├── test_python_mcp.py           # Legacy live/manual script; có ghi dữ liệu Base
├── requirements.txt             # Python dependencies
├── .env.example                 # Placeholder an toàn; `.env*` thật bị ignore
└── README.md
```

---

## 🚀 Cài đặt & Cấu hình

### 1. Cài đặt môi trường local

```bash
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
cp .env.example .env
```

Chỉ cho stdio local, chỉnh file `.env` riêng thành `BASE_MCP_ENVIRONMENT=development`. Không dùng chế độ development cho HTTP/SSE hoặc bất kỳ endpoint có thể truy cập qua mạng.

Chạy stdio server:

```bash
python main.py
```

### 2. Cấu hình file `.env`

Tạo hoặc chỉnh sửa file `.env` tại thư mục gốc:

```env
# Base Account API Access Token (v2)
BASE_ACCOUNT_ACCESS_TOKEN_V2=your_base_account_access_token_v2_here

# Base Wework API Access Token (v3)
BASE_WEWORK_ACCESS_TOKEN=your_base_wework_access_token_here

# Domain Base.vn (Mặc định: base.vn)
BASE_DOMAIN=base.vn

# Username mặc định của bot/admin khi tạo task/project
BASE_WEWORK_DEFAULT_CREATOR=@admin

# Timeout (ms)
BASE_API_TIMEOUT_MS=30000

# Enable debug logging
BASE_MCP_DEBUG=false

# Template giữ production để fail closed. Chỉ đổi sang development cho stdio local.
BASE_MCP_ENVIRONMENT=production
BASE_MCP_SERVICE_TOKEN=
```

### 2a. Private Streamable HTTP deployment

The Streamable HTTP server is for the private BIDU worker network only. Do not
publish the MCP endpoint to the public internet and do not send Base API tokens
to browser clients. Production requires a distinct bearer token generated by
the deployment secret manager or `openssl rand -hex 32`:

```env
BASE_MCP_ENVIRONMENT=production
BASE_MCP_SERVICE_TOKEN=
```

`BASE_MCP_SERVICE_TOKEN` is supplied by the deployment environment and is never
copied into the Docker image. Requests to `/mcp` must use
`Authorization: Bearer <BASE_MCP_SERVICE_TOKEN>` and receive the `sync:read`
scope. Never paste its value into source, command history, image layers,
connector JSON or logs. Production exposes only the two normalized sync-read
tools. The Docker health check remains unauthenticated at `/health`; it returns
only `{"status":"healthy","service":"base-vn-mcp"}` and never exposes Base
credentials.

### 2b. BIDU sync connector binding

Configure the BIDU backend connector with this exact binding:

```json
{
  "employee_tool": {
    "tool": "base_sync_list_employees",
    "cursor_argument": "cursor",
    "items_path": "items",
    "next_cursor_path": "next_cursor"
  },
  "task_tool": {
    "tool": "base_sync_list_project_tasks",
    "cursor_argument": "cursor",
    "items_path": "items",
    "next_cursor_path": "next_cursor"
  }
}
```

The backend supplies `project_id` and `limit=100`. Worker gọi
`http://base-mcp:3001/mcp` với `Authorization: Bearer` từ `BASE_MCP_TOKEN`, có
cùng giá trị bí mật với `BASE_MCP_SERVICE_TOKEN` của service này. Hai Base
provider token chỉ thuộc container Base MCP; chúng không được chuyển cho
backend API/worker/frontend. Pagination dùng `items` và `next_cursor`; lỗi
transport/schema được backend ghi thành mã lỗi đã làm sạch. Integration là
manual-only. Automatic sync và writeback vẫn bị tắt.

### 3. Chạy kiểm thử an toàn

```bash
python -m pytest -q tests
```

Suite này dùng fixture/transport giả và không gọi Base thật. Không dùng `test_python_mcp.py` như lệnh CI hoặc smoke test: script legacy đó đọc dữ liệu thật, sau đó tạo, sửa và hoàn thành một task Wework. Chỉ chạy nó trong tenant thử nghiệm tách biệt khi đã có phê duyệt rõ ràng.

### 4. Docker image và kiểm tra local

Build image theo Git SHA để backend có thể pin đúng phiên bản:

```bash
BASE_MCP_SHA=$(git rev-parse --short=12 HEAD)
docker build -t "base-mcp:$BASE_MCP_SHA" .
```

Tạo file env ngoài source control với quyền truy cập hạn chế, đặt hai Base token thật, `BASE_MCP_ENVIRONMENT=production` và một `BASE_MCP_SERVICE_TOKEN` ngẫu nhiên. Sau đó chạy image chỉ trên loopback để smoke test:

```bash
docker run --rm -d --name base-mcp-release \
  -p 127.0.0.1:3001:3001 \
  --env-file /absolute/private/path/base-mcp.env \
  "base-mcp:$BASE_MCP_SHA"
curl -fsS http://127.0.0.1:3001/health
```

Một request không bearer tới `/mcp` phải bị từ chối 401/403. Không gọi tool Base trong smoke test release. Production không publish port 3001 ra host/public internet.

### 5. Coolify / VPS private deployment

Khuyến nghị dùng service `base-mcp` trong Compose của backend BIDU để đảm bảo đúng private network và secret allowlist. Nếu build bằng Coolify:

1. Chọn repository này, build context ở root và Dockerfile `Dockerfile`; tag image bằng Git SHA hoặc digest bất biến.
2. Không gắn public domain/Traefik route. Chỉ kết nối service vào private network dùng chung với BIDU worker; API, frontend và internet không truy cập trực tiếp.
3. Cấu hình port nội bộ `3001`, health path `/health`, và các secret trong secret UI: hai Base access token cùng `BASE_MCP_SERVICE_TOKEN`. Đặt `BASE_MCP_ENVIRONMENT=production`.
4. Không dùng `.env` hoặc secret làm build argument. Sau deploy, kiểm tra health và chạy `python -m scripts.check_mcp base-bidu` từ BIDU worker để xác nhận đúng hai tool đọc trước khi migration/import.
5. Ghi lại Base MCP Git SHA, image digest và backend SHA; giữ image trước đó để rollback.

---

## 🔌 Hướng dẫn tích hợp AI Agent

### 1. Hermes Agent Dashboard (Khuyên dùng)

Trong modal **ADD MCP SERVER** trên Hermes Dashboard:

| Trường | Giá trị cần điền |
| :--- | :--- |
| **NAME** | `base-vn` |
| **TRANSPORT** | `stdio` |
| **COMMAND** | `/opt/homebrew/bin/python3.11` *(hoặc `python3`)* |
| **ARGS** | `/path/to/BaseMCP/main.py` |
| **ENVIRONMENT** | Điền các biến môi trường (mỗi dòng 1 biến): |

```env
BASE_ACCOUNT_ACCESS_TOKEN_V2=your_base_account_access_token_v2_here
BASE_WEWORK_ACCESS_TOKEN=your_base_wework_access_token_here
BASE_DOMAIN=base.vn
BASE_WEWORK_DEFAULT_CREATOR=@admin
```

#### Hoặc kết nối qua SSE Server:
1. Mở terminal chạy:
   ```bash
   python3 main.py --transport sse --port 3001
   ```
2. Trong Hermes Dashboard:
   - **TRANSPORT**: `sse`
   - **URL**: `http://localhost:3001/sse`

---

### 2. Claude Desktop

Thêm vào `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "base-vn": {
      "command": "/opt/homebrew/bin/python3.11",
      "args": ["/path/to/BaseMCP/main.py"],
      "env": {
        "BASE_ACCOUNT_ACCESS_TOKEN_V2": "your_base_account_access_token_v2_here",
        "BASE_WEWORK_ACCESS_TOKEN": "your_base_wework_access_token_here",
        "BASE_DOMAIN": "base.vn",
        "BASE_WEWORK_DEFAULT_CREATOR": "@admin"
      }
    }
  }
}
```

---

### 3. Cursor & Antigravity IDE

Thêm vào file cấu hình MCP (`mcp_config.json`):

```json
{
  "mcpServers": {
    "base-vn": {
      "command": "/opt/homebrew/bin/python3.11",
      "args": ["/path/to/BaseMCP/main.py"]
    }
  }
}
```

---

## 🛠 Danh sách MCP Tools

Development/stdio đăng ký 53 tools. Production BIDU chỉ đăng ký hai sync-read tools dưới đây; các tool còn lại không được publish trên HTTP production.

| Nhóm | Công cụ | Mô tả |
| :--- | :--- | :--- |
| **BIDU Sync Read** | `base_sync_list_employees` | Đọc nhân sự theo contract phân trang chuẩn hóa |
| | `base_sync_list_project_tasks` | Đọc task của một project theo contract phân trang chuẩn hóa |
| **Account** | `base_account_get_all_users` | Lấy danh sách toàn bộ nhân viên công ty |
| | `base_account_search_user` | Tìm kiếm nhân viên theo Email hoặc Username |
| | `base_account_create_user` | Tạo mới tài khoản nhân viên |
| | `base_account_update_user` | Cập nhật hồ sơ nhân viên |
| | `base_account_disable_user` | Vô hiệu hóa tài khoản nhân viên |
| | `base_account_enable_user` | Kích hoạt lại tài khoản |
| | `base_account_get_direct_reports` | Lấy danh sách nhân viên cấp dưới của quản lý |
| | `base_account_get_units` | Lấy danh sách phòng ban, đơn vị tổ chức |
| | `base_account_get_group_detail` | Xem chi tiết nhóm/phòng ban theo path |
| | `base_account_create_group` | Tạo nhóm/phòng ban mới |
| | `base_account_edit_group` | Sửa thông tin nhóm/phòng ban |
| | `base_account_set_group_managers` | Thiết lập danh sách quản lý nhóm |
| | `base_account_set_subscription_users`| Gán quyền ứng dụng cho nhân viên |
| | `base_account_get_system_logs` | Lấy nhật ký hệ thống |
| | `base_account_get_user_logins` | Xem lịch sử đăng nhập nhân viên |
| **Wework Projects** | `base_wework_list_projects` | Lấy danh sách dự án và team |
| | `base_wework_get_project_summary` | Xem tóm tắt dự án |
| | `base_wework_get_project_detail` | Xem chi tiết dự án và task |
| | `base_wework_get_project_members` | Lấy danh sách thành viên/quản lý trong 1 dự án |
| | `base_wework_list_all_members` | Lấy danh sách tất cả dev trong workspace |
| | `base_wework_create_project` | Tạo dự án / team mới |
| | `base_wework_edit_project` | Chỉnh sửa thông tin dự án |
| | `base_wework_add_project_manager` | Thêm quản lý dự án |
| | `base_wework_set_project_manager` | Thiết lập lại quản lý dự án |
| | `base_wework_exchange_project_manager` | Chuyển đổi vai trò quản lý |
| | `base_wework_add_project_member` | Thêm thành viên vào dự án |
| | `base_wework_set_project_member` | Thiết lập lại thành viên dự án |
| | `base_wework_exchange_project_member` | Chuyển đổi thành viên sang dự án khác |
| | `base_wework_remove_project_user` | Xóa thành viên khỏi dự án |
| **Wework Tasks** | `base_wework_create_task` | Tạo task mới, giao việc, deadline, urgent |
| | `base_wework_edit_task` | Chỉnh sửa task |
| | `base_wework_get_task` | Xem chi tiết task |
| | `base_wework_mark_task_done` | Đánh dấu hoàn thành task |
| | `base_wework_get_task_comments` | Xem danh sách bình luận task |
| | `base_wework_get_task_logs` | Xem lịch sử cập nhật task |
| | `base_wework_get_custom_table` | Xem custom table của task |
| | `base_wework_list_tasks_by_project` | Lọc task trong dự án |
| **Wework Depts** | `base_wework_list_departments` | Danh sách phòng ban Wework |
| | `base_wework_get_department` | Chi tiết phòng ban |
| | `base_wework_create_department` | Tạo phòng ban mới |
| | `base_wework_edit_department` | Sửa phòng ban |
| | `base_wework_remove_department` | Xóa phòng ban |
| | `base_wework_add_department_manager` | Thêm quản lý phòng ban |
| | `base_wework_remove_department_manager` | Xóa quản lý phòng ban |
| **Wework Tasklists & Topics** | `base_wework_get_tasklist` | Xem chi tiết tasklist |
| | `base_wework_create_tasklist` | Tạo tasklist mới |
| | `base_wework_list_topics` | Danh sách bài thảo luận |
| | `base_wework_get_topic` | Chi tiết bài thảo luận |
| **User & Overview** | `base_wework_list_user_tasks` | Lấy danh sách task của 1 dev |
| | `base_wework_list_user_activities` | Xem hoạt động gần đây của dev |
| | `base_wework_get_user_overview` | Báo cáo tổng hợp toàn diện về dev |

---

## 📄 License

Mã nguồn được phát hành theo giấy phép **MIT License**.