Kontent.ai

Máy chủ MCP Kontent.ai

Chuyển đổi hoạt động nội dung của bạn bằng các công cụ hỗ trợ AI cho Kontent.ai. Tạo, quản lý và khám phá nội dung có cấu trúc của bạn thông qua các cuộc trò chuyện 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 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 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ác công cụ khả dụng
• ⚙️ 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 thích 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 bằng npx:

Truyền tải STDIO

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

Truyền tải HTTP có thể phát trực tuyến

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

🛠️ Các công cụ khả dụng

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. Lấy 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ả các loại nội dung Kontent.ai
• list-content-type-usages – Liệt kê nơi sử dụng 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 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ả cá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 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ả cá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 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 có, nếu không thì 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 có bản nháp mới hơn nhưng bạn cần nội dung hiện đang xuất bản (trực tiếp)
• get-content-item-translations – Lấy tất cả cá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ỏ qua sẽ được 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ỏ qua sẽ được giữ nguyên. Đối với các phần tử văn bản đa dạng thứ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 hoàn chỉnh, bao gồm cả 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: 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 một tài sản Kontent.ai cụ thể theo ID
• list-assets – Lấy tất cả cá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ả các thư mục tài sản Kontent.ai
• patch-asset-folders – Sửa đổi các thư mục tài sản Kontent.ai bằng 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ả các ngôn ngữ Kontent.ai (bao gồm cả ngôn ngữ 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 thao tác thay thế (chỉ có thể sửa đổi ngôn ngữ hoạt động - để kích hoạt/hủy kích hoạt, 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ả các bộ sưu tập Kontent.ai. Bộ sưu tập đặt 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 các bộ sưu tập Kontent.ai bằng 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ả cá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 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ả cá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ả cá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à các 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 đượ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 đến 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 đánh giá, đánh giá 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 ngay lập tức biến thể 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 tùy chọn chỉ định múi giờ
• 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 ngay lập tức biến thể (làm cho nó không khả dụ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 tùy chọn chỉ định múi giờ
• cancel-scheduled-publishing-content-item-variant – Hủy lịch xuất bản biến thể mục nội dung trong Kontent.ai. Thao tác này đưa biến thể đã được lên lịch xuất bản trở lại bước quy trình làm việc trước đó, cho phép chỉnh sửa thêm

⚙️ 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ế độ một người thuê (STDIO)

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

Chế độ nhiều người thuê (HTTP có thể phát trực tuyến)

Đối với truyền tải HTTP có thể phát trực tuyến, 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 đề Ủy quyền: 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.

KONTENT_API_KEY và KONTENT_ENVIRONMENT_ID bị bỏ qua trên truyền tải này, ngay cả khi chúng được đặt trong môi trường của máy chủ. Mỗi yêu cầu phải mang thông tin xác thực của riêng nó; yêu cầu không có sẽ bị từ chối thay vì được phục vụ bằng thông tin xác thực của máy chủ.

🔒 Bảo mật

Tiêm prompt gián tiếp

Nội dung do máy chủ này trả về (ví dụ: một phần tử do biên tập viên viết) có thể chứa văn bản mà một LLM được kết nối diễn giải như các chỉ dẫn — tiêm prompt gián tiếp. Một tác nhân bị chiếm quyền có thể bị điều hướng đế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 biến đổi nội dung mà nó trả về, vì vậy việc phòng thủ được phân lớp:

• Sử dụng khóa API Management có đặ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 của tác nhân bị chiếm quyền chỉ đơn giản là thất bại tại ranh giới API — biện pháp kiểm soát mạnh nhất, vì nó giữ vững bất kể hành vi của mô hình.
• Giữ con người trong vòng lặp. Mọi công cụ đều mang chú thích MCP — các thao tác đọc là readOnlyHint, các công cụ chỉ tạo là bổ sung, 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 các thao tác đọc và nhắc trước các lệnh gọi phá hoại. 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 có người giám sát với khóa có quyền ghi.
• Thêm một cổng kiểm soát 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ụ: hook Claude Code) cho phép bạn nhắc 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. Báo cáo các vấn đề bảo mật một cách riêng tư tới security@kontent.ai.

🚀 Các Tùy Chọn Vận Chuyển

📟 Vận Chuyển STDIO

Để chạy máy chủ với vận chuyển STDIO, 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>"
      }
    }
}

🌊 Vận Chuyển HTTP Streamable (Đa Người Thuê)

Vận chuyển HTTP Streamable 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 qua các tham số đường dẫn URL và xác thực Bearer.

Đầu 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>"

[!IMPORTANT] 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/ - Các triển khai công cụ MCP
  • clients/ - Thiết lập máy khách API Kontent.ai
  • schemas/ - Các lược đồ xác thực dữ liệu
  • utils/ - Các 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
  • app.ts - Nhà máy ứng dụng Express cho vận chuyển HTTP Streamable
  • 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 vận chuyển

🔍 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 streamable đ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 npm version [patch|minor|major] - điều 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 pull request
3. Hợp nhất pull request
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. 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ý MCP GitHub

Giấy Phép

MIT