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.
- package/README.md +293 -72
- package/dist/constants.d.ts +2 -1
- package/dist/constants.js +18 -1
- package/dist/constants.js.map +1 -1
- package/dist/hosted/accounts.d.ts +13 -0
- package/dist/hosted/accounts.js +70 -0
- package/dist/hosted/accounts.js.map +1 -0
- package/dist/hosted/config.d.ts +73 -0
- package/dist/hosted/config.js +200 -0
- package/dist/hosted/config.js.map +1 -0
- package/dist/hosted/http.d.ts +23 -0
- package/dist/hosted/http.js +524 -0
- package/dist/hosted/http.js.map +1 -0
- package/dist/hosted/pages.d.ts +22 -0
- package/dist/hosted/pages.js +130 -0
- package/dist/hosted/pages.js.map +1 -0
- package/dist/hosted/provider.d.ts +54 -0
- package/dist/hosted/provider.js +190 -0
- package/dist/hosted/provider.js.map +1 -0
- package/dist/hosted/store.d.ts +119 -0
- package/dist/hosted/store.js +254 -0
- package/dist/hosted/store.js.map +1 -0
- package/dist/hosted/upstream.d.ts +68 -0
- package/dist/hosted/upstream.js +280 -0
- package/dist/hosted/upstream.js.map +1 -0
- package/dist/index.d.ts +5 -1
- package/dist/index.js +19 -24
- package/dist/index.js.map +1 -1
- package/dist/instructions.d.ts +1 -1
- package/dist/instructions.js +16 -1
- package/dist/instructions.js.map +1 -1
- package/dist/server.d.ts +26 -0
- package/dist/server.js +47 -0
- package/dist/server.js.map +1 -0
- package/dist/services/client.d.ts +43 -4
- package/dist/services/client.js +35 -9
- package/dist/services/client.js.map +1 -1
- package/dist/services/format.d.ts +17 -4
- package/dist/services/format.js.map +1 -1
- package/dist/tools/catalog.d.ts +2 -2
- package/dist/tools/catalog.js.map +1 -1
- package/dist/tools/crud.d.ts +2 -2
- package/dist/tools/crud.js.map +1 -1
- package/dist/tools/customers.d.ts +2 -2
- package/dist/tools/customers.js +12 -4
- package/dist/tools/customers.js.map +1 -1
- package/dist/tools/documents.d.ts +2 -2
- package/dist/tools/documents.js +73 -43
- package/dist/tools/documents.js.map +1 -1
- package/dist/tools/files-io.d.ts +44 -0
- package/dist/tools/files-io.js +173 -0
- package/dist/tools/files-io.js.map +1 -0
- package/dist/tools/files.d.ts +2 -2
- package/dist/tools/files.js +9 -27
- package/dist/tools/files.js.map +1 -1
- package/dist/tools/finance.d.ts +2 -2
- package/dist/tools/finance.js.map +1 -1
- package/dist/tools/incoming.d.ts +11 -0
- package/dist/tools/incoming.js +222 -0
- package/dist/tools/incoming.js.map +1 -0
- package/dist/tools/meta.d.ts +2 -2
- package/dist/tools/meta.js +14 -6
- package/dist/tools/meta.js.map +1 -1
- package/dist/tools/registry.d.ts +40 -9
- package/dist/tools/registry.js +75 -12
- package/dist/tools/registry.js.map +1 -1
- package/dist/tools/search.d.ts +9 -8
- package/dist/tools/search.js +49 -17
- package/dist/tools/search.js.map +1 -1
- package/dist/tools/work.d.ts +2 -2
- package/dist/tools/work.js.map +1 -1
- 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
|
|
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
|
-
- **
|
|
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.
|
|
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
|
-
|
|
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
|
|
73
|
-
|
|
74
|
-
### 4. Register with Claude Code
|
|
251
|
+
> the key through the client's config, not via `.env`.
|
|
75
252
|
|
|
76
|
-
|
|
253
|
+
### Publishing to npm
|
|
77
254
|
|
|
78
255
|
```bash
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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
|
-
|
|
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
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
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
|
-
|
|
270
|
+
## Hosted mode (claude.ai connector, several easybill accounts)
|
|
96
271
|
|
|
97
|
-
|
|
272
|
+
`easybill-mcp --http` runs the server as a remote MCP endpoint (Streamable HTTP) for a whole
|
|
273
|
+
company:
|
|
98
274
|
|
|
99
|
-
|
|
100
|
-
|
|
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
|
-
|
|
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
|
-
|
|
298
|
+
### Tenant configuration
|
|
106
299
|
|
|
107
300
|
```json
|
|
108
301
|
{
|
|
109
|
-
"
|
|
110
|
-
"
|
|
111
|
-
|
|
112
|
-
|
|
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
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
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
|
-
|
|
134
|
-
claude mcp add easybill --env EASYBILL_API_KEY=your_key -- npx -y github:stack74/easybill-mcp
|
|
135
|
-
```
|
|
318
|
+
### Environment
|
|
136
319
|
|
|
137
|
-
|
|
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
|
-
|
|
141
|
-
|
|
142
|
-
|
|
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
|
-
|
|
146
|
-
|
|
147
|
-
|
|
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
|
-
|
|
150
|
-
|
|
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
|
|
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**:
|
|
378
|
+
| `easybill_find_customer` | read — **start here**: search customers or suppliers by name, email or number |
|
|
175
379
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
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
|
-
| `
|
|
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
|
|
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
|
-
###
|
|
519
|
+
### Full-text search vs. filters
|
|
299
520
|
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
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
|
|
package/dist/constants.d.ts
CHANGED
|
@@ -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 (
|
|
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 (
|
|
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
|
package/dist/constants.js.map
CHANGED
|
@@ -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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"}
|