@syncfusion/maui-assistant 0.1.0

package/README.md

@@ -0,0 +1,202 @@
+# SyncfusionMAUIAssistant MCP Server
+
+## Overview
+
+The SyncfusionMAUIAssistant is a specialized [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server designed to enhance development with Syncfusion's MAUI component libraries. It integrates seamlessly with [MCP-compatible clients](https://modelcontextprotocol.io/clients) to provide intelligent assistance for building MAUI applications with Syncfusion<sup style="font-size:70%">&reg;</sup> components.
+
+### Key Features
+
+* Intelligent code generation for Syncfusion<sup style="font-size:70%">&reg;</sup> MAUI components.
+* Detailed component documentation and usage examples.
+* Troubleshooting assistance for common integration challenges.
+
+## Prerequisites
+
+Before using SyncfusionMAUIAssistant, ensure you have:
+
+* Required [node](https://nodejs.org/en/) version >= 18
+* A [compatible MCP client](https://modelcontextprotocol.io/clients) (VS Code with GitHub Copilot, [Syncfusion<sup style="font-size:70%">&reg;</sup> CodeStudio](https://www.syncfusion.com/code-studio/), etc.)
+* An active Syncfusion<sup style="font-size:70%">&reg;</sup> license (any of the following):
+  - [Commercial License](https://www.syncfusion.com/sales/unlimitedlicense)
+  - [Free Community License](https://www.syncfusion.com/products/communitylicense)
+  - [Free Trial](https://www.syncfusion.com/account/manage-trials/start-trials)
+* An active [API KEY](https://syncfusion.com/account/api-key)
+
+## Unlimited Access
+
+Syncfusion<sup style="font-size:70%">&reg;</sup> offers unlimited access to this MCP server. There are no restrictions on:
+
+* Number of requests
+* Components usage
+* Query types
+* Usage duration
+
+This ensures users can fully leverage Syncfusion<sup style="font-size:70%">&reg;</sup> components to enhance their development experience without limitations.
+
+## Installation
+
+Before you can invoke the `SyncfusionMAUIAssistant` MCP server, you need to configure your MCP client with these core settings. The **Generic MCP Server Settings** shown below are identical across all clients:
+
+### Generic MCP Server Settings
+
+- **npm package name**: `@syncfusion/maui-assistant`
+- **Type**: stdio (standard input/output transport)
+- **Command**: npx
+- **Arguments**: -y
+- **Server name**: syncfusionMAUIAssistant
+
+You need to add your [Syncfusion API key](https://syncfusion.com/account/api-key) as an env parameter in the configuration file:
+
+```json
+"env": {
+  "Syncfusion_API_Key": "YOUR_API_KEY"
+}
+```
+
+Below are setup instructions for popular MCP clients:
+
+### Syncfusion<sup style="font-size:70%">&reg;</sup> Code Studio
+
+* In [Code Studio](https://www.syncfusion.com/code-studio/), open MCP Marketplace and navigate to the `Custom Servers` tab.
+* Enter the Server Name as `maui-mcp`, choose Server Type as npm package, and set the NPM Package name to `@syncfusion/maui-assistant`.
+* Add an environment variable as `Syncfusion_API_Key` and value as your [Syncfusion API key](https://syncfusion.com/account/api-key), then click **Install Server**.
+* Once installed, the server will appear in the User Installed Server list, and will be added to the **config.yaml** file.
+* The server is now ready for use in Code Studio. For more details, refer to the [Code Studio documentation](https://help.syncfusion.com/code-studio/reference/configure-properties/mcp/customservers#npm-server).
+
+### VS Code (GitHub Copilot MCP)
+
+* To configure an MCP server for a specific workspace, you can create a `.vscode/mcp.json` file in your workspace folder.
+
+```json
+{
+  "servers": {
+    "syncfusion-maui-assistant": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@syncfusion/maui-assistant@latest"
+      ],
+      "env": {
+        "Syncfusion_API_Key": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+* After updating the configuration in mcp.json, you'll notice a "Start" option at the top of the config. This allows you to easily start the SyncfusionMauiAssistant server directly from the settings interface without additional commands.
+
+* Confirm the server is active by checking for a message like: `SyncfusionMAUIAssistant is running...` in the output.
+
+* For additional guidance, refer to the [VS Code documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_add-an-mcp-server).
+
+### Cursor
+
+To configure an MCP server for a specific workspace, you can create a .cursor/mcp.json file in your workspace folder.
+
+```json
+{
+  "mcpServers": {
+    "syncfusion-maui-assistant": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@syncfusion/maui-assistant@latest"
+      ],
+      "env": {
+       "Syncfusion_API_Key": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### JetBrains IDEs
+
+* Go to Settings -> Tools -> AI Assistant -> Model Context Protocol (MCP).
+* Click + Add to add a new MCP server configuration.
+* In the New MCP Server dialog, switch the dropdown as `As JSON` and add the following config:
+
+```json
+{
+  "mcpServers": {
+    "syncfusion-maui-assistant": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@syncfusion/maui-assistant@latest"
+      ],
+      "env": {
+       "Syncfusion_API_Key": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+* Click OK and Apply.
+
+* For further assistance, see the [JetBrains documentation](https://www.jetbrains.com/help/ai-assistant/mcp.html#connect-to-an-mcp-server).
+
+> For more detailed information about configuring MCP servers in various clients, refer to the official documentations, e.g., [Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json)
+
+## Usage
+
+To activate the SyncfusionMAUIAssistant MCP server:
+
+1. Start your prompt with one of the following:
+    * 'SyncfusionMAUIAssistant'
+    * '/syncfusion-maui-assistant'
+    * '/syncfusion-maui'
+    * '@syncfusion-maui'
+    * '@ask_syncfusion_maui'
+    * 'maui'
+
+   In VS Code, you can use `#SyncfusionMAUIAssistant` for direct invocation.
+
+2. Grant permission for the server to run (for the session, workspace, or always).
+3. For best results, start a new chat for each new topic to maintain clean context.
+
+### Mode availability
+
+Syncfusion<sup style="font-size:70%">&reg;</sup> MCP Servers provide full access to all AI interaction modes — Ask/Chat, Edit, and Agent — across supported MCP clients.
+
+### Best Practices for Effective Usage
+
+1. `Be specific`: Mention both platform and component (e.g., "How do I create a Syncfusion MAUI Grid with paging and filtering?").
+2. `Provide context`: Include details about your use case for more targeted solutions.
+3. `Use descriptive queries`: Avoid vague questions that lack necessary context.
+4. `Start fresh for new topics`: Begin a new chat session when switching components or topics.
+
+### Example Queries
+
+Here are some effective ways to use SyncfusionMAUIAssistant:
+
+ * "Create a Syncfusion MAUI Grid component with paging, sorting and filtering."
+ * "How do I implement data binding with Syncfusion MAUI scheduler?"
+
+## Troubleshooting
+
+If you encounter issues:
+
+ * Verify your API key is correctly configured.
+ * Ensure the MCP server is enabled in your client's tools selection.
+ * Check that you're using a compatible MCP client version.
+ * Try restarting your development environment.
+
+## Support
+
+Product support is available through the following mediums.
+
+* [Support ticket](https://support.syncfusion.com/support/tickets/create) - Guaranteed Response in 24 hours | Unlimited tickets | Holiday support
+* [Community forum](https://www.syncfusion.com/forums/maui)
+* [Request feature or report bug](https://www.syncfusion.com/feedback/maui)
+* Live chat
+
+## License
+ This is a commercial product and requires a paid license for possession or use. Syncfusion<sup>®</sup> licensed software, including this component, is subject to the terms and conditions of [Syncfusion's EULA](https://www.syncfusion.com/eula/es/). To acquire a license, you can purchase [here](https://www.syncfusion.com/sales/products) or start a free 30-day trial [here](https://www.syncfusion.com/account/manage-trials/start-trials).
+ A free [community license](https://www.syncfusion.com/products/communitylicense) is also available for companies and individuals whose organizations have less than $1 million USD in annual gross revenue and five or fewer developers.
+     © Copyright 2025 Syncfusion<sup>®</sup> Inc. All Rights Reserved. The Syncfusion<sup>®</sup> Essential Studio<sup>®</sup> license and copyright applies to this distribution.
+    The Syncfusion<sup>®</sup> Essential<sup>®</sup> Studio license and copyright applies to this distribution.

package/dist/index.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { SyncfusionMAUIAssistantTool } from "./tools/maui.js";
+import { toolRegistry } from "./utils/toolRegistry.js";
+// Register tools in the registry
+toolRegistry.register(SyncfusionMAUIAssistantTool);
+async function runServer() {
+    const server = new McpServer({
+        name: "SyncfusionMAUIAssistant",
+        version: "0.1.0"
+    });
+    for (const tool of toolRegistry.getAll()) {
+        server.tool(tool.name, tool.description, tool.inputSchema, tool.handler);
+    }
+    const transport = new StdioServerTransport();
+    // Set up the transport to listen for incoming messages
+    const shutdown = async (signal) => {
+        console.info(`Received ${signal}. Shutting down server...`);
+        try {
+            await transport.close();
+            console.info('Server shut down successfully.');
+            process.exit(0);
+        }
+        catch (error) {
+            console.error(error, 'Error during server shutdown.');
+            process.exit(1);
+        }
+    };
+    // Handle shutdown signals and errors
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    process.on('uncaughtException', (error) => {
+        console.error('Uncaught exception:', error);
+        process.exit(1);
+    });
+    process.on('unhandledRejection', (reason, promise) => {
+        console.error('Unhandled rejection at:', promise, 'reason:', reason);
+        process.exit(1);
+    });
+    // Start the server and listen for incoming messages on stdin
+    await server.connect(transport);
+    process.stderr.write("[INFO] SyncfusionMAUIAssistant is running...\n");
+}
+runServer().catch((error) => {
+    console.error(`Server error: ${error}`);
+    process.exit(1);
+});

package/dist/tools/maui.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { callSyncfusionHelpbotAPI } from "../utils/helpbot.js";
+const TOOL_NAME = "SyncfusionMAUIAssistant";
+const TOOL_DESCRIPTION = `
+The ${TOOL_NAME} helps you with Syncfusion UI for MAUI development questions and provides documentation references. This tool is useful when you need assistance with:
+
+1. Understanding specific Syncfusion MAUI components like Grid, Chart, Scheduler, DatePicker, etc.
+2. Implementation techniques for Syncfusion MAUI components
+
+Provide your detailed question in the 'query' parameter. When your question involves specific Syncfusion MAUI components it will detect component references for retrieving relevant documentation and assistance.
+This tool understands the context based on the context MCP client will send the proper query to this server.
+This tool can be automatically triggered when any of the following phrases are detected in the user's input:
+- 'SyncfusionMAUIAssistant'
+- '/syncfusion-maui-assistant'
+- '/syncfusion-maui'
+- '@syncfusion-maui'
+- '@ask_syncfusion_maui'
+- 'maui'
+`;
+// Define the input schema shape for the tool
+const inputSchema = {
+    query: z.string().describe("The query used to search for Syncfusion MAUI components, features, or realworld use cases of Syncfusion components"),
+    components: z.string().optional().describe("Retrieve the components list information from the user query make sure to separate components using , .")
+};
+export const SyncfusionMAUIAssistantTool = {
+    name: TOOL_NAME,
+    description: TOOL_DESCRIPTION,
+    inputSchema,
+    handler: async ({ query, components }) => {
+        try {
+            const result = await callSyncfusionHelpbotAPI(query, 'MAUI', components);
+            if ('error' in result) {
+                if (result.error.includes("401")) {
+                    return resHandler(`❌ Request failed due to an invalid API key. Please try again with the valid API key.`);
+                }
+                return resHandler(`❌ Request failed (status ${result.status}): ${result.error}`);
+            }
+            const systemPrompt = 'Include this information in context for more accurate response generation: ';
+            return resHandler(systemPrompt + result.data);
+        }
+        catch (error) {
+            console.error(`Error during Syncfusion MAUI Assistant processing for query "${query}":`, error);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return resHandler(`❌ An error occurred while processing the request: ${errorMessage}`);
+        }
+    }
+};
+const resHandler = (msg) => {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: msg,
+            }
+        ]
+    };
+};

package/dist/utils/helpbot.js

@@ -0,0 +1,24 @@
+import axios from 'axios';
+const apiKey = process.env.Syncfusion_API_Key || "";
+export async function callSyncfusionHelpbotAPI(query, platform, components) {
+    try {
+        const resp = await axios.post("https://helpbot.syncfusion.com/api/documents/search", { "query": `${query} ${components}`, "platform": platform, "tool": "maui-mcp" }, {
+            headers: {
+                "Content-Type": "application/json",
+                "API-Key": apiKey
+            }
+        });
+        const text = JSON.stringify(resp.data, null, 2);
+        return { data: text, status: resp.status };
+    }
+    catch (err) {
+        if (axios.isAxiosError(err)) {
+            const status = err.response?.status ?? 0;
+            const message = (typeof err.response?.data === 'string'
+                ? err.response.data
+                : JSON.stringify(err.response?.data)) || err.message;
+            return { error: message, status };
+        }
+        return { error: err.message, status: 0 };
+    }
+}

package/dist/utils/toolRegistry.js

@@ -0,0 +1,13 @@
+export class ToolRegistry {
+    tools = new Map();
+    register(tool) {
+        this.tools.set(tool.name, tool);
+    }
+    getAll() {
+        return Array.from(this.tools.values());
+    }
+    getTool(name) {
+        return this.tools.get(name);
+    }
+}
+export const toolRegistry = new ToolRegistry();

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@syncfusion/maui-assistant",
+  "version": "0.1.0",
+  "description": "MCP server that provides efficient access to Syncfusion documentation, implementation guidelines, and code generation for MAUI",
+  "type": "module",
+  "bin": {
+    "maui-assistant": "./dist/index.js"
+  },
+  "keywords": [
+    "MCP Server",
+    "Model Context Protocol",
+    "MAUI",
+    "Syncfusion",
+    "AI",
+    "Copilot",
+    "SyncfusionMAUI"
+  ],
+  "files": [
+    "dist",
+    "assets"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.13.2",
+    "axios": "1.12.1"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "tsc",
+    "inspector": "npx @modelcontextprotocol/inspector dist/index.js"
+  }
+}