@progress/kendo-react-mcp 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# KendoReact MCP Server
+
+The KendoReact [MCP Server](https://modelcontextprotocol.io/introduction) enables you achieve interation with AI and reach new levels of developer productivity. The MCP server provides proprietary context to AI-powered IDEs, apps and tools. You can use the KendoReact MCP server to ask about Kendo UI for React components, features, or general usage. You can successfully prompt more complex questions and tasks, and generate tailored code that includes Kendo UI for React components and API.
+
+## Prerequisites
+
+To use the KendoReact MCP server, you need:
+
+* A [compatible MCP client (IDE, code editor or app)](https://modelcontextprotocol.io/clients) that supports *MCP tools*.
+* A [Telerik user account](https://www.telerik.com/account/).
+* An active [DevCraft or Kendo UI for React license](https://www.telerik.com/kendo-react-ui/pricing) or a [Kendo UI for React trial](https://www.telerik.com/kendo-react-ui).
+
+## Installation
+
+Use the documentation of your AI-powered MCP client to add the Kendo React MCP server to a specific workspace or globally. You can see installation tips and examples for some popular MCP clients below.
+
+The generic settings of the KendoReact MCP server are:
+
+* Server name: `kendo-react-assistant`
+* Type: `stdio` (standard input/output transport)
+* Command: `npx` (the MCP server works through an npm package)
+* Supported arguments: `-y`
+* npm package name: `@progress/kendo-react-mcp`
+* You also need to add your [Telerik licence key](https://www.telerik.com/kendo-react-ui/components/my-license) as an `env` parameter in the `mcp.json` file. There are two options:
+    * (recommended) Use a `TELERIK_LICENSE_PATH` argument and point to your Telerik license file location.
+    * Use a `TELERIK_LICENSE_KEY` argument and paste your Telerik license key. Make sure to [update the license key](https://www.telerik.com/kendo-react-ui/components/my-license) when necessary.
+
+## Authentication
+
+The MCP server requires a valid Telerik account with a valid license. In order to get a valid license key check the [KendoReact documentation](https://www.telerik.com/kendo-react-ui/components/my-license).
+
+To set up the license key, you need to set it up as an environment variable in the JSON configuration file.
+
+## Configuration Examples
+
+### VSCode - Copilot
+
+Refer to [Use MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
+
+To enable the Kendo React MCP server in a specific workspace or Blazor app, add a `.vscode` folder with an `mcp.json` file at the root of the workspace:
+
+> .vscode/mcp.json at the workspace root
+
+```json
+{
+  "servers": {
+    "kendo-react-assistant": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@progress/kendo-react-mcp@latest"],
+      "env": {
+        "TELERIK_LICENSE_PATH": "THE_PATH_TO_YOUR_LICENSE_FILE",
+        // or
+        "TELERIK_LICENSE_KEY": "YOUR_LICENSE_KEY"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Refer to [Model Context Protocol](https://docs.cursor.com/context/model-context-protocol).
+
+To [enable the Kendo React MCP server in a specific workspace](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server-to-your-workspace) or Blazor app, add a `.cursor` folder with an `mcp.json` file at the root of the workspace.
+
+> .cursor/mcp.json at the workspace root
+
+```json
+{
+  "mcpServers": {
+    "kendo-react-assistant": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@progress/kendo-react-mcp@latest"],
+      "env": {
+        "TELERIK_LICENSE_PATH": "THE_PATH_TO_YOUR_LICENSE_FILE",
+        // or
+        "TELERIK_LICENSE": "YOUR_LICENSE_KEY"
+      },
+    }
+  }
+}
+```
+
+## Usage
+
+To use the Kendo React MCP server:
+
+1. Start your prompt with one of the following:
+    * `kendo`
+    * `/kendo`
+    * `@kendo`
+    * `kendoblazor`
+    * `/kendoblazor`
+    * `@kendoblazor`
+1. Confirm that the Kendo React MCP server is used, because this doesn't happen deterministically. Look for a statement in the output, which is similar to:
+    * `Running kendo-react-assistant` (in VS Code)
+    * `Calling MCP tool kendo-react-assistant` (in Cursor)
+
+    If the Kendo React MCP server is not used even though it's installed and enabled, then try rephrasing your prompt and use another trigger syntax from the list in step 1.
+1. Grant the Kendo React MCP sewrver a permission to run for this session, workspace, or always.
+1. If you want to prompt for information or code that are not related to your previous prompts, it is a good practice to start a new session in a new chat window, so that the context is not polluted by irrelevant old information.
+
+To increase the probability of the Kendo React MCP Server being used, or to call it without the need to mention "kendo" explicitly, add custom idea instructions to your AI-powered tool. Here are examples for [GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot#about-repository-custom-instructions-for-github-copilot-chat) and [Cursor](https://docs.cursor.com/context/rules).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { ReactComponents, Suite, GrpcErrors, REACT_SUITE_NAME, } from './lib/constants.js';
+import { query as contextApiQuery } from './lib/grpc-client.js';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { log } from './lib/logger.js';
+import { LicenseError } from './lib/read-license.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageJsonPath = path.resolve(__dirname, '../package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+const server = new McpServer({
+    name: 'kendo-and-kendo-resources',
+    version: packageJson.version,
+});
+server.tool('kendo_react_assistant', `Answers questions and retrieves documentation about Kendo UI for React. 
+Use this tool when the user asks about Kendo UI for React features, specific components (e.g., Grid, Chart, Editor), implementation details, or general usage. 
+Provide the user's detailed question as the 'query'. If the question pertains to a specific Kendo UI for React component, 
+specify its name in the 'component' parameter. This tool can be automatically triggered when the following phrases are detected in the user's input/prompt:
+- 'kendo';
+- '/kendo';
+- '/kendoreact'
+- '/ask_kendo';
+- '/help_kendo';
+- '@kendo';
+- '@kendoblazor';
+- '@ask_kendo';
+- '@help_kendo'.`, {
+    query: z.string().describe('The query to search for.'),
+    component: z
+        .enum(ReactComponents)
+        .describe('The component to search for. If not specified, you can use General.'),
+}, async ({ query, component }) => {
+    log('Calling tool: ', JSON.stringify({ query, component }));
+    try {
+        const response = await contextApiQuery({
+            query,
+            component: component.toLocaleLowerCase(),
+            lib_name: Suite,
+            text_matches_count: 3,
+            code_matches_count: 0,
+            allowed_types: ['documentation'],
+        });
+        const content = [
+            ...response.values.map((item) => ({
+                type: 'text',
+                text: item,
+            })),
+        ];
+        log('Response from tool: ', JSON.stringify(content));
+        return {
+            content,
+        };
+    }
+    catch (error) {
+        log('Error calling context API: ', JSON.stringify(error));
+        if (error?.code === GrpcErrors.UNAUTHENTICATED) {
+            throw new Error('Error: You are not authenticated. Please verify the Telerik License Key provided is valid.');
+        }
+        else if (error?.code === GrpcErrors.RESOURCE_EXHAUSTED) {
+            throw new Error(`Error: You have exceeded the extension quota. Message: ${error.message}.`);
+        }
+        else if (error?.code === GrpcErrors.PERMISSION_DENIED) {
+            throw new Error(`Error: You do not have permission to access this resource. Please verify that you have a valid ${REACT_SUITE_NAME} license key.`);
+        }
+        else if (error instanceof LicenseError) {
+            log('License error: ', error.message);
+            throw error;
+        }
+        else {
+            throw new Error('Error: An error occurred while calling the service. Please try again later.');
+        }
+    }
+});
+async function startServer() {
+    const transport = new StdioServerTransport();
+    log('Starting server...');
+    await server.connect(transport);
+}
+startServer();

package/dist/lib/constants.d.ts

@@ -0,0 +1,10 @@
+export declare const LICENSE_ENV_VARS: string[];
+export declare const LICENSE_ENV_PATH_VAR = "TELERIK_LICENSE_PATH";
+export declare const REACT_SUITE_NAME = "Kendo UI for React";
+export declare const Suite = "react";
+export declare const ReactComponents: readonly ["ActionSheet", "AIPrompt", "Animation", "AppBar", "ArcGauge", "AutoComplete", "Avatar", "Badge", "Barcode", "BottomNavigation", "Breadcrumb", "Button", "ButtonGroup", "Calendar", "Card", "Chart", "Checkbox", "Chip", "ChipList", "ChunkProgressBar", "CircularGauge", "ColorGradient", "ColorPalette", "ColorPicker", "ComboBox", "ContextMenu", "ConversationalUI", "DataGrid", "DataQuery", "DateInput", "DateMath", "DatePicker", "DateRangePicker", "DateTimePicker", "Dialog", "Drag&Drop", "Drawer", "Drawing", "DropDownButton", "DropDownList", "DropDownTree", "Editor", "Error", "ExcelExport", "ExpansionPanel", "ExternalDropZone", "FileManager", "FileSaver", "Filter", "FlatColorPicker", "FloatingActionButton", "FloatingLabel", "FontIcon", "Form", "Gantt", "Gauge", "General", "GridLayout", "Hint", "Input", "Label", "LinearGauge", "ListBox", "ListView", "Loader", "Map", "MaskedTextBox", "Menu", "MultiColumnComboBox", "MultiSelect", "MultiSelectTree", "MultiViewCalendar", "Notification", "NumericTextBox", "OrgChart", "Pager", "PageTemplates/BuildingBlocks", "PanelBar", "PDFProcessing", "PDFViewer", "PivotGrid", "Popover", "Popup", "ProgressBar", "QRCode", "RadialGauge", "RadioButton", "RadioGroup", "RangeSlider", "Rating", "Ripple", "Sankey", "Scheduler", "ScrollView", "Signature", "Skeleton", "Slider", "Sortable", "Sparkline", "SplitButton", "Splitter", "Spreadsheet", "StackLayout", "Stepper", "StockChart", "SVGIcon", "Switch", "TabStrip", "TaskBoard", "TextArea", "TextBox", "TileLayout", "Timeline", "TimePicker", "Toolbar", "Tooltip", "TreeList", "TreeView", "Typography", "Upload", "VSCodeExtension", "Window"];
+export declare enum GrpcErrors {
+    UNAUTHENTICATED = 16,
+    RESOURCE_EXHAUSTED = 8,
+    PERMISSION_DENIED = 7
+}

package/dist/lib/constants.js

@@ -0,0 +1,134 @@
+export const LICENSE_ENV_VARS = ['TELERIK_LICENSE', 'KENDO_UI_LICENSE'];
+export const LICENSE_ENV_PATH_VAR = 'TELERIK_LICENSE_PATH';
+export const REACT_SUITE_NAME = 'Kendo UI for React';
+export const Suite = 'react';
+export const ReactComponents = [
+    'ActionSheet',
+    'AIPrompt',
+    'Animation',
+    'AppBar',
+    'ArcGauge',
+    'AutoComplete',
+    'Avatar',
+    'Badge',
+    'Barcode',
+    'BottomNavigation',
+    'Breadcrumb',
+    'Button',
+    'ButtonGroup',
+    'Calendar',
+    'Card',
+    'Chart',
+    'Checkbox',
+    'Chip',
+    'ChipList',
+    'ChunkProgressBar',
+    'CircularGauge',
+    'ColorGradient',
+    'ColorPalette',
+    'ColorPicker',
+    'ComboBox',
+    'ContextMenu',
+    'ConversationalUI',
+    'DataGrid',
+    'DataQuery',
+    'DateInput',
+    'DateMath',
+    'DatePicker',
+    'DateRangePicker',
+    'DateTimePicker',
+    'Dialog',
+    'Drag&Drop',
+    'Drawer',
+    'Drawing',
+    'DropDownButton',
+    'DropDownList',
+    'DropDownTree',
+    'Editor',
+    'Error',
+    'ExcelExport',
+    'ExpansionPanel',
+    'ExternalDropZone',
+    'FileManager',
+    'FileSaver',
+    'Filter',
+    'FlatColorPicker',
+    'FloatingActionButton',
+    'FloatingLabel',
+    'FontIcon',
+    'Form',
+    'Gantt',
+    'Gauge',
+    'General',
+    'GridLayout',
+    'Hint',
+    'Input',
+    'Label',
+    'LinearGauge',
+    'ListBox',
+    'ListView',
+    'Loader',
+    'Map',
+    'MaskedTextBox',
+    'Menu',
+    'MultiColumnComboBox',
+    'MultiSelect',
+    'MultiSelectTree',
+    'MultiViewCalendar',
+    'Notification',
+    'NumericTextBox',
+    'OrgChart',
+    'Pager',
+    'PageTemplates/BuildingBlocks',
+    'PanelBar',
+    'PDFProcessing',
+    'PDFViewer',
+    'PivotGrid',
+    'Popover',
+    'Popup',
+    'ProgressBar',
+    'QRCode',
+    'RadialGauge',
+    'RadioButton',
+    'RadioGroup',
+    'RangeSlider',
+    'Rating',
+    'Ripple',
+    'Sankey',
+    'Scheduler',
+    'ScrollView',
+    'Signature',
+    'Skeleton',
+    'Slider',
+    'Sortable',
+    'Sparkline',
+    'SplitButton',
+    'Splitter',
+    'Spreadsheet',
+    'StackLayout',
+    'Stepper',
+    'StockChart',
+    'SVGIcon',
+    'Switch',
+    'TabStrip',
+    'TaskBoard',
+    'TextArea',
+    'TextBox',
+    'TileLayout',
+    'Timeline',
+    'TimePicker',
+    'Toolbar',
+    'Tooltip',
+    'TreeList',
+    'TreeView',
+    'Typography',
+    'Upload',
+    'VSCodeExtension',
+    'Window',
+];
+export var GrpcErrors;
+(function (GrpcErrors) {
+    GrpcErrors[GrpcErrors["UNAUTHENTICATED"] = 16] = "UNAUTHENTICATED";
+    GrpcErrors[GrpcErrors["RESOURCE_EXHAUSTED"] = 8] = "RESOURCE_EXHAUSTED";
+    GrpcErrors[GrpcErrors["PERMISSION_DENIED"] = 7] = "PERMISSION_DENIED";
+})(GrpcErrors || (GrpcErrors = {}));

package/dist/lib/grpc-client.d.ts

@@ -0,0 +1,5 @@
+type Response = {
+    values: string[];
+};
+export declare function query(queryParams: any): Promise<Response>;
+export {};

package/dist/lib/grpc-client.js

@@ -0,0 +1,33 @@
+import protoLoader from '@grpc/proto-loader';
+import grpc from '@grpc/grpc-js';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { readLicense } from './read-license.js';
+const protoPath = join(dirname(fileURLToPath(import.meta.url)), '../../proto/service.proto');
+const proto = protoLoader.loadSync(protoPath, {
+    keepCase: true,
+    longs: String,
+    enums: String,
+    defaults: true,
+    oneofs: true,
+});
+const protoDescriptor = grpc.loadPackageDefinition(proto);
+const service = protoDescriptor.ContextQueryService;
+const client = new service('contextapi.telerik.com:443', grpc.credentials.createSsl());
+export async function query(queryParams) {
+    const license = readLicense();
+    const metadata = new grpc.Metadata();
+    if (license && typeof license === 'string') {
+        metadata.add('x-license-key', license);
+    }
+    return new Promise((resolve, reject) => {
+        client.query(queryParams, metadata, (err, response) => {
+            if (err) {
+                reject(err);
+            }
+            else {
+                resolve(response);
+            }
+        });
+    });
+}

package/dist/lib/logger.d.ts

@@ -0,0 +1 @@
+export declare function log(...args: any[]): void;

package/dist/lib/logger.js

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+let LOG_ENABLED = false;
+const LOG_FILE = process.env.DEBUG_LOG_FILE;
+const LOG_FILE_DEFINED = !!(LOG_FILE && typeof LOG_FILE === 'string');
+// check if the log file is a valid path
+if (LOG_FILE_DEFINED) {
+    const logDir = LOG_FILE.substring(0, LOG_FILE.lastIndexOf('/'));
+    if (!fs.existsSync(logDir)) {
+        fs.mkdirSync(logDir, { recursive: true });
+        fs.writeFileSync(LOG_FILE, '');
+    }
+}
+LOG_ENABLED = LOG_FILE_DEFINED && fs.existsSync(LOG_FILE);
+export function log(...args) {
+    if (LOG_ENABLED) {
+        // write a new line to the file with the date and time
+        const date = new Date();
+        const dateString = date.toISOString();
+        const logString = `${dateString}: ${args.join(' ')}\n`;
+        fs.appendFile(LOG_FILE, logString, (err) => {
+            if (err) {
+                console.error('Error writing to log file:', err);
+            }
+        });
+    }
+}

package/dist/lib/read-license.d.ts

@@ -0,0 +1,4 @@
+export declare class LicenseError extends Error {
+    constructor(message: string);
+}
+export declare function readLicense(): string | undefined;

package/dist/lib/read-license.js

@@ -0,0 +1,32 @@
+import { LICENSE_ENV_VARS, LICENSE_ENV_PATH_VAR } from './constants.js';
+import { readFileSync } from 'node:fs';
+import { log } from './logger.js';
+const LICENSE_PATH = process.env[LICENSE_ENV_PATH_VAR];
+const LICENSE_KEY = process.env[LICENSE_ENV_VARS[0]] || process.env[LICENSE_ENV_VARS[1]];
+// create a custom LicenseError class
+export class LicenseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LicenseError';
+    }
+}
+export function readLicense() {
+    if (!LICENSE_PATH && !LICENSE_KEY) {
+        throw new LicenseError(`No license found. Please set one of the following environment variables: ${LICENSE_ENV_VARS.join(', ')} or ${LICENSE_ENV_PATH_VAR}`);
+    }
+    let licenseKey;
+    if (LICENSE_PATH) {
+        try {
+            licenseKey = readFileSync(LICENSE_PATH, 'utf8');
+            log('License key read from file: ', LICENSE_PATH);
+        }
+        catch (error) {
+            throw new LicenseError(`Error reading license file: ${LICENSE_PATH}. Please verify the file exists and is readable.`);
+        }
+    }
+    if (LICENSE_KEY) {
+        licenseKey = LICENSE_KEY;
+        log('License key read from environment variable.');
+    }
+    return licenseKey;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@progress/kendo-react-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": "./dist/index.js",
+  "license": "See LICENSE.md",
+  "description": "Model Context Protocol for KendoReact",
+  "keywords": [
+    "MCP Server",
+    "Model Context Protocol",
+    "React",
+    "Kendo",
+    "Progress",
+    "AI",
+    "Copilot",
+    "KendoReact",
+    "KendoReact"
+  ],
+  "files": [
+    "dist",
+    "proto",
+    "README.md",
+    "LICENSE.md",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@grpc/grpc-js": "^1.13.3",
+    "@grpc/proto-loader": "^0.7.15",
+    "@modelcontextprotocol/sdk": "^1.8.0",
+    "tslib": "^2.3.0"
+  }
+}

package/proto/service.proto

@@ -0,0 +1,30 @@
+syntax = "proto3";
+option go_package = "github.com/telerik/ai-builder/contextapi/pkg/api/pb";
+
+
+message ContextQueryRequest {
+    string lib_name = 1;
+    string query = 2;
+    int32 text_matches_count = 3;
+    int32 code_matches_count = 4;
+    repeated string allowed_types = 5;
+    string component = 6;
+}
+
+message Item {
+    map<string, string> metadata = 1;
+    string content = 2;
+}
+
+message ContextQueryResponse {
+    repeated Item text = 1;
+    repeated Item code = 2;
+}
+
+message StringArray {
+    repeated string values = 1;
+}
+
+service ContextQueryService {
+    rpc Query(ContextQueryRequest) returns (StringArray);
+}