@kontent-ai/mcp-server 0.3.0 → 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Kontent s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,13 +1,21 @@
 # Kontent.ai MCP Server
 
+[![NPM Version][npm-shield]][npm-url]
+[![Contributors][contributors-shield]][contributors-url]
+[![Forks][forks-shield]][forks-url]
+[![Stargazers][stars-shield]][stars-url]
+[![Issues][issues-shield]][issues-url]
+[![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.
 
 ## Features
 
 - Retrieve content items, variants, and assets
-- Get content types and their structure
 - List available languages and assets
-- Create new content types and snippets
+- Get, List, and Create content types and snippets
+- Get, List, and Create taxonomies
 
 ## Getting Started
 
@@ -16,41 +24,53 @@ This server provides a Model Context Protocol (MCP) interface for interacting wi
 - Node.js (version specified in `.nvmrc`)
 - Kontent.ai account with API keys
 
-### Environment Variables
+### Running
 
-The following environment variables are needed:
+You can run this server with either stdio or sse transport.
 
-```
-KONTENT_ENVIRONMENT_ID=your_environment_id
-KONTENT_API_KEY=your_api_key
+### Stdio transport
+
+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",
+      "env": {
+        "KONTENT_API_KEY": "<management-api-key>",
+        "KONTENT_ENVIRONMENT_ID": "<environment-id>"
+      }
+    }
+}
 ```
 
-### Using with npx
+### SSE transport
 
-You can run the server directly with npx:
+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.
 
 ```bash
-# Run with SSE transport
-npx @kontent-ai/mcp-server sse
-
-# Run with STDIO transport
-npx @kontent-ai/mcp-server stdio
+npx @kontent-ai/mcp-server@latest sse
+```
+```env
+KONTENT_API_KEY=<management-api-key>
+KONTENT_ENVIRONMENT_ID=<environment-id>
+PORT=<port-number> # optionally specify port, defaults to 3001
 ```
 
-### Example mcp.json usage
-
+Then configure your MCP client to connect to the running server.
+Example:
 ```json
 {
-  "kontent-ai-stdio": {
-      "command": "npx @kontent-ai/mcp stdio",
-      "env": {
-        "KONTENT_API_KEY": "<management-api-key>",
-        "KONTENT_ENVIRONMENT_ID": "<environment-id>"
-      }
-    },
+  "kontent-ai-sse": {
+    "url": "http://localhost:3001/sse"
+  }
 }
 ```
 
+
+## Development
+
 ### Local Installation
 
 ```bash
@@ -69,8 +89,6 @@ npm run start:sse  # For SSE transport
 npm run start:stdio  # For STDIO transport
 ```
 
-## Development
-
 ### Available Scripts
 
 - `npm run build` - Compile TypeScript to JavaScript
@@ -88,4 +106,19 @@ npm run start:stdio  # For STDIO transport
 
 ## License
 
-MIT 
+MIT 
+
+[contributors-shield]: https://img.shields.io/github/contributors/kontent-ai/mcp-server.svg?style=for-the-badge
+[contributors-url]: https://github.com/kontent-ai/mcp-server/graphs/contributors
+[forks-shield]: https://img.shields.io/github/forks/kontent-ai/mcp-server.svg?style=for-the-badge
+[forks-url]: https://github.com/kontent-ai/mcp-server/network/members
+[stars-shield]: https://img.shields.io/github/stars/kontent-ai/mcp-server.svg?style=for-the-badge
+[stars-url]: https://github.com/kontent-ai/mcp-server/stargazers
+[issues-shield]: https://img.shields.io/github/issues/kontent-ai/mcp-server.svg?style=for-the-badge
+[issues-url]: https://github.com/kontent-ai/mcp-server/issues
+[license-shield]: https://img.shields.io/github/license/kontent-ai/mcp-server.svg?style=for-the-badge
+[license-url]: https://github.com/kontent-ai/mcp-server/blob/master/LICENSE.md
+[discord-shield]: https://img.shields.io/discord/821885171984891914?color=%237289DA&label=Kontent.ai%20Discord&logo=discord&style=for-the-badge
+[discord-url]: https://discord.com/invite/SKCxwPtevJ
+[npm-url]: https://www.npmjs.com/package/@kontent-ai/mcp-server
+[npm-shield]: https://img.shields.io/npm/v/%40kontent-ai%2Fmcp-server?style=for-the-badge&logo=npm&color=%23CB0000

package/build/schemas/contentTypeSchemas.js

@@ -8,7 +8,9 @@ const referenceObjectSchema = z.object({
 const baseElementSchema = {
     codename: z.string().optional(),
     external_id: z.string().optional(),
-    content_group: referenceObjectSchema.optional(),
+    content_group: referenceObjectSchema
+        .describe("An object with an id or codename property referencing a content group.")
+        .optional(),
 };
 const namedElementSchema = {
     ...baseElementSchema,
@@ -61,120 +63,131 @@ const textLengthLimitSchema = z.object({
     value: z.number(),
     applies_to: z.enum(['words', 'characters'])
 }).optional();
+// Individual element type schemas
+const assetElementSchema = z.object({
+    type: z.literal('asset'),
+    ...namedElementSchema,
+    asset_count_limit: countLimitSchema,
+    maximum_file_size: z.number().optional(),
+    allowed_file_types: z.enum(['adjustable', 'any']).optional(),
+    ...imageLimitSchema,
+    default: arrayDefaultSchema(),
+});
+const customElementSchema = z.object({
+    type: z.literal('custom'),
+    ...namedElementSchema,
+    source_url: z.string(),
+    json_parameters: z.string().optional(),
+    allowed_elements: z.array(referenceObjectSchema
+        .describe("An object with an id or codename property referencing an element.")).optional(),
+});
+const dateTimeElementSchema = z.object({
+    type: z.literal('date_time'),
+    ...namedElementSchema,
+    default: stringDefaultSchema,
+});
+const guidelinesElementSchema = z.object({
+    type: z.literal('guidelines'),
+    guidelines: z.string(),
+    ...baseElementSchema,
+});
+const modularContentElementSchema = z.object({
+    type: z.literal('modular_content'),
+    ...namedElementSchema,
+    allowed_content_types: z.array(referenceObjectSchema
+        .describe("An object with an id or codename property referencing a content type.")).optional(),
+    item_count_limit: countLimitSchema,
+    default: arrayDefaultSchema(),
+});
+const subpagesElementSchema = z.object({
+    type: z.literal('subpages'),
+    ...namedElementSchema,
+    allowed_content_types: z.array(referenceObjectSchema
+        .describe("An object with an id or codename property referencing a content type.")).optional(),
+    item_count_limit: countLimitSchema,
+});
+const multipleChoiceElementSchema = z.object({
+    type: z.literal('multiple_choice'),
+    ...namedElementSchema,
+    mode: z.enum(['single', 'multiple']),
+    options: z.array(z.object({
+        name: z.string(),
+        codename: z.string().optional(),
+        external_id: z.string().optional(),
+    })),
+    default: arrayDefaultSchema(),
+});
+const numberElementSchema = z.object({
+    type: z.literal('number'),
+    ...namedElementSchema,
+    default: numberDefaultSchema,
+});
+const richTextElementSchema = z.object({
+    type: z.literal('rich_text'),
+    ...namedElementSchema,
+    allowed_blocks: z.array(z.enum(['images', 'text', 'tables', 'components-and-items'])).optional(),
+    allowed_formatting: z.array(z.enum(['unstyled', 'bold', 'italic', 'code', 'link', 'subscript', 'superscript'])).optional(),
+    allowed_text_blocks: z.array(z.enum(['paragraph', 'heading-one', 'heading-two', 'heading-three', 'heading-four', 'heading-five', 'heading-six', 'ordered-list', 'unordered-list'])).optional(),
+    allowed_table_blocks: z.array(z.enum(['images', 'text'])).optional(),
+    allowed_table_formatting: z.array(z.enum(['unstyled', 'bold', 'italic', 'code', 'link', 'subscript', 'superscript'])).optional(),
+    allowed_table_text_blocks: z.array(z.enum(['paragraph', 'heading-one', 'heading-two', 'heading-three', 'heading-four', 'heading-five', 'heading-six', 'ordered-list', 'unordered-list'])).optional(),
+    allowed_content_types: z.array(referenceObjectSchema
+        .describe("An object with an id or codename property referencing a content type.")).optional(),
+    allowed_item_link_types: z.array(referenceObjectSchema
+        .describe("An object with an id or codename property referencing a content type.")).optional(),
+    ...imageLimitSchema,
+    allowed_image_types: z.enum(['adjustable', 'any']).optional(),
+    maximum_image_size: z.number().optional(),
+    maximum_text_length: textLengthLimitSchema,
+});
+const snippetElement = z.object({
+    type: z.literal('snippet'),
+    snippet: referenceObjectSchema
+        .describe("An object with an id or codename property referencing a snippet."),
+    ...baseElementSchema,
+});
+const taxonomyElementSchema = z.object({
+    type: z.literal('taxonomy'),
+    taxonomy_group: referenceObjectSchema
+        .describe("An object with an id or codename property referencing a taxonomy group."),
+    ...namedElementSchema,
+    term_count_limit: countLimitSchema,
+    default: arrayDefaultSchema(),
+});
+const textElementSchema = z.object({
+    type: z.literal('text'),
+    ...namedElementSchema,
+    maximum_text_length: textLengthLimitSchema,
+    validation_regex: regexValidationSchema,
+    default: stringDefaultSchema,
+});
+const urlSlugElementSchema = z.object({
+    type: z.literal('url_slug'),
+    ...namedElementSchema,
+    depends_on: z.object({
+        element: referenceObjectSchema
+            .describe("An object with an id or codename property referencing an element."),
+        snippet: referenceObjectSchema
+            .describe("An object with an id or codename property referencing a content type snippet.")
+            .optional(),
+    }),
+    validation_regex: regexValidationSchema,
+});
 // Define a union type of all possible element types for content types
-export const elementSchema = z.union([
-    // Asset element
-    z.object({
-        type: z.literal('asset'),
-        ...namedElementSchema,
-        asset_count_limit: countLimitSchema,
-        maximum_file_size: z.number().optional(),
-        allowed_file_types: z.enum(['adjustable', 'any']).optional(),
-        ...imageLimitSchema,
-        default: arrayDefaultSchema(),
-    }),
-    // Custom element
-    z.object({
-        type: z.literal('custom'),
-        ...namedElementSchema,
-        source_url: z.string(),
-        json_parameters: z.string().optional(),
-        allowed_elements: z.array(referenceObjectSchema).optional(),
-    }),
-    // Date time element
-    z.object({
-        type: z.literal('date_time'),
-        ...namedElementSchema,
-        default: stringDefaultSchema,
-    }),
-    // Guidelines element
-    z.object({
-        type: z.literal('guidelines'),
-        guidelines: z.string(),
-        ...baseElementSchema,
-    }),
-    // Linked items (modular content) element
-    z.object({
-        type: z.literal('modular_content'),
-        ...namedElementSchema,
-        allowed_content_types: z.array(referenceObjectSchema).optional(),
-        item_count_limit: countLimitSchema,
-        default: arrayDefaultSchema(),
-    }),
-    // Subpages element
-    z.object({
-        type: z.literal('subpages'),
-        ...namedElementSchema,
-        allowed_content_types: z.array(referenceObjectSchema).optional(),
-        item_count_limit: countLimitSchema,
-    }),
-    // Multiple choice element
-    z.object({
-        type: z.literal('multiple_choice'),
-        ...namedElementSchema,
-        mode: z.enum(['single', 'multiple']),
-        options: z.array(z.object({
-            name: z.string(),
-            codename: z.string().optional(),
-            external_id: z.string().optional(),
-        })),
-        default: arrayDefaultSchema(),
-    }),
-    // Number element
-    z.object({
-        type: z.literal('number'),
-        ...namedElementSchema,
-        default: numberDefaultSchema,
-    }),
-    // Rich text element
-    z.object({
-        type: z.literal('rich_text'),
-        ...namedElementSchema,
-        allowed_blocks: z.array(z.enum(['images', 'text', 'tables', 'components-and-items'])).optional(),
-        allowed_formatting: z.array(z.enum(['unstyled', 'bold', 'italic', 'code', 'link', 'subscript', 'superscript'])).optional(),
-        allowed_text_blocks: z.array(z.enum(['paragraph', 'heading-one', 'heading-two', 'heading-three', 'heading-four', 'heading-five', 'heading-six', 'ordered-list', 'unordered-list'])).optional(),
-        allowed_table_blocks: z.array(z.enum(['images', 'text'])).optional(),
-        allowed_table_formatting: z.array(z.enum(['unstyled', 'bold', 'italic', 'code', 'link', 'subscript', 'superscript'])).optional(),
-        allowed_table_text_blocks: z.array(z.enum(['paragraph', 'heading-one', 'heading-two', 'heading-three', 'heading-four', 'heading-five', 'heading-six', 'ordered-list', 'unordered-list'])).optional(),
-        allowed_content_types: z.array(referenceObjectSchema).optional(),
-        allowed_item_link_types: z.array(referenceObjectSchema).optional(),
-        ...imageLimitSchema,
-        allowed_image_types: z.enum(['adjustable', 'any']).optional(),
-        maximum_image_size: z.number().optional(),
-        maximum_text_length: textLengthLimitSchema,
-    }),
-    // Snippet element
-    z.object({
-        type: z.literal('snippet'),
-        snippet: referenceObjectSchema,
-        ...baseElementSchema,
-    }),
-    // Taxonomy element
-    z.object({
-        type: z.literal('taxonomy'),
-        taxonomy_group: referenceObjectSchema,
-        ...namedElementSchema,
-        term_count_limit: countLimitSchema,
-        default: arrayDefaultSchema(),
-    }),
-    // Text element
-    z.object({
-        type: z.literal('text'),
-        ...namedElementSchema,
-        maximum_text_length: textLengthLimitSchema,
-        validation_regex: regexValidationSchema,
-        default: stringDefaultSchema,
-    }),
-    // URL slug element
-    z.object({
-        type: z.literal('url_slug'),
-        ...namedElementSchema,
-        depends_on: z.object({
-            element: referenceObjectSchema,
-            snippet: referenceObjectSchema.optional(),
-        }),
-        validation_regex: regexValidationSchema,
-    }),
+export const elementSchema = z.discriminatedUnion('type', [
+    assetElementSchema,
+    customElementSchema,
+    dateTimeElementSchema,
+    guidelinesElementSchema,
+    modularContentElementSchema,
+    subpagesElementSchema,
+    multipleChoiceElementSchema,
+    numberElementSchema,
+    richTextElementSchema,
+    snippetElement,
+    taxonomyElementSchema,
+    textElementSchema,
+    urlSlugElementSchema,
 ]);
 // Define schema for content groups
 export const contentGroupSchema = z.object({
@@ -183,101 +196,16 @@ export const contentGroupSchema = z.object({
     codename: z.string().optional(),
 });
 // Define a union type for snippet elements (excluding url_slug and snippet elements)
-export const snippetElementSchema = z.union([
-    // Asset element
-    z.object({
-        type: z.literal('asset'),
-        ...namedElementSchema,
-        asset_count_limit: countLimitSchema,
-        maximum_file_size: z.number().optional(),
-        allowed_file_types: z.enum(['adjustable', 'any']).optional(),
-        ...imageLimitSchema,
-        default: arrayDefaultSchema(),
-    }),
-    // Custom element
-    z.object({
-        type: z.literal('custom'),
-        ...namedElementSchema,
-        source_url: z.string(),
-        json_parameters: z.string().optional(),
-        allowed_elements: z.array(referenceObjectSchema).optional(),
-    }),
-    // Date time element
-    z.object({
-        type: z.literal('date_time'),
-        ...namedElementSchema,
-        default: stringDefaultSchema,
-    }),
-    // Guidelines element
-    z.object({
-        type: z.literal('guidelines'),
-        guidelines: z.string(),
-        ...baseElementSchema,
-    }),
-    // Linked items (modular content) element
-    z.object({
-        type: z.literal('modular_content'),
-        ...namedElementSchema,
-        allowed_content_types: z.array(referenceObjectSchema).optional(),
-        item_count_limit: countLimitSchema,
-        default: arrayDefaultSchema(),
-    }),
-    // Subpages element
-    z.object({
-        type: z.literal('subpages'),
-        ...namedElementSchema,
-        allowed_content_types: z.array(referenceObjectSchema).optional(),
-        item_count_limit: countLimitSchema,
-    }),
-    // Multiple choice element
-    z.object({
-        type: z.literal('multiple_choice'),
-        ...namedElementSchema,
-        mode: z.enum(['single', 'multiple']),
-        options: z.array(z.object({
-            name: z.string(),
-            codename: z.string().optional(),
-            external_id: z.string().optional(),
-        })),
-        default: arrayDefaultSchema(),
-    }),
-    // Number element
-    z.object({
-        type: z.literal('number'),
-        ...namedElementSchema,
-        default: numberDefaultSchema,
-    }),
-    // Rich text element
-    z.object({
-        type: z.literal('rich_text'),
-        ...namedElementSchema,
-        allowed_blocks: z.array(z.enum(['images', 'text', 'tables', 'components-and-items'])).optional(),
-        allowed_formatting: z.array(z.enum(['unstyled', 'bold', 'italic', 'code', 'link', 'subscript', 'superscript'])).optional(),
-        allowed_text_blocks: z.array(z.enum(['paragraph', 'heading-one', 'heading-two', 'heading-three', 'heading-four', 'heading-five', 'heading-six', 'ordered-list', 'unordered-list'])).optional(),
-        allowed_table_blocks: z.array(z.enum(['images', 'text'])).optional(),
-        allowed_table_formatting: z.array(z.enum(['unstyled', 'bold', 'italic', 'code', 'link', 'subscript', 'superscript'])).optional(),
-        allowed_table_text_blocks: z.array(z.enum(['paragraph', 'heading-one', 'heading-two', 'heading-three', 'heading-four', 'heading-five', 'heading-six', 'ordered-list', 'unordered-list'])).optional(),
-        allowed_content_types: z.array(referenceObjectSchema).optional(),
-        allowed_item_link_types: z.array(referenceObjectSchema).optional(),
-        ...imageLimitSchema,
-        allowed_image_types: z.enum(['adjustable', 'any']).optional(),
-        maximum_image_size: z.number().optional(),
-        maximum_text_length: textLengthLimitSchema,
-    }),
-    // Taxonomy element
-    z.object({
-        type: z.literal('taxonomy'),
-        taxonomy_group: referenceObjectSchema,
-        ...namedElementSchema,
-        term_count_limit: countLimitSchema,
-        default: arrayDefaultSchema(),
-    }),
-    // Text element
-    z.object({
-        type: z.literal('text'),
-        ...namedElementSchema,
-        maximum_text_length: textLengthLimitSchema,
-        validation_regex: regexValidationSchema,
-        default: stringDefaultSchema,
-    }),
+export const snippetElementSchema = z.discriminatedUnion('type', [
+    assetElementSchema,
+    customElementSchema,
+    dateTimeElementSchema,
+    guidelinesElementSchema,
+    modularContentElementSchema,
+    subpagesElementSchema,
+    multipleChoiceElementSchema,
+    numberElementSchema,
+    richTextElementSchema,
+    taxonomyElementSchema,
+    textElementSchema,
 ]);

package/build/tools/list-taxonomy-groups-mapi.js

@@ -1,9 +1,6 @@
-import { z } from "zod";
 import { createMapiClient } from '../clients/kontentClients.js';
 export const registerTool = (server) => {
-    server.tool("list-taxonomy-groups-mapi", "Get all taxonomy groups from Management API", {
-        random_string: z.string().describe("Dummy parameter for no-parameter tools")
-    }, async () => {
+    server.tool("list-taxonomy-groups-mapi", "Get all taxonomy groups from Management API", {}, async () => {
         const client = createMapiClient();
         const response = await client
             .listTaxonomies()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontent-ai/mcp-server",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "type": "module",
   "scripts": {
     "build": "tsc",
@@ -17,16 +17,16 @@
   "author": "Jiri Lojda",
   "license": "MIT",
   "dependencies": {
-    "@kontent-ai/delivery-sdk": "^16.1.0",
+    "@kontent-ai/delivery-sdk": "^16.2.0",
     "@kontent-ai/management-sdk": "^7.9.0",
-    "@modelcontextprotocol/sdk": "^1.9.0",
+    "@modelcontextprotocol/sdk": "^1.11.4",
     "dotenv": "^16.5.0",
     "express": "^5.1.0",
-    "zod": "^3.24.2"
+    "zod": "^3.25.7"
   },
   "devDependencies": {
-    "@types/express": "^5.0.1",
-    "@types/node": "^22.14.1",
+    "@types/express": "^5.0.2",
+    "@types/node": "^22.15.19",
     "typescript": "^5.8.3"
   }
 }