n8n-nodes-clientify 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Clientify
+
+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,378 @@
+# n8n-nodes-clientify
+
+[![npm version](https://badge.fury.io/js/n8n-nodes-clientify.svg)](https://www.npmjs.com/package/n8n-nodes-clientify)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+N8N community node for integrating with Clientify CRM via Model Context Protocol (MCP). This node provides seamless access to all Clientify CRM operations including contacts, companies, deals, tasks, and more.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Prerequisites](#prerequisites)
+- [Configuration](#configuration)
+- [Available Operations](#available-operations)
+- [Usage Examples](#usage-examples)
+- [Troubleshooting](#troubleshooting)
+- [Support](#support)
+- [License](#license)
+
+## Installation
+
+### In n8n (GUI)
+
+1. Go to **Settings** → **Community Nodes**
+2. Click **Install**
+3. Enter: `n8n-nodes-clientify`
+4. Click **I understand the risks** and then **Install**
+5. **Restart n8n** (important - the node won't appear until you restart)
+
+### Via npm (Command Line)
+
+```bash
+cd ~/.n8n/nodes
+npm install n8n-nodes-clientify
+# Restart n8n
+```
+
+### Docker
+
+If running n8n in Docker, ensure you persist the nodes directory:
+
+```yaml
+volumes:
+  - n8n_data:/home/node/.n8n
+```
+
+Or enable auto-reinstall on restart:
+
+```yaml
+environment:
+  - N8N_REINSTALL_MISSING_PACKAGES=true
+```
+
+## Prerequisites
+
+- **n8n version:** 0.180.0 or higher
+- **Node.js version:** 20.15 or higher
+- **Clientify Account:** Active Clientify CRM account with API access
+- **Authentication Token:** JWT token from Clientify MCP server
+
+## Configuration
+
+### Step 1: Obtain Your Clientify MCP Token
+
+1. Log into your Clientify account
+2. Navigate to API settings or contact your Clientify administrator
+3. Generate or copy your MCP authentication token (JWT format)
+
+### Step 2: Add Credentials in n8n
+
+1. In n8n, go to **Credentials** → **New**
+2. Search for **"Clientify MCP API"**
+3. Enter your **Authentication Token** (JWT)
+4. Click **Save**
+
+### Step 3: Use the Node
+
+1. In your workflow, click **+** to add a node
+2. Search for **"Clientify"**
+3. Select the **Clientify** node
+4. Choose your saved credentials
+5. Select an operation from the dropdown
+6. Configure the parameters for your operation
+
+## Available Operations
+
+This node dynamically supports **26 operations** from the Clientify MCP API:
+
+### 📊 Companies
+- **List Companies** - Retrieve all companies with pagination
+- **Get Company** - Get detailed information for a specific company by ID
+- **Create Company** - Create a new company in the CRM
+- **Update Company** - Update an existing company
+- **Delete Company** - Remove a company from the CRM
+- **Search Companies** - Search for companies by criteria
+
+### 👥 Contacts
+- **List Contacts** - Retrieve all contacts or search for specific contacts
+- **Get Contact** - Get detailed information for a specific contact by ID
+- **Create Contact** - Create a new contact in the CRM
+- **Update Contact** - Update an existing contact
+- **Delete Contact** - Remove a contact from the CRM
+
+### 💼 Deals
+- **List Deals** - Retrieve all deals with filtering and pagination
+- **List Deals By Stage** - Filter deals by pipeline stage
+- **Get Deal** - Get detailed information for a specific deal by ID
+- **Create Deal** - Create a new deal/opportunity
+- **Update Deal** - Update an existing deal
+- **Delete Deal** - Remove a deal from the CRM
+- **Mark Deal Won** - Mark a deal as won/closed successfully
+- **Mark Deal Lost** - Mark a deal as lost/closed unsuccessfully
+
+### ✅ Tasks
+- **List Tasks** - Retrieve all tasks with pagination
+- **Get Task** - Get detailed information for a specific task by ID
+- **Create Task** - Create a new task/activity
+- **List Activity Types** - Get available activity types for tasks
+
+### ⚙️ Configuration & Utilities
+- **List Pipelines** - Retrieve all available sales pipelines
+- **Get Current User** - Get information about the authenticated user
+- **Get Current Time** - Get current date/time with timezone awareness
+
+## Usage Examples
+
+### Example 1: List All Contacts
+
+Retrieve a paginated list of all contacts in your CRM.
+
+**Configuration:**
+- **Operation:** `List Contacts`
+- **Parameters:** Leave empty for all contacts, or add filters
+
+**Output:** Array of contact objects with names, emails, phone numbers, and IDs.
+
+```json
+[
+  {
+    "id": 123,
+    "first_name": "John",
+    "last_name": "Doe",
+    "email": "john.doe@example.com",
+    "phone": "+1234567890",
+    "company_id": 456
+  }
+]
+```
+
+---
+
+### Example 2: Create a New Company
+
+Add a new company to your Clientify CRM.
+
+**Configuration:**
+- **Operation:** `Create Company`
+- **Parameters:**
+  - **name** (required): `Acme Corporation`
+  - **domain**: `acme.com`
+  - **industry**: `Technology`
+  - **description**: `Leading software provider`
+
+**Output:** Created company object with assigned ID.
+
+```json
+{
+  "id": 789,
+  "name": "Acme Corporation",
+  "domain": "acme.com",
+  "industry": "Technology",
+  "created_at": "2025-10-01T12:00:00Z"
+}
+```
+
+---
+
+### Example 3: Update a Deal and Mark as Won
+
+Update deal details and mark it as successfully closed.
+
+**Workflow:**
+1. **First Node:** Get the deal you want to update
+   - **Operation:** `Get Deal`
+   - **deal_id:** `{{$json.deal_id}}`
+
+2. **Second Node:** Update the deal
+   - **Operation:** `Update Deal`
+   - **deal_id:** `{{$json.id}}`
+   - **value:** `50000`
+   - **notes:** `Final negotiations completed`
+
+3. **Third Node:** Mark as won
+   - **Operation:** `Mark Deal Won`
+   - **deal_id:** `{{$json.id}}`
+
+---
+
+### Example 4: Search Companies and Create Contacts
+
+Find a company by name and create a new contact associated with it.
+
+**Workflow:**
+1. **Search Companies:**
+   - **Operation:** `Search Companies`
+   - **query:** `Acme`
+
+2. **Create Contact:**
+   - **Operation:** `Create Contact`
+   - **first_name:** `Jane`
+   - **last_name:** `Smith`
+   - **email:** `jane.smith@acme.com`
+   - **company_id:** `{{$json.id}}` (from previous node)
+
+---
+
+### Example 5: List All Deals in a Specific Pipeline Stage
+
+Retrieve deals that are in the "Negotiation" stage.
+
+**Configuration:**
+- **Operation:** `List Deals By Stage`
+- **Parameters:**
+  - **stage:** `Negotiation`
+
+**Use Case:** Create automated alerts when deals reach certain stages, or generate reports on pipeline health.
+
+---
+
+## Troubleshooting
+
+### Node Doesn't Appear After Installation
+
+**Problem:** The Clientify node doesn't show up in the node panel after installing.
+
+**Solution:**
+1. **Restart n8n completely** (required for community nodes)
+2. Clear your browser cache (Ctrl+Shift+Delete or Cmd+Shift+Delete)
+3. Search for "Clientify" (not the package name) in the node search
+4. Verify installation in **Settings → Community Nodes**
+
+### Authentication Errors
+
+**Problem:** "Authentication failed" or 401/403 errors.
+
+**Solution:**
+1. Verify your JWT token is valid and not expired
+2. Check that the token has the correct permissions in Clientify
+3. Ensure you're using the Clientify MCP token (not a regular API key)
+4. Try creating a new credential with a fresh token
+
+### "Missing required parameter" Errors
+
+**Problem:** Operation fails with missing parameter errors.
+
+**Solution:**
+1. Check which fields are marked as **required** (indicated by red asterisk)
+2. Some operations require specific IDs (contact_id, company_id, etc.)
+3. Use `Get` operations first to retrieve IDs, then pass them to `Update` or `Delete` operations
+4. Review the parameter descriptions for expected format
+
+### Operations Return Empty Results
+
+**Problem:** List operations return no results even though data exists.
+
+**Solution:**
+1. Check pagination parameters (page, page_size)
+2. Verify your token has permission to access the requested resources
+3. Try without filters first to confirm data access
+4. Check the Clientify web UI to confirm data exists
+
+### Node Execution Fails in Docker
+
+**Problem:** Node fails with "package not found" errors in Docker environments.
+
+**Solution:**
+1. Ensure community nodes directory is persisted in volumes:
+   ```yaml
+   volumes:
+     - n8n_data:/home/node/.n8n
+   ```
+2. Or enable auto-reinstall:
+   ```yaml
+   environment:
+     - N8N_REINSTALL_MISSING_PACKAGES=true
+   ```
+3. Restart the container after installing the node
+
+### Rate Limiting Errors
+
+**Problem:** "Too many requests" or 429 errors.
+
+**Solution:**
+1. Add delay between operations using n8n's **Wait** node
+2. Reduce the frequency of scheduled workflows
+3. Batch operations where possible
+4. Contact Clientify support to increase rate limits if needed
+
+## Parameter Reference
+
+### Common Parameters
+
+Most operations support these common parameters:
+
+- **page** (number): Page number for pagination (default: 1)
+- **page_size** (number): Number of results per page (default: 20, max: 100)
+- **sort_by** (string): Field to sort by (e.g., "created_at", "name")
+- **sort_order** (string): Sort direction ("asc" or "desc")
+
+### ID Parameters
+
+Operations that work with specific records require an ID parameter:
+
+- **company_id** (number): Unique identifier for a company
+- **contact_id** (number): Unique identifier for a contact
+- **deal_id** (number): Unique identifier for a deal
+- **task_id** (number): Unique identifier for a task
+
+## Advanced Usage
+
+### Combining Multiple Operations
+
+Create powerful workflows by chaining operations:
+
+```
+Trigger → Search Companies → Create Contact → Create Deal → Create Task
+```
+
+### Error Handling
+
+Use n8n's built-in error handling:
+
+1. Enable **"Continue On Fail"** in node settings
+2. Add an **IF** node to check for errors
+3. Route errors to notification nodes (Email, Slack, etc.)
+
+### Data Transformation
+
+Use n8n's **Code** or **Function** nodes to transform data between operations:
+
+```
+List Contacts → Code Node (transform) → External API
+```
+
+## Development & Contribution
+
+This is a community-maintained node. Contributions are welcome!
+
+**Repository:** https://github.com/contacteitor/clientify_ai
+
+**Report Issues:** https://github.com/contacteitor/clientify_ai/issues
+
+**Documentation:** See the `/n8n` directory in the repository
+
+## Support
+
+- **Issues & Bugs:** https://github.com/contacteitor/clientify_ai/issues
+- **Email:** sebastianonearth@gmail.com
+- **Clientify Documentation:** https://mcp.clientify.com/docs
+
+## Version History
+
+- **v0.1.0** (2025-10-01): Initial release
+  - 26 MCP operations supported
+  - Dynamic field generation from MCP API
+  - Full CRUD operations for contacts, companies, deals, tasks
+  - Pipeline and user management
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+Copyright (c) 2025 Clientify
+
+---
+
+**Made with ❤️ for the n8n community**
+
+*This is an unofficial community node. Clientify and n8n are trademarks of their respective owners.*

package/dist/credentials/ClientifyMcpApi.credentials.d.ts

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

package/dist/credentials/ClientifyMcpApi.credentials.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientifyMcpApi = void 0;
+class ClientifyMcpApi {
+    constructor() {
+        this.name = 'clientifyMcpApi';
+        this.displayName = 'Clientify MCP API';
+        this.documentationUrl = 'https://mcp.clientify.com/docs';
+        this.properties = [
+            {
+                displayName: 'Authentication Token',
+                name: 'authToken',
+                type: 'string',
+                typeOptions: {
+                    password: true,
+                },
+                default: '',
+                required: true,
+                placeholder: 'Enter your JWT token',
+                description: 'The x-end-user-token for authentication with Clientify MCP server',
+            },
+        ];
+    }
+}
+exports.ClientifyMcpApi = ClientifyMcpApi;

package/dist/nodes/ClientifyMcp/ClientifyMcpDynamic.node.d.ts

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

package/dist/nodes/ClientifyMcp/ClientifyMcpDynamic.node.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientifyMcpDynamic = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+const ClientifyMcpFields_1 = require("./ClientifyMcpFields");
+class ClientifyMcpDynamic {
+    constructor() {
+        this.description = {
+            displayName: 'Clientify',
+            name: 'clientifyMcpDynamic',
+            icon: 'file:clientify.svg',
+            group: ['transform'],
+            version: 1,
+            subtitle: '={{$parameter["tool"]}}',
+            description: 'Connect to Clientify CRM via MCP',
+            defaults: {
+                name: 'Clientify',
+            },
+            inputs: ["main" /* NodeConnectionType.Main */],
+            outputs: ["main" /* NodeConnectionType.Main */],
+            credentials: [
+                {
+                    name: 'clientifyMcpApi',
+                    required: true,
+                },
+            ],
+            properties: (() => {
+                const props = [
+                    {
+                        displayName: 'Tool',
+                        name: 'tool',
+                        type: 'options',
+                        options: ClientifyMcpFields_1.toolOptions,
+                        default: 'listContacts',
+                        required: true,
+                        description: 'Select the MCP tool to execute',
+                    },
+                    ...ClientifyMcpFields_1.toolFields,
+                ];
+                // Add additional fields for each tool
+                for (const toolOption of ClientifyMcpFields_1.toolOptions) {
+                    const additionalField = (0, ClientifyMcpFields_1.getAdditionalFieldsForTool)(toolOption.value);
+                    if (additionalField) {
+                        props.push(additionalField);
+                    }
+                }
+                return props;
+            })(),
+        };
+    }
+    async execute() {
+        var _a, _b, _c, _d, _e, _f;
+        const items = this.getInputData();
+        const returnData = [];
+        // Get credentials
+        const credentials = await this.getCredentials('clientifyMcpApi');
+        const authToken = credentials.authToken;
+        // MCP Server URL is fixed
+        const mcpUrl = 'https://mcp.clientify.com/mcp';
+        for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
+            try {
+                const toolName = this.getNodeParameter('tool', itemIndex);
+                // Build tool arguments from individual fields
+                const toolArguments = {};
+                // Process regular fields
+                for (const field of ClientifyMcpFields_1.toolFields) {
+                    const fieldName = field.name;
+                    // Check if this field should be shown for the current tool
+                    if ((_c = (_b = (_a = field.displayOptions) === null || _a === void 0 ? void 0 : _a.show) === null || _b === void 0 ? void 0 : _b.tool) === null || _c === void 0 ? void 0 : _c.includes(toolName)) {
+                        try {
+                            const value = this.getNodeParameter(fieldName, itemIndex);
+                            if (value !== undefined && value !== '' && value !== null) {
+                                toolArguments[fieldName] = value;
+                            }
+                        }
+                        catch (e) {
+                            // Field might not exist for this tool
+                        }
+                    }
+                }
+                // Process additional fields
+                const additionalFieldsParam = `additionalFields`;
+                try {
+                    const additionalFields = this.getNodeParameter(additionalFieldsParam, itemIndex);
+                    if (additionalFields && typeof additionalFields === 'object') {
+                        Object.assign(toolArguments, additionalFields);
+                    }
+                }
+                catch (e) {
+                    // Additional fields might not exist for this tool
+                }
+                // Step 1: Initialize session
+                const initRequest = {
+                    jsonrpc: '2.0',
+                    id: 1,
+                    method: 'initialize',
+                    params: {
+                        protocolVersion: '2024-11-05',
+                        capabilities: {}
+                    }
+                };
+                const initOptions = {
+                    method: 'POST',
+                    url: mcpUrl,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'x-end-user-token': authToken,
+                    },
+                    body: initRequest,
+                    json: true,
+                    returnFullResponse: true,
+                };
+                const initResponse = await this.helpers.httpRequest(initOptions);
+                // Extract session ID from headers
+                const sessionId = initResponse.headers['mcp-session-id'] || initResponse.headers['Mcp-Session-Id'];
+                if (!sessionId) {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), 'Failed to get session ID from MCP server');
+                }
+                // Step 2: Execute the selected tool
+                const requestBody = {
+                    jsonrpc: '2.0',
+                    id: 2,
+                    method: 'tools/call',
+                    params: {
+                        name: toolName,
+                        arguments: toolArguments,
+                    }
+                };
+                // Make request with session ID
+                const options = {
+                    method: 'POST',
+                    url: mcpUrl,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'x-end-user-token': authToken,
+                        'Mcp-Session-Id': sessionId,
+                    },
+                    body: requestBody,
+                    json: true,
+                };
+                const response = await this.helpers.httpRequest(options);
+                // Process response
+                if (response.error) {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `MCP Error: ${response.error.message || JSON.stringify(response.error)}`);
+                }
+                // Parse MCP response to make it user-friendly
+                let parsedResult = {};
+                try {
+                    // Check if response has the MCP structure with JSON string
+                    if ((_f = (_e = (_d = response.result) === null || _d === void 0 ? void 0 : _d.content) === null || _e === void 0 ? void 0 : _e[0]) === null || _f === void 0 ? void 0 : _f.text) {
+                        // Parse the JSON string from MCP response
+                        const mcpData = JSON.parse(response.result.content[0].text);
+                        // Return the parsed data directly - clean and accessible
+                        parsedResult = mcpData;
+                        // Add helpful boolean flags for common checks (generic, works for any response)
+                        if (typeof mcpData === 'object' && mcpData !== null) {
+                            // If there's a count field, add a boolean for it
+                            if ('count' in mcpData) {
+                                parsedResult._hasResults = mcpData.count > 0;
+                            }
+                            // If there's a results array, add a boolean for it
+                            if (Array.isArray(mcpData.results)) {
+                                parsedResult._hasResults = mcpData.results.length > 0;
+                                parsedResult._resultCount = mcpData.results.length;
+                            }
+                            // If there's a success field, expose it clearly
+                            if ('success' in mcpData) {
+                                parsedResult._success = mcpData.success;
+                            }
+                            // If there's an error field, expose it clearly
+                            if ('error' in mcpData) {
+                                parsedResult._hasError = true;
+                                parsedResult._error = mcpData.error;
+                            }
+                        }
+                    }
+                    else {
+                        // Not an MCP text response - return as is
+                        parsedResult = response.result || response;
+                    }
+                }
+                catch (parseError) {
+                    // If parsing fails, return original result
+                    parsedResult = response.result || response;
+                }
+                // Return formatted result with both parsed and raw data
+                returnData.push({
+                    json: Object.assign(Object.assign({ success: true, tool: toolName, sessionId: sessionId }, parsedResult), { 
+                        // Keep raw response for advanced users
+                        _raw: response.result || response }),
+                    pairedItem: itemIndex,
+                });
+            }
+            catch (error) {
+                if (this.continueOnFail()) {
+                    returnData.push({
+                        json: {
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        },
+                        pairedItem: itemIndex,
+                    });
+                    continue;
+                }
+                throw error;
+            }
+        }
+        return [returnData];
+    }
+}
+exports.ClientifyMcpDynamic = ClientifyMcpDynamic;

package/dist/nodes/ClientifyMcp/ClientifyMcpFields.d.ts

@@ -0,0 +1,15 @@
+import { INodeProperties } from 'n8n-workflow';
+export declare const toolOptions: ({
+    name: string;
+    value: string;
+    description: string;
+} | {
+    name: string;
+    value: string;
+    description?: undefined;
+})[];
+export declare const toolFields: INodeProperties[];
+export declare const additionalFieldsDefinitions: {
+    [key: string]: INodeProperties[];
+};
+export declare function getAdditionalFieldsForTool(toolName: string): INodeProperties | null;