mcp-zenskar 1.1.8 → 1.1.9

package/README.md

@@ -8,7 +8,7 @@ MCP server for the Zenskar API. 103 tools covering customers, contracts, invoice
 - Contracts: create, read, update, delete, amend, add phases and pricing, expire
 - Invoices: list, get, approve, void, generate, credit notes, download
 - Payments: create, edit, refund, delete, auto-charge
-- Credit notes: list, create (standalone or against invoice), get by ID
+- Credit notes: list, create against invoice, get by ID
 - Accounting: chart of accounts, journal entries and lines, balance sheet, income statement, account balances
 - Products: CRUD, pricing configurations
 - Plans: list, create, add products, preview estimates
@@ -124,9 +124,9 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 | `getInvoiceGenerationStatus` | Check invoice generation status |
 | `downloadInvoice` | Download invoice in JSON format |
 | `getInvoiceContractJsonActuals` | Get contract actuals for an invoice |
-| `getInvoicePayments` | Get payments for an invoice |
-| `getInvoicePaymentsById` | Get a specific payment on an invoice |
-| `getInvoicePaymentsWithoutRefunds` | Get invoice payments excluding refunds |
+| `getInvoicePayments` | Get successful payments currently mapped to an invoice |
+| `getInvoicePaymentsById` | Get successful payments for a specific invoice ID |
+| `getInvoicePaymentsWithoutRefunds` | Get original payment records for an invoice, excluding refund payment rows |
 | `getInvoiceLineItems` | Get invoice line items and pricing details |
 | `getInvoiceSummary` | Get invoice summary |
 | `getAllInvoiceTags` | Get all available invoice tags |
@@ -141,10 +141,10 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 ### Payments
 | Tool | Description |
 |---|---|
-| `listAllPayments` | List all payments with filtering and sorting |
+| `listAllPayments` | List all payments with filtering and sorting, including refund records |
 | `getPaymentById` | Get a payment by ID |
 | `createPayment` | Record a payment against an invoice |
-| `updatePayment` | Update a payment's status or details |
+| `updatePayment` | Update a payment's invoice allocations (`payment_parts`) |
 | `deleteManualPayment` | Delete a manual payment |
 | `editManualPayment` | Edit a manual payment's amount or method |
 | `refundPayment` | Refund a payment (full or partial) |
@@ -154,7 +154,6 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 |---|---|
 | `listCreditNotes` | List credit notes with pagination |
 | `getCreditNoteById` | Get a credit note by ID |
-| `createCreditNote` | Create a standalone credit note |
 
 ### Products and Pricing
 | Tool | Description |
@@ -232,16 +231,16 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 ### Metrics and Usage Events
 | Tool | Description |
 |---|---|
-| `listAggregates` | List billable metrics with filtering |
-| `getAggregateSchemas` | Get all billable metric schemas |
-| `getAggregateEstimates` | Get billable metric estimates |
-| `getAggregateById` | Get a billable metric by ID |
-| `getAggregateLogs` | Get logs for a billable metric |
-| `listRawMetrics` | List usage events with filtering |
-| `createRawMetric` | Create a usage event schema |
-| `getRawMetricById` | Get a usage event by ID |
-| `getRawMetricLogs` | Get logs for a usage event |
-| `getRawMetricBySlug` | Get a usage event by API slug |
+| `listAggregates` | List Billable Metrics with filtering; backend/API may also call these aggregates |
+| `getAggregateSchemas` | Show the underlying schemas for Billable Metrics (Aggregates); mainly useful for debugging or integration work |
+| `getAggregateEstimates` | Get Billable Metric estimates; backend/API may also call these aggregates |
+| `getAggregateById` | Get a Billable Metric by ID; backend/API may also call it an aggregate |
+| `getAggregateLogs` | Get logs for a Billable Metric (Aggregate) |
+| `listRawMetrics` | List Usage Events with filtering; backend/API may also call these raw metrics |
+| `createRawMetric` | Create a Usage Event schema; backend/API calls this a raw metric |
+| `getRawMetricById` | Get a Usage Event by ID; backend/API may also call it a raw metric |
+| `getRawMetricLogs` | Get logs for a Usage Event (raw metric) |
+| `getRawMetricBySlug` | Get a Usage Event by API slug; backend/API may also call it a raw metric |
 | `ingestRawMetricEvent` | Ingest a usage event |
 
 ### Other

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-zenskar",
-  "version": "1.1.8",
+  "version": "1.1.9",
   "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

@@ -539,7 +539,7 @@
     },
     {
       "name": "getInvoicePayments",
-      "description": "Get payments associated with a specific invoice.",
+      "description": "Get successful payments currently associated with a specific invoice. This view may omit refund records and non-success payment states.",
       "args": [
         {
           "name": "invoiceId",
@@ -670,7 +670,7 @@
     },
     {
       "name": "listAggregates",
-      "description": "Get billable metrics in paginated form with options for filtering by ID, name, and data source.",
+      "description": "List Billable Metrics (also called aggregates in backend/API terminology) in paginated form, with filtering by ID, name, and data source.",
       "args": [
         {
           "name": "cursor",
@@ -744,28 +744,28 @@
         "method": "GET"
       },
       "responseTemplate": {
-        "prependBody": "## Billable Metrics List\n\nHere is the list of billable metrics:\n\n"
+        "prependBody": "## Billable Metrics (Aggregates)\n\nHere is the list of billable metrics. Backend/API terminology may also call these aggregates:\n\n"
       }
     },
     {
       "name": "getAggregateSchemas",
-      "description": "Get all billable metric schemas belonging to an organization.",
+      "description": "Show the underlying storage/schema definitions for Billable Metrics (also called aggregates). Mainly useful for advanced debugging, SQL/schema inspection, and integration work rather than day-to-day business operations.",
       "args": [],
       "requestTemplate": {
         "url": "/aggregates/tables/schema",
         "method": "GET"
       },
       "responseTemplate": {
-        "prependBody": "## Billable Metric Schemas\n\nHere are the schemas for billable metrics:\n\n"
+        "prependBody": "## Billable Metric Schemas\n\nHere are the underlying schemas for billable metrics (aggregates):\n\n"
       }
     },
     {
       "name": "getAggregateEstimates",
-      "description": "Get billable metric estimates based on the specified criteria.",
+      "description": "Get Billable Metric estimates based on the specified criteria. Backend/API terminology may also call a billable metric an aggregate.",
       "args": [
         {
           "name": "aggregate_id",
-          "description": "The ID of the billable metric.",
+          "description": "The ID of the Billable Metric (aggregate).",
           "type": "string",
           "required": true,
           "position": "query"
@@ -805,16 +805,16 @@
         "method": "GET"
       },
       "responseTemplate": {
-        "prependBody": "## Billable Metric Estimates\n\nHere are the estimates for the billable metric:\n\n"
+        "prependBody": "## Billable Metric Estimates\n\nHere are the estimates for the Billable Metric (aggregate):\n\n"
       }
     },
     {
       "name": "getAggregateById",
-      "description": "Get the details of a billable metric by its ID.",
+      "description": "Get the details of a Billable Metric by its ID. Backend/API terminology may also call this an aggregate.",
       "args": [
         {
           "name": "aggregateId",
-          "description": "The ID of the billable metric.",
+          "description": "The ID of the Billable Metric (aggregate).",
           "type": "string",
           "required": true,
           "position": "path"
@@ -825,16 +825,16 @@
         "method": "GET"
       },
       "responseTemplate": {
-        "prependBody": "## Billable Metric Details\n\nHere are the details for the specified billable metric:\n\n"
+        "prependBody": "## Billable Metric Details\n\nHere are the details for the specified Billable Metric (aggregate):\n\n"
       }
     },
     {
       "name": "getAggregateLogs",
-      "description": "Get the logs related to a billable metric by its ID, with optional date and customer filters.",
+      "description": "Get logs related to a Billable Metric (also called an aggregate) by ID, with optional date and customer filters.",
       "args": [
         {
           "name": "aggregateId",
-          "description": "The ID of the billable metric.",
+          "description": "The ID of the Billable Metric (aggregate).",
           "type": "string",
           "required": true,
           "position": "path"
@@ -881,12 +881,12 @@
         "method": "GET"
       },
       "responseTemplate": {
-        "prependBody": "## Billable Metric Logs\n\nHere are the logs for the specified billable metric:\n\n"
+        "prependBody": "## Billable Metric Logs\n\nHere are the logs for the specified Billable Metric (aggregate):\n\n"
       }
     },
     {
       "name": "listRawMetrics",
-      "description": "Get usage events in paginated form, with options for filtering by ID, name, and API slug.",
+      "description": "List Usage Events. In backend/API terminology these are also called raw metrics. Supports filtering by ID, name, and API slug.",
       "args": [
         {
           "name": "cursor",
@@ -960,18 +960,18 @@
         "method": "GET"
       },
       "responseTemplate": {
-        "prependBody": "## Usage Events List\n\nHere is the list of usage events:\n\n"
+        "prependBody": "## Usage Events\n\nHere is the list of usage events. Backend/API terminology may also call these raw metrics:\n\n"
       }
     },
     {
       "name": "createRawMetric",
-      "description": "Create a new raw metric (usage event schema) with column definitions and connectors.",
+      "description": "Create a new Usage Event schema. In backend/API terminology this resource is called a raw metric. This defines the schema used for ingesting usage events.",
       "needsApproval": true,
       "approvalConfig": {
-        "title": "Create Raw Metric",
-        "description": "This will create a new raw metric and provision its event schema. Please review the payload carefully.",
+        "title": "Create Usage Event Schema",
+        "description": "This will create a new Usage Event schema (called a raw metric in backend/API terminology) and provision its event schema. Please review the payload carefully.",
         "warningText": "Ensure the dataschema and slug values are correct before continuing.",
-        "confirmText": "Create Raw Metric",
+        "confirmText": "Create Usage Event Schema",
         "cancelText": "Cancel",
         "sensitiveFields": [
           "name",
@@ -983,21 +983,21 @@
       "args": [
         {
           "name": "name",
-          "description": "Human-friendly name for the raw metric.",
+          "description": "Human-friendly name for the Usage Event schema (raw metric).",
           "type": "string",
           "required": true,
           "position": "body"
         },
         {
           "name": "api_slug",
-          "description": "API slug used when ingesting events (lowercase, underscores).",
+          "description": "API slug used when ingesting Usage Events (lowercase, underscores).",
           "type": "string",
           "required": true,
           "position": "body"
         },
         {
           "name": "dataschema",
-          "description": "Data schema of raw metric (JSON object). Structure: {\"data\": {custom_fields}, \"timestamp\": \"DateTime64\", \"customer_id\": \"String\"}. The 'data' map must include only valid ClickHouse types (String, Int64, Float64, Date32, DateTime64, UUID, Bool); use 'Bool' instead of 'Boolean'.",
+          "description": "Data schema of the Usage Event resource (called a raw metric in backend/API terminology). Structure: {\"data\": {custom_fields}, \"timestamp\": \"DateTime64\", \"customer_id\": \"String\"}. The 'timestamp' and 'customer_id' fields are mandatory schema fields for usage ingestion. The 'data' map must include only valid ClickHouse types (String, Int64, Float64, Date32, DateTime64, UUID, Bool); use 'Bool' instead of 'Boolean'.",
           "type": "object",
           "required": true,
           "position": "body",
@@ -1035,16 +1035,16 @@
         }
       },
       "responseTemplate": {
-        "prependBody": "## Raw Metric Created\n\nThe raw metric was created successfully:\n\n"
+        "prependBody": "## Usage Event Schema Created\n\nThe Usage Event schema (raw metric) was created successfully:\n\n"
       }
     },
     {
       "name": "getRawMetricById",
-      "description": "Get usage event details by its ID.",
+      "description": "Get Usage Event details by ID. Backend/API terminology may also call this a raw metric.",
       "args": [
         {
           "name": "rawMetricId",
-          "description": "The ID of the raw metric.",
+          "description": "The ID of the Usage Event resource (raw metric).",
           "type": "string",
           "required": true,
           "position": "path"
@@ -1060,11 +1060,11 @@
     },
     {
       "name": "getRawMetricLogs",
-      "description": "Get logs for a specific raw metric by its ID.",
+      "description": "Get Usage Event logs for a specific resource by ID. Backend/API terminology may also call this a raw metric.",
       "args": [
         {
           "name": "rawMetricId",
-          "description": "The ID of the raw metric.",
+          "description": "The ID of the Usage Event resource (raw metric).",
           "type": "string",
           "required": true,
           "position": "path"
@@ -1080,11 +1080,11 @@
     },
     {
       "name": "getRawMetricBySlug",
-      "description": "Get usage event details by its API slug.",
+      "description": "Get Usage Event details by API slug. Backend/API terminology may also call this a raw metric.",
       "args": [
         {
           "name": "rawMetricSlug",
-          "description": "The API slug of the raw metric.",
+          "description": "The API slug of the Usage Event resource (raw metric).",
           "type": "string",
           "required": true,
           "position": "path"
@@ -1100,7 +1100,7 @@
     },
     {
       "name": "getInvoicePaymentsById",
-      "description": "Get payments associated with a specific invoice ID.",
+      "description": "Get successful payments associated with a specific invoice ID. This endpoint is success-only and may not show refund rows.",
       "args": [
         {
           "name": "invoiceId",
@@ -1120,7 +1120,7 @@
     },
     {
       "name": "getInvoicePaymentsWithoutRefunds",
-      "description": "Get payments for an invoice, excluding refunds.",
+      "description": "Get original payment records for an invoice, excluding refund payment rows. Refunded or partially refunded original payments may still appear here.",
       "args": [
         {
           "name": "invoiceId",
@@ -1172,7 +1172,7 @@
     },
     {
       "name": "listAllPayments",
-      "description": "Retrieve a paginated list of all payments, with extensive filtering and sorting options.",
+      "description": "Retrieve a paginated list of all payments, including refund records, with extensive filtering and sorting options.",
       "args": [
         {
           "name": "cursor",
@@ -2268,12 +2268,12 @@
     },
     {
       "name": "ingestRawMetricEvent",
-      "description": "Ingest a usage event for the specified raw metric slug.",
+      "description": "Ingest a Usage Event for the specified resource slug. Backend/API terminology may also call the target resource a raw metric.",
       "needsApproval": true,
       "approvalConfig": {
         "title": "Ingest Usage Event",
-        "description": "This will ingest a usage event for the selected raw metric. Review the payload carefully.",
-        "warningText": "Ensure the data payload matches the raw metric schema before proceeding.",
+        "description": "This will ingest a Usage Event for the selected Usage Event schema (called a raw metric in backend/API terminology). Review the payload carefully.",
+        "warningText": "Ensure the data payload matches the Usage Event schema (raw metric schema) before proceeding.",
         "confirmText": "Ingest Usage Event",
         "cancelText": "Cancel",
         "sensitiveFields": [
@@ -2284,14 +2284,14 @@
       "args": [
         {
           "name": "rawMetricSlug",
-          "description": "Slug of the raw metric (e.g., api_usage_events).",
+          "description": "Slug of the Usage Event resource (raw metric), e.g. api_usage_events.",
           "type": "string",
           "required": true,
           "position": "path"
         },
         {
           "name": "event",
-          "description": "Usage event payload containing customer_id, timestamp, and data map with schema-compliant types. Before constructing the event, fetch the schema via getRawMetricBySlug (or reuse the response from createRawMetric) so you only include fields that exist in the raw metric. Use the provided type buckets such as String/Int64 or the exact column names returned by sample logs; do not invent new keys.",
+          "description": "Usage Event payload containing customer_id, timestamp, and a data map with schema-compliant types. customer_id and timestamp are mandatory event fields and must be provided in the payload; MCP does not auto-add them. Before constructing the event, fetch the schema via getRawMetricBySlug (or reuse the response from createRawMetric) so you only include fields that exist in the Usage Event schema (raw metric schema). Use the provided type buckets such as String/Int64 or the exact column names returned by sample logs; do not invent new keys.",
           "type": "object",
           "required": true,
           "position": "body",
@@ -3108,84 +3108,6 @@
         "prependBody": "## Credit Notes\n\n"
       }
     },
-    {
-      "name": "createCreditNote",
-      "description": "Create a standalone credit note (not tied to a specific invoice). Status enum: in_progress, issued, void, paid. Repayment method enum: credits, invoice_adjusted, external_payment, credits_against_payment, original_payment_method.",
-      "args": [
-        {
-          "name": "amount",
-          "description": "Credit note amount in the specified currency.",
-          "type": "number",
-          "required": true,
-          "position": "body"
-        },
-        {
-          "name": "currency",
-          "description": "Three-letter ISO 4217 currency code (e.g. USD).",
-          "type": "string",
-          "required": true,
-          "position": "body"
-        },
-        {
-          "name": "customer_id",
-          "description": "UUID of the customer this credit note is for.",
-          "type": "string",
-          "required": true,
-          "position": "body"
-        },
-        {
-          "name": "status",
-          "description": "Credit note status: in_progress, issued, void, or paid.",
-          "type": "string",
-          "required": true,
-          "position": "body",
-          "enum": [
-            "in_progress",
-            "issued",
-            "void",
-            "paid"
-          ]
-        },
-        {
-          "name": "repayment_method",
-          "description": "How the credit is applied: credits, invoice_adjusted, external_payment, credits_against_payment, or original_payment_method.",
-          "type": "string",
-          "required": true,
-          "position": "body",
-          "enum": [
-            "credits",
-            "invoice_adjusted",
-            "external_payment",
-            "credits_against_payment",
-            "original_payment_method"
-          ]
-        },
-        {
-          "name": "line_items",
-          "description": "Line items object describing the credit note breakdown.",
-          "type": "object",
-          "required": true,
-          "position": "body"
-        },
-        {
-          "name": "invoice_id",
-          "description": "Optional invoice UUID to associate the credit note with.",
-          "type": "string",
-          "required": false,
-          "position": "body"
-        }
-      ],
-      "requestTemplate": {
-        "url": "/credit_notes",
-        "method": "POST",
-        "headers": {
-          "Content-Type": "application/json"
-        }
-      },
-      "responseTemplate": {
-        "prependBody": "## Credit Note Created\n\n"
-      }
-    },
     {
       "name": "getCreditNoteById",
       "description": "Retrieve a credit note by its ID, including amount, status, customer, invoice association, and line items URL.",
@@ -3313,7 +3235,7 @@
     },
     {
       "name": "updatePayment",
-      "description": "Update a payment's invoice allocations (payment_parts).",
+      "description": "Update a payment's invoice allocations. The API requires a non-empty request body with payment_parts.",
       "args": [
         {
           "name": "paymentId",
@@ -3324,9 +3246,9 @@
         },
         {
           "name": "payment_parts",
-          "description": "Updated array of invoice allocations. Each element: {invoice_id: 'UUID', amount: 10000}.",
+          "description": "Updated array of invoice allocations. Each element: {invoice_id: 'UUID', amount: 10000}. This field is required by the API.",
           "type": "array",
-          "required": false,
+          "required": true,
           "position": "body"
         }
       ],

package/src/response-processor.js

@@ -2,7 +2,7 @@
 class ResponseProcessor {
   constructor() {
     // Minimal configuration
-    this.maxResponseLength = 50000;
+    this.maxResponseLength = 2000000;
   }
 
   processResponse(responseData, toolName) {
@@ -25,4 +25,4 @@ class ResponseProcessor {
   }
 }
 
-module.exports = ResponseProcessor;
+module.exports = ResponseProcessor;

package/src/server.js

@@ -196,6 +196,203 @@ function normalizeRawMetricDataschema(schema) {
   return normalized;
 }
 
+function extractListPayload(data) {
+  if (!data) return [];
+  if (Array.isArray(data)) return data;
+  if (Array.isArray(data.results)) return data.results;
+  if (data.api_response !== undefined) return extractListPayload(data.api_response);
+  return [];
+}
+
+function normalizeAccountCategory(category) {
+  if (!category || typeof category !== 'string') return 'Uncategorized';
+  const normalized = category.trim();
+  if (!normalized) return 'Uncategorized';
+  return normalized;
+}
+
+function getCategoryOrder(reportType, category) {
+  const balanceSheetOrder = {
+    Assets: 1,
+    Liabilities: 2,
+    Equity: 3
+  };
+  const incomeStatementOrder = {
+    Income: 1,
+    Revenue: 1,
+    'Cost of Goods Sold': 2,
+    Expense: 3,
+    Expenses: 3,
+    'Other Income': 4,
+    'Other Expense': 5,
+    'Other Expenses': 5
+  };
+  const map = reportType === 'getBalanceSheet' ? balanceSheetOrder : incomeStatementOrder;
+  return map[category] || 999;
+}
+
+function buildPeriodKey(row) {
+  const start = row?.interval_start || 'unknown_start';
+  const end = row?.interval_end || 'unknown_end';
+  return `${start}__${end}`;
+}
+
+function summarizePeriods(periodMap) {
+  return Object.values(periodMap)
+    .sort((a, b) => String(a.interval_start).localeCompare(String(b.interval_start)));
+}
+
+function buildAccountingStatementView(reportType, rows, accountLookup) {
+  const periodMap = new Map();
+  const sectionsMap = new Map();
+
+  rows.forEach(row => {
+    const category = normalizeAccountCategory(row.account_category);
+    const periodKey = buildPeriodKey(row);
+    const periodEntry = periodMap.get(periodKey) || {
+      key: periodKey,
+      interval_start: row.interval_start || null,
+      interval_end: row.interval_end || null
+    };
+    periodMap.set(periodKey, periodEntry);
+
+    if (!sectionsMap.has(category)) {
+      sectionsMap.set(category, {
+        category,
+        accounts: new Map(),
+        totals_by_period: {},
+        total_balance: 0,
+        total_debits: 0,
+        total_credits: 0
+      });
+    }
+
+    const section = sectionsMap.get(category);
+    const accountId = row.account_id || 'unknown_account';
+    const accountMeta = accountLookup.get(accountId) || {};
+    if (!section.accounts.has(accountId)) {
+      section.accounts.set(accountId, {
+        account_id: accountId,
+        account_name: row.account_name || accountMeta.name || accountId,
+        account_description: row.account_description || accountMeta.description || null,
+        account_category: category,
+        parent_path: row.account_parent_path || accountMeta.parent_path || null,
+        balance_normality: row.balance_normality || accountMeta.balance_normality || null,
+        periods: {},
+        total_balance: 0,
+        total_debits: 0,
+        total_credits: 0
+      });
+    }
+
+    const account = section.accounts.get(accountId);
+    account.periods[periodKey] = {
+      interval_start: row.interval_start || null,
+      interval_end: row.interval_end || null,
+      balance: row.balance ?? 0,
+      debits: row.debits ?? 0,
+      credits: row.credits ?? 0
+    };
+    account.total_balance += Number(row.balance || 0);
+    account.total_debits += Number(row.debits || 0);
+    account.total_credits += Number(row.credits || 0);
+
+    const sectionPeriod = section.totals_by_period[periodKey] || {
+      interval_start: row.interval_start || null,
+      interval_end: row.interval_end || null,
+      balance: 0,
+      debits: 0,
+      credits: 0
+    };
+    sectionPeriod.balance += Number(row.balance || 0);
+    sectionPeriod.debits += Number(row.debits || 0);
+    sectionPeriod.credits += Number(row.credits || 0);
+    section.totals_by_period[periodKey] = sectionPeriod;
+    section.total_balance += Number(row.balance || 0);
+    section.total_debits += Number(row.debits || 0);
+    section.total_credits += Number(row.credits || 0);
+  });
+
+  const sections = Array.from(sectionsMap.values())
+    .sort((a, b) => {
+      const orderDiff = getCategoryOrder(reportType, a.category) - getCategoryOrder(reportType, b.category);
+      return orderDiff !== 0 ? orderDiff : a.category.localeCompare(b.category);
+    })
+    .map(section => ({
+      category: section.category,
+      accounts: Array.from(section.accounts.values())
+        .sort((a, b) => a.account_name.localeCompare(b.account_name))
+        .map(account => ({
+          ...account,
+          periods: summarizePeriods(account.periods)
+        })),
+      totals_by_period: summarizePeriods(section.totals_by_period),
+      total_balance: section.total_balance,
+      total_debits: section.total_debits,
+      total_credits: section.total_credits
+    }));
+
+  return {
+    report_type: reportType === 'getBalanceSheet' ? 'balance_sheet' : 'income_statement',
+    periods: Array.from(periodMap.values()).sort((a, b) => String(a.interval_start).localeCompare(String(b.interval_start))),
+    sections
+  };
+}
+
+async function fetchJson(url, headers) {
+  const response = await fetch(url, { method: 'GET', headers });
+  const text = await response.text();
+  if (!response.ok) {
+    throw new Error(`Supplemental fetch failed: ${response.status} ${response.statusText}\nResponse: ${text}`);
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch (_error) {
+    throw new Error(`Supplemental fetch returned non-JSON response: ${text}`);
+  }
+}
+
+async function enrichAccountingReportResult(toolName, result, headers, baseUrl) {
+  if (!result || !Array.isArray(result.results)) {
+    return result;
+  }
+
+  try {
+    const chartUrl = `${baseUrl}/accounting_new/chart_of_accounts`;
+    const chartData = await fetchJson(chartUrl, headers);
+    const chartAccounts = extractListPayload(chartData);
+    const accountLookup = new Map(
+      chartAccounts
+        .filter(account => account && account.id)
+        .map(account => [account.id, account])
+    );
+
+    const enrichedRows = result.results.map(row => {
+      const account = accountLookup.get(row.account_id) || {};
+      return {
+        ...row,
+        account_name: account.name || row.account_id || null,
+        account_description: account.description || null,
+        account_category: normalizeAccountCategory(account.account_category),
+        account_parent_path: account.parent_path || null,
+        balance_normality: account.balance_normality || null
+      };
+    });
+
+    return {
+      ...result,
+      results: enrichedRows,
+      statement_view: buildAccountingStatementView(toolName, enrichedRows, accountLookup)
+    };
+  } catch (error) {
+    logger.warn(`[${toolName}] Failed to enrich accounting report output; returning raw report`, {
+      error: error.message
+    });
+    return result;
+  }
+}
+
 // Helper function to convert OpenAPI args to Zod schema
 function convertArgsToZodSchema(args) {
   const schemaObj = {};
@@ -587,7 +784,9 @@ async function executeAPICall(tool, args) {
 
     if (!response.ok) {
       logger.error(`[${tool.name}] API Error Response:`, responseText);
-      throw new Error(`API request failed: ${response.status} ${response.statusText}\nResponse: ${responseText}`);
+      let errorMessage = `API request failed: ${response.status} ${response.statusText}\nResponse: ${responseText}`;
+
+      throw new Error(errorMessage);
     }
 
     let result;
@@ -597,6 +796,11 @@ async function executeAPICall(tool, args) {
       logger.debug(`[${tool.name}] Failed to parse JSON response, returning as text`);
       result = responseText;
     }
+
+    if (tool.name === 'getBalanceSheet' || tool.name === 'getIncomeStatement') {
+      const baseUrl = process.env.ZENSKAR_API_BASE_URL || 'https://api.zenskar.com';
+      result = await enrichAccountingReportResult(tool.name, result, headers, baseUrl);
+    }
     
     // Apply response template if available
     if (tool.responseTemplate?.prependBody) {
@@ -815,7 +1019,7 @@ if (mcpConfig.tools && mcpConfig.tools.length > 0) {
           
           // Use adjusted args with enforced limits
           const adjustedArgs = limitsValidation.adjustedArgs;
-          
+
           // Track limit adjustments
           if (args.limit && adjustedArgs.limit && args.limit !== adjustedArgs.limit) {
             limitRequested = args.limit;