@kontent-ai/mcp-server 0.4.2 → 0.5.0

package/README.md

@@ -8,34 +8,116 @@
 [![MIT License][license-shield]][license-url]
 [![Discord][discord-shield]][discord-url]
 
-This server provides a Model Context Protocol (MCP) interface for interacting with Kontent.ai's Management and Delivery APIs. It enables AI assistants to access and manipulate Kontent.ai content using standardized tools.
+> Transform your content operations with AI-powered tools for Kontent.ai. Create, manage, and explore your structured content through natural language conversations in your favorite AI-enabled editor.
 
-## Features
+Kontent.ai MCP Server implements the Model Context Protocol to connect your Kontent.ai projects with AI tools like Claude, Cursor, and VS Code. It enables AI models to understand your content structure and perform operations through natural language instructions.
 
-- Retrieve content items, variants, and assets
-- List available languages and assets
-- Get, List, and Create content types and snippets
-- Get, List, and Create taxonomies
+## ✨ Key Features
 
-## Getting Started
+* 🚀 **Rapid prototyping**: Transform your diagrams into live content models in seconds
+* 📈 **Data Visualisation**: Visualise your content model in any format you want
 
-### Prerequisites
+## Table of Contents
 
-- Node.js (version specified in `.nvmrc`)
-- Kontent.ai account with API keys
+* [🔌 Quickstart](#-quickstart)
+  * [🔑 Prerequisites](#-prerequisites)
+  * [🛠 Setup Options](#-setup-options)
+* [🛠️ Available Tools](#️-available-tools)
+* [⚙️ Configuration](#️-configuration)
+* [🚀 Transport Options](#-transport-options)
+  * [📟 STDIO Transport](#-stdio-transport)
+  * [🌐 SSE Transport](#-sse-transport)
+* [💻 Development](#-development)
+  * [🛠 Local Installation](#-local-installation)
+  * [📂 Project Structure](#-project-structure)
+  * [🔍 Debugging](#-debugging)
+* [License](#license)
 
-### Running
+## 🔌 Quickstart
 
-You can run this server with either stdio or sse transport.
+### 🔑 Prerequisites
 
-### Stdio transport
+Before you can use the MCP server, you need:
+
+1. **A Kontent.ai account** - [Sign up](https://kontent.ai/signup) if you don't have an account.
+1. **A project** - [Create a project](https://kontent.ai/learn/docs/projects#a-create-projects) to work with.
+1. **Management API key** - [Create a Management API key](https://kontent.ai/learn/docs/apis/api-keys#a-create-management-api-keys) with appropriate permissions.
+1. **Environment ID** - [Get your environment ID](https://kontent.ai/learn/docs/environments#a-get-your-environment-id).
+
+### 🛠 Setup Options
+
+You can run the Kontent.ai MCP Server with npx:
+
+#### STDIO Transport
+
+```bash
+npx @kontent-ai/mcp-server@latest stdio
+```
+
+#### SSE Transport
+
+```bash
+npx @kontent-ai/mcp-server@latest sse
+```
+
+## 🛠️ Available Tools
+
+### Content Type Management
+
+* **get-type-mapi** – Get a specific content type by codename
+* **list-content-types-mapi** – List all content types in the environment
+* **add-content-type-mapi** – Create a new content type with elements
+
+### Content Type Snippet Management
+
+* **get-type-snippet-mapi** – Get a specific content type snippet by codename
+* **list-content-type-snippets-mapi** – List all content type snippets
+* **add-content-type-snippet-mapi** – Create a new content type snippet
+
+### Taxonomy Management
+
+* **get-taxonomy-group-mapi** – Get a specific taxonomy group by codename
+* **list-taxonomy-groups-mapi** – List all taxonomy groups
+* **add-taxonomy-group-mapi** – Create a new taxonomy group with terms
+
+### Content Item Management
+
+* **get-item-mapi** – Get a specific content item by codename
+* **get-item-dapi** – Get a content item by codename from Delivery API
+* **get-variant-mapi** – Get a language variant of a content item
+* **add-content-item-mapi** – Create a new content item (structure only)
+* **upsert-language-variant-mapi** – Create or update a language variant with content
+
+### Asset Management
+
+* **get-asset-mapi** – Get a specific asset by codename
+* **list-assets-mapi** – List all assets in the environment
+
+### Language Management
+
+* **list-languages-mapi** – List all languages configured in the environment
+
+## ⚙️ Configuration
+
+The server requires the following environment variables:
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| KONTENT_API_KEY | Your Kontent.ai Management API key | ✅ |
+| KONTENT_ENVIRONMENT_ID | Your environment ID | ✅ |
+| PORT | Port for SSE transport (defaults to 3001) | ❌ |
+
+## 🚀 Transport Options
+
+### 📟 STDIO Transport
+
+To run the server with STDIO transport, configure your MCP client with:
 
-To run the server with stdio transport configure your MCP client with the command to run and the necessary environment variables.
-Example:
 ```json
 {
   "kontent-ai-stdio": {
-      "command": "npx @kontent-ai/mcp-server@latest stdio",
+      "command": "npx",
+      "args": ["@kontent-ai/mcp-server@latest", "stdio"],
       "env": {
         "KONTENT_API_KEY": "<management-api-key>",
         "KONTENT_ENVIRONMENT_ID": "<environment-id>"
@@ -44,22 +126,22 @@ Example:
 }
 ```
 
-### SSE transport
+### 🌐 SSE Transport
 
-You can also run your server manually with the SSE transport and configure your MCP client to connect to the port the server is running on.
-Run the following command to start the server and ensure the environment variables are defined for it either by providing `.env` file in the `cwd` or providing the variables to the process any other way.
+For SSE transport, first start the server:
 
 ```bash
 npx @kontent-ai/mcp-server@latest sse
 ```
+
+With environment variables in a `.env` file, or otherwise accessible to the process:
 ```env
 KONTENT_API_KEY=<management-api-key>
 KONTENT_ENVIRONMENT_ID=<environment-id>
-PORT=<port-number> # optionally specify port, defaults to 3001
+PORT=3001  # optional, defaults to 3001
 ```
 
-Then configure your MCP client to connect to the running server.
-Example:
+Then configure your MCP client:
 ```json
 {
   "kontent-ai-sse": {
@@ -68,10 +150,9 @@ Example:
 }
 ```
 
+## 💻 Development
 
-## Development
-
-### Local Installation
+### 🛠 Local Installation
 
 ```bash
 # Clone the repository
@@ -89,21 +170,34 @@ npm run start:sse  # For SSE transport
 npm run start:stdio  # For STDIO transport
 ```
 
-### Available Scripts
-
-- `npm run build` - Compile TypeScript to JavaScript
-- `npm run start:sse` - Start the server with Server-Sent Events transport
-- `npm run start:stdio` - Start the server with Standard IO transport
-
-### Project Structure
+### 📂 Project Structure
 
 - `src/` - Source code
   - `tools/` - MCP tool implementations
   - `clients/` - Kontent.ai API client setup
   - `schemas/` - Data validation schemas
+  - `utils/` - Utility functions
+    - `errorHandler.ts` - Standardized error handling for MCP tools
+    - `throwError.ts` - Generic error throwing utility
   - `server.ts` - Main server setup and tool registration
   - `bin.ts` - Single entry point that handles both transport types
 
+### 🔍 Debugging
+
+For debugging, you can use the MCP inspector:
+
+```bash
+npx @modelcontextprotocol/inspector -e KONTENT_API_KEY=<key> -e KONTENT_ENVIRONMENT_ID=<env-id> node path/to/build/bin.js
+```
+
+Or use the MCP inspector on a running sse server:
+
+```bash
+npx @modelcontextprotocol/inspector
+```
+
+This provides a web interface for inspecting and testing the available tools.
+
 ## License
 
 MIT 

package/build/bin.js

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
-import 'dotenv/config';
+import "dotenv/config";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import express from "express";
+import packageJson from "../package.json" with { type: "json" };
 import { createServer } from "./server.js";
+const version = packageJson.version;
 async function startSSE() {
     const app = express();
     const { server } = createServer();
     let transport;
-    app.get("/sse", async (req, res) => {
+    app.get("/sse", async (_req, res) => {
         transport = new SSEServerTransport("/message", res);
         await server.connect(transport);
     });
@@ -17,25 +19,27 @@ async function startSSE() {
     });
     const PORT = process.env.PORT || 3001;
     app.listen(PORT, () => {
-        console.log(`Kontent.ai MCP Server (SSE) running on port ${PORT}`);
+        console.log(`Kontent.ai MCP Server v${version} (SSE) running on port ${PORT}`);
     });
 }
 async function startStdio() {
     const { server } = createServer();
     const transport = new StdioServerTransport();
+    console.log(`Kontent.ai MCP Server v${version} (stdio) starting`);
     await server.connect(transport);
 }
 async function main() {
     const args = process.argv.slice(2);
     const transportType = args[0]?.toLowerCase();
-    if (!transportType || (transportType !== 'stdio' && transportType !== 'sse')) {
-        console.error('Please specify a valid transport type: stdio or sse');
+    if (!transportType ||
+        (transportType !== "stdio" && transportType !== "sse")) {
+        console.error("Please specify a valid transport type: stdio or sse");
         process.exit(1);
     }
-    if (transportType === 'stdio') {
+    if (transportType === "stdio") {
         await startStdio();
     }
-    else if (transportType === 'sse') {
+    else if (transportType === "sse") {
         await startSSE();
     }
 }

package/build/clients/kontentClients.js

@@ -1,5 +1,6 @@
-import { createManagementClient } from '@kontent-ai/management-sdk';
+import { createManagementClient } from "@kontent-ai/management-sdk";
 import packageJson from "../../package.json" with { type: "json" };
+import { throwError } from "../utils/throwError.js";
 const sourceTrackingHeaderName = "X-KC-SOURCE";
 /**
  * Creates a Kontent.ai Management API client
@@ -9,14 +10,17 @@ const sourceTrackingHeaderName = "X-KC-SOURCE";
  */
 export const createMapiClient = (environmentId, apiKey) => {
     return createManagementClient({
-        apiKey: apiKey ?? process.env.KONTENT_API_KEY ?? throwError("KONTENT_API_KEY is not set"),
-        environmentId: environmentId ?? process.env.KONTENT_ENVIRONMENT_ID ?? throwError("KONTENT_ENVIRONMENT_ID is not set"),
-        headers: [{
+        apiKey: apiKey ??
+            process.env.KONTENT_API_KEY ??
+            throwError("KONTENT_API_KEY is not set"),
+        environmentId: environmentId ??
+            process.env.KONTENT_ENVIRONMENT_ID ??
+            throwError("KONTENT_ENVIRONMENT_ID is not set"),
+        headers: [
+            {
                 header: sourceTrackingHeaderName,
                 value: `${packageJson.name};${packageJson.version}`,
-            }],
+            },
+        ],
     });
 };
-const throwError = (message) => {
-    throw new Error(message);
-};

package/build/schemas/contentItemSchemas.js

@@ -0,0 +1,205 @@
+import { z } from "zod";
+// Define a reusable reference object schema
+const referenceObjectSchema = z
+    .object({
+    id: z.string().optional(),
+    codename: z.string().optional(),
+    external_id: z.string().optional(),
+})
+    .describe("An object with an id, codename, or external_id property referencing another item. Using codename is preferred for better readability.");
+// Language variant element value schemas
+const textElementValueSchema = z.object({
+    value: z.string().describe("The text content of the element"),
+});
+const numberElementValueSchema = z.object({
+    value: z.number().describe("The numeric value of the element"),
+});
+const dateTimeElementValueSchema = z.object({
+    value: z
+        .string()
+        .nullable()
+        .describe("The ISO-8601 formatted date-time string, or null for empty"),
+});
+const multipleChoiceElementValueSchema = z.object({
+    value: z
+        .array(referenceObjectSchema)
+        .describe("Array of references to the selected options by their codename or id"),
+});
+const assetElementValueSchema = z.object({
+    value: z
+        .array(referenceObjectSchema)
+        .describe("Array of references to assets by their codename or id"),
+});
+const modularContentElementValueSchema = z.object({
+    value: z
+        .array(referenceObjectSchema)
+        .describe("Array of references to linked content items by their codename or id"),
+});
+const taxonomyElementValueSchema = z.object({
+    value: z
+        .array(referenceObjectSchema)
+        .describe("Array of references to taxonomy terms by their codename or id"),
+});
+const richTextElementValueSchema = z.object({
+    value: z.string().describe("The rich text content as HTML string"),
+});
+const urlSlugElementValueSchema = z.object({
+    value: z.string().describe("The URL slug value"),
+});
+const customElementValueSchema = z.object({
+    value: z.string().describe("The JSON string value for custom element"),
+});
+// Union type for all possible element values
+const _elementValueSchema = z.discriminatedUnion("value", [
+    textElementValueSchema,
+    numberElementValueSchema,
+    dateTimeElementValueSchema,
+    multipleChoiceElementValueSchema,
+    assetElementValueSchema,
+    modularContentElementValueSchema,
+    taxonomyElementValueSchema,
+    richTextElementValueSchema,
+    urlSlugElementValueSchema,
+    customElementValueSchema,
+]);
+// Language variant element schema
+const languageVariantElementSchema = z
+    .record(z.string().describe("Element codename as key"), z
+    .union([
+    textElementValueSchema,
+    numberElementValueSchema,
+    dateTimeElementValueSchema,
+    multipleChoiceElementValueSchema,
+    assetElementValueSchema,
+    modularContentElementValueSchema,
+    taxonomyElementValueSchema,
+    richTextElementValueSchema,
+    urlSlugElementValueSchema,
+    customElementValueSchema,
+])
+    .describe("Element value object with 'value' property containing the element's content"))
+    .describe("Object where keys are element codenames and values are element value objects");
+// Collection reference schema
+const collectionReferenceSchema = z
+    .object({
+    reference: referenceObjectSchema
+        .nullable()
+        .describe("Reference to a collection by id, codename, or external_id. Use null to remove from collection."),
+})
+    .describe("Collection assignment for the content item");
+// Content item creation schema
+export const contentItemCreateSchema = z
+    .object({
+    name: z
+        .string()
+        .min(1)
+        .max(200)
+        .describe("Display name of the content item (1-200 characters)"),
+    codename: z
+        .string()
+        .optional()
+        .describe("Codename of the content item (optional, will be generated from name if not provided)"),
+    type: referenceObjectSchema.describe("Reference to the content type by id, codename, or external_id"),
+    external_id: z
+        .string()
+        .optional()
+        .describe("External ID for the content item (optional, useful for external system integration)"),
+    collection: collectionReferenceSchema
+        .optional()
+        .describe("Collection assignment for the content item (optional)"),
+})
+    .describe("Schema for creating a new content item");
+// Language variant creation/update schema
+export const languageVariantUpsertSchema = z
+    .object({
+    elements: languageVariantElementSchema.describe("Object containing element values for the language variant. Keys are element codenames, values are element value objects."),
+    workflow_step: referenceObjectSchema
+        .optional()
+        .describe("Reference to workflow step by id or codename (optional)"),
+})
+    .describe("Schema for creating or updating a language variant of a content item");
+// Complete content item with language variant schema for convenience
+export const contentItemWithVariantSchema = z
+    .object({
+    item: contentItemCreateSchema.describe("Content item data"),
+    language_codename: z
+        .string()
+        .default("default")
+        .describe("Codename of the language for the variant (defaults to 'default')"),
+    variant: languageVariantUpsertSchema.describe("Language variant data with element values"),
+})
+    .describe("Schema for creating a content item along with its language variant in one operation");
+// Element value helper schemas for better LLM understanding
+export const elementValueHelpers = {
+    text: z
+        .object({
+        value: z.string().describe("Text content"),
+    })
+        .describe("Text element value - use for simple text fields like titles, descriptions, etc."),
+    richText: z
+        .object({
+        value: z.string().describe("HTML content as string"),
+    })
+        .describe("Rich text element value - use for formatted content with HTML tags"),
+    number: z
+        .object({
+        value: z.number().describe("Numeric value"),
+    })
+        .describe("Number element value - use for numeric fields like prices, quantities, etc."),
+    dateTime: z
+        .object({
+        value: z
+            .string()
+            .nullable()
+            .describe("ISO-8601 date-time string or null"),
+    })
+        .describe("Date-time element value - use ISO format like '2023-12-25T10:30:00.000Z' or null for empty"),
+    multipleChoice: z
+        .object({
+        value: z
+            .array(z.object({
+            codename: z.string().describe("Codename of the selected option"),
+        }))
+            .describe("Array of selected option references"),
+    })
+        .describe("Multiple choice element value - reference options by their codename"),
+    asset: z
+        .object({
+        value: z
+            .array(z.object({
+            codename: z.string().describe("Codename of the asset"),
+        }))
+            .describe("Array of asset references"),
+    })
+        .describe("Asset element value - reference assets by their codename"),
+    modularContent: z
+        .object({
+        value: z
+            .array(z.object({
+            codename: z
+                .string()
+                .describe("Codename of the linked content item"),
+        }))
+            .describe("Array of content item references"),
+    })
+        .describe("Modular content element value - reference other content items by their codename"),
+    taxonomy: z
+        .object({
+        value: z
+            .array(z.object({
+            codename: z.string().describe("Codename of the taxonomy term"),
+        }))
+            .describe("Array of taxonomy term references"),
+    })
+        .describe("Taxonomy element value - reference taxonomy terms by their codename"),
+    urlSlug: z
+        .object({
+        value: z.string().describe("URL slug value"),
+    })
+        .describe("URL slug element value - use for SEO-friendly URLs"),
+    custom: z
+        .object({
+        value: z.string().describe("JSON string value"),
+    })
+        .describe("Custom element value - depends on the custom element implementation"),
+};