@ekwo-ai/mcp 0.4.0

package/README.md

@@ -0,0 +1,253 @@
+# @ekwo-ai/mcp
+
+The [Model Context Protocol](https://modelcontextprotocol.io) server for
+[Ekwo OS](https://github.com/Ekwo-ai/ekwo-os). It lets an AI assistant keep the
+books in your own Postgres: read the ledger, raise an invoice, post it, match
+a payment, pull the VAT return or the French FEC — **as you**, under the row
+level security of your own installation.
+
+```sh
+npx @ekwo-ai/mcp
+```
+
+It speaks MCP over stdio and is started by a client, never by hand.
+
+## What it is, and what it is not
+
+The server holds no privileges of its own. It signs in as the person using it,
+or is handed their access token, and everything it can do afterwards is
+exactly what that person can do: a viewer reads and cannot write, a member of
+one company cannot see another, a locked period refuses a posting. None of
+that is checked in this package — the policies and the triggers in the schema
+decide, and this server reports what they answered.
+
+Three things it will never do:
+
+- **Write a ledger line.** Every entry comes out of `post_document`,
+  `post_payment`, `post_entry` or `reconcile`, which carry the accounting
+  rules. Direct inserts are for the objects a person types: contacts, draft
+  documents and their lines, payments, bank transactions.
+- **Delete or edit a posted entry.** There is no unpost, and no tool that
+  removes one. A mistake is corrected with a credit note, which is how
+  accounting has always worked. `unreconcile` is the only undo here, and
+  matching changes no account.
+- **Use a `service_role` key.** It would work, and that is the objection: it
+  bypasses every policy, so the assistant would answer for companies its user
+  was never invited to. The server refuses to start with one.
+
+## Configuration
+
+### The recommended route: PostgREST, as the signed-in user
+
+```json
+{
+  "mcpServers": {
+    "ekwo": {
+      "command": "npx",
+      "args": ["-y", "@ekwo-ai/mcp"],
+      "env": {
+        "SUPABASE_URL": "https://YOURREF.supabase.co",
+        "SUPABASE_ANON_KEY": "your anon (publishable) key",
+        "EKWO_EMAIL": "you@example.com",
+        "EKWO_PASSWORD": "your password"
+      }
+    }
+  }
+}
+```
+
+That block goes in `claude_desktop_config.json` for Claude Desktop, or in
+`.mcp.json` at the root of a project for Claude Code. `EKWO_ACCESS_TOKEN`
+replaces the address and the password when you already hold a session; with
+the password, the session is kept in memory and refreshed, and nothing is
+written to disk.
+
+### The fallback: a direct Postgres connection
+
+For a self-hosted installation with no PostgREST in front of the database, or
+for tests.
+
+```json
+{
+  "env": {
+    "EKWO_DB_URL": "postgresql://…",
+    "EKWO_ACT_AS_USER_ID": "the auth.users id this server acts for"
+  }
+}
+```
+
+`EKWO_ACT_AS_USER_ID` is **required**, and that is the whole point of this
+mode. A database connection is nobody: `auth.uid()` is null, row level
+security is bypassed rather than satisfied, and a server running that way
+would be a way round the policies rather than a client of them. So every
+query runs inside a transaction that sets `request.jwt.claims` to that user
+and switches to the `authenticated` role, and the policies bind exactly as
+they do over the API. This mode needs the `postgres` package installed
+alongside the server; the recommended route needs no driver at all.
+
+| Variable | Meaning |
+|---|---|
+| `SUPABASE_URL` | `https://<ref>.supabase.co` |
+| `SUPABASE_ANON_KEY` | The anon (publishable) key. A `service_role` key is refused. |
+| `EKWO_EMAIL` / `EKWO_PASSWORD` | The user this assistant acts as |
+| `EKWO_ACCESS_TOKEN` | A session already in hand, instead of the two above |
+| `EKWO_DB_URL` | A direct Postgres connection, for a self-hosted installation |
+| `EKWO_ACT_AS_USER_ID` | Required with `EKWO_DB_URL`: the `auth.users` id to act for |
+
+## The tools
+
+Every write names its company explicitly.
+
+| Tool | What it does |
+|---|---|
+| `list_companies` | The companies you are a member of, with your role on each |
+| `get_company` | Financial years, lock dates, journals, default accounts |
+| `list_accounts` | The accounts a company works with, by code prefix, type or name. `include_all` for the whole chart |
+| `search_contacts` | Customers and suppliers, by name, type or VAT number |
+| `search_products` | The catalogue: code, unit, price, account and tax of what is sold and bought |
+| `list_documents` | Invoices, credit notes and quotes, filtered |
+| `get_document` | One document with its lines and the entry it produced |
+| `list_bank_accounts` | The bank accounts of a company, with the journal and ledger account behind each |
+| `list_bank_transactions` | Statement lines, pending by default |
+| `trial_balance` | Opening, movements and closing per account |
+| `general_ledger` | Every posted line of an account, with a running balance |
+| `aged_balance` | What is still owed, bucketed by age, read from the ledger |
+| `vat_return` | The boxes for a period, summed from the ledger |
+| `ec_sales_list` | The recapitulative statement of intra-Community supplies: one line per customer VAT number and per nature |
+| `portfolio_upcoming_filings` | *Portfolio* = the companies you may read: for an accounting firm, its clients ([`docs/firms.md`](../../docs/firms.md)). What falls due between two dates in every company you hold `filings.read` on. One row per company at least: a pack that names no deadline is listed without a date, and says so |
+| `portfolio_filings_touched_since` | Declarations that have gone and whose period received entries afterwards, across the same companies, with the company named |
+| `list_statements` / `financial_statement` | The schemes a company can be presented on, and one statement |
+| `generate_fec` | The French FEC as text, with its checks and its filename |
+| `read_audit_log` | Who changed what and when: the configuration of a company, and the acts that change a state. Append-only; nothing writes it |
+| `get_preferences` | What you prefer, and the language chain to read labels with |
+| `list_invitations` | Who has been invited into a company and not yet joined |
+| `list_api_keys` | The machine keys of a company, and what each may do |
+| `describe_pack` | Which country packs this installation holds: their version, how much anyone has read them, and the register of texts each was built from — title, official publisher, link and the day it was opened |
+| `status` | Schema version, instance, connection, companies |
+| `create_contact` | A customer, supplier or other third party |
+| `create_product` | A catalogue row: code, name, unit, price, account, tax |
+| `update_product` | Changes one, or retires it with `active: false` |
+| `pin_accounts` | Adds accounts to the working chart a company sees first, or takes one back out with `pinned: false` |
+| `create_document` | A draft invoice, credit note or quote, with its lines. With `client_ref`, calling twice creates once |
+| `update_document_lines` | Replaces the lines of a **draft** |
+| `post_document` | Books it. Cannot be undone. `dry_run: true` returns the entry the database would write, and writes nothing |
+| `record_payment` | Books money in or out and matches it against open invoices — or, with `document_id`, against that document alone, which then names the contact and the direction. With `client_ref`, recording twice records once |
+| `reconcile` / `unreconcile` | Matches two ledger lines, or undoes one matching |
+| `create_bank_account` | Registers an account from its IBAN and wires it to the bank journal. Running it twice with the same IBAN creates nothing |
+| `create_bank_transaction` | One statement line by hand, for an installation with no feed |
+| `import_bank_statement` | A statement file (`camt.053`, `coda`, `cfonb120`) into statements and pending lines. Books nothing; the same file twice creates nothing; an unknown account or a statement that does not add up is refused by name, a missing statement is signalled |
+| `lock_period` | Moves the accounting and VAT lock dates. Needs `company.write`. |
+| `opening_balance` | The trial balance of whatever kept the books before, as the opening entry |
+| `close_fiscal_year` / `reopen_fiscal_year` | Closes a year the way the country pack says, or reverses a close run too early |
+| `create_company` | A company on a country pack, with its chart and its first financial year. An instance-level act |
+| `update_company_profile` | What a company says about itself on its documents |
+| `set_preferences` | Your own language, timezone, formats and default company |
+| `invite_member` / `revoke_invitation` | Invites an address into a company, or withdraws the invitation. The token is shown once |
+| `create_api_key` / `revoke_api_key` | A key for a machine, scoped to one company and a list of capabilities |
+
+**`list_accounts` answers with the working chart, not the whole one.** A
+country pack transcribes the regulation — 353 accounts in Belgium, 1 026 in
+Luxembourg — and a company works with a few dozen of them, so the default is
+what `accounts_in_use()` returns: the accounts carrying posted entries, those
+the company's own settings or an enabled module point at, and those somebody
+pinned, minus the deprecated ones. Every answer carries a `scope` field saying
+which it used. `in_use_from` and `in_use_to` narrow the movements to a period;
+`include_all` returns the whole chart; `include_deprecated` returns it with the
+retired accounts too; and `ekwo://companies/{id}/chart` was already the
+resource that carries everything. None of this restricts anything: a document
+line may name any account of the chart that is not deprecated, and every write
+tool still accepts one.
+
+`post_document`, `record_payment`, `update_document_lines`, `unreconcile`,
+`lock_period`, `opening_balance`, `close_fiscal_year`, `reopen_fiscal_year`,
+`revoke_invitation` and `revoke_api_key` are annotated destructive in the
+protocol, so a client can ask before calling them.
+
+**What a tool may do is the capability the user holds**, not the tool's own
+right: the server acts as the person it signed in as, so `post_document` works
+for an accountant and is refused to a viewer, by the database, with the
+database's own words. `get_company` returns `your_capabilities` for exactly
+that reason.
+
+**The modules.** A module of this installation gets its own tools, under the
+prefix its `module.json` declares, and the server reads `public.modules` at
+startup to know which: `assets_list`, `assets_create`, `assets_schedule`,
+`assets_run_depreciation`, `assets_dispose`, `budgets_list`,
+`budgets_upsert_lines`, `budgets_variance`. A module that is not installed is
+not offered, because a tool a model cannot use is worse than a tool it cannot
+see. PostgREST serves a module's schema only once the project exposes it, and
+the refusal it answers with is a profile error that says nothing useful — so
+every module tool turns it into the sentence that names the setting.
+
+**Resources.** `ekwo://companies/{id}/chart` is the whole chart of accounts;
+`ekwo://companies/{id}/taxes` is every tax with the ledger account and the
+declaration box each of its postings feeds.
+
+**Prompts.** `close_month` walks the month-end checklist — drafts, unmatched
+bank lines, the balance, the VAT, what is still open. `prepare_vat_return`
+pulls the boxes and ties them back to the ledger before anything is filed.
+
+## Conventions
+
+- **Amounts are decimal strings.** `"1210.00"`, never a float. They go in that
+  way and come back that way, because `numeric` is exact and a float is not.
+- **Dates are ISO**, `2026-06-15`. Identifiers are uuids.
+- **Totals are computed by the database.** `create_document` returns the draft
+  with the totals the schema derived, not with anything the caller supplied.
+- **Refusals travel unchanged.** `period_locked:`, `entry_unbalanced:`,
+  `document_total_mismatch:` and the rest arrive with the message the database
+  raised, plus one sentence saying what it means. They are answers, not
+  obstacles to route around.
+- **A product fills a line in and never constrains it.** A line naming
+  `product_code` takes the catalogue's text, description, unit, price, account
+  and tax; anything the line carries wins over that. What is already posted is
+  never touched when the catalogue changes, and a product referenced by a line
+  is retired with `active: false` rather than deleted.
+- **A missing tax is a missing tax.** A line with no tax books a base with no
+  VAT box, which is not the same as 0 %. A missing *account* is different: it
+  can only mean "resolve it", because a product line with no account is
+  refused by a check constraint. So a line may leave `account_code` out, and
+  the database fills it — the company default, then the country model.
+
+## Testing it by hand
+
+The automated tests run every tool against the real schema in Postgres
+compiled to WebAssembly (`tests/mcp/`), including the refusals. Two things
+they cannot run: PostgREST and GoTrue. To exercise those, on a project you can
+throw away:
+
+```sh
+npx ekwo init --country BE --org "Scratch" --company "Scratch BV" …   # a real project
+```
+
+Then point a client at it — in Claude Desktop, the JSON block above — and:
+
+1. **"List my companies."** The company you created, with `your_role: owner`.
+2. **"What are the journals and the lock dates?"** `get_company`.
+3. **"Create a customer called Dumont, then invoice them 1 000 € plus 21 %
+   VAT for consulting."** `create_contact`, then `create_document`; the answer
+   carries `amount_total: "1210.00"` computed by the database.
+   Or with a catalogue: **"add a product CONS-JOUR, a consulting day at 500 €
+   on 704000 at 21 %, then invoice Dumont two of them"** — `create_product`,
+   then `create_document` with `product_code` and nothing else on the line.
+4. **"Post it."** `post_document`. The entry books 704 / 451 / 400 and takes a
+   number like `SAL/2026/0001`.
+5. **"They paid 500 € on the 10th."** `record_payment`, which books the bank
+   line and matches it; the invoice becomes partially paid.
+6. **"Show me the trial balance and the VAT for the quarter."**
+   `trial_balance` and `vat_return`.
+7. **"Lock June."** `lock_period`, then try to post something dated in June:
+   the refusal comes back as `period_locked:`.
+
+A payment needs somewhere to book the bank side. On a company installed from a
+country model the bank and cash journals already point at their account
+(`550000` and `570000` in Belgium, `512000` and `530000` in France), so
+`record_payment` works with nothing else set up. `create_bank_account` names
+the real account — the IBAN is the one thing nobody can derive — and wires it
+to the journal; `bank_account_id` on the payment then says which one the money
+moved on, which is what you need with several accounts in one journal. Until a
+company has one, `ekwo doctor` says so.
+
+## Licence
+
+[AGPL-3.0-only](../../LICENSE) © Ekwo AI.

package/dist/backend.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The one interface every tool is written against.
+ *
+ * There are two ways to reach an Ekwo database and neither of them is a
+ * privileged one. The recommended route is PostgREST with the signed-in
+ * user's own token, which is how the schema is meant to be read and written:
+ * row level security decides, exactly as it would for that person in a
+ * browser. The second is a direct Postgres connection, for a self-hosted
+ * installation and for the tests — and even there the claims and the role are
+ * set on every call, so the same policies apply.
+ *
+ * Tools therefore never see a client, a token or a connection string. They
+ * see `select`, `insert`, `update`, `remove` and `rpc`, and what comes back
+ * is whatever the policies let through.
+ */
+import { BooksError, columnName, identifier, qualified, socleCode, type Backend, type Filter, type Order, type Row, type SelectQuery, type Value } from '@ekwo-ai/core';
+export { columnName, identifier, qualified, socleCode };
+export type { Backend, Filter, Order, Row, SelectQuery, Value };
+/** The core's error, under the name this package has always exported. */
+export declare const EkwoMcpError: typeof BooksError;
+export type EkwoMcpError = BooksError;
+/** The socle error, with the sentence that explains it when we have one. */
+export declare function explain(message: string): EkwoMcpError;
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,UAAU,EACV,UAAU,EACV,UAAU,EACV,SAAS,EACT,SAAS,EACT,KAAK,OAAO,EACZ,KAAK,MAAM,EACX,KAAK,KAAK,EACV,KAAK,GAAG,EACR,KAAK,WAAW,EAChB,KAAK,KAAK,EACX,MAAM,eAAe,CAAC;AAKvB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;AACxD,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;AAEhE,yEAAyE;AACzE,eAAO,MAAM,YAAY,mBAAa,CAAC;AACvC,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC;AAuEtC,4EAA4E;AAC5E,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAcrD"}

package/dist/backend.js

@@ -0,0 +1,105 @@
+/**
+ * The one interface every tool is written against.
+ *
+ * There are two ways to reach an Ekwo database and neither of them is a
+ * privileged one. The recommended route is PostgREST with the signed-in
+ * user's own token, which is how the schema is meant to be read and written:
+ * row level security decides, exactly as it would for that person in a
+ * browser. The second is a direct Postgres connection, for a self-hosted
+ * installation and for the tests — and even there the claims and the role are
+ * set on every call, so the same policies apply.
+ *
+ * Tools therefore never see a client, a token or a connection string. They
+ * see `select`, `insert`, `update`, `remove` and `rpc`, and what comes back
+ * is whatever the policies let through.
+ */
+import { BooksError, columnName, identifier, qualified, socleCode, } from '@ekwo-ai/core';
+// Moved to the core, where the command line reads them too: what a refusal is
+// called, what a backend is and what an error of this layer looks like cannot
+// be decided twice. Still exported from here, under the names they always had.
+export { columnName, identifier, qualified, socleCode };
+/** The core's error, under the name this package has always exported. */
+export const EkwoMcpError = BooksError;
+/**
+ * What each socle refusal means, in one sentence.
+ *
+ * Only the codes a client of this server can actually provoke are listed. An
+ * unknown code is not a failure of this table: the raw message is already the
+ * answer, and the sentence is the part that was optional.
+ */
+const HINTS = {
+    period_locked: 'The company has an accounting lock date on or after this date. Ask the owner to move lock_date, or book on a later date.',
+    tax_period_locked: 'The company has a VAT lock date covering this date. Anything carrying a declaration box is frozen there.',
+    fiscal_year_closed: 'The financial year covering this date is closed. Reopen it, or book in an open year.',
+    entry_unbalanced: 'The debit and the credit of the entry differ. Nothing was posted.',
+    entry_empty: 'The entry has no lines.',
+    document_empty: 'The document has no billable line, so there is nothing to book.',
+    document_already_posted: 'This document has already been booked. Read it back rather than posting it twice.',
+    document_already_booked: 'This document already points at an entry. Read it back rather than posting it twice.',
+    document_cancelled: 'A cancelled document cannot be booked.',
+    entry_posted: 'A posted entry is immutable, in an open period too: its lines, its date, its state, and it is not deleted. Undo it with a reversal entry that names it in reversed_entry_id.',
+    entry_posted_by_hand: 'An entry becomes posted through post_entry, which draws its number from the journal counter, dates the posting and checks the period. Setting the state by hand is refused unless the row is exactly what post_entry would have written.',
+    document_posted_by_hand: 'A document becomes posted through post_document, which builds its entry. Setting the state by hand on an entry that was not built for this document is refused.',
+    entry_born_posted: 'An entry is created as a draft and posted with post_entry. One that is already posted arrives only with a company loaded from an archive, by import_company.',
+    document_posted: 'This document was issued, and what produced an entry does not change afterwards: not its lines, not its figures, not its state, and it is not deleted. Correct it with a credit note that names it in reversed_document_id, and issue another.',
+    document_born_posted: 'A document is created as a draft and posted with post_document. One that is already posted arrives only with a company loaded from an archive, by import_company.',
+    document_posted_without_entry: 'A document becomes posted through post_document, which builds its entry. Setting the state by hand is refused.',
+    document_amount_paid_is_derived: 'What a document was settled by comes from the matching of its entry. Match a payment or a credit note against it instead of writing the figure.',
+    document_payment_state_is_derived: 'The settlement state follows from what was matched against the document. It is never written.',
+    document_not_accountable: 'Quotes and purchase orders are not booked. Turn it into an invoice first.',
+    document_total_mismatch: 'The header total disagrees with what the lines book. The lines are right by construction, so the header is what needs fixing.',
+    tax_not_in_force: 'That tax is not applicable on the accounting date. Pick the tax in force for that period.',
+    unsupported_tax_amount_type: 'Only percentage taxes can be posted; a fixed-amount tax has no basis to spread.',
+    no_counterpart_account: 'No receivable or payable account is set, either on the contact or as a company default.',
+    no_journal: 'No journal was given and the company has no default for this kind of document.',
+    unknown_bank_account: 'The statement is of an account this company does not have, and an import never creates one: an account nobody decided is mapped to no journal. create_bank_account adds it; then import the file again.',
+    unbalanced_statement: 'The opening balance plus the booked lines is not the closing balance the bank declared, so a line is missing or altered. Nothing was imported; get the file again from the bank.',
+    statement_without_balances: 'Without an opening and a closing balance nothing proves the lines are all there. Nothing was imported.',
+    unreadable_statement_line: 'A booked line cannot be held as it is — no amount, no date, another currency than the account, or more decimals than the ledger keeps. Nothing was imported.',
+    statement_conflict: 'A statement with this identifier and date was already imported with other balances. The bank may have reissued it; nothing was changed.',
+    statement_currency_mismatch: 'The statement is in another currency than the bank account it belongs to. Nothing is converted on import.',
+    bank_account_mismatch: 'The bank account named is not the account the statement is of.',
+    no_bank_account: 'The payment names no bank account and its journal has no default account. create_bank_account adds one and wires it to the journal.',
+    missing_account: 'The line names no account, and the company and its country model have no default for this kind of document. Give account_code on the line, or set the company default.',
+    payment_already_booked: 'This payment already has an entry.',
+    payment_cancelled: 'A cancelled payment cannot be booked.',
+    reconcile_same_side: 'Matching pairs a debit with a credit; both lines are on the same side.',
+    reconcile_account_mismatch: 'The two lines are on different accounts.',
+    reconcile_over_debit: 'The amount is larger than what is still open on the debit line.',
+    reconcile_over_credit: 'The amount is larger than what is still open on the credit line.',
+    reconcile_nothing_left: 'Both lines are already fully matched.',
+    account_not_reconcilable: 'That account is not reconcilable, so nothing on it can be matched.',
+    unknown_document: 'No document with that id is visible to you.',
+    unknown_entry_line: 'No ledger line with that id is visible to you.',
+    unknown_reconciliation: 'No matching with that id is visible to you.',
+    unknown_payment: 'No payment with that id is visible to you.',
+};
+/**
+ * Check constraints that a client can legitimately provoke, in the words a
+ * model can act on.
+ *
+ * Postgres names the constraint and nothing else — "violates check constraint
+ * document_lines_product_has_account" says which rule broke and not what to
+ * do. These few are the ones reachable through a tool, so they get the same
+ * shape as a socle raise: an identifier, then a sentence.
+ */
+const CONSTRAINTS = {
+    document_lines_product_has_account: 'missing_account: a line has no account, and neither the product, the company nor the country model supplies a default for this kind of document',
+};
+/** The socle error, with the sentence that explains it when we have one. */
+export function explain(message) {
+    for (const [constraint, rewritten] of Object.entries(CONSTRAINTS)) {
+        if (message.includes(constraint)) {
+            const code = socleCode(rewritten);
+            const hint = code === undefined ? undefined : HINTS[code];
+            return new EkwoMcpError(rewritten, {
+                ...(code !== undefined ? { code } : {}),
+                ...(hint !== undefined ? { hint } : {}),
+            });
+        }
+    }
+    const code = socleCode(message);
+    const hint = code === undefined ? undefined : HINTS[code];
+    return new EkwoMcpError(message, { ...(code !== undefined ? { code } : {}), ...(hint !== undefined ? { hint } : {}) });
+}
+//# sourceMappingURL=backend.js.map

package/dist/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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"}

package/dist/bin.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * `npx @ekwo-ai/mcp`, over stdio.
+ *
+ * Everything comes from the environment, because that is how an MCP client
+ * launches a server: a command and a block of variables in
+ * `claude_desktop_config.json` or `.mcp.json`. Nothing is read from a file
+ * and nothing is written to one — a credential cache would save one paste and
+ * turn the first accidental `git add .` into a disclosure.
+ *
+ * stdout belongs to the protocol. Anything this process has to say to a human
+ * goes to stderr, or the client sees a parse error instead of a server.
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;GAWG"}

package/dist/bin.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * `npx @ekwo-ai/mcp`, over stdio.
+ *
+ * Everything comes from the environment, because that is how an MCP client
+ * launches a server: a command and a block of variables in
+ * `claude_desktop_config.json` or `.mcp.json`. Nothing is read from a file
+ * and nothing is written to one — a credential cache would save one paste and
+ * turn the first accidental `git add .` into a disclosure.
+ *
+ * stdout belongs to the protocol. Anything this process has to say to a human
+ * goes to stderr, or the client sees a parse error instead of a server.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { openBackend, readConfig } from './config.js';
+import { assertSchemaSupported } from './schema.js';
+import { SERVER_VERSION, buildServer } from './server.js';
+import { installedModules } from './tools/modules.js';
+async function main() {
+    const argument = process.argv[2];
+    if (argument === '--help' || argument === '-h') {
+        process.stderr.write(HELP);
+        return;
+    }
+    if (argument === '--version' || argument === '-v') {
+        process.stderr.write(`${SERVER_VERSION}\n`);
+        return;
+    }
+    const config = readConfig(process.env);
+    const backend = await openBackend(config);
+    // Before anything else: a database older than this server is refused by
+    // name rather than answered from wrong assumptions.
+    const schemaVersion = await assertSchemaSupported(backend);
+    // What this installation carries, from the registry table. A database that
+    // predates the module framework answers with nothing, and the socle's own
+    // tools are all a client then sees.
+    const modules = await installedModules(backend);
+    const server = buildServer(backend, { modules });
+    const shutdown = async () => {
+        await server.close().catch(() => { });
+        await backend.close().catch(() => { });
+        process.exit(0);
+    };
+    process.on('SIGINT', () => void shutdown());
+    process.on('SIGTERM', () => void shutdown());
+    await server.connect(new StdioServerTransport());
+    process.stderr.write(`ekwo-mcp: connected over ${config.mode === 'sql' ? 'a direct Postgres connection' : 'PostgREST as the signed-in user'}` +
+        `, schema ${schemaVersion}` +
+        `${modules.length > 0 ? `, modules: ${modules.join(', ')}` : ''}\n`);
+}
+const HELP = `ekwo-mcp — the Model Context Protocol server for Ekwo OS.
+
+It speaks MCP over stdio and is started by a client, not by hand. Configure it
+in claude_desktop_config.json or .mcp.json with:
+
+  SUPABASE_URL            https://<ref>.supabase.co
+  SUPABASE_ANON_KEY       the anon (publishable) key — never the service_role key
+  EKWO_EMAIL              the user this assistant acts as
+  EKWO_PASSWORD           their password
+  EKWO_ACCESS_TOKEN       an access token, instead of the two above
+
+For a self-hosted database, without PostgREST in front of it:
+
+  EKWO_DB_URL             postgresql://…
+  EKWO_ACT_AS_USER_ID     the auth.users id this server acts for — required,
+                          because a database connection is nobody
+
+Row level security applies either way. This server has no privileges of its
+own and refuses a service_role key.
+`;
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,KAAK,UAAU,IAAI;IACjB,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC/C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3B,OAAO;IACT,CAAC;IACD,IAAI,QAAQ,KAAK,WAAW,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QAClD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,cAAc,IAAI,CAAC,CAAC;QAC5C,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,wEAAwE;IACxE,oDAAoD;IACpD,MAAM,aAAa,GAAG,MAAM,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC3D,2EAA2E;IAC3E,0EAA0E;IAC1E,oCAAoC;IACpC,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAEjD,MAAM,QAAQ,GAAG,KAAK,IAAmB,EAAE;QACzC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACrC,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAC;IAE7C,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IACjD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,4BAA4B,MAAM,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,8BAA8B,CAAC,CAAC,CAAC,iCAAiC,EAAE;QACtH,YAAY,aAAa,EAAE;QAC3B,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CACtE,CAAC;AACJ,CAAC;AAED,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;CAmBZ,CAAC;AAEF,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACpF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/columns.d.ts

@@ -0,0 +1,59 @@
+/**
+ * What each tool reads back, written once.
+ *
+ * Two rules run through every list. A `numeric` column is asked for as
+ * `amount::text`, so the exact decimal arrives rather than a float; a `date`
+ * or a timestamp likewise, so `2026-06-15` is a string on both routes instead
+ * of whatever a driver decided a date object should be. Everything else —
+ * uuid, text, boolean, integer — crosses unchanged.
+ */
+export declare const COMPANY: string[];
+export declare const FISCAL_YEAR: string[];
+export declare const ACCOUNT: string[];
+export declare const JOURNAL: string[];
+export declare const CONTACT: string[];
+export declare const TAX: string[];
+export declare const DOCUMENT: string[];
+/**
+ * The mentions the law of a country puts on one document, from the view that
+ * decides which of them apply. `text_i18n` crosses as it is: a renderer picks
+ * the language, and the server has no business choosing one.
+ */
+export declare const DOCUMENT_LEGAL_MENTION: string[];
+/**
+ * What the country of a document requires of it, beside the mentions: the
+ * payment term the law sets, how the number is built, when the tax falls due
+ * and how the document is exchanged. Read from `country_defaults`, which
+ * holds null wherever the pack has said nothing — and null is the answer, not
+ * an invitation to substitute another country's.
+ */
+export declare const COUNTRY_DOCUMENT_RULES: string[];
+/**
+ * The header of a document, from the view that assembles it: the seller, the
+ * buyer, the amounts, where it is paid and what the country of the document
+ * requires. `document_line_items` is the lines and `document_legal_mentions`
+ * the sentences — three reads, and no client holding a copy of the
+ * letterhead.
+ */
+export declare const DOCUMENT_HEADER: string[];
+export declare const PRODUCT: string[];
+export declare const DOCUMENT_LINE: string[];
+export declare const ENTRY: string[];
+export declare const ENTRY_LINE: string[];
+export declare const BANK_ACCOUNT: string[];
+export declare const BANK_TRANSACTION: string[];
+export declare const PAYMENT: string[];
+/**
+ * An invitation, without its secret. `token_hash` is deliberately absent: it
+ * is of no use to a client, and a list of hashes is a thing to leak rather
+ * than a thing to show.
+ */
+/** What one person chose for themselves. Null everywhere is the fresh state. */
+export declare const USER_PREFERENCES: string[];
+export declare const INVITATION: string[];
+/** A machine key, without its hash. The secret is returned once, elsewhere. */
+export declare const API_KEY: string[];
+export declare const INSTANCE: string[];
+export declare const RECONCILIATION: string[];
+export declare const AUDIT_LOG: string[];
+//# sourceMappingURL=columns.d.ts.map

package/dist/columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"columns.d.ts","sourceRoot":"","sources":["../src/columns.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,OAAO,UAqCnB,CAAC;AAEF,eAAO,MAAM,WAAW,UAAoE,CAAC;AAE7F,eAAO,MAAM,OAAO,UASnB,CAAC;AAEF,eAAO,MAAM,OAAO,UAAmD,CAAC;AAExE,eAAO,MAAM,OAAO,UAYnB,CAAC;AAEF,eAAO,MAAM,GAAG,UAsBf,CAAC;AAEF,eAAO,MAAM,QAAQ,UAqBpB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,UAOlC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,UAWlC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,UAmE3B,CAAC;AAEF,eAAO,MAAM,OAAO,UAgBnB,CAAC;AAEF,eAAO,MAAM,aAAa,UAiBzB,CAAC;AAEF,eAAO,MAAM,KAAK,UAejB,CAAC;AAEF,eAAO,MAAM,UAAU,UAsBtB,CAAC;AAEF,eAAO,MAAM,YAAY,UAUxB,CAAC;AAEF,eAAO,MAAM,gBAAgB,UAiB5B,CAAC;AAEF,eAAO,MAAM,OAAO,UAcnB,CAAC;AAEF;;;;GAIG;AACH,gFAAgF;AAChF,eAAO,MAAM,gBAAgB,UAS5B,CAAC;AAEF,eAAO,MAAM,UAAU,UAYtB,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,OAAO,UAWnB,CAAC;AAEF,eAAO,MAAM,QAAQ,UAQpB,CAAC;AAEF,eAAO,MAAM,cAAc,UAa1B,CAAC;AAEF,eAAO,MAAM,SAAS,UAarB,CAAC"}