Base.vn FastMCP Server (Python)

FastMCP Python 3.10+ License: 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).

📂 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)
├── test_python_mcp.py           # Integration test suite
├── requirements.txt             # Python dependencies
├── .env                         # Environment variables (Tokens)
└── README.md

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

1. Cài đặt thư viện Python

pip install -r requirements.txt

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

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

# 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

3. Chạy kiểm thử tự động

python3 test_python_mcp.py

🔌 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):

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:

Mở terminal chạy:

python3 main.py --transport sse --port 3001

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:

{
  "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):

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

🛠 Danh sách MCP Tools (51 Tools)

Nhóm	Công cụ	Mô tả
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.