bkper 3.3.3 → 3.5.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 2025
+
+### **July 2025**
+
+**MCP Server**
+- Added support for AI assistants to analyze your books with monthly and year-to-date balances
+- Improved date filtering with more intuitive `before:` operator
+- Added setup instructions for Claude Desktop and other AI tools
+
+### **June 2025**
+
+**bkper-node CLI**
+- Introduced MCP server - connect AI assistants to your Bkper books with `bkper mcp start`
+- Added book name filtering to quickly find specific books

package/README.md

@@ -34,6 +34,7 @@ yarn global add bkper
 - ```logout```  - Logs out the user by deleting client credentials.
 - ```app -c```  - Create a new App based on ```./bkperapp.yaml``` file.
 - ```app -u```  - Update an existing App based on ```./bkperapp.yaml``` file.
+- ```mcp start``` - Start the Bkper MCP (Model Context Protocol) server.
 
 ### Examples
 ```
@@ -76,9 +77,13 @@ id: my-custom-app
 # The readable name of the App or Bot.
 name: My Custom App
 
-# Set your logo url from public host. Best fit 200x200 px. Use https://
+# The logo url from public host. Best fit 200x200 px. Use https://
 logoUrl: https://static.thenounproject.com/png/2318500-200.png
 
+# The logo url to be used when in dark mode
+logoUrlDark: https://static.thenounproject.com/png/2318500-200.png
+
+
 
 # CONTEXT MENU CONFIGURATION
 
@@ -95,15 +100,17 @@ menuPopupWidth: 500 # width in pixels. Default to 80% of screen width.
 menuPopupHeight: 300 # height in pixels. Default to 90% of screen height.
 
 
-# BOT EVENTS CONFIGURATION
+#ASSISTANT CONFIGURATION
+
+# The conversation url to be called by Bkper when a new conversation message is added
+conversationUrl: https://us-central1-bkper-tax-trigger.cloudfunctions.net/chat
 
-# The production webhook url to be called by Bkper when an event occurs.
-webhookUrl: https://us-central1-bkper-tax-trigger.cloudfunctions.net/prod
 
-# The development webhook url to be called while developing. 
-# It will be prioritized over webhookUrl when the bot is running by the app owner or developer. 
-# Unset it when done developing.
-webhookUrlDev: https://9850-2804-1b2-1003-88ab-bca4-9ed8-d199-bb7f.ngrok-free.app
+
+# BOT EVENTS CONFIGURATION
+
+# The webhook url to be called by Bkper when an event occurs.
+webhookUrl: https://us-central1-bkper-tax-trigger.cloudfunctions.net/events
 
 # The events the Bot is capable of processing by the webhook. 
 # This is optional and, if not specified, no events will be processed.
@@ -195,6 +202,72 @@ Bkper.setConfig({
 })
 ```
 
+### MCP (Model Context Protocol) Server
+
+Bkper includes an MCP server that allows AI assistants and other tools to interact with your Bkper books through the [Model Context Protocol](https://modelcontextprotocol.io).
+
+#### Starting the MCP Server
+
+```bash
+bkper mcp start
+```
+
+The server runs on stdio and provides the following tools:
+
+- **list_books** - List all books accessible by the authenticated user
+- **get_book** - Get details of a specific book by ID
+- **get_balances** - Get account balances for a specific date or period
+- **list_transactions** - List transactions with filtering options
+
+#### Prerequisites
+
+Before using the MCP server:
+1. Login using `bkper login` to set up authentication
+2. Ensure the `BKPER_API_KEY` environment variable is set
+
+The MCP server uses the same authentication as the CLI, reading credentials from `~/.bkper-credentials.json`.
+
+#### Integration Examples
+
+##### Claude Desktop
+
+Add to your configuration file:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "bkper": {
+      "command": "npx",
+      "args": ["bkper", "mcp", "start"],
+      "env": {
+        "BKPER_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+##### Other MCP Clients
+
+For other MCP-compatible clients, configure them to run:
+```bash
+BKPER_API_KEY=your-api-key npx bkper mcp start
+```
+
+The server communicates via stdio, so any MCP client that supports stdio transport can connect to it.
+
+#### Available MCP Tools
+
+Once connected, the MCP client can:
+- List your Bkper books
+- Get account balances for any date or period
+- Search and filter transactions
+- Analyze your financial data
+
+For more information about the Model Context Protocol, visit [modelcontextprotocol.io](https://modelcontextprotocol.io).
+
 
 
 ## Documentation

package/lib/cli.js

@@ -8,12 +8,13 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { App, Bkper } from 'bkper-js';
+import { App } from 'bkper-js';
 import program from 'commander';
 import fs from 'fs';
 import * as YAML from 'yaml';
-import { getOAuthToken, login, logout } from './auth/local-auth-service.js';
+import { login, logout } from './auth/local-auth-service.js';
 import dotenv from 'dotenv';
+import { setupBkper } from './mcp/bkper-factory.js';
 dotenv.config();
 program
     .command('login')
@@ -34,10 +35,7 @@ program
     .option('-c, --create', 'Create a new App')
     .action((options) => __awaiter(void 0, void 0, void 0, function* () {
     try {
-        Bkper.setConfig({
-            apiKeyProvider: () => __awaiter(void 0, void 0, void 0, function* () { return process.env.BKPER_API_KEY || ''; }),
-            oauthTokenProvider: () => getOAuthToken()
-        });
+        setupBkper();
         let json;
         if (fs.existsSync('./bkperapp.json')) {
             json = JSON.parse(fs.readFileSync('./bkperapp.json', 'utf8'));
@@ -66,5 +64,21 @@ program
         console.log(err);
     }
 }));
+const mcpCommand = program.command('mcp').description('Bkper MCP server commands');
+mcpCommand
+    .command('start')
+    .description('Start Bkper MCP server')
+    .action(() => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        // Import and start the MCP server directly
+        const { BkperMcpServer } = yield import('./mcp/server.js');
+        const server = new BkperMcpServer();
+        yield server.run();
+    }
+    catch (err) {
+        console.error('Error starting MCP server:', err);
+        process.exit(1);
+    }
+}));
 program.parse(process.argv);
 //# sourceMappingURL=cli.js.map

package/lib/cli.js.map

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

package/lib/mcp/bkper-factory.d.ts

@@ -0,0 +1,10 @@
+import { Bkper } from 'bkper-js';
+/**
+ * Get a configured Bkper instance with authentication setup.
+ * Uses singleton pattern to avoid repeated configuration.
+ *
+ * @returns Configured Bkper instance
+ */
+export declare function getBkperInstance(): Bkper;
+export declare function setupBkper(): void;
+//# sourceMappingURL=bkper-factory.d.ts.map

package/lib/mcp/bkper-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bkper-factory.d.ts","sourceRoot":"","sources":["../../src/mcp/bkper-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAKjC;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,KAAK,CAiBxC;AAED,wBAAgB,UAAU,SAKzB"}

package/lib/mcp/bkper-factory.js

@@ -0,0 +1,40 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { Bkper } from 'bkper-js';
+import { getOAuthToken } from '../auth/local-auth-service.js';
+let configuredBkperInstance = undefined;
+/**
+ * Get a configured Bkper instance with authentication setup.
+ * Uses singleton pattern to avoid repeated configuration.
+ *
+ * @returns Configured Bkper instance
+ */
+export function getBkperInstance() {
+    // Return mock instance if in test environment
+    if (process.env.NODE_ENV === 'test' || globalThis.__mockBkper) {
+        return globalThis.__mockBkper || Bkper;
+    }
+    // Return cached instance if already configured
+    if (configuredBkperInstance) {
+        return configuredBkperInstance;
+    }
+    // Configure Bkper with authentication
+    setupBkper();
+    // Cache the configured instance
+    configuredBkperInstance = new Bkper();
+    return configuredBkperInstance;
+}
+export function setupBkper() {
+    Bkper.setConfig({
+        apiKeyProvider: () => __awaiter(this, void 0, void 0, function* () { return process.env.BKPER_API_KEY || ''; }),
+        oauthTokenProvider: () => getOAuthToken()
+    });
+}
+//# sourceMappingURL=bkper-factory.js.map

package/lib/mcp/bkper-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bkper-factory.js","sourceRoot":"","sources":["../../src/mcp/bkper-factory.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAE9D,IAAI,uBAAuB,GAAsB,SAAS,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB;IAC9B,8CAA8C;IAC9C,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,IAAK,UAAkB,CAAC,WAAW,EAAE,CAAC;QACvE,OAAQ,UAAkB,CAAC,WAAW,IAAI,KAAK,CAAC;IAClD,CAAC;IAED,+CAA+C;IAC/C,IAAI,uBAAuB,EAAE,CAAC;QAC5B,OAAO,uBAAuB,CAAC;IACjC,CAAC;IAED,sCAAsC;IACtC,UAAU,EAAE,CAAC;IACb,gCAAgC;IAChC,uBAAuB,GAAG,IAAI,KAAK,EAAE,CAAC;IAEtC,OAAO,uBAAuB,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,KAAK,CAAC,SAAS,CAAC;QACd,cAAc,EAAE,GAAS,EAAE,gDAAC,OAAA,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAA,GAAA;QAC3D,kBAAkB,EAAE,GAAG,EAAE,CAAC,aAAa,EAAE;KAC1C,CAAC,CAAC;AACL,CAAC"}

package/lib/mcp/server.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { CallToolResult, ListToolsResult } from '@modelcontextprotocol/sdk/types.js';
+declare class BkperMcpServer {
+    private server;
+    constructor();
+    private setupToolHandlers;
+    private setupErrorHandling;
+    run(): Promise<void>;
+    testListTools(): Promise<ListToolsResult>;
+    testCallTool(name: string, args?: Record<string, unknown>): Promise<CallToolResult>;
+}
+export { BkperMcpServer };
+//# sourceMappingURL=server.d.ts.map

package/lib/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":";AAOA,OAAO,EAEL,cAAc,EAGd,eAAe,EAEhB,MAAM,oCAAoC,CAAC;AAO5C,cAAM,cAAc;IAClB,OAAO,CAAC,MAAM,CAAS;;IAmBvB,OAAO,CAAC,iBAAiB;IAgCzB,OAAO,CAAC,kBAAkB;IAWpB,GAAG;IAOH,aAAa,IAAI,OAAO,CAAC,eAAe,CAAC;IAczC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,cAAc,CAAC;CAc9F;AAGD,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/lib/mcp/server.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import dotenv from 'dotenv';
+dotenv.config();
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { handleGetBook, getBookToolDefinition } from './tools/get_book.js';
+import { handleGetBalances, getBalancesToolDefinition } from './tools/get_balances.js';
+import { handleListTransactions, listTransactionsToolDefinition } from './tools/list_transactions.js';
+import { handleListBooks, listBooksToolDefinition } from './tools/list_books.js';
+class BkperMcpServer {
+    constructor() {
+        this.server = new Server({
+            name: 'bkper-mcp-server',
+            version: '1.0.0',
+        }, {
+            capabilities: {
+                tools: {}
+            }
+        });
+        this.setupToolHandlers();
+        this.setupErrorHandling();
+    }
+    setupToolHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, () => __awaiter(this, void 0, void 0, function* () {
+            return {
+                tools: [
+                    listBooksToolDefinition,
+                    getBookToolDefinition,
+                    getBalancesToolDefinition,
+                    listTransactionsToolDefinition,
+                ],
+            };
+        }));
+        this.server.setRequestHandler(CallToolRequestSchema, (request) => __awaiter(this, void 0, void 0, function* () {
+            switch (request.params.name) {
+                case 'list_books':
+                    return yield handleListBooks(request.params.arguments);
+                case 'get_book':
+                    return yield handleGetBook(request.params.arguments);
+                case 'get_balances':
+                    return yield handleGetBalances(request.params.arguments);
+                case 'list_transactions':
+                    return yield handleListTransactions(request.params.arguments);
+                default:
+                    throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
+            }
+        }));
+    }
+    setupErrorHandling() {
+        this.server.onerror = (error) => {
+            console.error('[MCP Error]', error);
+        };
+        process.on('SIGINT', () => __awaiter(this, void 0, void 0, function* () {
+            yield this.server.close();
+            process.exit(0);
+        }));
+    }
+    run() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const transport = new StdioServerTransport();
+            yield this.server.connect(transport);
+            console.error('Bkper MCP server running on stdio');
+        });
+    }
+    // Test helper methods for accessing MCP handlers directly
+    testListTools() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Call the list tools handler directly for testing
+            const requestHandlers = this.server._requestHandlers;
+            const handler = requestHandlers.get('tools/list');
+            if (!handler)
+                throw new Error('ListTools handler not found');
+            // Create proper MCP request format
+            const request = {
+                method: 'tools/list',
+                params: {}
+            };
+            return yield handler(request);
+        });
+    }
+    testCallTool(name_1) {
+        return __awaiter(this, arguments, void 0, function* (name, args = {}) {
+            // Call the call tool handler directly for testing  
+            const requestHandlers = this.server._requestHandlers;
+            const handler = requestHandlers.get('tools/call');
+            if (!handler)
+                throw new Error('CallTool handler not found');
+            // Create proper MCP request format
+            const request = {
+                method: 'tools/call',
+                params: { name, arguments: args }
+            };
+            return yield handler(request);
+        });
+    }
+}
+// Export the class for testing
+export { BkperMcpServer };
+// Only run the server if this file is executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const server = new BkperMcpServer();
+    server.run().catch(console.error);
+}
+//# sourceMappingURL=server.js.map

package/lib/mcp/server.js.map

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

package/lib/mcp/system-prompt.md

@@ -0,0 +1,192 @@
+# Bkper MCP Usage Guide
+
+## Essential Tools
+
+### Discovery
+- `list_books()` - Find available books
+- `get_book({ bookId })` - Book details, structure, and group hierarchies
+
+### Analysis
+- `get_balances({ bookId, query })` - **THE** tool for all balance analysis
+- `list_transactions({ bookId, query })` - Transaction inspection only (never for balance calculations)
+
+## Core Rules
+
+### 1. Root Group Discovery
+**Always discover and use root groups dynamically based on account group types:**
+1. Call `get_book({ bookId })` to see the hierarchy
+2. Look for the top-level group that contains:
+   - **For Balance Sheet**: Both ASSET and LIABILITY account types
+   - **For P&L**: Both INCOMING and OUTGOING account types
+3. Use that group name (not its children) in your queries
+
+**Example**: If you see this structure:
+```
+"Total Equity" (root)
+├── "Assets" (type: ASSET)
+├── "Liabilities" (type: LIABILITY)
+```
+Then use `group:'Total Equity'` - NOT `group:'Assets'` or `group:'Liabilities'`
+
+### 2. Date Filter Matching
+
+- **Permanent accounts** (ASSET, LIABILITY): Use `before:` dates for point-in-time
+- **Non-permanent accounts** (INCOMING, OUTGOING): Use `after:` and `before:` for periods
+
+- **IMPORTANT:** `after:` is inclusive and `before:` is exclusive, so, for example, to filter the whole 2024 year, the range might be `after:2024-01-01 before:2025-01-01` 
+
+### 3. Correct Tool Selection
+- **Balance analysis**: Always use `get_balances`
+- **Transaction inspection**: Use `list_transactions` (never for calculations)
+
+### 4. Balance Analysis Query Requirements (MANDATORY)
+- **MUST include either `group:` or `account:` operator in EVERY query**
+- Never query subgroups directly (Assets, Liabilities, Revenue, Expenses) - use root groups
+- When using `account:`, be specific about individual accounts
+- Always include appropriate date filters
+- Balance analysis queries without group/account operators will be rejected with an error
+- Transaction queries can be without group/account operators
+
+## Examples
+
+### Balance Sheet Analysis
+```javascript
+// After discovering root group for ASSET + LIABILITY accounts
+get_balances({ 
+  bookId: "book-123", 
+  query: "group:'Total Equity' before:$m" 
+})
+```
+
+### P&L Analysis
+```javascript
+// After discovering root group for INCOMING + OUTGOING accounts
+get_balances({ 
+  bookId: "book-123", 
+  query: "group:'Profit & Loss' after:$m-12 before:$m" 
+})
+```
+
+### Complete Financial Statements
+```javascript
+// After discovering both root groups
+const balanceSheet = await get_balances({ 
+  bookId: "book-123", 
+  query: "group:'Total Equity' before:$m+1" 
+});
+
+const pnl = await get_balances({ 
+  bookId: "book-123", 
+  query: "group:'Profit & Loss' after:$m-1 before:$m" 
+});
+```
+
+### Transaction Inspection
+```javascript
+// Recent transactions (inspection only)
+list_transactions({ 
+  bookId: "book-123", 
+  query: "after:$d-30" 
+})
+
+// Large transactions
+list_transactions({ 
+  bookId: "book-123", 
+  query: "amount>1000 after:$m-1 before:$m" 
+})
+```
+
+## Account Structure Reference
+
+### Account Types
+| Type | Nature | Examples |
+|------|--------|----------|
+| **ASSET** | Permanent | Cash, Accounts Receivable |
+| **LIABILITY** | Permanent | Accounts Payable, Loans |
+| **INCOMING** | Non-permanent | Sales, Interest Income |
+| **OUTGOING** | Non-permanent | Rent, Utilities |
+
+### Example Group Hierarchies
+
+**Example 1: Permanent Accounts (Balance Sheet Analysis)**
+```
+"Total Equity"
+├── Assets
+│   ├── Current Assets
+│   └── Fixed Assets
+└── Liabilities
+    ├── Current Liabilities
+    └── Long-term Liabilities
+```
+
+**Example 2: Non-Permanent Accounts (Profit & Loss Analysis)**
+```
+"Profit & Loss"
+├── Revenue
+│   ├── Product Sales
+│   └── Service Revenue
+└── Expenses
+    ├── Operating Expenses
+    └── Administrative Expenses
+```
+
+**Note**: Root group names vary by book. Always discover the actual names using `get_book()` which includes group hierarchies.
+
+## Quick Reference
+
+### Date Variables
+- `$d` - Today
+- `$m` - Current month end
+- `$y` - Current year end
+- `$d-N` - N days ago
+- `$m-N` - N months ago
+
+### Query Patterns
+```
+group:'[ROOT_GROUP_NAME]' before:$m                      // Balance sheet (permanent accounts)
+group:'[ROOT_GROUP_NAME]' after:$m-1 before:$m      // P&L (non-permanent accounts)
+after:2024-01-01 before:2025-01-01                  // Date range
+amount>1000                                          // Amount filter (transactions only)
+```
+
+### Analysis Workflow
+1. **Discover**: `list_books()` → `get_book()` (includes groups)
+2. **Identify Root Groups**: Find groups containing the group types you need
+3. **Analyze**: `get_balances()` with discovered root groups
+4. **Inspect**: `list_transactions()` for transaction details
+
+## Reports and Insights Formatting
+
+### Markdown Output Preference
+When generating financial insights, reports, or analysis, **strongly prefer well-structured Markdown** for better readability across platforms (cloud, desktop, mobile). Use tables for financial data, clear headers for sections, bold formatting for totals and key metrics, and icons to enhance visual appeal.
+
+
+## Common Mistakes to Avoid
+
+❌ **Wrong**: `get_balances({ query: "before:$m" })` - Missing group/account operator!  
+✅ **Right**: `get_balances({ query: "group:'[ROOT_GROUP]' before:$m" })`
+
+❌ **Wrong**: `get_balances({ query: "after:2024-01-01" })` - Missing group/account operator!  
+✅ **Right**: `get_balances({ query: "group:'[ROOT_GROUP]' after:2024-01-01 before:2025-01-01" })`
+
+❌ **Wrong**: `get_balances({ query: "group:'Assets'" })` - Using subgroup instead of root group  
+✅ **Right**: `get_balances({ query: "group:'[ROOT_GROUP_WITH_ASSETS]' before:$m" })`
+
+❌ **Wrong**: Query without any filtering  
+✅ **Right**: Always include `group:` or `account:` operator for focused analysis
+
+❌ **Wrong**: Using `list_transactions` for balance calculations  
+✅ **Right**: Use `get_balances` for all balance analysis
+
+❌ **Wrong**: Using `before:` without `after:` dates with non-permanent accounts  
+✅ **Right**: Use `after:` and `before:` with INCOMING/OUTGOING accounts
+
+❌ **Wrong**: Using different date variables on same query. E.g.`after:$y-1` and `before:$d`
+✅ **Right**: Use same date variables on same query. E.g. `after:$y-1` and `before:$y`
+
+❌ **Wrong**: Assuming fixed root group names  
+✅ **Right**: Always discover root groups using `get_book()` then navigate its `groups` property
+
+## CRITICAL REQUIREMENT
+
+**⚠️ ALL get_balances queries MUST include either `group:` or `account:` operator.**

package/lib/mcp/tools/get_balances.d.ts

@@ -0,0 +1,26 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+interface GetBalancesParams {
+    bookId: string;
+    query: string;
+}
+export declare function handleGetBalances(params: GetBalancesParams): Promise<CallToolResult>;
+export declare const getBalancesToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            bookId: {
+                type: string;
+                description: string;
+            };
+            query: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export {};
+//# sourceMappingURL=get_balances.d.ts.map

package/lib/mcp/tools/get_balances.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get_balances.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/get_balances.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAuB,MAAM,oCAAoC,CAAC;AAIzF,UAAU,iBAAiB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AASD,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAoG1F;AAED,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;CAiBrC,CAAC"}

package/lib/mcp/tools/get_balances.js

@@ -0,0 +1,106 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { getBkperInstance } from '../bkper-factory.js';
+import { BalanceType } from 'bkper-js';
+export function handleGetBalances(params) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            // Validate required parameters
+            if (!params.bookId) {
+                throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter: bookId');
+            }
+            if (!params.query) {
+                throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter: query');
+            }
+            // Validate query contains either group: or account: operator
+            if (!params.query.includes('group:') && !params.query.includes('account:')) {
+                throw new McpError(ErrorCode.InvalidParams, 'Query must include either \'group:\' or \'account:\' operator for proper balance filtering. Example: "group:\'Assets\' before:$m" or "account:\'Cash\' before:$m"');
+            }
+            // Get configured Bkper instance
+            const bkper = getBkperInstance();
+            // Get the book first
+            const book = yield bkper.getBook(params.bookId, true);
+            if (!book) {
+                throw new McpError(ErrorCode.InvalidParams, `Book not found: ${params.bookId}`);
+            }
+            // Get balances from the book with query (required by bkper-js)
+            let actualQuery = params.query;
+            // Enforce monthly periodicity by modifying query
+            if (actualQuery.includes('by:d')) {
+                // Replace daily periodicity with monthly
+                actualQuery = actualQuery.replace(/by:d/g, 'by:m');
+            }
+            else if (actualQuery.includes('by:y')) {
+                // Replace yearly periodicity with monthly
+                actualQuery = actualQuery.replace(/by:y/g, 'by:m');
+            }
+            else if (!actualQuery.includes('by:')) {
+                // Append monthly periodicity if no by: operator present
+                actualQuery = actualQuery + ' by:m';
+            }
+            // If by:m is already present, keep it unchanged
+            // Get the first container to access createDataTable
+            const balancesReport = yield book.getBalancesReport(actualQuery);
+            // Determine balance type based on presence of after: operator
+            const type = actualQuery.includes('after:') ? BalanceType.PERIOD : BalanceType.CUMULATIVE;
+            // Use BalancesDataTableBuilder to generate matrix
+            let matrix;
+            // Get the first container to access createDataTable
+            const dataTableBuilder = balancesReport.createDataTable()
+                .formatValues(false) // Raw numbers for LLMs
+                .formatDates(true) // YYYY-MM-DD dates
+                .raw(true) // Raw balances
+                .expanded(4)
+                .type(type); // 
+            matrix = dataTableBuilder.build();
+            // Build response with matrix format
+            const response = {
+                matrix,
+                query: actualQuery
+            };
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(response, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            // Re-throw MCP errors as-is
+            if (error instanceof McpError) {
+                throw error;
+            }
+            // Handle other errors
+            throw new McpError(ErrorCode.InternalError, `Failed to get balances: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+}
+export const getBalancesToolDefinition = {
+    name: 'get_balances',
+    description: 'Get account balances with query filtering. Use get_book first to understand group hierarchy and usage rules.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            bookId: {
+                type: 'string',
+                description: 'The unique identifier of the book'
+            },
+            query: {
+                type: 'string',
+                description: 'Required query to filter balances (e.g., "account:\'Cash\'", "group:\'Assets\'", "before:2024-01-31")'
+            }
+        },
+        required: ['bookId', 'query']
+    }
+};
+//# sourceMappingURL=get_balances.js.map

package/lib/mcp/tools/get_balances.js.map

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

package/lib/mcp/tools/get_book.d.ts

@@ -0,0 +1,21 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+interface GetBookParams {
+    bookId: string;
+}
+export declare function handleGetBook(params: GetBookParams): Promise<CallToolResult>;
+export declare const getBookToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            bookId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export {};
+//# sourceMappingURL=get_book.d.ts.map

package/lib/mcp/tools/get_book.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get_book.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/get_book.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAuB,MAAM,oCAAoC,CAAC;AAOzF,UAAU,aAAa;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAkED,wBAAsB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAqElF;AAED,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;CAajC,CAAC"}

package/lib/mcp/tools/get_book.js

@@ -0,0 +1,126 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { getBkperInstance } from '../bkper-factory.js';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+function buildHierarchicalStructure(groups) {
+    const groupMap = new Map();
+    const rootGroups = [];
+    // First pass: create all group nodes
+    groups.forEach(group => {
+        const node = {
+            id: group.getId() || '',
+            name: group.getName() || '',
+            type: group.getType() || '',
+            hidden: group.isHidden() || false,
+            permanent: group.isPermanent() || false,
+            properties: group.getProperties() || {},
+            children: []
+        };
+        groupMap.set(node.id, node);
+    });
+    // Second pass: build hierarchy
+    groups.forEach(group => {
+        const node = groupMap.get(group.getId() || '');
+        if (!node)
+            return;
+        const parent = group.getParent();
+        if (parent) {
+            const parentNode = groupMap.get(parent.getId() || '');
+            if (parentNode) {
+                parentNode.children.push(node);
+            }
+        }
+        else {
+            // No parent = root group
+            rootGroups.push(node);
+        }
+    });
+    return rootGroups;
+}
+function loadSystemPrompt() {
+    try {
+        // Get the directory where this file is located and navigate to the parent mcp directory
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = dirname(__filename);
+        const mcpPath = join(__dirname, '..');
+        const systemPrompt = readFileSync(join(mcpPath, 'system-prompt.md'), 'utf-8');
+        return systemPrompt;
+    }
+    catch (error) {
+        return `# Bkper MCP System Prompt\n\nDocumentation not available.\nError: ${error instanceof Error ? error.message : String(error)}\nPath attempted: ${join(dirname(fileURLToPath(import.meta.url)), '..', 'system-prompt.md')}`;
+    }
+}
+export function handleGetBook(params) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            // Validate required parameters
+            if (!params.bookId) {
+                throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter: bookId');
+            }
+            // Get configured Bkper instance
+            const bkperInstance = getBkperInstance();
+            // Get the specific book
+            const book = yield bkperInstance.getBook(params.bookId, false, true);
+            if (!book) {
+                throw new McpError(ErrorCode.InvalidParams, `Book not found: ${params.bookId}`);
+            }
+            // Get book JSON data
+            const bookJson = book.json();
+            // Get groups from the book
+            const groups = yield book.getGroups();
+            // Build hierarchical structure
+            const hierarchicalGroups = buildHierarchicalStructure(groups || []);
+            bookJson.groups = hierarchicalGroups;
+            // Build response with book data and groups
+            const response = {
+                book: bookJson,
+                readme: loadSystemPrompt()
+            };
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(response, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            // Handle specific book not found errors
+            if (error instanceof Error && error.message.includes('not found')) {
+                throw new McpError(ErrorCode.InvalidParams, `Book not found: ${params.bookId}`);
+            }
+            // Re-throw MCP errors as-is
+            if (error instanceof McpError) {
+                throw error;
+            }
+            // Handle other errors
+            throw new McpError(ErrorCode.InternalError, `Failed to get book: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+}
+export const getBookToolDefinition = {
+    name: 'get_book',
+    description: 'Retrieve detailed information about a specific book including its group hierarchy and system prompt',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            bookId: {
+                type: 'string',
+                description: 'The unique identifier of the book to retrieve'
+            }
+        },
+        required: ['bookId']
+    }
+};
+//# sourceMappingURL=get_book.js.map

package/lib/mcp/tools/get_book.js.map

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

package/lib/mcp/tools/list_books.d.ts

@@ -0,0 +1,21 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+interface ListBooksParams {
+    filter: string;
+}
+export declare function handleListBooks(params: ListBooksParams): Promise<CallToolResult>;
+export declare const listBooksToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            filter: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export {};
+//# sourceMappingURL=list_books.d.ts.map

package/lib/mcp/tools/list_books.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list_books.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/list_books.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAuB,MAAM,oCAAoC,CAAC;AAGzF,UAAU,eAAe;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAsBD,wBAAsB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA+BtF;AAED,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;CAanC,CAAC"}

package/lib/mcp/tools/list_books.js

@@ -0,0 +1,67 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { getBkperInstance } from '../bkper-factory.js';
+function fetchBooks(filter) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // Get configured Bkper instance
+        const bkperInstance = getBkperInstance();
+        // Get books using high-level wrapper with required filter
+        const bkperBooks = yield bkperInstance.getBooks(filter);
+        // Return full book JSON data - no filtering, no transforming
+        const books = bkperBooks.map((book) => book.json());
+        const total = books.length;
+        return { books, total };
+    });
+}
+export function handleListBooks(params) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            // Fetch all books with required filter
+            const { books, total } = yield fetchBooks(params.filter);
+            // Build response
+            const response = {
+                total,
+                books
+            };
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(response, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            // Re-throw MCP errors as-is
+            if (error instanceof McpError) {
+                throw error;
+            }
+            // Handle other errors
+            throw new McpError(ErrorCode.InternalError, `Failed to list books: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+}
+export const listBooksToolDefinition = {
+    name: 'list_books',
+    description: 'List books with mandatory filtering by name or property',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            filter: {
+                type: 'string',
+                description: 'Required filter to search books by name or property (case-insensitive substring match)'
+            }
+        },
+        required: ['filter']
+    }
+};
+//# sourceMappingURL=list_books.js.map

package/lib/mcp/tools/list_books.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list_books.js","sourceRoot":"","sources":["../../../src/mcp/tools/list_books.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAkB,SAAS,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAWvD,SAAe,UAAU,CAAC,MAAc;;QACtC,gCAAgC;QAChC,MAAM,aAAa,GAAG,gBAAgB,EAAE,CAAC;QAEzC,0DAA0D;QAC1D,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAExD,6DAA6D;QAC7D,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,IAAS,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAEzD,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;QAE3B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC1B,CAAC;CAAA;AAED,MAAM,UAAgB,eAAe,CAAC,MAAuB;;QAC3D,IAAI,CAAC;YACH,uCAAuC;YACvC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAEzD,iBAAiB;YACjB,MAAM,QAAQ,GAAkB;gBAC9B,KAAK;gBACL,KAAK;aACN,CAAC;YAEF,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;qBACxC;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,4BAA4B;YAC5B,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;gBAC9B,MAAM,KAAK,CAAC;YACd,CAAC;YAED,sBAAsB;YACtB,MAAM,IAAI,QAAQ,CAChB,SAAS,CAAC,aAAa,EACvB,yBAAyB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAClF,CAAC;QACJ,CAAC;IACH,CAAC;CAAA;AAED,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,IAAI,EAAE,YAAY;IAClB,WAAW,EAAE,yDAAyD;IACtE,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,wFAAwF;aACtG;SACF;QACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;KACrB;CACF,CAAC"}

package/lib/mcp/tools/list_transactions.d.ts

@@ -0,0 +1,38 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+interface ListTransactionsParams {
+    bookId: string;
+    cursor?: string;
+    query: string;
+    limit?: number;
+}
+export declare function handleListTransactions(params: ListTransactionsParams): Promise<CallToolResult>;
+export declare const listTransactionsToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            bookId: {
+                type: string;
+                description: string;
+            };
+            cursor: {
+                type: string;
+                description: string;
+            };
+            query: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+                minimum: number;
+                maximum: number;
+            };
+        };
+        required: string[];
+    };
+};
+export {};
+//# sourceMappingURL=list_transactions.d.ts.map

package/lib/mcp/tools/list_transactions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list_transactions.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/list_transactions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAuB,MAAM,oCAAoC,CAAC;AAGzF,UAAU,sBAAsB;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAUD,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,cAAc,CAAC,CA0EpG;AAED,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2B1C,CAAC"}

package/lib/mcp/tools/list_transactions.js

@@ -0,0 +1,95 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { getBkperInstance } from '../bkper-factory.js';
+export function handleListTransactions(params) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            // Validate required parameters
+            if (!params.bookId) {
+                throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter: bookId');
+            }
+            if (!params.query) {
+                throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter: query');
+            }
+            // Get configured Bkper instance
+            const bkperInstance = getBkperInstance();
+            // Get the book first
+            const book = yield bkperInstance.getBook(params.bookId);
+            if (!book) {
+                throw new McpError(ErrorCode.InvalidParams, `Book not found: ${params.bookId}`);
+            }
+            // Set up pagination parameters
+            const limit = Math.min(params.limit || 25, 100); // Default 25, max 100
+            // Get transactions using native API pagination
+            const transactionList = yield book.listTransactions(params.query, limit, params.cursor);
+            // Get transactions from list
+            const transactionItems = transactionList.getItems();
+            const transactions = transactionItems.map((transaction) => transaction.json());
+            // Get pagination info from list
+            const hasMore = transactionItems.length > 0;
+            const nextCursor = transactionList.getCursor() || null;
+            // Build response
+            const response = {
+                transactions,
+                hasMore,
+                cursor: nextCursor,
+                limit
+            };
+            // Include query in response (now always provided)
+            response.query = params.query;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(response, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            // Re-throw MCP errors as-is
+            if (error instanceof McpError) {
+                throw error;
+            }
+            // Handle other errors
+            throw new McpError(ErrorCode.InternalError, `Failed to list transactions: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+}
+export const listTransactionsToolDefinition = {
+    name: 'list_transactions',
+    description: 'List transactions with native API cursor-based pagination and query filtering. Use get_book first to understand query syntax and usage rules.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            bookId: {
+                type: 'string',
+                description: 'The unique identifier of the book'
+            },
+            cursor: {
+                type: 'string',
+                description: 'Pagination cursor for next page (provided by previous response)'
+            },
+            query: {
+                type: 'string',
+                description: 'Required query string to filter transactions using comprehensive syntax (account:, from:, to:, group:, on:, after:, before:, amount:, text search, logical operators, etc.)'
+            },
+            limit: {
+                type: 'number',
+                description: 'Number of transactions per page (default: 25, maximum: 100)',
+                minimum: 1,
+                maximum: 100
+            }
+        },
+        required: ['bookId', 'query']
+    }
+};
+//# sourceMappingURL=list_transactions.js.map

package/lib/mcp/tools/list_transactions.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bkper",
-  "version": "3.3.3",
+  "version": "3.5.0",
   "description": "Node.js command line client for Bkper",
   "bin": {
     "bkper": "./lib/cli.js"
@@ -17,14 +17,32 @@
   "files": [
     "lib/**/*"
   ],
+  "mcp": {
+    "server": {
+      "command": "node",
+      "args": [
+        "lib/cli.js",
+        "mcp",
+        "start"
+      ],
+      "env": {}
+    }
+  },
   "scripts": {
     "clean": "rm -rf ./lib & rm -rf ./node_modules & wait",
     "prebuild": "bun install",
     "build": "run-s build:*",
-    "build:clean": "gts clean",
+    "build:clean": "gts clean && rimraf temp",
     "build:compile": "tsc",
+    "build:copy-docs": "mkdir -p lib/docs && cp -f docs/*.md lib/docs/ 2>/dev/null || true",
+    "build:copy-mcp-assets": "mkdir -p lib/mcp && cp -f src/mcp/*.md lib/mcp/ 2>/dev/null || true",
     "predev": "bun run build",
-    "dev": "tsc -w",
+    "dev": "bun run build && npx concurrently \"tsc -w\" \"./scripts/dev-mcp.sh\"",
+    "mcp": "bun run build && node lib/cli.js mcp start",
+    "test": "TS_NODE_PROJECT=tsconfig.test.json mocha",
+    "test:unit": "TS_NODE_PROJECT=tsconfig.test.json mocha --config .mocharc.json",
+    "test:integration": "TS_NODE_PROJECT=tsconfig.test.json mocha --config .mocharc.integration.json",
+    "test:all": "bun run test:unit && bun run test:integration",
     "upgrade:api": "bun update @bkper/bkper-api-types --latest && bun update bkper-js --latest",
     "patch": "yarn version --patch",
     "minor": "yarn version --minor",
@@ -34,19 +52,28 @@
   },
   "dependencies": {
     "@google-cloud/local-auth": "^3.0.1",
-    "bkper-js": "^1.30.0",
+    "@modelcontextprotocol/sdk": "^1.13.1",
+    "bkper-js": "^2.4.0",
     "commander": "^6.2.1",
     "dotenv": "^8.2.0",
     "google-auth-library": "^9.14.0",
     "yaml": "^2.5.1"
   },
   "devDependencies": {
-    "@bkper/bkper-api-types": "^5.15.1",
+    "@bkper/bkper-api-types": "^5.23.0",
+    "@types/chai": "^4.3.0",
     "@types/commander": "^2.12.2",
+    "@types/mocha": "^10.0.0",
     "@types/node": "^22.5.1",
+    "chai": "^4.3.0",
+    "concurrently": "^8.2.2",
     "gts": "^3.0.3",
+    "mocha": "^10.0.0",
+    "nodemon": "^3.0.1",
     "npm-run-all": "^4.1.5",
     "rimraf": "^3.0.2",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
     "typescript": "^5.5.4"
   }
 }