·

Confluence MCP với OpenCode

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

OpenCode là một CLI coding agent mã nguồn mở, không gắn với một nhà cung cấp LLM duy nhất — bạn có thể cắm Claude, GPT, hay model local qua Ollama, và cấu hình MCP server theo chuẩn chung. Vì OpenCode còn khá trẻ so với Claude Code hay Cursor, hệ sinh thái tool xung quanh nó (bao gồm cách xử lý MCP server) có một số khác biệt bạn cần biết trước khi đưa Confluence MCP vào workflow thật.

Bài này giả định bạn đã đọc bài đầu module về Confluence MCP tổng quan (tool cốt lõi, xác thực API token vs OAuth). Ở đây mình tập trung vào phần dành riêng cho OpenCode: cấu hình file, cách agent gọi tool trong CLI, một ví dụ sinh ADR thực tế, và những hạn chế bạn nên lường trước.

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

OpenCode đọc cấu hình MCP từ file opencode.json ở root project (hoặc ~/.config/opencode/opencode.json cho cấu hình global). Cấu trúc key mcp hơi khác Claude Code — dùng field type là "local" (chạy qua stdio) hoặc "remote" (chạy qua HTTP/SSE):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "confluence": {
      "type": "remote",
      "url": "https://mcp.atlassian.com/v1/sse",
      "enabled": true
    }
  }
}

Nếu bạn dùng server community qua API token (bắt buộc với Confluence Data Center on-prem, vì Atlassian Remote MCP chỉ hỗ trợ Confluence Cloud):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "confluence": {
      "type": "local",
      "command": ["npx", "-y", "@aashari/mcp-server-atlassian-confluence"],
      "environment": {
        "CONFLUENCE_SITE_NAME": "your-company",
        "CONFLUENCE_USER_EMAIL": "you@company.com",
        "CONFLUENCE_API_TOKEN": "{env:CONFLUENCE_API_TOKEN}"
      },
      "enabled": true
    }
  }
}

Chú ý cú pháp interpolate biến môi trường của OpenCode dùng {env:VAR_NAME}, khác với ${VAR_NAME} mà Claude Code hay Cursor dùng — nhầm cú pháp này là lỗi phổ biến nhất khi mới chuyển từ client khác sang OpenCode.

Sau khi lưu config, chạy opencode để vào TUI (terminal UI), rồi gõ /mcp để xem danh sách server đã kết nối và trạng thái của chúng. Nếu confluence hiện trạng thái lỗi, dùng opencode --print-logs khi khởi động lại để xem chi tiết stack trace kết nối — thường là do thiếu biến môi trường hoặc sai định dạng command (OpenCode yêu cầu array, không phải string như một số client khác).

Mẹo: Khi chuyển đổi qua lại giữa nhiều coding agent CLI (Claude Code, OpenCode, Gemini CLI) trong cùng một project, viết sẵn cả 3 file config (.mcp.json, opencode.json, .gemini/settings.json) và commit chung, nhưng dùng cùng một biến môi trường gốc (ví dụ .env chung) để tránh tình trạng token bị lệch giữa các tool.

Đọc Và Tạo Confluence Page Từ OpenCode

Trong TUI của OpenCode, bạn ra prompt bằng ngôn ngữ tự nhiên như bình thường, agent tự quyết định khi nào cần gọi tool MCP. Thử một prompt đọc:

Search Confluence space PLAT cho các page có từ khóa "circuit breaker",
in ra title và page_id của 5 kết quả liên quan nhất.

OpenCode sẽ hiện một khối "tool call" trực tiếp trong luồng chat, với tên tool đầy đủ dạng confluence_confluence_search (namespace theo tên server bạn đặt trong config, ở đây là confluence, ghép với tên tool gốc) — cú pháp namespacing này có thể gây nhầm lẫn ban đầu vì tên tool bị lặp chữ, nhưng đó là cách OpenCode tránh đụng tên khi bạn có nhiều MCP server cùng expose tool trùng tên.

Với hành động ghi, ví dụ tạo page:

Đọc source code trong lib/circuit-breaker/, viết một Confluence page
mới trong space PLAT, dưới parent "Resilience Patterns", tiêu đề
"Circuit Breaker Implementation Notes", gồm: Overview, State Machine
(Closed/Open/Half-Open), Configuration, Failure Thresholds, Testing Strategy.

OpenCode theo mặc định (config permission chưa set) sẽ hỏi xác nhận qua dialog trong TUI trước khi thực thi tool ghi. Bạn có thể tinh chỉnh permission cho riêng tool Confluence trong opencode.json:

{
  "permission": {
    "mcp": {
      "confluence_confluence_search": "allow",
      "confluence_confluence_get_page": "allow",
      "confluence_confluence_create_page": "ask",
      "confluence_confluence_update_page": "ask"
    }
  }
}

Mẹo: Vì tên tool trong OpenCode bị namespace theo tên server (dễ gõ sai khi cấu hình permission), luôn chạy /mcp rồi xem chính xác tên tool được liệt kê trước khi viết rule permission trong opencode.json — copy paste chính xác từ đó, đừng tự đoán format tên.

Ví Dụ Thực Tế: Sinh ADR Từ Source Code Trong OpenCode

Đây là workflow mình thấy hiệu quả nhất với OpenCode trong thực tế: sinh Architecture Decision Record ngay sau khi một quyết định kỹ thuật lớn được implement, khi context còn "nóng" trong đầu agent (agent vừa đọc/sửa code xong nên hiểu rõ lý do quyết định).

Giả sử team vừa chuyển từ polling sang webhook cho một tích hợp bên thứ ba. Prompt:

Đọc diff giữa branch main và feature/webhook-migration trong thư mục
src/integrations/stripe/. Dựa vào các thay đổi này, viết một ADR đầy đủ
theo format:


## Status
Accepted

## Context
[Giải thích vì sao polling không còn phù hợp — dựa vào code cũ đã bị xóa]

## Decision
[Mô tả giải pháp webhook đã implement — dựa vào code mới]

## Consequences
[Trade-off: độ trễ giảm nhưng cần xử lý idempotency và webhook signature verification]

Tạo page này trong Confluence space ARCH, dưới parent "ADRs — Payments",
giữ nguyên cấu trúc heading trên.

Điểm hay của cách làm này: vì agent vừa đọc diff thật (không phải suy đoán chung), phần "Context" và "Consequences" sinh ra thường bám sát thực tế hơn nhiều so với việc yêu cầu viết ADR từ mô tả bằng lời của con người — agent sẽ nhắc tới đúng tên function, tên config, và edge case đã xử lý trong code.

Sau khi page được tạo, review lại phần "Consequences" cẩn thận — đây là phần agent dễ generic hóa nhất (kiểu "cải thiện performance, giảm rủi ro") nếu code diff không có comment giải thích rõ trade-off. Bổ sung thủ công phần này nếu cần.

Mẹo: Luôn yêu cầu agent trích dẫn (quote) trực tiếp một đoạn code hoặc commit message cụ thể vào mục "Context" của ADR — điều này buộc agent bám vào evidence thật, giảm hẳn tình trạng "bịa" lý do nghe hợp lý nhưng không đúng thực tế.

Hạn Chế Đã Biết Của Confluence MCP Trong OpenCode

Vì OpenCode còn tương đối mới trong việc chuẩn hóa hỗ trợ MCP, có vài điểm bạn nên lường trước để tránh bất ngờ khi triển khai:

Thiếu UI xem trước nội dung page dạng rendered. Khác với VS Code extension của Claude Code hiện preview markdown ngay trong sidebar, OpenCode TUI hiện nội dung page dạng raw text/JSON trong khối tool call — khó review nhanh với page dài, bạn nên mở song song browser để xem kết quả thật sau khi tạo.

Xử lý page rất dài dễ vượt context window. Khi gọi confluence_get_page trên một page cực dài (ví dụ runbook 5000 từ), toàn bộ nội dung storage format (XHTML) của Confluence đổ vào context — với page phức tạp có nhiều table/macro, dung lượng token có thể lớn hơn bạn tưởng do markup XHTML verbose hơn markdown nhiều. Với model có context window (cửa sổ ngữ cảnh) nhỏ, việc này dễ gây tràn context giữa session dài.

Không có cơ chế retry tự động khi version conflict. Khi hai người/agent cùng update một page, Confluence trả lỗi conflict version — OpenCode hiện lỗi này ra và dừng lại, bạn phải tự yêu cầu agent đọc lại version mới nhất rồi thử update lại, không có auto-retry built-in như một số MCP client khác.

Mẹo: Với page dài, luôn yêu cầu agent chỉ lấy một phần cụ thể trước (ví dụ "chỉ lấy mục Retry Policy của page này") nếu server hỗ trợ, hoặc yêu cầu agent tóm tắt ngay sau khi đọc để giải phóng context — đừng để nhiều page dài chồng lên nhau trong một session.

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

Vài kinh nghiệm khi chạy Confluence MCP với OpenCode cho team platform/infra:

  • OpenCode phù hợp nhất cho workflow chạy trong CI/script (dùng opencode run non-interactive) hơn là tương tác dài — vì thiếu preview trực quan, việc review từng bước trong terminal kém tiện hơn Claude Code VS Code extension.
  • Luôn pin phiên bản server community trong config (ví dụ @aashari/mcp-server-atlassian-confluence@1.2.0 thay vì để mặc định lấy latest) để tránh breaking change bất ngờ khi server cập nhật schema tool.
  • Nếu team đa dạng công cụ (một số dùng Claude Code, một số dùng OpenCode), thống nhất namespace tên server MCP giữa các file config (luôn đặt tên confluence, không đổi thành atlassian-confluence ở file này và confluence-mcp ở file khác) để prompt/rule permission có thể tái dùng chung.

Mẹo: Viết một script kiểm tra sức khỏe kết nối MCP (opencode run "Kiểm tra kết nối tới Confluence bằng cách search một từ khóa test, báo lại pass/fail" chạy qua cron hàng ngày) để phát hiện sớm khi token hết hạn hoặc server bị đổi endpoint, tránh tình trạng cả team phát hiện ra Confluence MCP "chết" giữa lúc đang cần gấp.

Tiếp Confluence MCP với Gemini CLI