@neuctra/finance-mcp 1.0.0 → 1.0.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/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  An [MCP](https://modelcontextprotocol.io) server that tells AI assistants how to use Neuctra
4
4
  Finance: how to record expenses and income, move money, track debts, reserve money with holds,
5
- ask for approval, fix mistakes and handle errors, using the `@neuctra/finance` SDK.
5
+ manage invoices, ask for approval, fix mistakes and handle errors, using the `@neuctra/finance` SDK.
6
6
 
7
7
  It is documentation only. It never connects to a Finance account, needs no key and cannot move
8
8
  money; the assistant uses it to write correct code for your app.
@@ -16,7 +16,7 @@ All read-only guides. None of them connects to a Finance account or moves money.
16
16
  | `get_setup_guide` | How it fits together, install, client, keys and permissions, testing. Call first. |
17
17
  | `list_sdk_methods` | Every SDK method with its permission. Only these exist. Optional `group`. |
18
18
  | `get_sdk_method` | One method: params, return value, errors, example (`expenses.record`, `income.record`...). |
19
- | `get_example` | A full workflow: `record-expense`, `record-income`, `transfer-money`, `read-transactions`, `manage-debts`, `reserve-money`, `request-approval`, `fix-a-mistake`, `handle-webhooks`, `safe-retries`, `rest-api`. |
19
+ | `get_example` | A full workflow: `record-expense`, `record-income`, `transfer-money`, `read-transactions`, `manage-debts`, `manage-invoices`, `reserve-money`, `request-approval`, `fix-a-mistake`, `handle-webhooks`, `safe-retries`, `rest-api`. |
20
20
  | `get_error_reference` | What an error code means and what to do. No code returns the whole list. |
21
21
 
22
22
  ## Setup
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@neuctra/finance-mcp",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "MCP server that teaches AI assistants how to manage expenses, income and more with the Neuctra Finance SDK.",
5
5
  "type": "module",
6
6
  "main": "./src/index.js",
package/src/docs.js CHANGED
@@ -65,11 +65,12 @@ Call \`finance.me()\` first to see which permissions and accounts the key has.`,
65
65
 
66
66
  | Permission | Allows |
67
67
  | --- | --- |
68
- | \`read\` | Read accounts, balances, transactions, debts and the summary. |
68
+ | \`read\` | Read accounts, balances, transactions, debts, invoices and the summary. |
69
69
  | \`expenses:write\` | Record expenses. Refused when the account would go below zero. |
70
70
  | \`income:write\` | Record income into an account. |
71
71
  | \`transfers:write\` | Move money between two accounts of the business. |
72
72
  | \`debts:write\` | Create debts and record payments or collections. |
73
+ | \`invoices:write\` | Create, update, send, pay, void and delete invoice drafts. |
73
74
  | \`holds:write\` | Reserve money, then capture or release it. **Server keys only.** |
74
75
  | \`requests:write\` | Ask for approval to spend above an account's approval line. |
75
76
  | \`reversals:write\` | Undo a transaction with an opposite entry. |
@@ -246,6 +247,35 @@ await finance.debts.get(debtId);
246
247
  Paying more than what is outstanding fails with \`OVERPAYMENT\`. A debt has \`principal\`, \`outstanding\`, \`paid\`, \`status\` (open | settled | cancelled), \`dueDate\` and \`isOverdue\`.`,
247
248
  },
248
249
 
250
+ invoices: {
251
+ title: "Manage invoices",
252
+ summary: "Create and manage invoice drafts, send invoices and record payments into an account.",
253
+ body: `# Invoices
254
+
255
+ Invoice reads need \`read\`; changes need \`invoices:write\`. Invoices belong to the business. When recording a payment, choose an \`accountId\`; the key's allowed accounts and per-transaction limit are checked.
256
+
257
+ \`\`\`js
258
+ const draft = await finance.invoices.create({
259
+ customer: { name: "Acme Ltd", email: "billing@acme.test" },
260
+ lines: [
261
+ { description: "Consulting", quantity: 2, unitPrice: 500, taxRate: 10 },
262
+ ],
263
+ dueDate: "2026-12-01",
264
+ idempotencyKey: "invoice-2026-001",
265
+ });
266
+
267
+ const { invoice, emailed, emailError } = await finance.invoices.send(draft.id, { email: true });
268
+ const payment = await finance.invoices.pay(invoice.id, {
269
+ accountId: "acc_sales01",
270
+ amount: 500,
271
+ idempotencyKey: "invoice-payment-001",
272
+ });
273
+ console.log(payment.invoice.due, payment.account.balance);
274
+ \`\`\`
275
+
276
+ Use \`finance.invoices.list()\` and \`finance.invoices.get(id)\` to read invoices. Drafts can be updated with \`finance.invoices.update(id, changes)\` or deleted with \`finance.invoices.delete(id)\`. Sending assigns the invoice number; the customer link is returned only to keys with \`invoices:write\`. A sent invoice cannot be edited or deleted. Payments may be partial but cannot exceed the amount due. Void an unpaid sent invoice with \`finance.invoices.void(id, { reason })\`.`,
277
+ },
278
+
249
279
  holds: {
250
280
  title: "Reserve money first (holds)",
251
281
  summary: "Authorize, capture or void a hold so money is reserved before paying.",
@@ -431,6 +461,13 @@ curl -X POST https://finance-api.yourcompany.com/v1/expenses \\
431
461
  | GET | /v1/debts/:id | read | One debt. |
432
462
  | POST | /v1/debts | debts:write | direction, counterparty, amount, accountId, dueDate. |
433
463
  | POST | /v1/debts/:id/payments | debts:write | amount, accountId. |
464
+ | GET | /v1/invoices | read | List invoices. |
465
+ | GET | /v1/invoices/:id | read | One invoice. |
466
+ | POST | /v1/invoices | invoices:write | Create a draft from customer and line items. |
467
+ | PATCH / DELETE | /v1/invoices/:id | invoices:write | Update or delete a draft. |
468
+ | POST | /v1/invoices/:id/send | invoices:write | Send; optionally email the customer. |
469
+ | POST | /v1/invoices/:id/payments | invoices:write | Post payment into accountId. |
470
+ | POST | /v1/invoices/:id/void | invoices:write | Void an unpaid sent invoice. |
434
471
  | POST | /v1/holds | holds:write | accountId, amount, expiresInMinutes. |
435
472
  | GET | /v1/holds/:id | read | One hold. |
436
473
  | POST | /v1/holds/:id/capture | holds:write | amount (optional, at most the held amount). |
package/src/errors.js CHANGED
@@ -2,7 +2,7 @@ export const ERRORS = [
2
2
  ["INSUFFICIENT_FUNDS", 402, "The account cannot cover the amount. Nothing was deducted. details: balance, held, available, requested, shortBy.", "Tell the owner to add money, or lower the amount. Check first with accounts.canSpend."],
3
3
  ["ACCOUNT_FROZEN", 423, "The owner paused spending from this account.", "Alert the owner; do not retry."],
4
4
  ["ACCOUNT_CLOSED", 409, "The account no longer accepts money in or out.", "Use another account."],
5
- ["OVERPAYMENT", 422, "More than the outstanding amount was paid on a debt.", "Pay at most debt.outstanding."],
5
+ ["OVERPAYMENT", 422, "More than the outstanding amount was paid on a debt or invoice.", "Pay at most debt.outstanding or invoice.due."],
6
6
  ["VALIDATION_ERROR", 400, "A field is missing or malformed. The message names it.", "Fix the field and resend."],
7
7
  ["NOT_FOUND", 404, "The account, transaction, debt, hold or request does not exist in this business.", "Check the id and that the key belongs to this business."],
8
8
  ["INVALID_API_KEY", 401, "The key is wrong.", "Check NEUCTRA_FINANCE_KEY."],
@@ -20,6 +20,11 @@ export const ERRORS = [
20
20
  ["CATEGORY_REQUIRED", 400, "The business requires a known category.", "Pass an existing category."],
21
21
  ["PERIOD_LOCKED", 409, "The owner closed the books for that date.", "Use a later occurredAt."],
22
22
  ["IDEMPOTENCY_MISMATCH", 422, "The idempotency key was already used for a different request.", "Use a new key for different work."],
23
+ ["INVOICE_SENT", 409, "A sent invoice cannot be changed or deleted.", "Void it and send a new invoice with the changes."],
24
+ ["INVOICE_DRAFT", 409, "An invoice must be sent before recording a payment; drafts cannot be voided.", "Send the invoice first, or delete the draft."],
25
+ ["INVOICE_VOID", 409, "The invoice was voided.", "Create and send a new invoice."],
26
+ ["INVOICE_PAID", 409, "The invoice has already been paid in full.", "No further payment is needed."],
27
+ ["INVOICE_HAS_PAYMENTS", 409, "An invoice with payments cannot be voided.", "Reverse its payments first."],
23
28
  ["HOLD_EXPIRED", 409, "The hold ended.", "Authorize a new hold."],
24
29
  ["HOLD_NOT_ACTIVE", 409, "The hold was already captured or voided.", "Read it with holds.get."],
25
30
  ["CAPTURE_TOO_LARGE", 422, "Tried to capture more than was held.", "Capture the held amount or less."],
package/src/methods.js CHANGED
@@ -75,6 +75,42 @@ export const METHODS = [
75
75
  params: `debtId (required), amount (required), accountId?, ${MOVE}`, returns: "{ debt, transaction, account, replayed }", errors: "OVERPAYMENT, INSUFFICIENT_FUNDS, NOT_FOUND, MISSING_SCOPE",
76
76
  example: `await finance.debts.pay(debt.id, { amount: 5000, description: "Installment 1" });` },
77
77
 
78
+ { name: "invoices.list", call: "finance.invoices.list()", scope: "read", group: "Invoices",
79
+ does: "Lists invoices for the business. Invoice records are business-level; invoice payments are assigned to accounts separately.",
80
+ params: "none", returns: "Invoice[]", errors: "MISSING_SCOPE",
81
+ example: `const invoices = await finance.invoices.list();\ninvoices.map(({ number, status, due }) => ({ number, status, due }));` },
82
+ { name: "invoices.get", call: "finance.invoices.get(invoiceId)", scope: "read", group: "Invoices",
83
+ does: "Gets one invoice, including its lines, payment totals, status and (for keys with invoices:write) customer link.",
84
+ params: "invoiceId (required)", returns: "Invoice", errors: "NOT_FOUND, MISSING_SCOPE",
85
+ example: `const invoice = await finance.invoices.get(invoiceId);\ninvoice.due;` },
86
+ { name: "invoices.create", call: "finance.invoices.create(input)", scope: "invoices:write", group: "Invoices",
87
+ does: "Creates an invoice draft. Reusing the same idempotencyKey and input returns the same draft.",
88
+ params: "customer { name, email?, address? } and lines [{ description, unitPrice, quantity?, taxRate? }] (required); issueDate?, dueDate?, taxLabel?, category?, notes?, idempotencyKey?",
89
+ returns: "Invoice", errors: "VALIDATION_ERROR, MISSING_SCOPE, IDEMPOTENCY_MISMATCH",
90
+ example: `const draft = await finance.invoices.create({\n customer: { name: "Acme Ltd", email: "billing@acme.test" },\n lines: [{ description: "Consulting", quantity: 2, unitPrice: 500, taxRate: 10 }],\n idempotencyKey: "invoice-2026-001",\n});` },
91
+ { name: "invoices.update", call: "finance.invoices.update(invoiceId, input)", scope: "invoices:write", group: "Invoices",
92
+ does: "Updates an invoice draft. Sent invoices cannot be edited.",
93
+ params: "invoiceId (required), any draft fields: customer?, lines?, issueDate?, dueDate?, taxLabel?, category?, notes?",
94
+ returns: "Invoice", errors: "NOT_FOUND, INVOICE_SENT, VALIDATION_ERROR, MISSING_SCOPE",
95
+ example: `await finance.invoices.update(draft.id, { notes: "Thank you for your business." });` },
96
+ { name: "invoices.delete", call: "finance.invoices.delete(invoiceId)", scope: "invoices:write", group: "Invoices",
97
+ does: "Deletes an invoice draft. Sent invoices cannot be deleted.",
98
+ params: "invoiceId (required)", returns: "void", errors: "NOT_FOUND, INVOICE_SENT, MISSING_SCOPE",
99
+ example: `await finance.invoices.delete(draft.id);` },
100
+ { name: "invoices.send", call: "finance.invoices.send(invoiceId, input?)", scope: "invoices:write", group: "Invoices",
101
+ does: "Numbers and sends a draft. Optionally emails the customer; the returned emailError reports delivery failure without undoing the send.",
102
+ params: "invoiceId (required), email? (boolean, default false)", returns: "{ invoice, emailed, emailError }", errors: "NOT_FOUND, INVOICE_VOID, VALIDATION_ERROR, MISSING_SCOPE",
103
+ example: `const { invoice, emailed, emailError } = await finance.invoices.send(draft.id, { email: true });` },
104
+ { name: "invoices.pay", call: "finance.invoices.pay(invoiceId, input)", scope: "invoices:write", group: "Invoices",
105
+ does: "Records a partial or full invoice payment as income in the specified account. The key's allowed accounts and per-transaction limit are enforced.",
106
+ params: `invoiceId (required), accountId, amount (required, major units), description?, occurredAt?, idempotencyKey?`,
107
+ returns: "{ invoice, transaction, account, replayed }", errors: "OVERPAYMENT, INVOICE_DRAFT, INVOICE_VOID, INVOICE_PAID, ACCOUNT_NOT_ALLOWED, AMOUNT_LIMIT, MISSING_SCOPE",
108
+ example: `const payment = await finance.invoices.pay(invoice.id, {\n accountId: "acc_sales01",\n amount: 500,\n idempotencyKey: "invoice-payment-001",\n});\npayment.invoice.due; payment.account.balance;` },
109
+ { name: "invoices.void", call: "finance.invoices.void(invoiceId, { reason })", scope: "invoices:write", group: "Invoices",
110
+ does: "Voids a sent invoice with no payments. Delete drafts instead; reverse recorded payments before voiding.",
111
+ params: "invoiceId, reason (both required)", returns: "Invoice", errors: "INVOICE_DRAFT, INVOICE_VOID, INVOICE_HAS_PAYMENTS, MISSING_SCOPE",
112
+ example: `await finance.invoices.void(invoice.id, { reason: "Issued to the wrong customer" });` },
113
+
78
114
  { name: "holds.authorize", call: "finance.holds.authorize(input)", scope: "holds:write (server keys only)", group: "Holds",
79
115
  does: "Reserves money before you pay. Available drops at once so nothing else can spend it. Expires after 7 days by default (max 30).",
80
116
  params: "accountId, amount (required); expiresInMinutes? (default 10080, max 43200), category?, description?, reference?, counterparty?, idempotencyKey?", returns: "{ hold, replayed }",
@@ -128,7 +164,7 @@ export function formatMethod(m) {
128
164
  `- **Params:** ${m.params}`,
129
165
  `- **Returns:** ${m.returns}`,
130
166
  `- **Can fail with:** ${m.errors}`,
131
- m.group === "Money" || m.group === "Debts" || m.group === "Holds"
167
+ m.group === "Money" || m.group === "Debts" || m.group === "Invoices" || m.group === "Holds"
132
168
  ? "- Amounts are major units (1500.5 = 1,500.50). Writes carry an idempotency key automatically."
133
169
  : "",
134
170
  "",
package/src/server.js CHANGED
@@ -4,7 +4,7 @@ import { TOPICS } from "./docs.js";
4
4
  import { METHODS, findMethod, formatMethod, methodNames } from "./methods.js";
5
5
  import { ERRORS, formatError } from "./errors.js";
6
6
 
7
- const INSTRUCTIONS = `Neuctra Finance records where business money goes (expenses, income, transfers, debts, holds, approvals) through the @neuctra/finance SDK. Do not write Finance code from memory. Call get_setup_guide once, then list_sdk_methods, then get_sdk_method for each call you will write. Use get_example for a complete workflow (record an expense, record income...) and get_error_reference when a call fails. If a method is not listed, it does not exist.`;
7
+ const INSTRUCTIONS = `Neuctra Finance records where business money goes (expenses, income, transfers, debts, invoices, holds, approvals) through the @neuctra/finance SDK. Do not write Finance code from memory. Call get_setup_guide once, then list_sdk_methods, then get_sdk_method for each call you will write. Use get_example for a complete workflow (record an expense, manage invoices...) and get_error_reference when a call fails. If a method is not listed, it does not exist.`;
8
8
 
9
9
  const READ = { readOnlyHint: true, openWorldHint: false };
10
10
  const text = (t) => ({ content: [{ type: "text", text: t }] });
@@ -17,6 +17,7 @@ const EXAMPLES = {
17
17
  "transfer-money": "transfers",
18
18
  "read-transactions": "transactions",
19
19
  "manage-debts": "debts",
20
+ "manage-invoices": "invoices",
20
21
  "reserve-money": "holds",
21
22
  "request-approval": "approvals",
22
23
  "fix-a-mistake": "reversals",
@@ -43,7 +44,7 @@ export function createServer() {
43
44
  "list_sdk_methods",
44
45
  "List SDK methods",
45
46
  "Every @neuctra/finance method with the permission it needs and what it does. Only these exist.",
46
- { group: z.enum(["Connect", "Read", "Money", "Debts", "Holds", "Approvals", "Webhooks"]).optional().describe("Limit to one group.") },
47
+ { group: z.enum(["Connect", "Read", "Money", "Debts", "Invoices", "Holds", "Approvals", "Webhooks"]).optional().describe("Limit to one group.") },
47
48
  ({ group }) => {
48
49
  const list = METHODS.filter((m) => !group || m.group === group);
49
50
  const out = list.map((m) => `- \`${m.call}\` [${m.scope}]: ${m.does.split(". ")[0].replace(/\.$/, "")}.`);
@@ -54,7 +55,7 @@ export function createServer() {
54
55
  tool(
55
56
  "get_sdk_method",
56
57
  "Get SDK method",
57
- "Full detail for one method: permission, params, return value, errors it can raise and an example. Example names: expenses.record, income.record, transfers.create, holds.capture.",
58
+ "Full detail for one method: permission, params, return value, errors it can raise and an example. Example names: expenses.record, income.record, invoices.pay, transfers.create, holds.capture.",
58
59
  { method: z.string().min(1).describe(`Method name. One of: ${methodNames().join(", ")}`) },
59
60
  ({ method }) => {
60
61
  const m = findMethod(method);