mcp-zenskar 1.0.12 → 1.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-zenskar",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "Model Context Protocol (MCP) server for Zenskar API - customer management, invoicing, and billing operations",
   "main": "src/server.js",
   "bin": {

package/src/mcp-config.json

@@ -24,7 +24,14 @@
         },
         {
           "name": "search",
-          "description": "General search query (e.g., 'name=john,custom_data.key=john@zenskar.com').",
+          "description": "Advanced key-value search query. Format: 'field=value' or 'field1=value1,field2=value2'. Supports any customer field including nested JSON paths. Examples: 'customer_name=Acme', 'email=john@example.com', 'customer_name=Acme,external_id=EXT-100', 'custom_data.users=abc@dev.in'. String fields use case-insensitive contains matching. Do NOT pass plain text — always use field=value format.",
+          "type": "string",
+          "required": false,
+          "position": "query"
+        },
+        {
+          "name": "search_name_external_id",
+          "description": "Quick relevance-ranked search across customer_name and external_id. Accepts plain text (e.g., 'Acme'). Results are ranked: exact match first, then starts-with, then contains. Simpler alternative to the 'search' parameter when you only need to find customers by name or external ID.",
           "type": "string",
           "required": false,
           "position": "query"
@@ -38,14 +45,14 @@
           "position": "query"
         },
         {
-          "name": "sortKey",
+          "name": "sort_key",
           "description": "Key to sort the results by (e.g., 'id').",
           "type": "string",
           "required": false,
           "position": "query"
         },
         {
-          "name": "sortType",
+          "name": "sort_type",
           "description": "Sort order type (e.g., 'asc' for ascending).",
           "type": "string",
           "required": false,
@@ -108,7 +115,7 @@
           "position": "query"
         },
         {
-          "name": "phoneNumber__ilike",
+          "name": "phone_number__ilike",
           "description": "Case-insensitive partial match for phone number.",
           "type": "string",
           "required": false,
@@ -218,14 +225,14 @@
           "position": "query"
         },
         {
-          "name": "sortKey",
+          "name": "sort_key",
           "description": "Key to sort the results by (e.g., 'id').",
           "type": "string",
           "required": false,
           "position": "query"
         },
         {
-          "name": "sortType",
+          "name": "sort_type",
           "description": "Sort order type (e.g., 'asc').",
           "type": "string",
           "required": false,
@@ -265,14 +272,14 @@
       "description": "Retrieve a paginated list of invoices, with options for filtering by customer, status, amounts, due date, creation date, and related customer/contract details.",
       "args": [
         {
-          "name": "customerId",
+          "name": "customer_id",
           "description": "Filter invoices by a specific customer ID.",
           "type": "string",
           "required": false,
           "position": "query"
         },
         {
-          "name": "customerExternalId",
+          "name": "customer_external_id",
           "description": "Filter invoices by a customer's external ID.",
           "type": "string",
           "required": false,
@@ -317,70 +324,70 @@
           "position": "query"
         },
         {
-          "name": "contractId",
+          "name": "contract_id",
           "description": "Filter by contract ID.",
           "type": "string",
           "required": false,
           "position": "query"
         },
         {
-          "name": "externalId",
+          "name": "external_id",
           "description": "Filter by invoice external ID.",
           "type": "string",
           "required": false,
           "position": "query"
         },
         {
-          "name": "invoiceTotal__gte",
+          "name": "invoice_total__gte",
           "description": "Filter by invoice total greater than or equal to.",
           "type": "number",
           "required": false,
           "position": "query"
         },
         {
-          "name": "invoiceTotal__lte",
+          "name": "invoice_total__lte",
           "description": "Filter by invoice total less than or equal to.",
           "type": "number",
           "required": false,
           "position": "query"
         },
         {
-          "name": "amountDue__gte",
+          "name": "amount_due__gte",
           "description": "Filter by amount due greater than or equal to.",
           "type": "number",
           "required": false,
           "position": "query"
         },
         {
-          "name": "amountDue__lte",
+          "name": "amount_due__lte",
           "description": "Filter by amount due less than or equal to.",
           "type": "number",
           "required": false,
           "position": "query"
         },
         {
-          "name": "dueDate__gte",
+          "name": "due_date__gte",
           "description": "Filter by due date greater than or equal to (ISO 8601).",
           "type": "string",
           "required": false,
           "position": "query"
         },
         {
-          "name": "dueDate__lte",
+          "name": "due_date__lte",
           "description": "Filter by due date less than or equal to (ISO 8601).",
           "type": "string",
           "required": false,
           "position": "query"
         },
         {
-          "name": "createdAt__gte",
+          "name": "created_at__gte",
           "description": "Filter by creation date greater than or equal to (ISO 8601).",
           "type": "string",
           "required": false,
           "position": "query"
         },
         {
-          "name": "createdAt__lte",
+          "name": "created_at__lte",
           "description": "Filter by creation date less than or equal to (ISO 8601).",
           "type": "string",
           "required": false,
@@ -421,7 +428,7 @@
           "position": "path"
         },
         {
-          "name": "customerId",
+          "name": "customer_id",
           "description": "The ID of the customer associated with the invoice (optional).",
           "type": "string",
           "required": false,
@@ -448,7 +455,7 @@
           "position": "path"
         },
         {
-          "name": "contractId",
+          "name": "contract_id",
           "description": "The ID of the contract associated with the invoice.",
           "type": "string",
           "required": true,
@@ -502,7 +509,7 @@
           "position": "query"
         },
         {
-          "name": "customerId",
+          "name": "customer_id",
           "description": "Optional customer ID associated with the invoice.",
           "type": "string",
           "required": false,
@@ -695,7 +702,7 @@
           "position": "query"
         },
         {
-          "name": "sortKey",
+          "name": "sort_key",
           "description": "Key to sort the results by (e.g., 'id').",
           "type": "string",
           "required": false,
@@ -703,7 +710,7 @@
           "position": "query"
         },
         {
-          "name": "sortType",
+          "name": "sort_type",
           "description": "Sort order type (e.g., 'asc').",
           "type": "string",
           "required": false,
@@ -732,7 +739,7 @@
           "position": "query"
         },
         {
-          "name": "createdAt__gte",
+          "name": "created_at__gte",
           "description": "Filter by creation date greater than or equal to (ISO 8601).",
           "type": "string",
           "required": false,
@@ -764,35 +771,35 @@
       "description": "Get billable metric estimates based on the specified criteria.",
       "args": [
         {
-          "name": "aggregateId",
+          "name": "aggregate_id",
           "description": "The ID of the billable metric.",
           "type": "string",
           "required": true,
           "position": "query"
         },
         {
-          "name": "customerId",
+          "name": "customer_id",
           "description": "The ID of the customer.",
           "type": "string",
           "required": true,
           "position": "query"
         },
         {
-          "name": "startDate",
+          "name": "start_date",
           "description": "Start date of the estimate (YYYY-MM-DD).",
           "type": "string",
           "required": true,
           "position": "query"
         },
         {
-          "name": "endDate",
+          "name": "end_date",
           "description": "End date of the estimate (YYYY-MM-DD).",
           "type": "string",
           "required": true,
           "position": "query"
         },
         {
-          "name": "getSingle",
+          "name": "get_single",
           "description": "Whether to get a single estimate (defaults to true).",
           "type": "boolean",
           "required": false,
@@ -840,14 +847,14 @@
           "position": "path"
         },
         {
-          "name": "startDate",
+          "name": "start_date",
           "description": "Start date for filtering logs (YYYY-MM-DD).",
           "type": "string",
           "required": false,
           "position": "query"
         },
         {
-          "name": "endDate",
+          "name": "end_date",
           "description": "End date for filtering logs (YYYY-MM-DD).",
           "type": "string",
           "required": false,
@@ -861,14 +868,14 @@
           "position": "query"
         },
         {
-          "name": "customerId",
+          "name": "customer_id",
           "description": "Filter by customer ID.",
           "type": "string",
           "required": false,
           "position": "query"
         },
         {
-          "name": "queryLimit",
+          "name": "query_limit",
           "description": "Limit the number of log entries (defaults to 100).",
           "type": "integer",
           "required": false,
@@ -911,7 +918,7 @@
           "position": "query"
         },
         {
-          "name": "sortKey",
+          "name": "sort_key",
           "description": "Key to sort the results by (e.g., 'created_at').",
           "type": "string",
           "required": false,
@@ -919,7 +926,7 @@
           "position": "query"
         },
         {
-          "name": "sortType",
+          "name": "sort_type",
           "description": "Sort order type (e.g., 'asc').",
           "type": "string",
           "required": false,
@@ -1212,14 +1219,14 @@
           "position": "query"
         },
         {
-          "name": "sortKey",
+          "name": "sort_key",
           "description": "Key to sort the results by (e.g., 'id').",
           "type": "string",
           "required": false,
           "position": "query"
         },
         {
-          "name": "sortType",
+          "name": "sort_type",
           "description": "Sort order type (e.g., 'asc').",
           "type": "string",
           "required": false,
@@ -1241,28 +1248,28 @@
           "position": "query"
         },
         {
-          "name": "customerId",
+          "name": "customer_id",
           "description": "Filter by customer ID.",
           "type": "string",
           "required": false,
           "position": "query"
         },
         {
-          "name": "connectorId",
+          "name": "connector_id",
           "description": "Filter by connector ID.",
           "type": "string",
           "required": false,
           "position": "query"
         },
         {
-          "name": "externalId__ilike",
+          "name": "external_id__ilike",
           "description": "Case-insensitive partial match for external ID.",
           "type": "string",
           "required": false,
           "position": "query"
         },
         {
-          "name": "paymentMethod",
+          "name": "payment_method",
           "description": "Filter by payment method (e.g., 'card', 'cash', 'bank_transfer').",
           "type": "string",
           "required": false,
@@ -1326,14 +1333,14 @@
           "position": "query"
         },
         {
-          "name": "currencyCode__ilike",
+          "name": "currency_code__ilike",
           "description": "Case-insensitive partial match for currency code.",
           "type": "string",
           "required": false,
           "position": "query"
         },
         {
-          "name": "receiptNumber__ilike",
+          "name": "receipt_number__ilike",
           "description": "Case-insensitive partial match for receipt number.",
           "type": "string",
           "required": false,
@@ -1368,7 +1375,7 @@
           "position": "query"
         },
         {
-          "name": "parentId",
+          "name": "parent_id",
           "description": "Filter by parent payment ID.",
           "type": "string",
           "required": false,
@@ -1389,14 +1396,14 @@
           "position": "query"
         },
         {
-          "name": "createdAt__gte",
+          "name": "created_at__gte",
           "description": "Filter by creation date greater than or equal to (ISO 8601).",
           "type": "string",
           "required": false,
           "position": "query"
         },
         {
-          "name": "createdAt__lte",
+          "name": "created_at__lte",
           "description": "Filter by creation date less than or equal to (ISO 8601).",
           "type": "string",
           "required": false,
@@ -1868,7 +1875,7 @@
           "enum": [
             "Quantity",
             "Feature",
-            "Access"
+            "Credits"
           ]
         },
         {
@@ -2433,9 +2440,9 @@
         },
         {
           "name": "status",
-          "description": "Contract status (defaults to 'draft').",
+          "description": "Contract status (required, typically 'draft' for new contracts).",
           "type": "string",
-          "required": false,
+          "required": true,
           "position": "body",
           "default": "draft",
           "enum": ["draft", "active", "paused", "expired", "disputed"]

package/src/server.js

@@ -409,6 +409,35 @@ async function executeAPICall(tool, args) {
       nestAddress('ship_to_', 'ship_to_address');
     }
 
+    // Same address nesting for createBusinessEntity
+    if (tool.name === 'createBusinessEntity') {
+      const nestAddress = (prefix, targetKey) => {
+        const fieldMap = {
+          [`${prefix}line1`]: 'line1',
+          [`${prefix}line2`]: 'line2',
+          [`${prefix}line3`]: 'line3',
+          [`${prefix}city`]: 'city',
+          [`${prefix}state`]: 'state',
+          [`${prefix}zipCode`]: 'zipCode',
+          [`${prefix}country`]: 'country'
+        };
+        const obj = {};
+        let has = false;
+        Object.entries(fieldMap).forEach(([flatKey, nestedKey]) => {
+          if (bodyParams[flatKey] !== undefined) {
+            obj[nestedKey] = bodyParams[flatKey];
+            delete bodyParams[flatKey];
+            has = true;
+          }
+        });
+        if (has) {
+          bodyParams[targetKey] = obj;
+          logger.debug(`[${tool.name}] Transformed flat ${prefix}* fields into ${targetKey} object`);
+        }
+      };
+      nestAddress('address_', 'address');
+    }
+
     // Smart defaults for helper tools
     if (tool.name === 'extractContractFromRaw') {
       // Auto-populate organization_id from user context or env var if not provided
@@ -447,6 +476,10 @@ async function executeAPICall(tool, args) {
     
     if (Object.keys(bodyParams).length > 0) {
       body = JSON.stringify(bodyParams);
+    } else if (method === 'PATCH' || method === 'POST' || method === 'PUT') {
+      // Always send at least an empty JSON body for non-GET methods
+      // Some endpoints (e.g., approveInvoice) require a body even when no body params are provided
+      body = '{}';
     }
   }
 

package/test-mcp.mjs

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+/**
+ * MCP Server Integration Test
+ * Tests the Zenskar MCP server via the actual MCP protocol (stdio transport).
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const ORG_ID = '888ae523-8878-4ed7-85cc-6c0a54320568';
+const API_KEY = 'sandbox_yA9yieTXSqnGxROOoyLMWIP2CTuCm5j_311CVHu16-U';
+
+const userContext = {
+  organization: ORG_ID,
+  authorization: API_KEY,
+};
+
+let client;
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+async function callTool(name, args = {}) {
+  const result = await client.callTool({
+    name,
+    arguments: { ...args, __userContext: userContext },
+  });
+  // MCP returns content array; extract text
+  const text = result.content?.map(c => c.text).join('') || '';
+  const json = (() => { try { return JSON.parse(text); } catch { return null; } })();
+  return { text, json, raw: result };
+}
+
+async function test(label, fn) {
+  try {
+    await fn();
+    passed++;
+    console.log(`  ✅ ${label}`);
+  } catch (err) {
+    failed++;
+    failures.push({ label, error: err.message || String(err) });
+    console.log(`  ❌ ${label}: ${err.message || err}`);
+  }
+}
+
+function assert(cond, msg) {
+  if (!cond) throw new Error(msg);
+}
+
+// ─── MAIN ────────────────────────────────────────────────────
+async function main() {
+  console.log('Starting MCP server via stdio...\n');
+
+  const transport = new StdioClientTransport({
+    command: 'node',
+    args: ['src/server.js'],
+    env: { ...process.env, ZENSKAR_ORGANIZATION: ORG_ID, ZENSKAR_API_KEY: API_KEY },
+  });
+
+  client = new Client({ name: 'test-client', version: '1.0.0' });
+  await client.connect(transport);
+
+  // List available tools
+  const { tools } = await client.listTools();
+  console.log(`MCP server connected. ${tools.length} tools registered.\n`);
+
+  // ─── CUSTOMERS ──────────────────────────────────────────
+  console.log('── Customers ──');
+
+  let customerId;
+  await test('listCustomers (basic)', async () => {
+    const { json } = await callTool('listCustomers', { limit: 2 });
+    const resp = json?.api_response || json;
+    assert(resp?.results?.length > 0, 'No results returned');
+    assert(resp.total_count > 0, 'total_count missing');
+    customerId = resp.results[0].id;
+  });
+
+  await test('listCustomers (search field=value)', async () => {
+    const { json } = await callTool('listCustomers', { search: 'customer_name=Star' });
+    const resp = json?.api_response || json;
+    assert(resp?.total_count <= 10, `Expected filtered results, got ${resp?.total_count}`);
+  });
+
+  await test('listCustomers (search_name_external_id)', async () => {
+    const { json } = await callTool('listCustomers', { search_name_external_id: 'Star', limit: 5 });
+    const resp = json?.api_response || json;
+    assert(resp?.total_count <= 10, `Expected filtered results, got ${resp?.total_count}`);
+  });
+
+  await test('getCustomerById', async () => {
+    if (!customerId) throw new Error('No customer ID from previous test');
+    const { json } = await callTool('getCustomerById', { customerId });
+    const resp = json?.api_response || json;
+    assert(resp?.id === customerId, 'ID mismatch');
+  });
+
+  // ─── CONTACTS ──────────────────────────────────────────
+  console.log('\n── Contacts ──');
+
+  let contactId;
+  await test('listContacts', async () => {
+    const { json } = await callTool('listContacts', { limit: 2 });
+    const resp = json?.api_response || json;
+    assert(resp?.results?.length > 0, 'No contacts');
+    contactId = resp.results[0].id;
+  });
+
+  await test('getContactById', async () => {
+    if (!contactId) throw new Error('No contact ID');
+    const { json } = await callTool('getContactById', { contactId });
+    const resp = json?.api_response || json;
+    assert(resp?.id === contactId, 'ID mismatch');
+  });
+
+  // ─── INVOICES ──────────────────────────────────────────
+  console.log('\n── Invoices ──');
+
+  let invoiceId;
+  await test('listInvoices (basic)', async () => {
+    const { json } = await callTool('listInvoices', { limit: 2 });
+    const resp = json?.api_response || json;
+    assert(resp?.results?.length > 0, 'No invoices');
+    invoiceId = resp.results[0].id;
+  });
+
+  await test('listInvoices (customer_id filter)', async () => {
+    if (!customerId) throw new Error('No customer ID');
+    const { json } = await callTool('listInvoices', { customer_id: customerId, limit: 1 });
+    const resp = json?.api_response || json;
+    // Should filter (may return 0 if customer has no invoices, but should not error)
+    assert(resp?.total_count !== undefined, 'Missing total_count');
+  });
+
+  await test('listInvoices (invoice_total__gte filter)', async () => {
+    const { json } = await callTool('listInvoices', { invoice_total__gte: 100, limit: 1 });
+    const resp = json?.api_response || json;
+    assert(resp?.total_count !== undefined, 'Missing total_count');
+  });
+
+  await test('getInvoiceById', async () => {
+    if (!invoiceId) throw new Error('No invoice ID');
+    const { json } = await callTool('getInvoiceById', { invoiceId });
+    const resp = json?.api_response || json;
+    assert(resp?.id === invoiceId, 'ID mismatch');
+  });
+
+  await test('getInvoiceLineItems', async () => {
+    if (!invoiceId) throw new Error('No invoice ID');
+    const { json } = await callTool('getInvoiceLineItems', { invoiceId });
+    const resp = json?.api_response || json;
+    assert(resp !== null, 'No response');
+  });
+
+  await test('getInvoiceSummary', async () => {
+    if (!invoiceId) throw new Error('No invoice ID');
+    const { json } = await callTool('getInvoiceSummary', { invoiceId });
+    const resp = json?.api_response || json;
+    assert(resp !== null, 'No response');
+  });
+
+  await test('getAllInvoiceTags', async () => {
+    const { json } = await callTool('getAllInvoiceTags');
+    const resp = json?.api_response || json;
+    assert(resp?.tags, 'No tags returned');
+  });
+
+  // ─── PAYMENTS ──────────────────────────────────────────
+  console.log('\n── Payments ──');
+
+  let paymentId;
+  await test('listAllPayments (basic)', async () => {
+    const { json } = await callTool('listAllPayments', { limit: 2 });
+    const resp = json?.api_response || json;
+    assert(resp?.results?.length > 0, 'No payments');
+    paymentId = resp.results[0].id;
+  });
+
+  await test('listAllPayments (sort_key + payment_method filter)', async () => {
+    const { json } = await callTool('listAllPayments', { sort_key: 'created_at', sort_type: 'DESC', payment_method: 'bank_transfer', limit: 1 });
+    const resp = json?.api_response || json;
+    assert(resp?.total_count !== undefined, 'Missing total_count');
+  });
+
+  await test('getPaymentById', async () => {
+    if (!paymentId) throw new Error('No payment ID');
+    const { json } = await callTool('getPaymentById', { paymentId });
+    const resp = json?.api_response || json;
+    assert(resp?.id === paymentId, 'ID mismatch');
+  });
+
+  // ─── CONTRACTS ──────────────────────────────────────────
+  console.log('\n── Contracts ──');
+
+  await test('listContracts (basic)', async () => {
+    const { json } = await callTool('listContracts', { limit: 2 });
+    const resp = json?.api_response || json;
+    assert(resp?.results?.length > 0, 'No contracts');
+  });
+
+  await test('listContracts (status filter)', async () => {
+    const { json } = await callTool('listContracts', { status: 'active', limit: 1 });
+    const resp = json?.api_response || json;
+    assert(resp?.total_count !== undefined, 'Missing total_count');
+  });
+
+  // ─── AGGREGATES (Billable Metrics) ──────────────────────
+  console.log('\n── Billable Metrics ──');
+
+  let aggregateId;
+  await test('listAggregates', async () => {
+    const { json } = await callTool('listAggregates', { limit: 2 });
+    const resp = json?.api_response || json;
+    assert(resp?.results?.length > 0, 'No aggregates');
+    aggregateId = resp.results[0].id;
+  });
+
+  await test('getAggregateById', async () => {
+    if (!aggregateId) throw new Error('No aggregate ID');
+    const { json } = await callTool('getAggregateById', { aggregateId });
+    const resp = json?.api_response || json;
+    assert(resp?.id === aggregateId, 'ID mismatch');
+  });
+
+  await test('getAggregateSchemas', async () => {
+    const { json } = await callTool('getAggregateSchemas');
+    const resp = json?.api_response || json;
+    assert(Array.isArray(resp), 'Expected array of schemas');
+  });
+
+  await test('getAggregateEstimates (snake_case params)', async () => {
+    if (!aggregateId || !customerId) throw new Error('Missing IDs');
+    // This may return 404 domain error (no data) but should NOT 422
+    try {
+      const { json } = await callTool('getAggregateEstimates', {
+        aggregate_id: aggregateId,
+        customer_id: customerId,
+        start_date: '2025-01-01',
+        end_date: '2025-12-31',
+      });
+      // If we get here, great
+    } catch (e) {
+      // 404 domain error is OK (AGGREGATE_ESTIMATE_NOT_FOUND), 422 is NOT
+      if (e.message?.includes('422')) throw new Error('Got 422 — snake_case params not working');
+    }
+  });
+
+  // ─── RAW METRICS ──────────────────────────────────────
+  console.log('\n── Raw Metrics ──');
+
+  let rawMetricSlug;
+  await test('listRawMetrics', async () => {
+    const { json } = await callTool('listRawMetrics', { limit: 2 });
+    const resp = json?.api_response || json;
+    assert(resp?.results?.length > 0, 'No raw metrics');
+    rawMetricSlug = resp.results[0].api_slug;
+  });
+
+  await test('getRawMetricBySlug', async () => {
+    if (!rawMetricSlug) throw new Error('No slug');
+    const { json } = await callTool('getRawMetricBySlug', { rawMetricSlug });
+    const resp = json?.api_response || json;
+    assert(resp?.api_slug === rawMetricSlug, 'Slug mismatch');
+  });
+
+  // ─── OTHER TOOLS ──────────────────────────────────────
+  console.log('\n── Other Tools ──');
+
+  await test('getCurrentDateTime', async () => {
+    const { json } = await callTool('getCurrentDateTime');
+    const resp = json?.api_response || json;
+    assert(resp?.currentDate || resp?.currentDateTime, 'No date returned');
+  });
+
+  await test('getCustomerPortalConfiguration', async () => {
+    const { json } = await callTool('getCustomerPortalConfiguration');
+    const resp = json?.api_response || json;
+    assert(resp !== null, 'No response');
+  });
+
+  // ─── SUMMARY ──────────────────────────────────────────
+  console.log(`\n${'═'.repeat(50)}`);
+  console.log(`RESULTS: ${passed} passed, ${failed} failed out of ${passed + failed} tests`);
+  if (failures.length > 0) {
+    console.log('\nFailed tests:');
+    failures.forEach(f => console.log(`  ❌ ${f.label}: ${f.error}`));
+  }
+  console.log(`${'═'.repeat(50)}\n`);
+
+  await client.close();
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+main().catch(err => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});