bkper 3.5.1 → 3.5.4
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
|
@@ -1,6 +1,10 @@
|
|
|
1
|
-
[Bkper REST API]: https://bkper.com/docs/#rest-
|
|
1
|
+
[Bkper REST API]: https://bkper.com/docs/#rest-api-enabling
|
|
2
2
|
|
|
3
|
-
A **command line** utility
|
|
3
|
+
A **command line** utility for managing [Bkper Apps and Bots](https://bkper.com/docs/) and running the [Model Context Protocol (MCP) server](https://modelcontextprotocol.io).
|
|
4
|
+
|
|
5
|
+
The MCP server enables AI assistants and agents to interact with your Bkper books through a standardized protocol.
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/bkper)
|
|
4
8
|
|
|
5
9
|
## Installation
|
|
6
10
|
|
|
@@ -30,11 +34,11 @@ yarn global add bkper
|
|
|
30
34
|
|
|
31
35
|
## Commands
|
|
32
36
|
|
|
33
|
-
- ```login``` - Logs the user in. Saves the client credentials to a ```~/.bkper-credentials.json``` file.
|
|
37
|
+
- ```login``` - Logs the user in. Saves the client credentials to a ```~/.config/bkper/.bkper-credentials.json``` file.
|
|
34
38
|
- ```logout``` - Logs out the user by deleting client credentials.
|
|
39
|
+
- ```mcp start``` - Start the Bkper MCP (Model Context Protocol) server.
|
|
35
40
|
- ```app -c``` - Create a new App based on ```./bkperapp.yaml``` file.
|
|
36
41
|
- ```app -u``` - Update an existing App based on ```./bkperapp.yaml``` file.
|
|
37
|
-
- ```mcp start``` - Start the Bkper MCP (Model Context Protocol) server.
|
|
38
42
|
|
|
39
43
|
### Examples
|
|
40
44
|
```
|
|
@@ -44,6 +48,77 @@ npm bkper login
|
|
|
44
48
|
yarn bkper login
|
|
45
49
|
```
|
|
46
50
|
|
|
51
|
+
### MCP (Model Context Protocol) Server
|
|
52
|
+
|
|
53
|
+
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).
|
|
54
|
+
|
|
55
|
+
#### Starting the MCP Server
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
bkper mcp start
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The server runs on stdio and provides the following tools:
|
|
62
|
+
|
|
63
|
+
- **list_books** - List all books accessible by the authenticated user
|
|
64
|
+
- **get_book** - Get details of a specific book by ID
|
|
65
|
+
- **get_balances** - Get account balances for a specific date or period
|
|
66
|
+
- **list_transactions** - List transactions with filtering options
|
|
67
|
+
|
|
68
|
+
#### Prerequisites
|
|
69
|
+
|
|
70
|
+
Before using the MCP server:
|
|
71
|
+
1. Login using `bkper login` to set up authentication
|
|
72
|
+
2. Enable the [Bkper REST API]
|
|
73
|
+
3. Ensure the `BKPER_API_KEY` environment variable is set.
|
|
74
|
+
|
|
75
|
+
The MCP server uses the same authentication as the CLI, reading credentials from `~/.config/bkper/.bkper-credentials.json`.
|
|
76
|
+
|
|
77
|
+
#### Integration Examples
|
|
78
|
+
|
|
79
|
+
##### Claude Desktop
|
|
80
|
+
|
|
81
|
+
Add to your configuration file:
|
|
82
|
+
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
83
|
+
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
84
|
+
|
|
85
|
+
```json
|
|
86
|
+
{
|
|
87
|
+
"mcpServers": {
|
|
88
|
+
"bkper": {
|
|
89
|
+
"command": "npx",
|
|
90
|
+
"args": ["bkper", "mcp", "start"],
|
|
91
|
+
"env": {
|
|
92
|
+
"BKPER_API_KEY": "your-api-key-here"
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
##### Other MCP Clients
|
|
100
|
+
|
|
101
|
+
For other MCP-compatible clients, configure them to run:
|
|
102
|
+
```bash
|
|
103
|
+
BKPER_API_KEY=your-api-key npx bkper mcp start
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The server communicates via stdio, so any MCP client that supports stdio transport can connect to it.
|
|
107
|
+
|
|
108
|
+
#### Available MCP Tools
|
|
109
|
+
|
|
110
|
+
Once connected, the MCP client can:
|
|
111
|
+
- List your Bkper books
|
|
112
|
+
- Get account balances for any date or period
|
|
113
|
+
- Search and filter transactions
|
|
114
|
+
- Analyze your financial data
|
|
115
|
+
|
|
116
|
+
For more information about the Model Context Protocol, visit [modelcontextprotocol.io](https://modelcontextprotocol.io).
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
## Apps and Bots
|
|
121
|
+
|
|
47
122
|
### Environment Variables
|
|
48
123
|
The following environment variable is necessary in order to communicate with the [Bkper REST API]:
|
|
49
124
|
|
|
@@ -202,74 +277,6 @@ Bkper.setConfig({
|
|
|
202
277
|
})
|
|
203
278
|
```
|
|
204
279
|
|
|
205
|
-
### MCP (Model Context Protocol) Server
|
|
206
|
-
|
|
207
|
-
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).
|
|
208
|
-
|
|
209
|
-
#### Starting the MCP Server
|
|
210
|
-
|
|
211
|
-
```bash
|
|
212
|
-
bkper mcp start
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
The server runs on stdio and provides the following tools:
|
|
216
|
-
|
|
217
|
-
- **list_books** - List all books accessible by the authenticated user
|
|
218
|
-
- **get_book** - Get details of a specific book by ID
|
|
219
|
-
- **get_balances** - Get account balances for a specific date or period
|
|
220
|
-
- **list_transactions** - List transactions with filtering options
|
|
221
|
-
|
|
222
|
-
#### Prerequisites
|
|
223
|
-
|
|
224
|
-
Before using the MCP server:
|
|
225
|
-
1. Login using `bkper login` to set up authentication
|
|
226
|
-
2. Ensure the `BKPER_API_KEY` environment variable is set
|
|
227
|
-
|
|
228
|
-
The MCP server uses the same authentication as the CLI, reading credentials from `~/.bkper-credentials.json`.
|
|
229
|
-
|
|
230
|
-
#### Integration Examples
|
|
231
|
-
|
|
232
|
-
##### Claude Desktop
|
|
233
|
-
|
|
234
|
-
Add to your configuration file:
|
|
235
|
-
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
236
|
-
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
237
|
-
|
|
238
|
-
```json
|
|
239
|
-
{
|
|
240
|
-
"mcpServers": {
|
|
241
|
-
"bkper": {
|
|
242
|
-
"command": "npx",
|
|
243
|
-
"args": ["bkper", "mcp", "start"],
|
|
244
|
-
"env": {
|
|
245
|
-
"BKPER_API_KEY": "your-api-key-here"
|
|
246
|
-
}
|
|
247
|
-
}
|
|
248
|
-
}
|
|
249
|
-
}
|
|
250
|
-
```
|
|
251
|
-
|
|
252
|
-
##### Other MCP Clients
|
|
253
|
-
|
|
254
|
-
For other MCP-compatible clients, configure them to run:
|
|
255
|
-
```bash
|
|
256
|
-
BKPER_API_KEY=your-api-key npx bkper mcp start
|
|
257
|
-
```
|
|
258
|
-
|
|
259
|
-
The server communicates via stdio, so any MCP client that supports stdio transport can connect to it.
|
|
260
|
-
|
|
261
|
-
#### Available MCP Tools
|
|
262
|
-
|
|
263
|
-
Once connected, the MCP client can:
|
|
264
|
-
- List your Bkper books
|
|
265
|
-
- Get account balances for any date or period
|
|
266
|
-
- Search and filter transactions
|
|
267
|
-
- Analyze your financial data
|
|
268
|
-
|
|
269
|
-
For more information about the Model Context Protocol, visit [modelcontextprotocol.io](https://modelcontextprotocol.io).
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
280
|
## Documentation
|
|
274
281
|
|
|
275
282
|
- [Developer Docs](https://bkper.com/docs)
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"local-auth-service.d.ts","sourceRoot":"","sources":["../../src/auth/local-auth-service.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"local-auth-service.d.ts","sourceRoot":"","sources":["../../src/auth/local-auth-service.ts"],"names":[],"mappings":"AA0CA,wBAAsB,KAAK,kBAK1B;AAED,wBAAgB,MAAM,SAKrB;AAED,wBAAgB,UAAU,YAEzB;AAED;;GAEG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CA8BnD"}
|
|
@@ -19,7 +19,24 @@ const __filename = fileURLToPath(import.meta.url); // get the resolved path to t
|
|
|
19
19
|
const __dirname = path.dirname(__filename); // get the name of the directory
|
|
20
20
|
const keys = require(`${__dirname}/keys.json`);
|
|
21
21
|
let storedCredentials;
|
|
22
|
-
const
|
|
22
|
+
const oldCredentialsPath = `${os.homedir()}/.bkper-credentials.json`;
|
|
23
|
+
const configDir = `${os.homedir()}/.config/bkper`;
|
|
24
|
+
const storedCredentialsPath = `${configDir}/.bkper-credentials.json`;
|
|
25
|
+
// Migrate from old location if exists
|
|
26
|
+
if (!fs.existsSync(storedCredentialsPath) && fs.existsSync(oldCredentialsPath)) {
|
|
27
|
+
try {
|
|
28
|
+
// Ensure config directory exists
|
|
29
|
+
fs.mkdirSync(configDir, { recursive: true });
|
|
30
|
+
// Move credentials to new location
|
|
31
|
+
const oldCredentials = fs.readFileSync(oldCredentialsPath, 'utf8');
|
|
32
|
+
fs.writeFileSync(storedCredentialsPath, oldCredentials, 'utf8');
|
|
33
|
+
fs.rmSync(oldCredentialsPath);
|
|
34
|
+
console.log('Migrated credentials to new location: ~/.config/bkper/');
|
|
35
|
+
}
|
|
36
|
+
catch (err) {
|
|
37
|
+
console.error('Failed to migrate credentials:', err);
|
|
38
|
+
}
|
|
39
|
+
}
|
|
23
40
|
try {
|
|
24
41
|
let credentialsJson = fs.readFileSync(storedCredentialsPath, 'utf8');
|
|
25
42
|
storedCredentials = JSON.parse(credentialsJson);
|
|
@@ -73,6 +90,8 @@ export function getOAuthToken() {
|
|
|
73
90
|
}
|
|
74
91
|
function storeCredentials(credentials) {
|
|
75
92
|
storedCredentials = credentials;
|
|
93
|
+
// Ensure config directory exists before writing
|
|
94
|
+
fs.mkdirSync(configDir, { recursive: true });
|
|
76
95
|
fs.writeFileSync(storedCredentialsPath, JSON.stringify(credentials, null, 4), 'utf8');
|
|
77
96
|
}
|
|
78
97
|
//# sourceMappingURL=local-auth-service.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"local-auth-service.js","sourceRoot":"","sources":["../../src/auth/local-auth-service.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAQ,EAAC,YAAY,EAAC,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,EAAe,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,oCAAoC;AACvF,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,gCAAgC;AAE5E,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,SAAS,YAAY,CAAC,CAAC;AAE/C,IAAI,iBAA8B,CAAC;AAEnC,MAAM,
|
|
1
|
+
{"version":3,"file":"local-auth-service.js","sourceRoot":"","sources":["../../src/auth/local-auth-service.ts"],"names":[],"mappings":"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"}
|