mcp-zenskar 1.0.14 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,118 @@
1
+ # Changelog
2
+
3
+ ## v1.1.0 — 2026-03-06
4
+
5
+ Added 61 new tools (42 → 103 total) covering contracts, invoices, credit notes, payments, accounting, products, plans, quotes, contacts, business entities, and more.
6
+
7
+ ### All Tools
8
+
9
+ | Tool | Description |
10
+ |---|---|
11
+ | `listCustomers` | List customers with search, filtering, and pagination |
12
+ | `getCustomerById` | Get a customer by ID |
13
+ | `createCustomer` | Create a customer with address and tax info |
14
+ | `updateCustomer` | Update customer details (partial update) |
15
+ | `listContacts` | List contacts with pagination |
16
+ | `getContactById` | Get a contact by ID |
17
+ | `createContact` | Create a contact for a customer |
18
+ | `updateContact` | Update a contact's details |
19
+ | `listContracts` | List contracts with filtering by status, customer, dates |
20
+ | `getContractById` | Get a contract with phases, pricings, and customer details |
21
+ | `createContract` | Create a contract with phases and pricing |
22
+ | `updateContract` | Update contract terms, status, pricing, or renewal policy |
23
+ | `deleteContract` | Delete a draft contract |
24
+ | `getContractAmendments` | Get amendment history for a contract |
25
+ | `createContractPhase` | Add a phase to a contract (add-ons, expansions) |
26
+ | `createContractPhasePricing` | Add pricing to a contract phase |
27
+ | `expireContract` | Expire an active contract |
28
+ | `createContractPrompt` | Create a contract prompt |
29
+ | `extractContractFromRaw` | Extract contract data from raw text using AI |
30
+ | `listInvoices` | List invoices with filtering by customer, status, dates |
31
+ | `getInvoiceById` | Get an invoice by ID |
32
+ | `getInvoiceByExternalId` | Get an invoice by external ID |
33
+ | `getInvoiceGenerationStatus` | Check invoice generation status |
34
+ | `downloadInvoice` | Download invoice in JSON format |
35
+ | `getInvoiceContractJsonActuals` | Get contract actuals for an invoice |
36
+ | `getInvoicePayments` | Get payments for an invoice |
37
+ | `getInvoicePaymentsById` | Get a specific payment on an invoice |
38
+ | `getInvoicePaymentsWithoutRefunds` | Get invoice payments excluding refunds |
39
+ | `getInvoiceLineItems` | Get invoice line items and pricing details |
40
+ | `getInvoiceSummary` | Get invoice summary |
41
+ | `getAllInvoiceTags` | Get all available invoice tags |
42
+ | `generateInvoicePaymentLink` | Generate a payment link for an invoice |
43
+ | `payInvoice` | Initiate payment for an invoice |
44
+ | `approveInvoice` | Approve an invoice for billing |
45
+ | `voidInvoice` | Void an approved unpaid invoice |
46
+ | `generateInvoice` | Generate an invoice for a contract and date range |
47
+ | `createInvoiceCreditNote` | Create a credit note against an invoice |
48
+ | `createInvoiceCharge` | Auto-charge an invoice via payment gateway |
49
+ | `listAllPayments` | List all payments with filtering and sorting |
50
+ | `getPaymentById` | Get a payment by ID |
51
+ | `createPayment` | Record a payment against an invoice |
52
+ | `updatePayment` | Update a payment's status or details |
53
+ | `deleteManualPayment` | Delete a manual payment |
54
+ | `editManualPayment` | Edit a manual payment's amount or method |
55
+ | `refundPayment` | Refund a payment (full or partial) |
56
+ | `listCreditNotes` | List credit notes with pagination |
57
+ | `getCreditNoteById` | Get a credit note by ID |
58
+ | `createCreditNote` | Create a standalone credit note |
59
+ | `listProducts` | List products in the catalog |
60
+ | `getProductById` | Get a product by ID |
61
+ | `createProduct` | Create a product |
62
+ | `updateProduct` | Update a product's details |
63
+ | `getProductPricings` | Get pricing configs for a product |
64
+ | `createProductPricing` | Create a pricing config for a product |
65
+ | `listPlans` | List plan templates |
66
+ | `getPlanById` | Get a plan by ID with phases and pricing |
67
+ | `createPlan` | Create a plan template |
68
+ | `addProductsToPlan` | Add products to an existing plan |
69
+ | `previewPlanEstimate` | Preview estimated billing for a plan |
70
+ | `listAggregates` | List billable metrics with filtering |
71
+ | `getAggregateSchemas` | Get all billable metric schemas |
72
+ | `getAggregateEstimates` | Get billable metric estimates |
73
+ | `getAggregateById` | Get a billable metric by ID |
74
+ | `getAggregateLogs` | Get logs for a billable metric |
75
+ | `listRawMetrics` | List usage events with filtering |
76
+ | `createRawMetric` | Create a usage event schema |
77
+ | `getRawMetricById` | Get a usage event by ID |
78
+ | `getRawMetricLogs` | Get logs for a usage event |
79
+ | `getRawMetricBySlug` | Get a usage event by API slug |
80
+ | `ingestRawMetricEvent` | Ingest a usage event |
81
+ | `getChartOfAccounts` | Get the full chart of accounts |
82
+ | `listAccounts` | List GL accounts with filtering |
83
+ | `createAccount` | Create a GL account |
84
+ | `listJournalEntries` | List journal entries with filtering |
85
+ | `createJournalEntry` | Create a manual journal entry |
86
+ | `getJournalEntry` | Get a journal entry by ID with all lines |
87
+ | `listJournalLines` | List journal lines across all entries |
88
+ | `getBalanceSheet` | Get the balance sheet report |
89
+ | `getIncomeStatement` | Get the income statement (P&L) |
90
+ | `getAccountBalance` | Get balance for a specific GL account |
91
+ | `recogniseRevenue` | Trigger revenue recognition up to a date |
92
+ | `createQuote` | Create a quote/proposal |
93
+ | `previewQuoteEstimate` | Preview estimated billing for a quote |
94
+ | `getQuoteById` | Get a quote by ID |
95
+ | `acceptQuote` | Accept a quote, converting to a contract |
96
+ | `listCustomAttributes` | List custom attribute definitions |
97
+ | `createCustomAttribute` | Create a custom attribute definition |
98
+ | `listTaxCategories` | List tax categories |
99
+ | `createTaxCategory` | Create a tax category |
100
+ | `listJobs` | List async jobs (invoice gen, rev rec, etc.) |
101
+ | `getJobById` | Get a job by ID to check status |
102
+ | `listBusinessEntities` | List business entities |
103
+ | `getBusinessEntityById` | Get a business entity by ID |
104
+ | `createBusinessEntity` | Create a business entity |
105
+ | `updateBusinessEntity` | Update a business entity |
106
+ | `listCustomerAddresses` | List addresses for a customer |
107
+ | `createCustomerAddress` | Add an address to a customer |
108
+ | `updateCustomerAddress` | Update a customer address |
109
+ | `listPaymentMethods` | List payment methods for a customer |
110
+ | `attachPaymentMethod` | Attach a payment method to a customer |
111
+ | `createEntitlement` | Create an entitlement |
112
+ | `getCustomerPortalConfiguration` | Get customer portal config |
113
+ | `getCurrentDateTime` | Get current date/time in multiple formats |
114
+
115
+ ### Code Changes
116
+
117
+ - `src/mcp-config.json` — 61 new tool definitions added
118
+ - `src/server.js` — 1 line: added `updateCustomer` to address nesting logic
package/README.md CHANGED
@@ -1,15 +1,22 @@
1
1
  # Zenskar MCP Server
2
2
 
3
- A Model Context Protocol (MCP) server that provides AI assistants with access to the Zenskar API for customer management, invoicing, and billing operations.
4
-
5
- ## Features
6
-
7
- - **Customer Management**: List, search, create, and update customers
8
- - **Invoice Operations**: Create, retrieve, and manage invoices
9
- - **Subscription Management**: Handle subscription lifecycle
10
- - **Billing Operations**: Process payments and manage billing
11
- - **Multi-tenant Support**: Organization-based access control
12
- - **Secure Authentication**: Bearer token authentication
3
+ MCP server for the Zenskar API. 103 tools covering customers, contracts, invoices, payments, credit notes, accounting, products, plans, quotes, and more.
4
+
5
+ ## What it does
6
+
7
+ - Customers: list, search, create, update, addresses, contacts, payment methods
8
+ - Contracts: create, read, update, delete, amend, add phases and pricing, expire
9
+ - Invoices: list, get, approve, void, generate, credit notes, download
10
+ - Payments: create, edit, refund, delete, auto-charge
11
+ - Credit notes: list, create (standalone or against invoice), get by ID
12
+ - Accounting: chart of accounts, journal entries and lines, balance sheet, income statement, account balances
13
+ - Products: CRUD, pricing configurations
14
+ - Plans: list, create, add products, preview estimates
15
+ - Quotes: create, preview, accept (converts to contract)
16
+ - Business entities: list, get, create, update
17
+ - Jobs: monitor async operations
18
+ - Custom attributes and tax categories
19
+ - Multi-tenant, supports Bearer token and API key auth
13
20
 
14
21
  ## Installation
15
22
 
@@ -51,7 +58,7 @@ npx mcp-zenskar
51
58
  This MCP server requires two authentication parameters for every request:
52
59
 
53
60
  1. **Organization ID**: Your Zenskar organization identifier
54
- 2. **Authorization Token**: Your API Bearer token
61
+ 2. **Authorization Token**: Your API Bearer token or API key
55
62
 
56
63
  ### Getting Your Credentials
57
64
 
@@ -68,47 +75,193 @@ Once configured, you can ask Claude to interact with your Zenskar data:
68
75
 
69
76
  ```
70
77
  "Show me my recent customers"
71
- "Create an invoice for customer XYZ"
72
- "List all active subscriptions"
73
- ```
74
-
75
- ### Manual Tool Calls
76
-
77
- Each tool requires authentication parameters:
78
-
79
- ```javascript
80
- {
81
- "organization": "your-org-id",
82
- "authorization": "Bearer your-token",
83
- // ... other tool-specific parameters
84
- }
78
+ "Find the contract for Acme Corp and add a $500/month add-on phase"
79
+ "Create a $25 credit note against the latest invoice for customer X"
80
+ "Show me the balance sheet and income statement"
81
+ "List all products and their pricing configurations"
82
+ "Record a $1000 manual payment against invoice Y"
85
83
  ```
86
84
 
87
85
  ## Available Tools
88
86
 
89
- The server provides access to all Zenskar API endpoints including:
90
-
91
- - `listCustomers` - Retrieve paginated customer lists
92
- - `getCustomer` - Get specific customer details
93
- - `createCustomer` - Create new customers
94
- - `updateCustomer` - Update existing customers
95
- - `listInvoices` - Retrieve invoice lists
96
- - `createInvoice` - Generate new invoices
97
- - `getInvoice` - Get invoice details
98
- - And many more...
87
+ ### Customers
88
+ | Tool | Description |
89
+ |---|---|
90
+ | `listCustomers` | List customers with search, filtering, and pagination |
91
+ | `getCustomerById` | Get a customer by ID |
92
+ | `createCustomer` | Create a customer with address and tax info |
93
+ | `updateCustomer` | Update customer details (partial update) |
94
+
95
+ ### Contacts
96
+ | Tool | Description |
97
+ |---|---|
98
+ | `listContacts` | List contacts with pagination |
99
+ | `getContactById` | Get a contact by ID |
100
+ | `createContact` | Create a contact for a customer |
101
+ | `updateContact` | Update a contact's details |
102
+
103
+ ### Contracts
104
+ | Tool | Description |
105
+ |---|---|
106
+ | `listContracts` | List contracts with filtering by status, customer, dates |
107
+ | `getContractById` | Get a contract with phases, pricings, and customer details |
108
+ | `createContract` | Create a contract with phases and pricing |
109
+ | `updateContract` | Update contract terms, status, pricing, or renewal policy |
110
+ | `deleteContract` | Delete a draft contract |
111
+ | `getContractAmendments` | Get amendment history for a contract |
112
+ | `createContractPhase` | Add a phase to a contract (add-ons, expansions) |
113
+ | `createContractPhasePricing` | Add pricing to a contract phase |
114
+ | `expireContract` | Expire an active contract |
115
+ | `createContractPrompt` | Create a contract prompt |
116
+ | `extractContractFromRaw` | Extract contract data from raw text using AI |
117
+
118
+ ### Invoices
119
+ | Tool | Description |
120
+ |---|---|
121
+ | `listInvoices` | List invoices with filtering by customer, status, dates |
122
+ | `getInvoiceById` | Get an invoice by ID |
123
+ | `getInvoiceByExternalId` | Get an invoice by external ID |
124
+ | `getInvoiceGenerationStatus` | Check invoice generation status |
125
+ | `downloadInvoice` | Download invoice in JSON format |
126
+ | `getInvoiceContractJsonActuals` | Get contract actuals for an invoice |
127
+ | `getInvoicePayments` | Get payments for an invoice |
128
+ | `getInvoicePaymentsById` | Get a specific payment on an invoice |
129
+ | `getInvoicePaymentsWithoutRefunds` | Get invoice payments excluding refunds |
130
+ | `getInvoiceLineItems` | Get invoice line items and pricing details |
131
+ | `getInvoiceSummary` | Get invoice summary |
132
+ | `getAllInvoiceTags` | Get all available invoice tags |
133
+ | `generateInvoicePaymentLink` | Generate a payment link for an invoice |
134
+ | `payInvoice` | Initiate payment for an invoice |
135
+ | `approveInvoice` | Approve an invoice for billing |
136
+ | `voidInvoice` | Void an approved unpaid invoice |
137
+ | `generateInvoice` | Generate an invoice for a contract and date range |
138
+ | `createInvoiceCreditNote` | Create a credit note against an invoice |
139
+ | `createInvoiceCharge` | Auto-charge an invoice via payment gateway |
140
+
141
+ ### Payments
142
+ | Tool | Description |
143
+ |---|---|
144
+ | `listAllPayments` | List all payments with filtering and sorting |
145
+ | `getPaymentById` | Get a payment by ID |
146
+ | `createPayment` | Record a payment against an invoice |
147
+ | `updatePayment` | Update a payment's status or details |
148
+ | `deleteManualPayment` | Delete a manual payment |
149
+ | `editManualPayment` | Edit a manual payment's amount or method |
150
+ | `refundPayment` | Refund a payment (full or partial) |
151
+
152
+ ### Credit Notes
153
+ | Tool | Description |
154
+ |---|---|
155
+ | `listCreditNotes` | List credit notes with pagination |
156
+ | `getCreditNoteById` | Get a credit note by ID |
157
+ | `createCreditNote` | Create a standalone credit note |
158
+
159
+ ### Products and Pricing
160
+ | Tool | Description |
161
+ |---|---|
162
+ | `listProducts` | List products in the catalog |
163
+ | `getProductById` | Get a product by ID |
164
+ | `createProduct` | Create a product |
165
+ | `updateProduct` | Update a product's details |
166
+ | `getProductPricings` | Get pricing configs for a product |
167
+ | `createProductPricing` | Create a pricing config for a product |
168
+
169
+ ### Plans (Templates)
170
+ | Tool | Description |
171
+ |---|---|
172
+ | `listPlans` | List plan templates |
173
+ | `getPlanById` | Get a plan by ID with phases and pricing |
174
+ | `createPlan` | Create a plan template |
175
+ | `addProductsToPlan` | Add products to an existing plan |
176
+ | `previewPlanEstimate` | Preview estimated billing for a plan |
177
+
178
+ ### Accounting
179
+ | Tool | Description |
180
+ |---|---|
181
+ | `getChartOfAccounts` | Get the full chart of accounts |
182
+ | `listAccounts` | List GL accounts with filtering |
183
+ | `createAccount` | Create a GL account |
184
+ | `listJournalEntries` | List journal entries with filtering |
185
+ | `createJournalEntry` | Create a manual journal entry |
186
+ | `getJournalEntry` | Get a journal entry by ID with all lines |
187
+ | `listJournalLines` | List journal lines across all entries |
188
+ | `getBalanceSheet` | Get the balance sheet report |
189
+ | `getIncomeStatement` | Get the income statement (P&L) |
190
+ | `getAccountBalance` | Get balance for a specific GL account |
191
+ | `recogniseRevenue` | Trigger revenue recognition up to a date |
192
+
193
+ ### Quotes
194
+ | Tool | Description |
195
+ |---|---|
196
+ | `createQuote` | Create a quote/proposal |
197
+ | `previewQuoteEstimate` | Preview estimated billing for a quote |
198
+ | `getQuoteById` | Get a quote by ID |
199
+ | `acceptQuote` | Accept a quote, converting to a contract |
200
+
201
+ ### Custom Attributes and Tax
202
+ | Tool | Description |
203
+ |---|---|
204
+ | `listCustomAttributes` | List custom attribute definitions |
205
+ | `createCustomAttribute` | Create a custom attribute definition |
206
+ | `listTaxCategories` | List tax categories |
207
+ | `createTaxCategory` | Create a tax category |
208
+
209
+ ### Jobs
210
+ | Tool | Description |
211
+ |---|---|
212
+ | `listJobs` | List async jobs (invoice gen, rev rec, etc.) |
213
+ | `getJobById` | Get a job by ID to check status |
214
+
215
+ ### Business Entities
216
+ | Tool | Description |
217
+ |---|---|
218
+ | `listBusinessEntities` | List business entities |
219
+ | `getBusinessEntityById` | Get a business entity by ID |
220
+ | `createBusinessEntity` | Create a business entity |
221
+ | `updateBusinessEntity` | Update a business entity |
222
+
223
+ ### Customer Addresses and Payment Methods
224
+ | Tool | Description |
225
+ |---|---|
226
+ | `listCustomerAddresses` | List addresses for a customer |
227
+ | `createCustomerAddress` | Add an address to a customer |
228
+ | `updateCustomerAddress` | Update a customer address |
229
+ | `listPaymentMethods` | List payment methods for a customer |
230
+ | `attachPaymentMethod` | Attach a payment method to a customer |
231
+
232
+ ### Metrics and Usage Events
233
+ | Tool | Description |
234
+ |---|---|
235
+ | `listAggregates` | List billable metrics with filtering |
236
+ | `getAggregateSchemas` | Get all billable metric schemas |
237
+ | `getAggregateEstimates` | Get billable metric estimates |
238
+ | `getAggregateById` | Get a billable metric by ID |
239
+ | `getAggregateLogs` | Get logs for a billable metric |
240
+ | `listRawMetrics` | List usage events with filtering |
241
+ | `createRawMetric` | Create a usage event schema |
242
+ | `getRawMetricById` | Get a usage event by ID |
243
+ | `getRawMetricLogs` | Get logs for a usage event |
244
+ | `getRawMetricBySlug` | Get a usage event by API slug |
245
+ | `ingestRawMetricEvent` | Ingest a usage event |
246
+
247
+ ### Other
248
+ | Tool | Description |
249
+ |---|---|
250
+ | `createEntitlement` | Create an entitlement |
251
+ | `getCustomerPortalConfiguration` | Get customer portal config |
252
+ | `getCurrentDateTime` | Get current date/time in multiple formats |
99
253
 
100
254
  ## Security
101
255
 
102
- - All API requests require valid organization ID and Bearer token
103
- - Multi-tenant isolation ensures data privacy
104
- - No credentials are stored by the MCP server
105
- - All authentication is passed through from the client
256
+ - All requests require a valid organization ID and auth token
257
+ - No credentials are stored by the server
258
+ - Auth is passed through from the client
106
259
 
107
260
  ## Development
108
261
 
109
262
  ```bash
110
263
  # Clone the repository
111
- git clone https://github.com/your-org/mcp-zenskar
264
+ git clone https://github.com/zenskar/mcp-zenskar
112
265
  cd mcp-zenskar
113
266
 
114
267
  # Install dependencies
@@ -145,7 +298,7 @@ Then either point Claude to the globally-installed binary (usually `$(npm bin -g
145
298
 
146
299
  ## Configuration
147
300
 
148
- The server uses `src/mcp-config.json` to define available tools and API endpoints. This file contains the complete mapping of MCP tools to Zenskar API operations.
301
+ The server uses `src/mcp-config.json` to define available tools and API endpoints. This file contains the complete mapping of MCP tools to Zenskar API operations. All tools are declarative — no code changes needed to add new tools.
149
302
 
150
303
  ## License
151
304
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mcp-zenskar",
3
- "version": "1.0.14",
3
+ "version": "1.1.1",
4
4
  "description": "Model Context Protocol (MCP) server for Zenskar API - customer management, invoicing, and billing operations",
5
5
  "main": "src/server.js",
6
6
  "bin": {