MCP Server (Tích hợp AI)

SpecDown cung cấp máy chủ Model Context Protocol (MCP) để AI assistant có thể đọc, tìm kiếm, comment, cập nhật, upload ảnh, và lập kế hoạch sync tài liệu theo cách có cấu trúc.

MCP là gì?

Model Context Protocol là chuẩn mở để mô hình AI kết nối với hệ thống bên ngoài dưới dạng công cụ có cấu trúc. Với SpecDown MCP, agent không cần scrape UI mà vẫn có thể đọc spec, viết update, để lại comment review, upload ảnh, và lên kế hoạch sync remote.

Các công cụ hiện có

Đọc và khám phá

Ghi và cộng tác

Sync planning cho agent

Lấy API Key

1. Vào Cài đặt → API Keys.
2. Nhấn Generate new key.
3. Đặt tên và chọn project mà key có thể truy cập.
4. Sao chép key. Key chỉ hiển thị một lần.

Hai cách kết nối

SpecDown MCP hỗ trợ cả HTTP hosted và stdio local.

HTTP + SSE (từ xa)

Endpoint: https://specdown.app/api/mcp
Protocol: JSON-RPC 2.0 over HTTP + Server-Sent Events
Auth: Authorization: Bearer <your-api-key>

Stdio (cục bộ)

npx specdown-mcp --api-key <your-api-key>

Hoặc cài toàn cục:

npm install -g specdown-mcp
specdown-mcp --api-key <your-api-key>

Thiết lập Claude Desktop

Thêm SpecDown vào file claude_desktop_config.json:

{
  "mcpServers": {
    "specdown": {
      "command": "npx",
      "args": ["-y", "specdown-mcp"],
      "env": {
        "SPECDOWN_API_KEY": "your-api-key-here"
      }
    }
  }
}

Trên macOS, file nằm tại ~/Library/Application Support/Claude/claude_desktop_config.json.

Flow sync điển hình cho agent

Các sync tools được thiết kế cho agent đã có quyền đọc filesystem local từ host environment.

1. Đọc file local trong linked folder
2. Hash chúng thành [{ path, hash, documentId? }]
3. Gọi plan_sync với project_id, remote_prefix, local_files, và optional state_files
4. Review plan + summary trả về
5. Chuyển các remote mutation đã duyệt thành operations cho apply_sync_plan
6. Khi sync thành công, cập nhật local .specdown/sync-state.json

Ví dụ prompt

• "Đọc auth docs và tóm tắt login flow."
• "Tìm toàn bộ tài liệu có nhắc tới rate limiting và trả về doc path."
• "Tạo ADR mới dưới /architecture và seed nội dung ban đầu."
• "Upload diagram này rồi trả Markdown image link để chèn vào /guides/authentication.md."
• "Lập sync plan cho linked folder local của tôi, rồi show conflict trước khi apply."

Bảo mật

Mọi request MCP đều xác thực bằng Bearer token. Project access được kiểm tra phía server, nên API key chỉ truy cập được các project mà nó được cấp.

Các write tools như update_document, add_comment, upload_image, và apply_sync_plan cũng bị giới hạn trong cùng project scope đó.

Use Cases & Mẹo

Triển khai code theo spec sống

Viết spec trong SpecDown trước, sau đó để AI đọc trực tiếp nguồn chân lý thay vì bản copy-paste.

Review bằng AI + comment thread

"Đọc /api/authentication.md và thêm comment review cho những edge case còn thiếu."

"So sánh billing doc mới với bản cũ và comment vào những chỗ breaking change chưa rõ."

Agent quản lý local mirror

"Đọc linked folder local của tôi, gọi plan_sync, rồi cho tôi xem những gì sẽ được push."

"Chỉ apply các remote upsert trong sync plan đã duyệt, sau đó báo file nào bị skip."

Đây là phần MCP song hành với linked-folder workflow của CLI. MCP lên kế hoạch và áp remote mutation; host agent vẫn là bên đọc/ghi file local thật.

Khám phá backlink và đồ thị tài liệu

"Cho tôi xem toàn bộ tài liệu đang link tới /guides/authentication.md."

"Dựng đồ thị cho subtree /architecture rồi chỉ ra những doc đang đóng vai trò hub."

Dùng get_backlinks khi agent cần biết doc nào sẽ bị ảnh hưởng trước khi sửa, và dùng get_doc_graph khi cần nhìn quan hệ rộng hơn trong một khu vực tài liệu.

Properties và view kiểu bases

"Liệt kê frontmatter properties của toàn bộ tài liệu dưới /prd."

"Query subtree /roadmap để lấy các doc có status = draft và tags chứa agent."

Dùng list_properties khi agent cần metadata có cấu trúc trước khi sửa doc, và dùng query_view khi cần một working set đã lọc thay vì quét toàn bộ project.

Upload asset cho docs automation

"Upload file PNG này vào project hiện tại và trả Markdown image link."

"Gắn ảnh vừa upload vào /guides/onboarding.md rồi update doc với markdown tương ứng."

Automation cho project attachment

"Upload PDF này thành /assets/brief.pdf và trả về embed [@/assets/brief.pdf]."

"Liệt kê project files dưới /assets, đọc preview CSV, rồi tóm tắt các dòng."

Dùng list_project_files, read_project_file, và upload_project_file khi agent cần thao tác với file project. HTML/HTM sẽ thành document editable, còn file khác vẫn là asset chỉ preview.

Dùng với Cursor / Windsurf

# .cursor/mcp.json
{
  "mcpServers": {
    "specdown": {
      "command": "npx",
      "args": ["-y", "specdown-mcp"],
      "env": { "SPECDOWN_API_KEY": "your-api-key" }
    }
  }
}

Mẹo & Thủ thuật

• Tách API key theo project: tạo key riêng cho từng project hoặc từng môi trường.
• Bắt đầu bằng context: gọi read_project_context hoặc list_documents trước khi đào sâu vào doc cụ thể.
• Tìm trước rồi mới đọc: dùng search_documents để tiết kiệm token.
• Dùng comment cho review: nếu cần con người duyệt, ưu tiên add_comment thay vì sửa doc ngay.
• Lập plan trước khi apply: coi plan_sync là bước an toàn mặc định, còn apply_sync_plan là bước commit.
• Kiểm tra backlink trước khi sửa doc dùng chung: gọi get_backlinks hoặc get_doc_graph trước khi rewrite những tài liệu được nhiều nơi tham chiếu.
• Dùng properties để thu hẹp phạm vi đọc: gọi list_properties hoặc query_view trước khi mở toàn bộ PRD, ADR, hay runbook của project lớn.
• Kết hợp với CLI: MCP mạnh ở decision và tool-call có cấu trúc; CLI vẫn là cách đơn giản nhất để giữ working copy local thật trên đĩa.