·

Confluence MCP với Gemini CLI

Cài đặt Confluence MCP trong Gemini CLI để AI agent có thể đọc và viết trang tài liệu ngay trong trình soạn thảo.

Gemini CLI là coding agent chính thức của Google, chạy model Gemini và hỗ trợ MCP theo chuẩn chung nhưng có vài quy ước cấu hình riêng đáng chú ý. Nếu team bạn đang dùng Gemini CLI làm công cụ chính (thường vì lý do chi phí, hoặc vì đã có sẵn Google Workspace/GCP enterprise agreement), bài này sẽ giúp bạn nối nó với Confluence để tự động hóa việc đọc spec và sinh tài liệu kỹ thuật.

Giống các bài khác trong module, bài này không lặp lại phần tổng quan tool Confluence MCP (confluence_search, confluence_create_page...) đã nói ở bài đầu — tập trung thẳng vào phần đặc thù của Gemini CLI.

Cài Đặt Và Kết Nối Confluence MCP Vào Gemini CLI

Gemini CLI đọc cấu hình MCP từ file .gemini/settings.json ở project (hoặc ~/.gemini/settings.json cho cấu hình user toàn cục). Với Atlassian Remote MCP (OAuth, khuyến nghị cho Confluence Cloud):

{
  "mcpServers": {
    "confluence": {
      "httpUrl": "https://mcp.atlassian.com/v1/sse",
      "trust": false
    }
  }
}

Field trust khi để false (mặc định) buộc Gemini CLI hỏi xác nhận mỗi lần gọi tool — đây là điểm khác với một số client mặc định trust theo session. Nếu set trust: true, mọi tool call tới server này (bao gồm cả confluence_create_page, confluence_delete_page) sẽ auto-approve — không nên làm vậy cho một MCP server có quyền ghi, trừ khi bạn đã sandbox kỹ.

Với server community qua API token (bắt buộc nếu dùng Confluence Data Center on-prem):

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-confluence"],
      "env": {
        "CONFLUENCE_SITE_NAME": "your-company",
        "CONFLUENCE_USER_EMAIL": "you@company.com",
        "CONFLUENCE_API_TOKEN": "$CONFLUENCE_API_TOKEN"
      },
      "trust": false
    }
  }
}

Chú ý: Gemini CLI dùng cú pháp $VAR_NAME (không có dấu ngoặc nhọn) để interpolate biến môi trường trong một số phiên bản, khác với ${VAR_NAME} của Claude Code — kiểm tra changelog phiên bản Gemini CLI bạn đang dùng nếu biến không được resolve đúng, vì cú pháp này đã thay đổi qua vài release.

Kiểm tra kết nối bằng lệnh trong Gemini CLI:

/mcp

Lệnh này liệt kê server đã đăng ký kèm trạng thái kết nối và danh sách tool tương ứng. Nếu confluence không xuất hiện, chạy gemini --debug khi khởi động để xem log parse config chi tiết — lỗi hay gặp nhất là file JSON có trailing comma (Gemini CLI parse JSON chuẩn, không chấp nhận comment hay trailing comma như một số tool khác).

Mẹo: Luôn để trust: false cho server Confluence MCP khi mới setup, và chỉ nâng lên trust: true cho môi trường CI đã kiểm soát chặt (ví dụ chạy trong container tách biệt, chỉ có quyền vào một space test) — không bao giờ set trust: true trên máy cá nhân có quyền vào toàn bộ Confluence công ty.

Đọc Spec Và Sinh Tài Liệu Kỹ Thuật Từ Gemini CLI

Chạy gemini để vào interactive mode, rồi ra prompt đọc spec:

Đọc Confluence page trong space PROD có title "Notification Service — Spec v2",
tóm tắt lại các yêu cầu chính thành danh sách requirement có thể dùng làm
checklist implement.

Gemini CLI sẽ tự gọi confluence_search để tìm page theo title, sau đó confluence_get_page để lấy nội dung. Vì Gemini có context window (cửa sổ ngữ cảnh) rất lớn ở một số model (Gemini 1.5/2.x Pro), đây là lợi thế thực tế khi làm việc với page Confluence dài — bạn có thể yêu cầu nó đọc nhiều page liên quan cùng lúc mà ít lo tràn context hơn so với model context window nhỏ:

Đọc 3 page Confluence sau trong space PROD: "Notification Service — Spec v2",
"Event Bus — Architecture Overview", "Rate Limiting — Company Standard".
Dựa vào cả ba, viết ra danh sách các thành phần cần implement cho
Notification Service, kèm chú ý những điểm cần tuân theo company standard
về rate limiting.

Sau khi đọc spec, yêu cầu sinh tài liệu kỹ thuật ngược lại (từ code sang Confluence):

Đọc toàn bộ source trong src/services/notification/, so sánh với spec
đã đọc ở trên, viết một Confluence page mới "Notification Service —
Implementation Notes" trong space PROD, dưới parent "Notification Service — Spec v2",
liệt kê rõ những điểm implementation khác với spec ban đầu và lý do
(nếu suy luận được từ comment trong code).

Với hành động ghi này, Gemini CLI hiện prompt xác nhận dạng Allow once / Always allow / No — chọn "Allow once" cho tới khi bạn tin tưởng agent, tránh chọn "Always allow" quá sớm.

Mẹo: Tận dụng context window lớn của Gemini để đọc nhiều page liên quan trong một lần thay vì tách nhiều prompt nhỏ — điều này giúp agent nắm được mối liên hệ giữa các tài liệu (ví dụ spec tham chiếu company standard) mà một prompt đơn lẻ dễ bỏ sót.

Ví Dụ Thực Tế: Tự Động Sinh Confluence Page Từ Code Annotation Trong Gemini CLI

Một pattern hiệu quả với Gemini CLI: dùng annotation/docstring có sẵn trong code (JSDoc, docstring Python, comment chuẩn hóa) làm nguồn dữ liệu chính để sinh tài liệu, giảm khả năng agent tự suy diễn sai.

Giả sử codebase có annotation chuẩn hóa kiểu:

/**
 * @confluence-doc
 * @summary Validates and normalizes incoming webhook payloads from Stripe.
 * @param payload Raw webhook body as received from Stripe.
 * @throws InvalidSignatureError when the webhook signature header is missing or invalid.
 * @sideEffect Writes an audit log entry to the `webhook_audit_log` table.
 */
export function processStripeWebhook(payload: unknown): WebhookResult {
  // ...
}

Prompt:

Tìm tất cả function có annotation @confluence-doc trong src/, với mỗi
function trích xuất @summary, @param, @throws, @sideEffect. Tạo một
Confluence page duy nhất "Webhook Handlers — Auto-Generated Reference"
trong space ENG dưới parent "Auto-Generated Docs", mỗi function là một
mục H3 riêng theo đúng cấu trúc field trên. Ghi rõ ở đầu page dòng
"Generated automatically — do not edit manually. Source: annotations
in src/. Last generated: <ngày hôm nay>".

Cách làm này có ưu điểm lớn: vì nguồn dữ liệu là annotation có cấu trúc rõ ràng (không phải toàn bộ logic function), agent ít có cơ hội "bịa" hành vi không có trong code — nó chỉ trích xuất và định dạng lại. Đây cũng là nền tảng để tự động hóa hoàn toàn qua CI (bài cuối module sẽ đi sâu vào việc setup automation này).

Mẹo: Luôn thêm dòng cảnh báo "Generated automatically — do not edit manually" cùng timestamp vào đầu mọi page sinh tự động — nếu không, sớm hay muộn sẽ có người sửa tay trực tiếp trên Confluence, và lần agent chạy lại sẽ ghi đè mất phần sửa đó mà không ai biết tại sao.

So Sánh Kết Quả Confluence MCP Giữa Gemini CLI Và Claude Code

Sau khi chạy cùng một prompt sinh tài liệu trên cả hai công cụ (cùng codebase, cùng cấu trúc heading yêu cầu), có vài khác biệt đáng lưu ý bạn nên biết trước khi chọn công cụ cho từng loại việc:

Độ chi tiết của phần giải thích kỹ thuật. Claude Code (dùng model Claude) thường sinh ra phần giải thích trade-off và edge case chi tiết hơn khi được yêu cầu "giải thích lý do thiết kế" — phù hợp cho ADR hoặc tài liệu cần lý luận sâu. Gemini CLI thường sinh nội dung súc tích, bám sát cấu trúc yêu cầu hơn, phù hợp cho tài liệu tham chiếu kiểu API reference cần tra cứu nhanh.

Xử lý codebase lớn. Với context window lớn, Gemini CLI xử lý tốt hơn khi cần đọc nhiều file/page cùng lúc trong một request (ví dụ toàn bộ một service lớn 50+ file). Claude Code thường cần bạn chia nhỏ theo module hơn, nhưng đổi lại giữ được độ chính xác cao khi phân tích sâu một phần code cụ thể.

Format markdown khi convert sang Confluence storage format. Cả hai đều convert đúng heading, list, code block. Khác biệt nhỏ nằm ở bảng (table) phức tạp có nhiều dòng — nên luôn kiểm tra lại page thật trên Confluence sau khi tạo, bất kể dùng công cụ nào, vì bước convert markdown → XHTML storage format của Confluence đôi khi làm vỡ layout bảng lồng nhau.

Tốc độ phản hồi cho việc gọi tool liên tiếp. Với workflow cần gọi nhiều tool call liên tiếp (search → get_page → create_page trong một prompt), cả hai đều xử lý tốt, nhưng nên test thực tế trên chính hạ tầng công ty bạn (độ trễ mạng tới Confluence instance, rate limit của Atlassian) trước khi kết luận công cụ nào nhanh hơn — độ trễ phần lớn nằm ở phía Confluence API, không phải ở agent.

Mẹo: Đừng chọn công cụ dựa trên benchmark chung trên mạng — chạy thử chính prompt bạn sẽ dùng thật (sinh ADR, sinh API doc) trên cả hai công cụ với chính codebase của team, rồi để 2-3 senior engineer review kết quả song song trước khi quyết định công cụ chính thức cho workflow tài liệu.

Mẹo Và Lưu Ý Thực Chiến

Vài điều rút ra khi triển khai Confluence MCP với Gemini CLI cho thực tế:

  • Tận dụng context window lớn cho việc "đọc toàn cảnh" trước khi viết — ví dụ đọc toàn bộ space liên quan rồi mới yêu cầu sinh tài liệu, thay vì đọc từng page rời rạc.
  • Luôn set trust: false mặc định, chỉ bật trust: true cho môi trường CI đã kiểm soát scope chặt.
  • Kiểm tra kỹ cú pháp interpolate biến môi trường ($VAR vs ${VAR}) mỗi khi upgrade phiên bản Gemini CLI, vì đây là điểm dễ gây lỗi âm thầm (config trông đúng nhưng token không được resolve, dẫn tới lỗi 401 khó debug).

Mẹo: Nếu team dùng đa dạng LLM (Gemini CLI cho một số việc, Claude Code cho việc khác), giữ chung một bộ prompt template cho các tác vụ Confluence phổ biến (sinh ADR, sinh API doc, sync spec) trong một file dùng chung — chỉ khác nhau ở công cụ chạy, giúp output đồng nhất về cấu trúc dù chạy trên công cụ nào.

Tiếp Confluence MCP với Cursor