@cognigy/plugin-engine 1.0.0

package/dist/index.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { loadConfig } from "./config.js";
+import { CognigyApiClient } from "./api/client.js";
+import { ToolHandlers } from "./tools/handlers.js";
+import { tools } from "./tools/definitions.js";
+import { SERVER_INSTRUCTIONS } from "./instructions.js";
+import { logger } from "./utils/logger.js";
+import { RateLimiter } from "./utils/rateLimiter.js";
+async function main() {
+    try {
+        const config = loadConfig();
+        logger.setLevel(config.logLevel);
+        logger.info("Starting NiCE Cognigy MCP Connector", {
+            name: config.serverName,
+            version: config.serverVersion,
+        });
+        const apiClient = new CognigyApiClient({
+            baseUrl: config.apiBaseUrl,
+            apiKey: config.apiKey,
+        });
+        const toolHandlers = new ToolHandlers(apiClient, config.endpointBaseUrl, config.webchatBaseUrl, config.staticFilesBaseUrl);
+        const rateLimiter = new RateLimiter(config.rateLimit);
+        const server = new Server({ name: config.serverName, version: config.serverVersion }, {
+            capabilities: { tools: {} },
+            instructions: SERVER_INSTRUCTIONS,
+        });
+        server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            logger.info(`Tool call received: ${name}`);
+            const rateLimitKey = config.apiKey.substring(0, 10);
+            if (!rateLimiter.check(rateLimitKey)) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: "Rate limit exceeded" }),
+                        },
+                    ],
+                };
+            }
+            try {
+                const result = await toolHandlers.handleToolCall(name, args || {});
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result) }],
+                };
+            }
+            catch (error) {
+                logger.error("Tool execution error", {
+                    tool: name,
+                    error: error.message,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: error.message,
+                                status: error.status,
+                                code: error.code,
+                                traceId: error.traceId,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        logger.info("NiCE Cognigy MCP Connector started successfully");
+        const shutdown = async () => {
+            logger.info("Shutting down NiCE Cognigy MCP Connector");
+            rateLimiter.destroy();
+            await server.close();
+            process.exit(0);
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+    }
+    catch (error) {
+        logger.error("Failed to start MCP Server", {
+            error: error.message,
+            stack: error.stack,
+        });
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/instructions.d.ts

@@ -0,0 +1,2 @@
+export declare const SERVER_INSTRUCTIONS = "Cognigy.AI MCP Server \u2014 builds and iteratively improves LLM-powered AI Agents.\n\nIn clients that support plugin skills (e.g. Claude Code), detailed step-by-step workflow guidance auto-loads when your intent matches. The overview and hard rules below always apply.\n\nWORKFLOWS:\n- Build a new AI Agent: list projects \u2192 ENSURE an LLM exists (reuse via packages before setup_llm) \u2192 create_ai_agent \u2192 talk_to_agent \u2192 update_ai_agent. NEVER call talk_to_agent until a working LLM is confirmed in the project.\n- Add knowledge / RAG: embedding model vs project-level Knowledge Search model, set_knowledge_ai BEFORE creating the store, attach knowledge as a tool (not the persona) by default.\n- Reuse an LLM across projects: export each largeLanguageModel WITH its connection resource \u2192 upload_and_inspect \u2192 import \u2192 verify. An LLM without its connection is useless. Prefer this over setup_llm.\n- Add custom logic: create a tool first (create_tool), then add nodes INSIDE the tool branch with manage_flow_nodes (parentNodeId = toolNodeId, mode = \"appendChild\"). NEVER add nodes before the AI Agent Job node.\n- Deploy to Webchat: manage_webchat to create/update the endpoint. ALWAYS show the returned demoWebchatUrl as a clickable link.\n- Voice setup & go-live: create the Voice Gateway endpoint, then audit_voice_agent (dry-run, then apply).\n\nTOOL TYPE SELECTION (create_tool):\n- Default to toolType \"tool\" for general requests (e.g., \"unlock account\", \"check balance\", \"validate user\"). This is the most common and versatile type.\n- Use toolType \"http\" only when the user specifies a concrete HTTP/REST API endpoint to call.\n- Use toolType \"mcp\" ONLY when the user explicitly asks to connect to an external MCP (Model Context Protocol) server and provides a server URL. NEVER use \"mcp\" for general-purpose tool requests \u2014 it is a specialized integration type, not a default.\n- Use toolType \"knowledge\" when the user wants to search a Knowledge Store.\n- Use toolType \"send_email\" when the user wants to send emails.\n\nRULES:\n- create_ai_agent auto-provisions flow + AI Agent Job Node + REST endpoint. Do NOT create these separately.\n- An LLM resource MUST exist AND be successfully connected in the project before calling talk_to_agent. Do NOT attempt to test an agent without a confirmed working LLM \u2014 it will fail silently or return empty responses. If LLM setup failed or was not completed, skip testing and inform the user.\n- If another project already has a reusable LLM with connectionId, DO NOT call setup_llm first. Transfer the LLM + connection via manage_packages and only fall back to setup_llm if reuse is unavailable or failed.\n- NEVER hallucinate or guess API keys, connection URLs, or credentials. If an LLM needs to be created and no API key was provided by the user, ASK for it. Do NOT invent values.\n- Cognigy Connections are PROJECT-SCOPED. A connectionId from project A cannot be used in project B \u2014 it will fail with \"Connection does not exist\". The ONLY way to share a connection across projects is via package export/import. Do NOT attempt to pass a cross-project connectionId to setup_llm.\n- NEVER use dangerouslySkipConnectionTest to bypass a missing or cross-project connection. Fix the connection by importing the package or by creating a real same-project connection.\n- talk_to_agent hits a DIFFERENT base URL (endpoint-*.cognigy.ai) \u2014 not the API base URL.\n- delete_resource is the ONLY way to delete anything.\n- create_tool handles tool creation \u2014 it auto-provisions flow nodes internally. Do NOT create flow nodes for tools manually.\n- Never create two tools with the same `toolId`. Duplicate tool IDs can lead to failed tool execution or empty agent responses, and this is often a flow issue rather than an LLM or connection issue.\n- manage_flow_nodes is ONLY for building logic INSIDE tool branches. ALWAYS create a tool first (create_tool { toolType: \"tool\" }) then add nodes inside it using manage_flow_nodes with parentNodeId = toolNodeId and mode = \"appendChild\".\n- NEVER create standalone nodes before the AI Agent Job node. This is an anti-pattern that causes conversation loops and broken flows. ALL behavior \u2014 including authentication, data collection, greetings, and conditional logic \u2014 must be implemented as agent tools that the LLM decides when to invoke.\n- manage_flow_nodes only supports a curated set of node types: say, question, ifThenElse, lookup, setSessionContext, code, goTo, sleep, httpRequest.\n- manage_webchat creates a new endpoint when endpointId is omitted, and updates an existing endpoint only when endpointId is explicitly provided. To update an existing webchat, first use list_resources { resourceType: \"endpoint\", projectId } to find the endpointId.\n- manage_webchat ALWAYS returns demoWebchatUrl \u2014 present it to the user every time as a clickable link. Do NOT tell the user to find the URL in the Cognigy UI.";
+//# sourceMappingURL=instructions.d.ts.map

package/dist/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,mBAAmB,k5JAkCgI,CAAC"}

package/dist/instructions.js

@@ -0,0 +1,36 @@
+export const SERVER_INSTRUCTIONS = `Cognigy.AI MCP Server — builds and iteratively improves LLM-powered AI Agents.
+
+In clients that support plugin skills (e.g. Claude Code), detailed step-by-step workflow guidance auto-loads when your intent matches. The overview and hard rules below always apply.
+
+WORKFLOWS:
+- Build a new AI Agent: list projects → ENSURE an LLM exists (reuse via packages before setup_llm) → create_ai_agent → talk_to_agent → update_ai_agent. NEVER call talk_to_agent until a working LLM is confirmed in the project.
+- Add knowledge / RAG: embedding model vs project-level Knowledge Search model, set_knowledge_ai BEFORE creating the store, attach knowledge as a tool (not the persona) by default.
+- Reuse an LLM across projects: export each largeLanguageModel WITH its connection resource → upload_and_inspect → import → verify. An LLM without its connection is useless. Prefer this over setup_llm.
+- Add custom logic: create a tool first (create_tool), then add nodes INSIDE the tool branch with manage_flow_nodes (parentNodeId = toolNodeId, mode = "appendChild"). NEVER add nodes before the AI Agent Job node.
+- Deploy to Webchat: manage_webchat to create/update the endpoint. ALWAYS show the returned demoWebchatUrl as a clickable link.
+- Voice setup & go-live: create the Voice Gateway endpoint, then audit_voice_agent (dry-run, then apply).
+
+TOOL TYPE SELECTION (create_tool):
+- Default to toolType "tool" for general requests (e.g., "unlock account", "check balance", "validate user"). This is the most common and versatile type.
+- Use toolType "http" only when the user specifies a concrete HTTP/REST API endpoint to call.
+- Use toolType "mcp" ONLY when the user explicitly asks to connect to an external MCP (Model Context Protocol) server and provides a server URL. NEVER use "mcp" for general-purpose tool requests — it is a specialized integration type, not a default.
+- Use toolType "knowledge" when the user wants to search a Knowledge Store.
+- Use toolType "send_email" when the user wants to send emails.
+
+RULES:
+- create_ai_agent auto-provisions flow + AI Agent Job Node + REST endpoint. Do NOT create these separately.
+- An LLM resource MUST exist AND be successfully connected in the project before calling talk_to_agent. Do NOT attempt to test an agent without a confirmed working LLM — it will fail silently or return empty responses. If LLM setup failed or was not completed, skip testing and inform the user.
+- If another project already has a reusable LLM with connectionId, DO NOT call setup_llm first. Transfer the LLM + connection via manage_packages and only fall back to setup_llm if reuse is unavailable or failed.
+- NEVER hallucinate or guess API keys, connection URLs, or credentials. If an LLM needs to be created and no API key was provided by the user, ASK for it. Do NOT invent values.
+- Cognigy Connections are PROJECT-SCOPED. A connectionId from project A cannot be used in project B — it will fail with "Connection does not exist". The ONLY way to share a connection across projects is via package export/import. Do NOT attempt to pass a cross-project connectionId to setup_llm.
+- NEVER use dangerouslySkipConnectionTest to bypass a missing or cross-project connection. Fix the connection by importing the package or by creating a real same-project connection.
+- talk_to_agent hits a DIFFERENT base URL (endpoint-*.cognigy.ai) — not the API base URL.
+- delete_resource is the ONLY way to delete anything.
+- create_tool handles tool creation — it auto-provisions flow nodes internally. Do NOT create flow nodes for tools manually.
+- Never create two tools with the same \`toolId\`. Duplicate tool IDs can lead to failed tool execution or empty agent responses, and this is often a flow issue rather than an LLM or connection issue.
+- manage_flow_nodes is ONLY for building logic INSIDE tool branches. ALWAYS create a tool first (create_tool { toolType: "tool" }) then add nodes inside it using manage_flow_nodes with parentNodeId = toolNodeId and mode = "appendChild".
+- NEVER create standalone nodes before the AI Agent Job node. This is an anti-pattern that causes conversation loops and broken flows. ALL behavior — including authentication, data collection, greetings, and conditional logic — must be implemented as agent tools that the LLM decides when to invoke.
+- manage_flow_nodes only supports a curated set of node types: say, question, ifThenElse, lookup, setSessionContext, code, goTo, sleep, httpRequest.
+- manage_webchat creates a new endpoint when endpointId is omitted, and updates an existing endpoint only when endpointId is explicitly provided. To update an existing webchat, first use list_resources { resourceType: "endpoint", projectId } to find the endpointId.
+- manage_webchat ALWAYS returns demoWebchatUrl — present it to the user every time as a clickable link. Do NOT tell the user to find the URL in the Cognigy UI.`;
+//# sourceMappingURL=instructions.js.map

package/dist/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gKAkC6H,CAAC"}