Base.vn FastMCP Server (Python)

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).

Related MCP server: Basecamp MCP Server

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

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:

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:

# 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:

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:

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

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:

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:

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:

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:

   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:

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

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.

📄 License

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