@ctera/n8n-nodes-ctera-ai 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 CTERA Networks
+
+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

@@ -0,0 +1,238 @@
+# n8n-nodes-ctera-ai
+
+This is an n8n community node that provides integration with CTERA AI MCP (Model Context Protocol) server for intelligent document search and retrieval.
+
+[n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation platform.
+
+## Installation
+
+### Community Installation (Recommended)
+
+For n8n version 0.187.0 and above, you can install this node directly from npm:
+
+#### Standard Installation
+
+```bash
+npm install -g @ctera/n8n-nodes-ctera-ai
+```
+
+Then restart your n8n instance.
+
+#### Docker Installation
+
+For Docker-based n8n installations:
+
+```bash
+# Install the node inside the running container
+docker exec -it <container-name> npm install -g @ctera/n8n-nodes-ctera-ai
+
+# Restart the container
+docker restart <container-name>
+```
+
+Replace `<container-name>` with your actual container name (e.g., `n8n`, `n8n_n8n_1`).
+
+**Note**: The node will persist across container restarts but will need to be reinstalled if the container is recreated. To make it permanent, consider creating a custom Docker image or using volume mounts.
+
+### Manual Installation (Development)
+
+1. Navigate to your n8n installation:
+   ```bash
+   cd ~/.n8n/nodes
+   ```
+
+2. Clone the repository:
+   ```bash
+   git clone https://github.com/ctera/ctera-n8n-nodes.git
+   cd ctera-n8n-nodes
+   ```
+
+3. Install dependencies and build:
+   ```bash
+   npm install
+   npm run build
+   ```
+
+4. Restart n8n
+
+For more details, see the [n8n community nodes installation guide](https://docs.n8n.io/integrations/community-nodes/installation/).
+
+## Operations
+
+The CTERA AI node supports the following operations:
+
+### List Experts
+Get a list of all available experts (AI knowledge bases) in the system.
+
+**No parameters required**
+
+**Output**: Array of expert objects containing:
+- `id`: Expert ID for API calls
+- `name`: Display name of the expert
+- `description`: Brief description of the expert's knowledge domain
+- `mcp_endpoint`: Dedicated MCP endpoint URL for this expert
+
+### Semantic Search
+Search an expert's knowledge base using advanced semantic search.
+
+**Parameters**:
+- **Expert** (required): Select from available experts (dropdown populated via List Experts)
+- **Query** (required): Your search question or topic
+- **Additional Options**:
+  - Modified After: Filter files modified on or after this date (YYYY-MM-DD)
+  - Modified Before: Filter files modified before this date (YYYY-MM-DD)
+  - Max Results: Number of relevant chunks to return (1-50, default: 5)
+
+**Output**: Array of relevant document chunks with:
+- Text content
+- Source file paths
+- Relevance scores
+- Metadata (dates, file types, etc.)
+
+### Chat
+Have a conversational interaction with an AI expert about their knowledge domain.
+
+**Parameters**:
+- **Expert** (required): Select from available experts
+- **Message** (required): Your message or question to the expert
+- **Conversation ID** (optional): Continue an existing conversation thread
+
+**Output**: 
+- AI expert's response
+- Conversation ID (for follow-up messages)
+- Citations to source documents (if applicable)
+
+## Credentials
+
+This node requires CTERA AI MCP API credentials:
+
+### Setup Instructions
+
+1. **Generate a Bearer Token**:
+   ```bash
+   # Replace YOUR_MCP_SERVER, YOUR_OID, and email with your actual values
+   curl -k "https://YOUR_MCP_SERVER/api/tokens/generate?oid=YOUR_OID&email=your.email@example.com" | jq -r .token
+   ```
+
+2. **Add Credentials in n8n**:
+   - Go to **Credentials** → **New Credential**
+   - Search for "CTERA AI MCP API"
+   - Fill in:
+     - **MCP Server URL**: Your MCP server base URL (e.g., `https://mcp.example.com`)
+     - **Bearer Token**: Paste the token from step 1
+     - **Ignore SSL Issues**: Enable if using self-signed certificates
+
+3. **Test the Credentials**: Click "Test" to verify connection
+
+## Example Workflows
+
+### Competitive Intelligence Daily Report
+
+```
+Schedule Trigger (Daily 9 AM)
+  ↓
+CTERA AI: List Experts
+  ↓
+Split In Batches
+  ↓
+CTERA AI: Semantic Search
+  - Expert: {{$json.id}}
+  - Query: "Recent updates, announcements, and new features"
+  - Modified After: {{$today.minus(7, 'days')}}
+  ↓
+Aggregate Results
+  ↓
+Send Email: Daily Intelligence Summary
+```
+
+### Interactive Q&A Chatbot
+
+```
+Webhook (Receive Question)
+  ↓
+CTERA AI: Chat
+  - Expert: (pre-configured expert ID)
+  - Message: {{$json.question}}
+  - Conversation ID: {{$json.conversationId}}
+  ↓
+Format Response
+  ↓
+Return Webhook Response
+```
+
+### Document Discovery Workflow
+
+```
+Schedule Trigger (Hourly)
+  ↓
+CTERA AI: Semantic Search
+  - Expert: "Product Documentation"
+  - Query: "Installation and setup guides"
+  - Modified After: {{$today.minus(1, 'hour')}}
+  ↓
+Filter: If results not empty
+  ↓
+Send Slack Notification
+```
+
+## Compatibility
+
+Tested with:
+- n8n version: 1.0.0+
+- CTERA AI MCP Server: 1.6.16+
+
+## Resources
+
+* [n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/)
+* [CTERA AI MCP Architecture](https://cteranet.atlassian.net/wiki/spaces/AI/pages/4757454995)
+* [Model Context Protocol](https://modelcontextprotocol.io/)
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Watch Mode
+
+```bash
+npm run dev
+```
+
+### Linting
+
+```bash
+npm run lint
+npm run lintfix
+```
+
+### Publishing
+
+For maintainers publishing new versions to npm, see [PUBLISH.md](PUBLISH.md) for detailed instructions.
+
+## Version History
+
+### 0.1.0
+- Initial public release
+- List Experts operation  
+- Semantic Search operation
+- Chat with Expert operation
+- Bearer token authentication
+
+## License
+
+[MIT](LICENSE)
+
+## Support
+
+For issues and questions:
+- GitHub Issues: https://github.com/ctera/ctera-n8n-nodes/issues
+- CTERA Support: support@ctera.com
+
+
+
+
+
+

package/dist/credentials/CteraAiMcpApi.credentials.d.ts

@@ -0,0 +1,7 @@
+import { ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class CteraAiMcpApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+}

package/dist/credentials/CteraAiMcpApi.credentials.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CteraAiMcpApi = void 0;
+class CteraAiMcpApi {
+    constructor() {
+        this.name = 'cteraAiMcpApi';
+        this.displayName = 'CTERA AI MCP API';
+        this.documentationUrl = 'https://cteranet.atlassian.net/wiki/spaces/AI/pages/4757454995';
+        this.properties = [
+            {
+                displayName: 'MCP Server URL',
+                name: 'serverUrl',
+                type: 'string',
+                default: '',
+                required: true,
+                placeholder: 'https://mcp.your-domain.com',
+                description: 'The base URL of your CTERA AI MCP server (e.g., https://mcp.example.com)',
+            },
+            {
+                displayName: 'Bearer Token',
+                name: 'bearerToken',
+                type: 'string',
+                typeOptions: {
+                    password: true,
+                },
+                default: '',
+                required: true,
+                description: 'Bearer token for authentication. Generate using: curl -k "https://<your-instance>/api/tokens/generate?oid=<your-oid>&email=<your-email>"',
+            },
+            {
+                displayName: 'Ignore SSL Issues',
+                name: 'allowUnauthorizedCerts',
+                type: 'boolean',
+                default: true,
+                description: 'Whether to connect even if SSL certificate validation is not possible',
+            },
+        ];
+        // Note: Test is not included here since each node provides its own expert endpoint URL
+        // The node will test the connection when executing
+    }
+}
+exports.CteraAiMcpApi = CteraAiMcpApi;

package/dist/nodes/CteraAi/CteraAi.node.d.ts

@@ -0,0 +1,5 @@
+import { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class CteraAi implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}

package/dist/nodes/CteraAi/CteraAi.node.js

@@ -0,0 +1,260 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CteraAi = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+class CteraAi {
+    constructor() {
+        this.description = {
+            displayName: 'CTERA Data Intelligence',
+            name: 'cteraAi',
+            icon: 'file:ctera.svg',
+            group: ['transform'],
+            version: 1,
+            subtitle: '={{$parameter["tool"]}}',
+            description: 'Interact with CTERA Data Intelligence experts via per-expert MCP endpoints',
+            defaults: {
+                name: 'CTERA Data Intelligence',
+            },
+            inputs: ['main'],
+            outputs: ['main'],
+            credentials: [
+                {
+                    name: 'cteraAiMcpApi',
+                    required: true,
+                },
+            ],
+            properties: [
+                {
+                    displayName: 'Expert MCP Endpoint URL',
+                    name: 'expertEndpointUrl',
+                    type: 'string',
+                    default: '',
+                    required: true,
+                    displayOptions: {
+                        hide: {
+                            operation: ['listExperts'],
+                        },
+                    },
+                    placeholder: 'https://mcp.your-domain.com/mcp/experts/EXPERT_ID',
+                    description: 'The per-expert MCP endpoint URL. Use "List Experts" operation to get this URL.',
+                },
+                {
+                    displayName: 'Operation',
+                    name: 'operation',
+                    type: 'options',
+                    options: [
+                        {
+                            name: 'List Experts',
+                            value: 'listExperts',
+                            description: 'Get list of all available experts',
+                        },
+                        {
+                            name: 'Semantic Search (for RAG)',
+                            value: 'search',
+                            description: 'Retrieve raw text chunks for Retrieval-Augmented Generation',
+                        },
+                        {
+                            name: 'Chat (Generative Answer)',
+                            value: 'chat',
+                            description: 'Get a direct, generated answer from the expert',
+                        },
+                    ],
+                    default: 'search',
+                    required: true,
+                    description: 'Choose the operation to perform',
+                },
+                {
+                    displayName: 'Query',
+                    name: 'query',
+                    type: 'string',
+                    default: '',
+                    required: true,
+                    displayOptions: {
+                        hide: {
+                            operation: ['listExperts'],
+                        },
+                    },
+                    placeholder: 'What are the key features of the product?',
+                    description: 'The natural language question to ask your data',
+                    typeOptions: {
+                        rows: 4,
+                    },
+                },
+                {
+                    displayName: 'Additional Options',
+                    name: 'additionalOptions',
+                    type: 'collection',
+                    placeholder: 'Add Option',
+                    default: {},
+                    displayOptions: {
+                        show: {
+                            operation: ['search'],
+                        },
+                    },
+                    options: [
+                        {
+                            displayName: 'Modified Date Start',
+                            name: 'modified_date_start',
+                            type: 'dateTime',
+                            default: '',
+                            description: 'Filter results from files modified on or after this date',
+                        },
+                        {
+                            displayName: 'Modified Date End',
+                            name: 'modified_date_end',
+                            type: 'dateTime',
+                            default: '',
+                            description: 'Filter results from files modified up to this date',
+                        },
+                        {
+                            displayName: 'Number of Results (k)',
+                            name: 'k',
+                            type: 'number',
+                            default: 5,
+                            description: 'Number of text chunks to fetch (top-k)',
+                            typeOptions: {
+                                minValue: 1,
+                                maxValue: 50,
+                            },
+                        },
+                        {
+                            displayName: 'Window Size',
+                            name: 'window_size',
+                            type: 'number',
+                            default: 2,
+                            description: 'Context window size around matches (in KB)',
+                            typeOptions: {
+                                minValue: 1,
+                                maxValue: 10,
+                            },
+                        },
+                    ],
+                },
+            ],
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const returnData = [];
+        const credentials = await this.getCredentials('cteraAiMcpApi');
+        const bearerToken = credentials.bearerToken;
+        const allowUnauthorizedCerts = credentials.allowUnauthorizedCerts;
+        const mcpServerUrl = credentials.serverUrl.replace(/\/$/, ''); // Remove trailing slash
+        for (let i = 0; i < items.length; i++) {
+            try {
+                const operation = this.getNodeParameter('operation', i);
+                let toolName;
+                let serverUrl;
+                const params = {};
+                // Determine tool name, server URL, and parameters based on operation
+                if (operation === 'listExperts') {
+                    toolName = 'ctera_list_experts';
+                    serverUrl = `${mcpServerUrl}/mcp-bearer`;
+                    // No parameters needed
+                }
+                else if (operation === 'search') {
+                    toolName = 'expert_semantic_search';
+                    serverUrl = this.getNodeParameter('expertEndpointUrl', i);
+                    const query = this.getNodeParameter('query', i);
+                    const additionalOptions = this.getNodeParameter('additionalOptions', i, {});
+                    params.query = query;
+                    if (additionalOptions.modified_date_start) {
+                        params.modified_date_start = new Date(additionalOptions.modified_date_start).toISOString();
+                    }
+                    if (additionalOptions.modified_date_end) {
+                        params.modified_date_end = new Date(additionalOptions.modified_date_end).toISOString();
+                    }
+                    if (additionalOptions.k) {
+                        params.k = additionalOptions.k;
+                    }
+                    if (additionalOptions.window_size) {
+                        params.window_size = additionalOptions.window_size;
+                    }
+                }
+                else if (operation === 'chat') {
+                    toolName = 'expert_chat';
+                    serverUrl = this.getNodeParameter('expertEndpointUrl', i);
+                    const query = this.getNodeParameter('query', i);
+                    params.message = query;
+                }
+                else {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Unknown operation: ${operation}`, {
+                        itemIndex: i,
+                    });
+                }
+                // Construct the JSON-RPC payload
+                const requestBody = {
+                    jsonrpc: '2.0',
+                    method: 'tools/call',
+                    params: {
+                        name: toolName,
+                        arguments: params,
+                    },
+                    id: i + 1,
+                };
+                // Make the HTTP request
+                const response = await this.helpers.httpRequest({
+                    method: 'POST',
+                    url: serverUrl,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Authorization': `Bearer ${bearerToken}`,
+                    },
+                    body: requestBody,
+                    json: true,
+                    skipSslCertificateValidation: allowUnauthorizedCerts,
+                });
+                // Handle MCP error responses
+                if (response.error) {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `MCP Error: ${response.error.message || JSON.stringify(response.error)}`, { itemIndex: i });
+                }
+                // Parse the result from MCP response
+                let result;
+                if (response.result && response.result.content) {
+                    // MCP returns content array
+                    const content = response.result.content[0];
+                    if (content && content.type === 'text') {
+                        try {
+                            // Try to parse as JSON if it looks like JSON
+                            result = JSON.parse(content.text);
+                        }
+                        catch {
+                            // If not JSON, return as text
+                            result = content.text;
+                        }
+                    }
+                    else {
+                        result = content;
+                    }
+                }
+                else {
+                    result = response.result;
+                }
+                returnData.push({
+                    json: {
+                        operation,
+                        toolName,
+                        result,
+                        ...items[i].json,
+                    },
+                    pairedItem: { item: i },
+                });
+            }
+            catch (error) {
+                if (this.continueOnFail()) {
+                    returnData.push({
+                        json: {
+                            error: error.message,
+                            ...items[i].json,
+                        },
+                        pairedItem: { item: i },
+                    });
+                    continue;
+                }
+                throw error;
+            }
+        }
+        return [returnData];
+    }
+}
+exports.CteraAi = CteraAi;

package/dist/nodes/CteraAi/ctera.svg

@@ -0,0 +1,13 @@
+<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <g clip-path="url(#ub91fxv4ea)" transform="scale(1.15) translate(-1.8, -1.8)">
+        <path d="M20 0H4a4 4 0 0 0-4 4v16a4 4 0 0 0 4 4h16a4 4 0 0 0 4-4V4a4 4 0 0 0-4-4z" fill="#4F5CE5"/>
+        <path d="M20.373 15.297a8.941 8.941 0 0 1-2.01 3.066A8.98 8.98 0 0 1 12 21a8.883 8.883 0 0 1-3.297-.627 8.942 8.942 0 0 1-3.066-2.01A8.981 8.981 0 0 1 3 12c0-1.163.22-2.277.627-3.297a8.943 8.943 0 0 1 2.01-3.066A8.982 8.982 0 0 1 12 3c1.163 0 2.277.22 3.297.627a8.943 8.943 0 0 1 3.066 2.01l-1.65 1.65A6.668 6.668 0 0 0 12 5.333a6.663 6.663 0 0 0-4.713 1.953A6.668 6.668 0 0 0 5.333 12a6.664 6.664 0 0 0 1.953 4.713A6.668 6.668 0 0 0 12 18.667a6.662 6.662 0 0 0 4.713-1.953 6.667 6.667 0 0 0 1.49-2.27l2.17.853z" fill="#fff" stroke="#4F5CE5" stroke-width=".667" stroke-miterlimit="10"/>
+        <path d="M18.203 14.443a6.668 6.668 0 0 1-3.543 3.67 6.608 6.608 0 0 1-2.66.554 6.669 6.669 0 0 1-6.113-4.007A6.607 6.607 0 0 1 5.333 12 6.668 6.668 0 0 1 9.34 5.887 6.607 6.607 0 0 1 12 5.333a6.667 6.667 0 0 1 4.713 1.953L14.71 9.29A3.818 3.818 0 0 0 12 8.167c-.543 0-1.06.113-1.53.316A3.85 3.85 0 0 0 8.167 12c0 .543.113 1.06.316 1.53a3.847 3.847 0 0 0 5.047 1.987 3.848 3.848 0 0 0 2.037-2.114l2.636 1.04z" fill="#fff" stroke="#4F5CE5" stroke-width=".667" stroke-miterlimit="10"/>
+        <path d="M13.874 12c0 .13-.08.247-.204.292l-1.006.372-.37 1.007a.31.31 0 0 1-.584 0l-.373-1.007-1.007-.371a.31.31 0 0 1 0-.583l1.007-.373.37-1.008a.31.31 0 0 1 .584 0l.373 1.008 1.007.37a.308.308 0 0 1 .203.293z" fill="#fff"/>
+    </g>
+    <defs>
+        <clipPath id="ub91fxv4ea">
+            <path fill="#fff" d="M0 0h24v24H0z"/>
+        </clipPath>
+    </defs>
+</svg>

package/index.js

@@ -0,0 +1,10 @@
+module.exports = {
+	...require('./dist/nodes/CteraAi/CteraAi.node'),
+	...require('./dist/credentials/CteraAiMcpApi.credentials'),
+};
+
+
+
+
+
+

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@ctera/n8n-nodes-ctera-ai",
+  "version": "0.1.0",
+  "description": "n8n community node for CTERA AI MCP integration - enables semantic search, chat, and expert discovery",
+  "keywords": [
+    "n8n-community-node-package",
+    "n8n",
+    "ctera",
+    "ai",
+    "mcp",
+    "rag"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/ctera/ctera-n8n-nodes",
+  "author": {
+    "name": "CTERA Networks",
+    "email": "support@ctera.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ctera/ctera-n8n-nodes.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.js",
+  "scripts": {
+    "build": "tsc && gulp build:icons",
+    "dev": "tsc --watch",
+    "format": "prettier nodes credentials --write",
+    "lint": "eslint 'nodes/**/*.ts' 'credentials/**/*.ts' package.json",
+    "lintfix": "eslint 'nodes/**/*.ts' 'credentials/**/*.ts' package.json --fix",
+    "prepublishOnly": "npm run build && npm run lint"
+  },
+  "files": [
+    "dist"
+  ],
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": [
+      "dist/credentials/CteraAiMcpApi.credentials.js"
+    ],
+    "nodes": [
+      "dist/nodes/CteraAi/CteraAi.node.js"
+    ]
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^5.62.0",
+    "@typescript-eslint/parser": "^5.59.0",
+    "eslint": "^8.40.0",
+    "eslint-plugin-n8n-nodes-base": "^1.12.0",
+    "gulp": "^5.0.1",
+    "n8n-workflow": "^1.0.0",
+    "prettier": "^2.8.8",
+    "typescript": "^5.0.4"
+  },
+  "peerDependencies": {
+    "n8n-workflow": "^1.0.0"
+  }
+}