Kontent.ai

Máy chủ MCP Kontent.ai

Chuyển đổi hoạt động nội dung của bạn với các công cụ hỗ trợ AI dành cho Kontent.ai. Tạo, quản lý và khám phá nội dung có cấu trúc thông qua các cuộc trò chuyện bằng ngôn ngữ tự nhiên trong trình soạn thảo hỗ trợ AI yêu thích của bạn.

Máy chủ MCP Kontent.ai triển khai Giao thức Ngữ cảnh Mô hình để kết nối các dự án Kontent.ai của bạn với các công cụ AI như Claude, Cursor và VS Code. Nó cho phép các mô hình AI hiểu cấu trúc nội dung của bạn và thực hiện các thao tác thông qua hướng dẫn bằng ngôn ngữ tự nhiên.

✨ Tính năng chính

• 🚀 Tạo mẫu nhanh: Chuyển đổi sơ đồ của bạn thành mô hình nội dung trực tiếp chỉ trong vài giây
• 📈 Trực quan hóa dữ liệu: Trực quan hóa mô hình nội dung của bạn ở bất kỳ định dạng nào bạn muốn

Mục lục

• ✨ Tính năng chính
• 🔌 Bắt đầu nhanh
• 🛠️ Công cụ có sẵn
• ⚙️ Cấu hình
• 🔒 Bảo mật
• 🚀 Tùy chọn truyền tải
• 💻 Phát triển
  • 🛠 Cài đặt cục bộ
  • 📂 Cấu trúc dự án
  • 🔍 Gỡ lỗi
  • 📦 Quy trình phát hành
• Giấy phép

🔌 Bắt đầu nhanh

🔑 Điều kiện tiên quyết

Trước khi bạn có thể sử dụng máy chủ MCP, bạn cần:

1. Tài khoản Kontent.ai - Đăng ký nếu bạn chưa có tài khoản.
2. Một dự án - Tạo dự án để làm việc.
3. Khóa API quản lý - Tạo khóa với các quyền phù hợp.
4. ID môi trường - Lấy ID môi trường của bạn.

🛠 Tùy chọn thiết lập

Bạn có thể chạy Máy chủ MCP Kontent.ai với npx:

Truyền tải STDIO

npx @kontent-ai/mcp-server@latest stdio

Truyền tải HTTP có thể truyền phát

npx @kontent-ai/mcp-server@latest shttp

🛠️ Công cụ có sẵn

Hướng dẫn thao tác vá

• get-patch-guide – 🚨 BẮT BUỘC trước bất kỳ thao tác vá nào. Nhận hướng dẫn thao tác vá cho Kontent.ai theo loại thực thể

Quản lý loại nội dung

• get-content-type – Lấy loại nội dung Kontent.ai theo ID
• list-content-types – Lấy tất cả loại nội dung Kontent.ai
• create-content-type – Tạo loại nội dung Kontent.ai mới
• patch-content-type – Cập nhật loại nội dung Kontent.ai hiện có theo tên mã bằng các thao tác vá (di chuyển, thêm vào, xóa, thay thế)
• delete-content-type – Xóa loại nội dung Kontent.ai theo ID

Quản lý đoạn mã loại nội dung

• get-content-type-snippet – Lấy đoạn mã loại nội dung Kontent.ai theo ID
• list-content-type-snippets – Lấy tất cả đoạn mã loại nội dung Kontent.ai
• create-content-type-snippet – Tạo đoạn mã loại nội dung Kontent.ai mới
• patch-content-type-snippet – Cập nhật đoạn mã loại nội dung Kontent.ai hiện có theo ID bằng các thao tác vá (di chuyển, thêm vào, xóa, thay thế)
• delete-content-type-snippet – Xóa đoạn mã loại nội dung Kontent.ai theo ID

Quản lý phân loại

• get-taxonomy-group – Lấy nhóm phân loại Kontent.ai theo ID
• list-taxonomy-groups – Lấy tất cả nhóm phân loại Kontent.ai
• create-taxonomy-group – Tạo nhóm phân loại Kontent.ai mới
• patch-taxonomy-group – Cập nhật nhóm phân loại Kontent.ai bằng các thao tác vá (thêm vào, di chuyển, xóa, thay thế)
• delete-taxonomy-group – Xóa nhóm phân loại Kontent.ai theo ID

Quản lý mục nội dung

• get-content-item – Lấy mục nội dung Kontent.ai theo ID
• get-content-item-variant – Truy xuất biến thể mục nội dung Kontent.ai (phiên bản ngôn ngữ/bản dịch). Trả về phiên bản hiện tại — bản nháp nếu tồn tại, nếu không thì là bản đã xuất bản
• get-published-content-item-variant-version – Truy xuất phiên bản đã xuất bản của biến thể mục nội dung Kontent.ai. Sử dụng khi tồn tại phiên bản nháp mới hơn nhưng bạn cần nội dung đã xuất bản (trực tiếp) hiện tại
• get-content-item-translations – Lấy tất cả bản dịch mục nội dung Kontent.ai — mọi phiên bản ngôn ngữ (biến thể) của một mục nội dung cụ thể
• list-content-item-variants – Liệt kê, lọc, tìm kiếm các mục nội dung Kontent.ai với các biến thể mục nội dung (phiên bản ngôn ngữ/bản dịch)
• create-content-item – Tạo mục nội dung Kontent.ai mới (chỉ tạo vùng chứa, sử dụng create-content-item-variant để thêm phiên bản ngôn ngữ/bản dịch)
• update-content-item – Cập nhật mục nội dung Kontent.ai hiện có theo ID. Mục nội dung phải tồn tại - công cụ này sẽ không tạo mục mới
• delete-content-item – Xóa mục nội dung Kontent.ai theo ID
• create-content-item-variant – Tạo biến thể mục nội dung Kontent.ai gán người dùng hiện tại làm người đóng góp. Giá trị phần tử phải đáp ứng các giới hạn và hướng dẫn được xác định trong loại nội dung. Chỉ gửi các phần tử bạn muốn đặt; các phần tử bị bỏ qua sẽ khởi tạo trống
• update-content-item-variant – Cập nhật biến thể mục nội dung Kontent.ai của một mục nội dung. Giá trị phần tử phải đáp ứng các giới hạn và hướng dẫn được xác định trong loại nội dung. Chỉ gửi các phần tử bạn muốn thay đổi — các phần tử bị bỏ qua sẽ được giữ nguyên. Đối với các phần tử văn bản giàu có với các thành phần, hãy gửi toàn bộ phần tử (giá trị cộng với mảng thành phần đầy đủ, bao gồm các thành phần được giữ nguyên)
• create-new-content-item-variant-version – Tạo phiên bản mới của biến thể mục nội dung Kontent.ai. Thao tác này tạo phiên bản mới của biến thể mục nội dung hiện có, hữu ích cho việc tạo phiên bản nội dung và tạo bản nháp mới từ nội dung đã xuất bản
• delete-content-item-variant – Xóa biến thể mục nội dung Kontent.ai
• bulk-get-content-item-variants – Lấy hàng loạt các mục nội dung Kontent.ai với các biến thể mục nội dung của chúng theo cặp tham chiếu mục và ngôn ngữ. Sử dụng sau list-content-item-variants để truy xuất dữ liệu nội dung đầy đủ cho các cặp mục+ngôn ngữ cụ thể. Các mục không có biến thể trong ngôn ngữ được yêu cầu sẽ trả về mục mà không có thuộc tính biến thể. Trả về kết quả được phân trang với mã thông báo tiếp tục
• search-content-item-variants – Tìm kiếm ngữ nghĩa hỗ trợ AI để tìm nội dung theo ý nghĩa và khái niệm trong một biến thể mục nội dung cụ thể. Sử dụng cho: các tìm kiếm khái niệm khi bạn không biết từ khóa chính xác. Tùy chọn lọc hạn chế (chỉ ID biến thể)

Quản lý tài sản

• get-asset – Lấy tài sản Kontent.ai cụ thể theo ID
• list-assets – Lấy tất cả tài sản Kontent.ai
• update-asset – Cập nhật tài sản Kontent.ai theo ID

Quản lý thư mục tài sản

• list-asset-folders – Liệt kê tất cả thư mục tài sản Kontent.ai
• patch-asset-folders – Sửa đổi thư mục tài sản Kontent.ai bằng các thao tác vá (thêm vào để thêm thư mục mới, đổi tên để thay đổi tên, xóa để xóa thư mục)

Quản lý ngôn ngữ

• list-languages – Lấy tất cả ngôn ngữ Kontent.ai (bao gồm cả đang hoạt động và không hoạt động - kiểm tra thuộc tính is_active)
• create-language – Tạo ngôn ngữ Kontent.ai mới (ngôn ngữ luôn được tạo ở trạng thái hoạt động)
• patch-language – Cập nhật ngôn ngữ Kontent.ai bằng các thao tác thay thế (chỉ có thể sửa đổi ngôn ngữ đang hoạt động - để kích hoạt/vô hiệu hóa, hãy sử dụng giao diện web Kontent.ai)

Quản lý bộ sưu tập

• list-collections – Lấy tất cả bộ sưu tập Kontent.ai. Bộ sưu tập thiết lập ranh giới cho các mục nội dung trong môi trường của bạn và giúp tổ chức nội dung theo nhóm, thương hiệu hoặc dự án
• patch-collections – Cập nhật bộ sưu tập Kontent.ai bằng các thao tác vá (thêm vào để thêm bộ sưu tập mới, di chuyển để sắp xếp lại, xóa để xóa bộ sưu tập trống, thay thế để đổi tên)

Quản lý không gian

• list-spaces – Lấy tất cả không gian Kontent.ai
• create-space – Tạo không gian Kontent.ai mới để quản lý trang web hoặc kênh
• patch-space – Vá không gian Kontent.ai bằng các thao tác thay thế
• delete-space – Xóa không gian Kontent.ai

Quản lý vai trò

• list-roles – Lấy tất cả vai trò Kontent.ai. Yêu cầu gói Enterprise hoặc Flex với quyền "Quản lý vai trò tùy chỉnh"

Quản lý quy trình làm việc

• list-workflows – Lấy tất cả quy trình làm việc Kontent.ai. Quy trình làm việc xác định các giai đoạn vòng đời nội dung và chuyển tiếp giữa chúng
• create-workflow – Tạo quy trình làm việc Kontent.ai mới với các bước, chuyển tiếp, phạm vi và quyền vai trò tùy chỉnh
• update-workflow – Cập nhật quy trình làm việc Kontent.ai hiện có theo ID. Sửa đổi các bước, chuyển tiếp, phạm vi và quyền vai trò. Không thể xóa các bước đang được sử dụng
• delete-workflow – Xóa quy trình làm việc Kontent.ai theo ID. Quy trình làm việc không được đang được sử dụng bởi bất kỳ mục nội dung nào
• change-content-item-variant-workflow-step – Thay đổi bước quy trình làm việc của biến thể mục nội dung trong Kontent.ai. Thao tác này di chuyển biến thể mục nội dung sang một bước khác trong quy trình làm việc, cho phép quản lý vòng đời nội dung như di chuyển nội dung từ bản nháp sang xem xét, xem xét sang xuất bản, v.v.
• publish-content-item-variant – Xuất bản hoặc lên lịch xuất bản biến thể mục nội dung của một mục nội dung trong Kontent.ai. Thao tác này có thể xuất bản biến thể ngay lập tức hoặc lên lịch xuất bản vào một ngày và giờ cụ thể trong tương lai với chỉ định múi giờ tùy chọn
• unpublish-content-item-variant – Hủy xuất bản hoặc lên lịch hủy xuất bản biến thể mục nội dung của một mục nội dung trong Kontent.ai. Thao tác này có thể hủy xuất bản biến thể ngay lập tức (làm cho nó không khả dụng thông qua API Phân phối) hoặc lên lịch hủy xuất bản vào một ngày và giờ cụ thể trong tương lai với chỉ định múi giờ tùy chọn

⚙️ Cấu hình

Máy chủ hỗ trợ hai chế độ, mỗi chế độ gắn với truyền tải của nó:

Chế độ đơn thuê (STDIO)

Cấu hình thông tin xác thực qua biến môi trường:

Chế độ đa thuê (HTTP có thể truyền phát)

Đối với truyền tải HTTP có thể truyền phát, thông tin xác thực được cung cấp cho mỗi yêu cầu:

• ID môi trường dưới dạng tham số đường dẫn URL: /{environmentId}/mcp
• Khóa API qua mã thông báo Bearer trong tiêu đề Authorization: Authorization: Bearer <api-key>

Điều này cho phép một phiên bản máy chủ duy nhất xử lý các yêu cầu cho nhiều môi trường Kontent.ai mà không yêu cầu biến môi trường thông tin xác thực.

🔒 Bảo mật

Tiêm nhiễm gián tiếp

Nội dung được trả về bởi máy chủ này (ví dụ: một phần tử được viết bởi biên tập viên) có thể chứa văn bản mà LLM được kết nối diễn giải là hướng dẫn — tiêm nhiễm gián tiếp. Một tác nhân bị chiếm quyền có thể bị điều khiển thực hiện các lệnh gọi công cụ phá hoại (xóa / hủy xuất bản / ghi đè) hoặc làm rò rỉ các bản nháp chưa xuất bản. Đây là một vấn đề chưa được giải quyết trên toàn ngành mà máy chủ không thể khắc phục một cách đáng tin cậy bằng cách chuyển đổi nội dung nó trả về, vì vậy phòng thủ được phân lớp:

• Sử dụng khóa Management API với đặc quyền tối thiểu. Máy chủ hoạt động với bất kỳ khóa nào được cung cấp. Với khóa chỉ đọc, lệnh gọi phá hoại từ một tác nhân bị chiếm quyền sẽ đơn giản thất bại tại ranh giới API — đây là biện pháp kiểm soát mạnh nhất, vì nó có hiệu lực bất kể hành vi của mô hình.
• Giữ con người trong vòng kiểm soát. Mỗi công cụ đều mang chú thích MCP — thao tác đọc là readOnlyHint, công cụ chỉ tạo mới là cộng thêm, và các công cụ ghi đè hoặc xóa dữ liệu là destructiveHint — mà các máy khách tuân thủ sử dụng để tự động phê duyệt thao tác đọc và nhắc nhở trước các lệnh gọi phá hoại. Hãy chạy máy chủ với một máy khách như vậy và tránh các thiết lập tự động phê duyệt không giám sát đối với khóa có khả năng ghi.
• Thêm một rào chắn phía máy khách nếu máy khách của bạn hỗ trợ. Một số máy khách (ví dụ: Claude Code hooks) cho phép bạn nhắc nhở một cách xác định trước khi một công cụ phá hoại chạy, độc lập với mô hình. Điều này được cấu hình cục bộ; máy chủ không thể thực thi nó.

Đây là những gợi ý, không phải đảm bảo. Hãy báo cáo các vấn đề bảo mật một cách riêng tư tới [email protected].

🚀 Tùy chọn Truyền tải

📟 Truyền tải STDIO

Để chạy máy chủ với truyền tải STDIO, hãy cấu hình máy khách MCP của bạn với:

{
  "kontent-ai-stdio": {
      "command": "npx",
      "args": ["@kontent-ai/mcp-server@latest", "stdio"],
      "env": {
        "KONTENT_API_KEY": "<management-api-key>",
        "KONTENT_ENVIRONMENT_ID": "<environment-id>"
      }
    }
}

🌊 Truyền tải HTTP Có thể Truyền phát (Đa Đối tượng)

Truyền tải HTTP có thể truyền phát phục vụ nhiều môi trường Kontent.ai từ một phiên bản máy chủ duy nhất. Mỗi yêu cầu cung cấp thông tin xác thực thông qua tham số đường dẫn URL và xác thực Bearer.

Trước tiên, khởi động máy chủ:

npx @kontent-ai/mcp-server@latest shttp

{
  "servers": {
    "kontent-ai-multi": {
      "uri": "http://localhost:3001/<environment-id>/mcp",
      "headers": {
        "Authorization": "Bearer <management-api-key>"
      }
    }
  }
}

{
  "inputs": [
    {
      "id": "apiKey",
      "type": "password",
      "description": "Kontent.ai API Key"
    },
    {
      "id": "environmentId",
      "type": "text",
      "description": "Environment ID"
    }
  ],
  "servers": {
    "kontent-ai-multi": {
      "uri": "http://localhost:3001/${inputs.environmentId}/mcp",
      "headers": {
        "Authorization": "Bearer ${inputs.apiKey}"
      }
    }
  }
}

{
  "mcpServers": {
    "kontent-ai-multi": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3001/<environment-id>/mcp",
        "--header",
        "Authorization: Bearer <management-api-key>"
      ]
    }
  }
}

claude mcp add --transport http kontent-ai-multi \
  "http://localhost:3001/<environment-id>/mcp" \
  --header "Authorization: Bearer <management-api-key>"

[!QUAN TRỌNG] Thay thế <environment-id> bằng ID môi trường Kontent.ai của bạn (GUID) và <management-api-key> bằng khóa của bạn.

💻 Phát triển

🛠 Cài đặt Cục bộ

# Clone the repository
git clone https://github.com/kontent-ai/mcp-server.git
cd mcp-server

# Install dependencies
npm ci

# Build the project
npm run build

# Start the server
npm run start:stdio  # For STDIO transport
npm run start:shttp  # For Streamable HTTP transport

# Start the server with automatic reloading (no need to build first)
npm run dev:stdio  # For STDIO transport
npm run dev:shttp  # For Streamable HTTP transport

📂 Cấu trúc Dự án

• src/ - Mã nguồn
  • tools/ - Triển khai công cụ MCP
  • clients/ - Thiết lập máy khách API Kontent.ai
  • schemas/ - Lược đồ xác thực dữ liệu
  • utils/ - Hàm tiện ích
    • errorHandler.ts - Xử lý lỗi chuẩn hóa cho các công cụ MCP
    • throwError.ts - Tiện ích ném lỗi chung
  • server.ts - Thiết lập máy chủ chính và đăng ký công cụ
  • bin.ts - Điểm vào duy nhất xử lý cả hai loại truyền tải

🔍 Gỡ lỗi

Để gỡ lỗi, bạn có thể sử dụng trình kiểm tra MCP:

npx @modelcontextprotocol/inspector -e KONTENT_API_KEY=<key> -e KONTENT_ENVIRONMENT_ID=<env-id> node path/to/build/bin.js

Hoặc sử dụng trình kiểm tra MCP trên một máy chủ HTTP có thể truyền phát đang chạy:

npx @modelcontextprotocol/inspector

Điều này cung cấp một giao diện web để kiểm tra và thử nghiệm các công cụ có sẵn.

📦 Quy trình Phát hành

Để phát hành một phiên bản mới:

1. Tăng phiên bản bằng cách sử dụng npm version [patch|minor|major] - thao tác này cập nhật package.json, package-lock.json, và đồng bộ hóa với server.json
2. Đẩy commit lên nhánh của bạn và tạo một yêu cầu kéo (pull request)
3. Hợp nhất yêu cầu kéo
4. Tạo một bản phát hành GitHub mới với số phiên bản làm cả tên và thẻ, sử dụng ghi chú phát hành được tạo tự động
5. Việc xuất bản bản phát hành kích hoạt một quy trình làm việc tự động xuất bản lên npm và sổ đăng ký GitHub MCP

Giấy phép

MIT