easybill-mcp 1.0.1 → 1.2.0

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.
Files changed (72) hide show
  1. package/README.md +293 -72
  2. package/dist/constants.d.ts +2 -1
  3. package/dist/constants.js +18 -1
  4. package/dist/constants.js.map +1 -1
  5. package/dist/hosted/accounts.d.ts +13 -0
  6. package/dist/hosted/accounts.js +70 -0
  7. package/dist/hosted/accounts.js.map +1 -0
  8. package/dist/hosted/config.d.ts +73 -0
  9. package/dist/hosted/config.js +200 -0
  10. package/dist/hosted/config.js.map +1 -0
  11. package/dist/hosted/http.d.ts +23 -0
  12. package/dist/hosted/http.js +524 -0
  13. package/dist/hosted/http.js.map +1 -0
  14. package/dist/hosted/pages.d.ts +22 -0
  15. package/dist/hosted/pages.js +130 -0
  16. package/dist/hosted/pages.js.map +1 -0
  17. package/dist/hosted/provider.d.ts +54 -0
  18. package/dist/hosted/provider.js +190 -0
  19. package/dist/hosted/provider.js.map +1 -0
  20. package/dist/hosted/store.d.ts +119 -0
  21. package/dist/hosted/store.js +254 -0
  22. package/dist/hosted/store.js.map +1 -0
  23. package/dist/hosted/upstream.d.ts +68 -0
  24. package/dist/hosted/upstream.js +280 -0
  25. package/dist/hosted/upstream.js.map +1 -0
  26. package/dist/index.d.ts +5 -1
  27. package/dist/index.js +19 -24
  28. package/dist/index.js.map +1 -1
  29. package/dist/instructions.d.ts +1 -1
  30. package/dist/instructions.js +16 -1
  31. package/dist/instructions.js.map +1 -1
  32. package/dist/server.d.ts +26 -0
  33. package/dist/server.js +47 -0
  34. package/dist/server.js.map +1 -0
  35. package/dist/services/client.d.ts +43 -4
  36. package/dist/services/client.js +35 -9
  37. package/dist/services/client.js.map +1 -1
  38. package/dist/services/format.d.ts +17 -4
  39. package/dist/services/format.js.map +1 -1
  40. package/dist/tools/catalog.d.ts +2 -2
  41. package/dist/tools/catalog.js.map +1 -1
  42. package/dist/tools/crud.d.ts +2 -2
  43. package/dist/tools/crud.js.map +1 -1
  44. package/dist/tools/customers.d.ts +2 -2
  45. package/dist/tools/customers.js +12 -4
  46. package/dist/tools/customers.js.map +1 -1
  47. package/dist/tools/documents.d.ts +2 -2
  48. package/dist/tools/documents.js +73 -43
  49. package/dist/tools/documents.js.map +1 -1
  50. package/dist/tools/files-io.d.ts +44 -0
  51. package/dist/tools/files-io.js +173 -0
  52. package/dist/tools/files-io.js.map +1 -0
  53. package/dist/tools/files.d.ts +2 -2
  54. package/dist/tools/files.js +9 -27
  55. package/dist/tools/files.js.map +1 -1
  56. package/dist/tools/finance.d.ts +2 -2
  57. package/dist/tools/finance.js.map +1 -1
  58. package/dist/tools/incoming.d.ts +11 -0
  59. package/dist/tools/incoming.js +222 -0
  60. package/dist/tools/incoming.js.map +1 -0
  61. package/dist/tools/meta.d.ts +2 -2
  62. package/dist/tools/meta.js +14 -6
  63. package/dist/tools/meta.js.map +1 -1
  64. package/dist/tools/registry.d.ts +40 -9
  65. package/dist/tools/registry.js +75 -12
  66. package/dist/tools/registry.js.map +1 -1
  67. package/dist/tools/search.d.ts +9 -8
  68. package/dist/tools/search.js +49 -17
  69. package/dist/tools/search.js.map +1 -1
  70. package/dist/tools/work.d.ts +2 -2
  71. package/dist/tools/work.js.map +1 -1
  72. package/package.json +16 -2
package/README.md CHANGED
@@ -1,12 +1,14 @@
1
1
  # easybill MCP Server
2
2
 
3
3
  An [MCP](https://modelcontextprotocol.io) server for the [easybill REST API](https://www.easybill.de/api/).
4
- Gives Claude access to your invoices, customers, article catalogue, payments, projects and tracked time.
4
+ Gives any MCP-capable assistant — Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Zed,
5
+ Codex CLI, Gemini CLI, Cline — access to your invoices, customers, article catalogue, payments,
6
+ projects and tracked time.
5
7
 
6
8
  Built on the official [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk)
7
9
  (TypeScript), talking stdio.
8
10
 
9
- - **54 tools** across 12 easybill resources
11
+ - **64 tools** across 13 easybill resources (65 in hosted mode)
10
12
  - **Read-only by default** — create/update/delete tools stay unregistered unless you opt in
11
13
  - **Workflow-aware** — ships server instructions so the agent resolves the customer before
12
14
  writing a document, instead of guessing where to start
@@ -22,7 +24,175 @@ Built on the official [`@modelcontextprotocol/sdk`](https://github.com/modelcont
22
24
 
23
25
  In easybill: **Einstellungen → App-Center → API**. Create a key and copy it.
24
26
 
25
- ### 2. Build
27
+ ### 2. Register it with your client
28
+
29
+ This is a plain stdio MCP server published on npm, so any MCP client can run it with `npx` —
30
+ no clone, no build, no global install:
31
+
32
+ ```bash
33
+ npx -y easybill-mcp
34
+ ```
35
+
36
+ Configuration is entirely through environment variables (full list under
37
+ [Configuration](#configuration)). Two matter now:
38
+
39
+ - Leave `EASYBILL_ENABLE_WRITES` unset to start **read-only**.
40
+ - Set `EASYBILL_RATE_LIMIT_PER_MINUTE` to **10** on easybill's Professional plan or **60** on Premium (Free and Starter have no API access).
41
+
42
+ Most clients use the same JSON shape under an `mcpServers` key:
43
+
44
+ ```json
45
+ {
46
+ "mcpServers": {
47
+ "easybill": {
48
+ "command": "npx",
49
+ "args": ["-y", "easybill-mcp"],
50
+ "env": {
51
+ "EASYBILL_API_KEY": "your_api_key_here",
52
+ "EASYBILL_RATE_LIMIT_PER_MINUTE": "10"
53
+ }
54
+ }
55
+ }
56
+ }
57
+ ```
58
+
59
+ Where that block goes:
60
+
61
+ | Client | Config location |
62
+ |---|---|
63
+ | **Claude Desktop** | Settings → Developer → Edit Config, or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) · `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
64
+ | **Cursor** | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project) |
65
+ | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
66
+ | **Cline / Roo Code** | MCP Servers panel → Configure MCP Servers (`cline_mcp_settings.json`) |
67
+ | **Gemini CLI** | `~/.gemini/settings.json` |
68
+ | **Claude Code** | `claude mcp add`, see below |
69
+ | **VS Code / Copilot** | `.vscode/mcp.json`, different key — see below |
70
+ | **Zed** | `settings.json` → `context_servers`, see below |
71
+ | **Codex CLI** | `~/.codex/config.toml`, TOML instead of JSON — see below |
72
+
73
+ > **Windows:** if a client fails to start `npx`, use `"command": "cmd"` with
74
+ > `"args": ["/c", "npx", "-y", "easybill-mcp"]`.
75
+
76
+ #### Claude Code
77
+
78
+ ```bash
79
+ claude mcp add easybill \
80
+ --env EASYBILL_API_KEY=your_api_key_here \
81
+ --env EASYBILL_RATE_LIMIT_PER_MINUTE=10 \
82
+ -- npx -y easybill-mcp
83
+ ```
84
+
85
+ `claude mcp add` does not overwrite an existing entry — to change the environment later,
86
+ `claude mcp remove easybill -s local` first, then add it again.
87
+
88
+ #### VS Code (GitHub Copilot agent mode)
89
+
90
+ VS Code uses `servers`, not `mcpServers`, and can prompt for the key instead of storing it
91
+ in the file. Put this in `.vscode/mcp.json` (workspace) or open **MCP: Open User
92
+ Configuration**:
93
+
94
+ ```json
95
+ {
96
+ "inputs": [
97
+ { "id": "easybill_key", "type": "promptString", "description": "easybill API key", "password": true }
98
+ ],
99
+ "servers": {
100
+ "easybill": {
101
+ "type": "stdio",
102
+ "command": "npx",
103
+ "args": ["-y", "easybill-mcp"],
104
+ "env": {
105
+ "EASYBILL_API_KEY": "${input:easybill_key}",
106
+ "EASYBILL_RATE_LIMIT_PER_MINUTE": "10"
107
+ }
108
+ }
109
+ }
110
+ }
111
+ ```
112
+
113
+ #### Zed
114
+
115
+ In `settings.json`:
116
+
117
+ ```json
118
+ {
119
+ "context_servers": {
120
+ "easybill": {
121
+ "source": "custom",
122
+ "command": "npx",
123
+ "args": ["-y", "easybill-mcp"],
124
+ "env": {
125
+ "EASYBILL_API_KEY": "your_api_key_here",
126
+ "EASYBILL_RATE_LIMIT_PER_MINUTE": "10"
127
+ }
128
+ }
129
+ }
130
+ }
131
+ ```
132
+
133
+ #### Codex CLI
134
+
135
+ In `~/.codex/config.toml`:
136
+
137
+ ```toml
138
+ [mcp_servers.easybill]
139
+ command = "npx"
140
+ args = ["-y", "easybill-mcp"]
141
+ env = { EASYBILL_API_KEY = "your_api_key_here", EASYBILL_RATE_LIMIT_PER_MINUTE = "10" }
142
+ ```
143
+
144
+ #### Hosted clients that only speak remote MCP
145
+
146
+ For claude.ai and other remote-only clients, run the server in **hosted mode** (see
147
+ "Hosted mode" below): one connector for the whole company, each person connects the easybill
148
+ accounts they use with their personal API key.
149
+
150
+ For a quick single-user experiment you can instead bridge the stdio server locally:
151
+
152
+ ```bash
153
+ npx -y supergateway --stdio "npx -y easybill-mcp"
154
+ ```
155
+
156
+ Only do this if you understand the exposure: anything that reaches that endpoint reaches your
157
+ accounting data. Keep it bound to localhost or behind a tunnel with authentication, and never
158
+ run the bridge with writes enabled unless the endpoint is protected.
159
+
160
+ ### 3. Verify the connection
161
+
162
+ Ask the assistant to call `easybill_get_server_info`. It reports the mode, the limits and
163
+ whether easybill accepted the credentials:
164
+
165
+ ```json
166
+ {
167
+ "server_version": "1.0.1",
168
+ "writes_enabled": false,
169
+ "tools_registered": { "read_only": 28, "write": 0, "withheld_because_writes_disabled": 26 },
170
+ "rate_limit_per_minute": 10,
171
+ "connection": "ok — credentials accepted by easybill"
172
+ }
173
+ ```
174
+
175
+ ### 4. Enable writes, once you trust it
176
+
177
+ Add `EASYBILL_ENABLE_WRITES=true` to the server's environment:
178
+
179
+ ```bash
180
+ claude mcp add easybill \
181
+ --env EASYBILL_API_KEY=your_api_key_here \
182
+ --env EASYBILL_RATE_LIMIT_PER_MINUTE=10 \
183
+ --env EASYBILL_ENABLE_WRITES=true \
184
+ -- npx -y easybill-mcp
185
+ ```
186
+
187
+ The 26 write tools are registered at startup, so the change only takes effect once the client
188
+ restarts the server process — editing the config in a running session is not enough. Confirm
189
+ with `easybill_get_server_info`: `writes_enabled` must read `true`.
190
+
191
+ ---
192
+
193
+ ## Running from a local clone
194
+
195
+ For development, or to run a version you have not published:
26
196
 
27
197
  ```bash
28
198
  git clone https://github.com/stack74/easybill-mcp.git
@@ -31,7 +201,16 @@ npm install
31
201
  npm run build
32
202
  ```
33
203
 
34
- ### 3. Test locally first
204
+ Then point the client at the built entry point instead of `npx` — `"command": "node"`,
205
+ `"args": ["/absolute/path/to/easybill-mcp/dist/index.js"]`, same `env` block. Or straight from
206
+ GitHub without cloning, which is slower because it compiles TypeScript on install via the
207
+ `prepare` script and needs a toolchain:
208
+
209
+ ```bash
210
+ npx -y github:stack74/easybill-mcp
211
+ ```
212
+
213
+ ### Test locally first
35
214
 
36
215
  Copy `.env.example` to `.env`, put your key in it, then run the read-only self-test:
37
216
 
@@ -69,87 +248,112 @@ npm run inspect # MCP Inspector, loads .env
69
248
 
70
249
  > **Note:** `.env` is only read by these npm scripts, via Node's `--env-file`. The server
71
250
  > itself reads plain environment variables — when you register it with an MCP client, pass
72
- > the key through the client's config as shown below, not via `.env`.
73
-
74
- ### 4. Register with Claude Code
251
+ > the key through the client's config, not via `.env`.
75
252
 
76
- Read-only (recommended to start):
253
+ ### Publishing to npm
77
254
 
78
255
  ```bash
79
- claude mcp add easybill \
80
- --env EASYBILL_API_KEY=your_api_key_here \
81
- --env EASYBILL_RATE_LIMIT_PER_MINUTE=10 \
82
- -- node /absolute/path/to/easybill-mcp/dist/index.js
256
+ npm login # once, needs an npmjs.com account
257
+ npm run build && npm run smoke
258
+ npm publish # unscoped packages are public by default
83
259
  ```
84
260
 
85
- With write access, once you trust it:
261
+ Verify what ships before you publish — `npm pack --dry-run` lists the tarball contents.
262
+ Only `dist/`, `README.md`, `LICENSE` and `package.json` are included; `src/` and `.env`
263
+ are not.
86
264
 
87
- ```bash
88
- claude mcp add easybill \
89
- --env EASYBILL_API_KEY=your_api_key_here \
90
- --env EASYBILL_RATE_LIMIT_PER_MINUTE=10 \
91
- --env EASYBILL_ENABLE_WRITES=true \
92
- -- node /absolute/path/to/easybill-mcp/dist/index.js
93
- ```
265
+ For later releases bump the version first (`npm version patch|minor|major`), which also
266
+ creates a git tag. npm does not allow republishing an existing version.
267
+
268
+ ---
94
269
 
95
- Set `EASYBILL_RATE_LIMIT_PER_MINUTE` to **10** on the PLUS plan or **60** on BUSINESS.
270
+ ## Hosted mode (claude.ai connector, several easybill accounts)
96
271
 
97
- Verify it connected:
272
+ `easybill-mcp --http` runs the server as a remote MCP endpoint (Streamable HTTP) for a whole
273
+ company:
98
274
 
99
- ```
100
- > use easybill_get_server_info
101
- ```
275
+ 1. Someone adds the connector in claude.ai (or any OAuth-capable MCP client).
276
+ 2. The client opens this server's **connect page**. It lists the easybill accounts from your
277
+ tenant configuration; the person clicks *Verbinden* on each account they have access to and
278
+ pastes **their personal easybill API key** (easybill: user icon → *Profil und Einstellungen*
279
+ → *API Key*). The server checks it against easybill before storing it.
280
+ 3. *Fertig – zurück zu Claude* completes the client's OAuth flow.
281
+
282
+ Every tool then takes an `account` argument (`easybill_list_accounts` shows the status and
283
+ hands out a link to connect more accounts or replace a key). Keys are stored AES-GCM encrypted
284
+ in SQLite. A key easybill rejects later (regenerated, login removed) is marked and the model
285
+ hands out the link to replace it.
286
+
287
+ This server is the OAuth authorization server for the MCP client (claude.ai); easybill itself
288
+ only sees API-key requests. An API key does not say which easybill account it belongs to, so on
289
+ the first connection of a tenant the server remembers the account's login IDs (from `/logins`)
290
+ and refuses later keys from a different account, including a key that already belongs to another
291
+ configured tenant.
102
292
 
103
- ### 5. Claude Desktop (alternative)
293
+ **easybill OAuth instead of API keys** (`EASYBILL_CONNECT_MODE=oauth`): people log in at easybill
294
+ instead of pasting a key. easybill only allows dynamic client registration for an allowlist of
295
+ redirect URIs (claude.ai and similar), so this mode needs an OAuth client issued by easybill for
296
+ `<EASYBILL_PUBLIC_URL>/connect/callback` (`EASYBILL_OAUTH_CLIENT_ID` / `_SECRET`).
104
297
 
105
- Add to `claude_desktop_config.json`:
298
+ ### Tenant configuration
106
299
 
107
300
  ```json
108
301
  {
109
- "mcpServers": {
110
- "easybill": {
111
- "command": "node",
112
- "args": ["/absolute/path/to/easybill-mcp/dist/index.js"],
113
- "env": {
114
- "EASYBILL_API_KEY": "your_api_key_here",
115
- "EASYBILL_RATE_LIMIT_PER_MINUTE": "10"
116
- }
117
- }
118
- }
302
+ "tenants": [
303
+ { "id": "firma-a", "name": "Firma A GmbH", "plan": "PREMIUM", "writes": true },
304
+ { "id": "firma-b", "name": "Firma B GmbH", "plan": "PROFESSIONAL", "writes": false }
305
+ ]
119
306
  }
120
307
  ```
121
308
 
122
- ### Installing without cloning
123
-
124
- Once published to npm, no clone or build is needed — `npx` fetches and runs it:
125
-
126
- ```bash
127
- claude mcp add easybill --env EASYBILL_API_KEY=your_key -- npx -y easybill-mcp
128
- ```
129
-
130
- Straight from GitHub also works, but is slower (it compiles TypeScript on install
131
- via the `prepare` script) and needs a toolchain:
309
+ | Field | Meaning |
310
+ |---|---|
311
+ | `id` | Slug the model passes as `account`. |
312
+ | `name` | Shown on the connect page and to the model. |
313
+ | `plan` | `PROFESSIONAL` (10 req/min) or `PREMIUM` (60 req/min); the former names `PLUS` / `BUSINESS` work too. Free and Starter have no API access. Throttle shared by everyone on the account. Or set `rate_limit_per_minute`. |
314
+ | `writes` | `true` registers create/update/delete for this account and requests write scopes from easybill. Default read-only scopes. |
315
+ | `scopes` | Optional override of the easybill OAuth scopes. |
316
+ | `match` | OAuth mode only: `{ "<claim>": "<value>" }` checked against easybill's access-token claims, so a login of the wrong company is refused. The server logs the claims of every new connection. |
132
317
 
133
- ```bash
134
- claude mcp add easybill --env EASYBILL_API_KEY=your_key -- npx -y github:stack74/easybill-mcp
135
- ```
318
+ ### Environment
136
319
 
137
- ### Publishing to npm
320
+ | Variable | Default | Purpose |
321
+ |---|---|---|
322
+ | `EASYBILL_PUBLIC_URL` | — | **Required.** Public https base URL. The connector URL is `<this>/mcp`. |
323
+ | `EASYBILL_MCP_SECRET` | — | **Required.** ≥ 32 characters; encrypts stored tokens and signs the browser cookie. Changing it invalidates all connections. |
324
+ | `EASYBILL_TENANTS_FILE` / `EASYBILL_TENANTS` | — | **Required.** Path to the tenant JSON, or the JSON inline. |
325
+ | `EASYBILL_DB_PATH` | `./data/easybill-mcp.sqlite` | SQLite file. Put it on a persistent volume. |
326
+ | `PORT` / `HOST` | `3000` / `0.0.0.0` | Listen address. |
327
+ | `EASYBILL_CF_ACCESS_TEAM_DOMAIN` / `EASYBILL_CF_ACCESS_AUD` | — | Put the connect pages behind Cloudflare Access: team domain (e.g. `acme` or `acme.cloudflareaccess.com`) and the Access application's AUD tag. `/connect/*` then requires a valid Access token, checked by the server itself. |
328
+ | `EASYBILL_ICON_PATH` | — | Path to an `.svg`, `.png` or `.ico` file (e.g. a file mount in your hosting platform). Served as `/favicon.ico` and `/favicon.<ext>`, linked from the pages and announced as the MCP server icon. claude.ai shows the domain's favicon next to a custom connector. |
329
+ | `EASYBILL_CONNECT_MODE` | `apikey` (`oauth` if a client ID is set) | How people connect easybill accounts. |
330
+ | `EASYBILL_OAUTH_CLIENT_ID` / `_SECRET` | — | OAuth mode: the client easybill issued for this server. |
331
+ | `EASYBILL_OAUTH_ISSUER` | `https://api.easybill.de` | OAuth mode: easybill's OAuth issuer. |
332
+ | `EASYBILL_MCP_ACCESS_TOKEN_TTL` | `3600` | Lifetime (s) of access tokens issued to MCP clients. |
333
+ | `EASYBILL_MCP_REFRESH_TOKEN_TTL` | `7776000` | Lifetime (s) of refresh tokens issued to MCP clients (90 days). |
334
+
335
+ Needs Node.js ≥ 22.13 (built-in `node:sqlite`). The `Dockerfile` builds a ready image:
138
336
 
139
337
  ```bash
140
- npm login # once, needs an npmjs.com account
141
- npm run build && npm run smoke
142
- npm publish # unscoped packages are public by default
338
+ docker build -t easybill-mcp .
339
+ docker run -p 3000:3000 -v easybill-mcp-data:/data \
340
+ -v $PWD/tenants.json:/config/tenants.json:ro \
341
+ -e EASYBILL_TENANTS_FILE=/config/tenants.json \
342
+ -e EASYBILL_PUBLIC_URL=https://easybill-mcp.example.com \
343
+ -e EASYBILL_MCP_SECRET="$(openssl rand -base64 48)" \
344
+ easybill-mcp
143
345
  ```
144
346
 
145
- Verify what ships before you publish — `npm pack --dry-run` lists the tarball contents.
146
- Only `dist/`, `README.md`, `LICENSE` and `package.json` are included; `src/` and `.env`
147
- are not.
347
+ **Cloudflare Zero Trust:** protect only the path `/connect` with an Access application (the
348
+ connect pages are opened in a browser). Leave `/mcp`, `/token`, `/register`, `/authorize` and
349
+ `/.well-known/*` outside Access — claude.ai calls them from its servers and cannot pass an Access
350
+ login. Without the connect pages nobody can complete the authorization, so tokens stay out of
351
+ reach. Set the two `EASYBILL_CF_ACCESS_*` variables so the server rejects requests that bypass
352
+ Cloudflare (e.g. via the origin IP).
148
353
 
149
- For later releases bump the version first (`npm version patch|minor|major`), which also
150
- creates a git tag. npm does not allow republishing an existing version.
151
-
152
- ---
354
+ Run it behind TLS (reverse proxy). Then in claude.ai: *Settings → Connectors → Add custom
355
+ connector* with `https://easybill-mcp.example.com/mcp` (organization admins can add it once for
356
+ everyone; each person still connects their own easybill logins).
153
357
 
154
358
  ## Configuration
155
359
 
@@ -157,7 +361,7 @@ creates a git tag. npm does not allow republishing an existing version.
157
361
  |---|---|---|
158
362
  | `EASYBILL_API_KEY` | — | **Required.** Your easybill API key. |
159
363
  | `EASYBILL_ENABLE_WRITES` | *unset* | Set to `true` to register create/update/delete tools. Otherwise read-only. |
160
- | `EASYBILL_RATE_LIMIT_PER_MINUTE` | `60` | Client-side throttle. Use `10` for PLUS, `60` for BUSINESS. |
364
+ | `EASYBILL_RATE_LIMIT_PER_MINUTE` | `60` | Client-side throttle. Use `10` for Professional, `60` for Premium. |
161
365
  | `EASYBILL_CHARACTER_LIMIT` | `25000` | Max characters per response before truncation. |
162
366
  | `EASYBILL_TIMEOUT_MS` | `30000` | HTTP request timeout. |
163
367
  | `EASYBILL_MAX_RETRIES` | `3` | Retries on HTTP 429 / 5xx. |
@@ -171,11 +375,12 @@ creates a git tag. npm does not allow republishing an existing version.
171
375
 
172
376
  | Tool | Access |
173
377
  |---|---|
174
- | `easybill_find_customer` | read — **start here**: fuzzy search by name, email or number |
378
+ | `easybill_find_customer` | read — **start here**: search customers or suppliers by name, email or number |
175
379
 
176
- The easybill API has no full-text search, so this tool tries exact filters first, then pages
177
- the customer list and scores candidates locally. It tolerates legal forms (`GmbH & Co. KG`),
178
- punctuation (`M.B. MUSTERMANN` vs `MB Mustermann`), umlauts and word order.
380
+ Uses easybill's full-text search (one request, archived contacts included) and ranks the hits
381
+ locally, tolerating legal forms (`GmbH & Co. KG`), punctuation (`M.B. MUSTERMANN` vs
382
+ `MB Mustermann`), umlauts and word order. If the search endpoint is unavailable it falls back to
383
+ exact filters plus a local scan of the customer list.
179
384
 
180
385
  ### Documents — invoices, offers, credit notes, deliveries, orders
181
386
 
@@ -183,7 +388,8 @@ punctuation (`M.B. MUSTERMANN` vs `MB Mustermann`), umlauts and word order.
183
388
  |---|---|
184
389
  | `easybill_list_documents` | read |
185
390
  | `easybill_get_document` | read |
186
- | `easybill_download_document` | read — saves PDF / ZUGFeRD / XRechnung to disk |
391
+ | `easybill_search_documents` | read — full-text search by word, name or number |
392
+ | `easybill_download_document` | read — PDF, image, ZUGFeRD 1.0–2.5, XRechnung (to disk locally, inline when hosted) |
187
393
  | `easybill_list_document_versions` | read — audit trail |
188
394
  | `easybill_create_document` | write |
189
395
  | `easybill_update_document` | write |
@@ -225,9 +431,24 @@ punctuation (`M.B. MUSTERMANN` vs `MB Mustermann`), umlauts and word order.
225
431
  `easybill_delete_attachment`, `easybill_list_text_templates`, `easybill_get_text_template`,
226
432
  `easybill_list_pdf_templates`
227
433
 
434
+ ### Incoming documents (Eingangsbelege)
435
+
436
+ `easybill_list_incoming_documents`, `easybill_search_incoming_documents`,
437
+ `easybill_get_incoming_document`, `easybill_list_incoming_document_files`,
438
+ `easybill_download_incoming_document_file` (read);
439
+ `easybill_upload_incoming_document`, `easybill_update_incoming_document`,
440
+ `easybill_complete_incoming_document`, `easybill_delete_incoming_document` (write).
441
+
442
+ Uploads are extracted by easybill in the background; the tools guide the agent through
443
+ review → correction → completion.
444
+
228
445
  ### Server
229
446
 
230
447
  `easybill_get_server_info` — reports mode, limits and whether the credentials work.
448
+ In hosted mode also `easybill_list_accounts` — connected accounts and the link to connect more.
449
+
450
+ Files in hosted mode: downloads come back inside the tool result and uploads take base64 —
451
+ the server never reads or writes caller-chosen paths on its own disk.
231
452
 
232
453
  ---
233
454
 
@@ -275,7 +496,7 @@ legal reasons.
275
496
 
276
497
  ### Rate limits are low
277
498
 
278
- easybill allows **10 requests/minute on PLUS** and **60 on BUSINESS**. The server throttles
499
+ easybill allows **10 requests/minute on Professional** and **60 on Premium** (formerly PLUS and BUSINESS). The server throttles
279
500
  itself to `EASYBILL_RATE_LIMIT_PER_MINUTE` and, if a 429 slips through, retries while honouring
280
501
  `Retry-After`. Set the variable to match your plan — otherwise a broad question that pages
281
502
  through many documents will stall.
@@ -295,11 +516,11 @@ field set**, and single-record lookups return everything. Both accept `fields`:
295
516
  Responses over `EASYBILL_CHARACTER_LIMIT` are truncated, halving the item count until they
296
517
  fit, and say so in `truncation_message`.
297
518
 
298
- ### No fuzzy customer search
519
+ ### Full-text search vs. filters
299
520
 
300
- The easybill API has no full-text search. Customer filters match **exact** values (each
301
- accepts several comma-separated). To find a customer by partial name, either use the exact
302
- spelling or page through and match locally.
521
+ List filters match **exact** values (each accepts several comma-separated). For a partial name,
522
+ a word or a topic use the full-text tools (API 1.102+): `easybill_find_customer`,
523
+ `easybill_search_documents`, `easybill_search_incoming_documents`. Each costs one request.
303
524
 
304
525
  ### Useful filter recipes
305
526
 
@@ -12,7 +12,7 @@ export declare const CHARACTER_LIMIT: number;
12
12
  /** HTTP request timeout. */
13
13
  export declare const TIMEOUT_MS: number;
14
14
  /**
15
- * Client-side throttle. easybill allows 10 req/min (PLUS) and 60 req/min (BUSINESS).
15
+ * Client-side throttle. easybill allows 10 req/min (Professional) and 60 req/min (Premium).
16
16
  * Throttling locally is cheaper than burning retries on HTTP 429.
17
17
  */
18
18
  export declare const RATE_LIMIT_PER_MINUTE: number;
@@ -51,4 +51,5 @@ export declare const SUMMARY_FIELDS: {
51
51
  readonly customerGroup: readonly ["id", "number", "name", "display_name", "description"];
52
52
  readonly serialNumber: readonly ["id", "serial_number", "position_id", "document_id", "used_at", "created_at"];
53
53
  readonly pdfTemplate: readonly ["id", "name", "pdf_template", "document_type"];
54
+ readonly incomingDocument: readonly ["id", "status", "document_type", "document_number", "external_number", "issue_date", "due_date", "total_gross_amount", "total_net_amount", "currency_code", "is_paid", "supplier_id", "supplier", "interface", "created_at"];
54
55
  };
package/dist/constants.js CHANGED
@@ -32,7 +32,7 @@ export const CHARACTER_LIMIT = intFromEnv("EASYBILL_CHARACTER_LIMIT", 25_000, 1_
32
32
  /** HTTP request timeout. */
33
33
  export const TIMEOUT_MS = intFromEnv("EASYBILL_TIMEOUT_MS", 30_000, 1_000);
34
34
  /**
35
- * Client-side throttle. easybill allows 10 req/min (PLUS) and 60 req/min (BUSINESS).
35
+ * Client-side throttle. easybill allows 10 req/min (Professional) and 60 req/min (Premium).
36
36
  * Throttling locally is cheaper than burning retries on HTTP 429.
37
37
  */
38
38
  export const RATE_LIMIT_PER_MINUTE = intFromEnv("EASYBILL_RATE_LIMIT_PER_MINUTE", 60, 1);
@@ -215,5 +215,22 @@ export const SUMMARY_FIELDS = {
215
215
  customerGroup: ["id", "number", "name", "display_name", "description"],
216
216
  serialNumber: ["id", "serial_number", "position_id", "document_id", "used_at", "created_at"],
217
217
  pdfTemplate: ["id", "name", "pdf_template", "document_type"],
218
+ incomingDocument: [
219
+ "id",
220
+ "status",
221
+ "document_type",
222
+ "document_number",
223
+ "external_number",
224
+ "issue_date",
225
+ "due_date",
226
+ "total_gross_amount",
227
+ "total_net_amount",
228
+ "currency_code",
229
+ "is_paid",
230
+ "supplier_id",
231
+ "supplier",
232
+ "interface",
233
+ "created_at",
234
+ ],
218
235
  };
219
236
  //# sourceMappingURL=constants.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Hosted mode: the account overview tool and the instructions that explain
3
+ * accounts to the model.
4
+ */
5
+ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
6
+ import type { TenantConfig } from "./config.js";
7
+ import type { ConnectionRow } from "./store.js";
8
+ export declare function accountInstructions(tenants: TenantConfig[], connections: ConnectionRow[]): string;
9
+ export declare function registerAccountTools(server: McpServer, deps: {
10
+ tenants: TenantConfig[];
11
+ connections: ConnectionRow[];
12
+ manageLink: () => string;
13
+ }): void;
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Hosted mode: the account overview tool and the instructions that explain
3
+ * accounts to the model.
4
+ */
5
+ import { registerRead } from "../tools/registry.js";
6
+ function statusOf(connection) {
7
+ if (!connection)
8
+ return "not_connected";
9
+ return connection.broken_reason ? "expired" : "connected";
10
+ }
11
+ export function accountInstructions(tenants, connections) {
12
+ const usable = tenants.filter((t) => statusOf(connections.find((c) => c.tenant_id === t.id)) === "connected");
13
+ const lines = [
14
+ "# Accounts",
15
+ "",
16
+ "This server reaches several easybill accounts (companies). Every tool takes an `account` argument.",
17
+ ];
18
+ if (usable.length === 0) {
19
+ lines.push("", "No account is connected for this user yet. Call `easybill_list_accounts` and give the user the link to connect one.");
20
+ }
21
+ else {
22
+ lines.push("", "Connected for this user:", ...usable.map((t) => `- \`${t.id}\` = ${t.name} (${t.writes ? "read & write" : "read-only"})`), "", "- Customers, documents, IDs and numbers belong to ONE account. Never reuse an ID from one account in a call on another.", "- If the request does not make clear which account is meant and more than one is connected, ask the user.", "- If the user needs an account that is not connected, or a call reports an expired connection, call " +
23
+ "`easybill_list_accounts` and give them the link.");
24
+ }
25
+ return lines.join("\n");
26
+ }
27
+ export function registerAccountTools(server, deps) {
28
+ registerRead(server, {
29
+ name: "easybill_list_accounts",
30
+ title: "List easybill accounts and connection status",
31
+ description: "List the easybill accounts (companies) this server can reach, which of them the user has connected, " +
32
+ "and whether each allows writes. Also returns a link where the user connects more accounts or " +
33
+ "reconnects an expired one with their own easybill login.\n\n" +
34
+ "Call this when the user asks which accounts are available, names an account that is not connected, " +
35
+ "or a tool reports an expired connection. Give the user the link — it is valid for 30 minutes. " +
36
+ "Costs no easybill request.",
37
+ inputSchema: {},
38
+ accountless: true,
39
+ }, async () => {
40
+ const byTenant = new Map(deps.connections.map((c) => [c.tenant_id, c]));
41
+ const accounts = deps.tenants.map((t) => {
42
+ const connection = byTenant.get(t.id);
43
+ return {
44
+ account: t.id,
45
+ name: t.name,
46
+ status: statusOf(connection),
47
+ writes: t.writes,
48
+ ...(connection?.login_label ? { connected_as: connection.login_label } : {}),
49
+ };
50
+ });
51
+ const link = deps.manageLink();
52
+ const label = {
53
+ connected: "connected",
54
+ expired: "EXPIRED — reconnect via the link",
55
+ not_connected: "not connected",
56
+ };
57
+ const text = [
58
+ "# easybill accounts",
59
+ "",
60
+ ...accounts.map((a) => `- **${a.name}** (\`${a.account}\`): ${label[a.status]}` +
61
+ `${a.connected_as ? ` as ${a.connected_as}` : ""}, ${a.writes ? "read & write" : "read-only"}`),
62
+ "",
63
+ `Connect or reconnect accounts here (valid 30 minutes): ${link}`,
64
+ "A newly connected account works from the next tool call on — pass its id as `account` even if an " +
65
+ "older tool list does not show it yet.",
66
+ ].join("\n");
67
+ return { content: [{ type: "text", text }], structuredContent: { accounts, connect_url: link } };
68
+ });
69
+ }
70
+ //# sourceMappingURL=accounts.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"accounts.js","sourceRoot":"","sources":["../../src/hosted/accounts.ts"],"names":[],"mappings":"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"}