simpleshop-mcp-unofficial 0.1.0-alpha.1
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/LICENSE +28 -0
- package/README.cs.md +130 -0
- package/README.md +148 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1909 -0
- package/dist/index.js.map +1 -0
- package/package.json +90 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Pavel Ungr
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
Trademark notice:
|
|
26
|
+
"SimpleShop" and "Simpleshop" are trademarks of Redbit s.r.o. This project is
|
|
27
|
+
not affiliated with, endorsed by, or sponsored by Redbit s.r.o. or
|
|
28
|
+
SimpleShop.cz. The names are used solely to describe API compatibility.
|
package/README.cs.md
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# Simpleshop MCP
|
|
2
|
+
|
|
3
|
+
> Neoficiální Model Context Protocol (MCP) server pro [SimpleShop.cz](https://www.simpleshop.cz) API.
|
|
4
|
+
> Autor a maintainer: [Pavel Ungr](https://github.com/pavelungr).
|
|
5
|
+
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](#mapa)
|
|
8
|
+
[](README.md)
|
|
9
|
+
|
|
10
|
+
> ⚠️ **Neoficiální projekt.** Není nijak spojený se společností Redbit s.r.o. ani SimpleShop.cz.
|
|
11
|
+
> Uživatelé se připojují vlastními SimpleShop přihlašovacími údaji a nesou plnou odpovědnost za všechny
|
|
12
|
+
> akce provedené přes tento server, včetně vystavování, úprav a mazání účetních dokladů.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## K čemu to je
|
|
17
|
+
|
|
18
|
+
Lokální MCP server, který zpřístupňuje veřejné SimpleShop REST API jako MCP nástroje, zdroje a šablony promptů.
|
|
19
|
+
LLM klienti (Claude Desktop, Claude Code, Cursor, Codex a další) přes něj mohou číst, vyhledávat, vytvářet
|
|
20
|
+
a spravovat faktury, kontakty, produkty a další data ve vašem účtu SimpleShop.
|
|
21
|
+
|
|
22
|
+
Server běží **lokálně**. Přihlašovací údaje dostává přes environment proměnné, komunikuje přímo
|
|
23
|
+
s `api.simpleshop.cz` a nikam jinam nic neposílá.
|
|
24
|
+
|
|
25
|
+
## K čemu to není
|
|
26
|
+
|
|
27
|
+
- Není to oficiální produkt SimpleShop.
|
|
28
|
+
- Není to hostovaná multi-tenant služba.
|
|
29
|
+
- Nenahrazuje webové rozhraní SimpleShopu.
|
|
30
|
+
- Není to zálohovací nebo synchronizační nástroj.
|
|
31
|
+
- Není to obal nad jiný fakturační systém (Vyfakturuj, Pohoda…).
|
|
32
|
+
|
|
33
|
+
## Stav projektu
|
|
34
|
+
|
|
35
|
+
**Pre-release / plánování.** Repozitář aktuálně obsahuje architekturu, design a plánovací dokumenty.
|
|
36
|
+
Implementace bude přicházet v milnících popsaných v [`docs/requirements/prd.md`](docs/requirements/prd.md).
|
|
37
|
+
|
|
38
|
+
## Rychlý start (cílové rozhraní)
|
|
39
|
+
|
|
40
|
+
> Příkazy níže popisují **cílovou** instalaci. Bude fungovat po vydání verze `0.1.0-alpha`.
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
SIMPLESHOP_LOGIN="user@example.com" \
|
|
44
|
+
SIMPLESHOP_API_KEY="vas-api-klic" \
|
|
45
|
+
npx -y simpleshop-mcp-unofficial@latest
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Konfigurace MCP klienta (Claude Desktop / Claude Code)
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"mcpServers": {
|
|
53
|
+
"simpleshop": {
|
|
54
|
+
"command": "npx",
|
|
55
|
+
"args": ["-y", "simpleshop-mcp-unofficial@latest"],
|
|
56
|
+
"env": {
|
|
57
|
+
"SIMPLESHOP_LOGIN": "user@example.com",
|
|
58
|
+
"SIMPLESHOP_API_KEY": "vas-api-klic",
|
|
59
|
+
"SIMPLESHOP_READ_ONLY": "false",
|
|
60
|
+
"SIMPLESHOP_ENABLE_DESTRUCTIVE_TOOLS": "false"
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
> **Doporučení:** v produkci pinujte major verzi (`simpleshop-mcp-unofficial@1`) místo `@latest`.
|
|
68
|
+
|
|
69
|
+
## Bezpečnostní režimy
|
|
70
|
+
|
|
71
|
+
| Režim | Čtení | Zápis | E-mail | Destruktivní |
|
|
72
|
+
|---|---|---|---|---|
|
|
73
|
+
| `read-only` | ✓ | ✗ | ✗ | ✗ |
|
|
74
|
+
| `safe-write` (doporučený default) | ✓ | ✓ | ✗ | ✗ |
|
|
75
|
+
| `email-write` | ✓ | ✓ | ✓ | ✗ |
|
|
76
|
+
| `full` | ✓ | ✓ | ✓ | ✓ |
|
|
77
|
+
|
|
78
|
+
Přepíná se přes environment flagy (viz [README.md](README.md) → Configuration).
|
|
79
|
+
Důvody jednotlivých rozhodnutí najdete v [`docs/architecture.md`](docs/architecture.md).
|
|
80
|
+
|
|
81
|
+
## Mapa
|
|
82
|
+
|
|
83
|
+
| Fáze | Cíl | Verze |
|
|
84
|
+
|---|---|---|
|
|
85
|
+
| 0 | Bootstrap (tento repozitář) | — |
|
|
86
|
+
| 1 | Core MVP (read-only tools, test připojení) | `0.1.0-alpha` |
|
|
87
|
+
| 2 | Write tools (vytvořit/upravit faktury, kontakty) | `0.2.0` |
|
|
88
|
+
| 3 | E-mail + destruktivní tools (za flagem) | `0.3.0` |
|
|
89
|
+
| 4 | MCP zdroje + šablony promptů | `0.4.0` |
|
|
90
|
+
| 5 | Helper tools, Docker, registry | `1.0.0` |
|
|
91
|
+
|
|
92
|
+
Detailní plán: [`docs/requirements/prd.md`](docs/requirements/prd.md).
|
|
93
|
+
|
|
94
|
+
## Dokumentace
|
|
95
|
+
|
|
96
|
+
- [`CLAUDE.md`](CLAUDE.md) — kompletní design a rozhodovací dokument.
|
|
97
|
+
- [`docs/architecture.md`](docs/architecture.md) — vrstvy, datový tok, klíčová rozhodnutí.
|
|
98
|
+
- [`docs/conventions.md`](docs/conventions.md) — názvosloví, commit, branch a kódové konvence.
|
|
99
|
+
- [`docs/gotchas.md`](docs/gotchas.md) — nečekané chování a workaroundy.
|
|
100
|
+
- [`docs/api/`](docs/api/) — mapování modulů na SimpleShop endpointy.
|
|
101
|
+
- [`docs/requirements/prd.md`](docs/requirements/prd.md) — produktové požadavky a decision log.
|
|
102
|
+
|
|
103
|
+
## Soukromí
|
|
104
|
+
|
|
105
|
+
- Server běží lokálně na vašem počítači.
|
|
106
|
+
- API přihlašovací údaje se předávají environment proměnnými a nejsou nikam logovány.
|
|
107
|
+
- Žádná telemetrie defaultně (opt-in OpenTelemetry export pouze pokud explicitně zapnete).
|
|
108
|
+
- Audit log (pokud je zapnutý) je lokální soubor — máte ho pod kontrolou.
|
|
109
|
+
|
|
110
|
+
Hlášení bezpečnostních problémů: [`SECURITY.md`](SECURITY.md).
|
|
111
|
+
|
|
112
|
+
## Související zdroje
|
|
113
|
+
|
|
114
|
+
- [SimpleShop API dokumentace (Apiary)](https://simpleshopcz.docs.apiary.io/)
|
|
115
|
+
- [Oficiální SimpleShop PHP SDK](https://github.com/redbitcz/simpleshop-api-php-sdk)
|
|
116
|
+
- [Návod Redbit k API](https://podpora.redbit.cz/navod/api-ve-vyfakturuj-cz-a-simpleshopu/)
|
|
117
|
+
- [Model Context Protocol](https://modelcontextprotocol.io/)
|
|
118
|
+
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
|
|
119
|
+
|
|
120
|
+
## Přispívání
|
|
121
|
+
|
|
122
|
+
Pull requesty vítáme — nejdřív si prosím přečtěte [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
|
123
|
+
Účastí v projektu souhlasíte s [Kodexem chování](CODE_OF_CONDUCT.md).
|
|
124
|
+
|
|
125
|
+
## Licence
|
|
126
|
+
|
|
127
|
+
[MIT](LICENSE) © 2026 Pavel Ungr.
|
|
128
|
+
|
|
129
|
+
„SimpleShop" a „Simpleshop" jsou ochranné známky společnosti Redbit s.r.o. a jsou zde použity výhradně
|
|
130
|
+
k popisu kompatibility s API.
|
package/README.md
ADDED
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
# Simpleshop MCP
|
|
2
|
+
|
|
3
|
+
> Unofficial Model Context Protocol (MCP) server for the [SimpleShop.cz](https://www.simpleshop.cz) API.
|
|
4
|
+
> Created and maintained by [Pavel Ungr](https://github.com/pavelungr).
|
|
5
|
+
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](#roadmap)
|
|
8
|
+
[](README.cs.md)
|
|
9
|
+
|
|
10
|
+
> ⚠️ **Unofficial.** This project is not affiliated with, endorsed by, or sponsored by Redbit s.r.o. or SimpleShop.cz.
|
|
11
|
+
> Users connect with their own SimpleShop credentials and assume full responsibility for any actions taken via this server,
|
|
12
|
+
> including the creation, modification, and deletion of accounting documents.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## What this is
|
|
17
|
+
|
|
18
|
+
A local MCP server that exposes the SimpleShop public REST API as a set of MCP tools, resources and prompts.
|
|
19
|
+
LLM-based clients (Claude Desktop, Claude Code, Cursor, Codex, etc.) can use it to read, search, create and manage
|
|
20
|
+
invoices, contacts, products and related data in your SimpleShop account.
|
|
21
|
+
|
|
22
|
+
The server runs **locally**. It receives your SimpleShop credentials from environment variables, talks directly
|
|
23
|
+
to `api.simpleshop.cz`, and never sends data to any third party.
|
|
24
|
+
|
|
25
|
+
## What this is not
|
|
26
|
+
|
|
27
|
+
- Not an official SimpleShop product.
|
|
28
|
+
- Not a hosted multi-tenant service.
|
|
29
|
+
- Not a replacement for the SimpleShop web UI.
|
|
30
|
+
- Not a backup or sync solution.
|
|
31
|
+
- Not a wrapper around any other invoicing system (Vyfakturuj, Pohoda, …).
|
|
32
|
+
|
|
33
|
+
## Status
|
|
34
|
+
|
|
35
|
+
**Pre-release / planning.** The repository currently contains the architecture, design and planning documents.
|
|
36
|
+
Implementation will land in milestones described in [`docs/requirements/prd.md`](docs/requirements/prd.md).
|
|
37
|
+
|
|
38
|
+
## Quick start (planned interface)
|
|
39
|
+
|
|
40
|
+
> The commands below describe the **target** install experience. They will work once `0.1.0-alpha` ships.
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
SIMPLESHOP_LOGIN="user@example.com" \
|
|
44
|
+
SIMPLESHOP_API_KEY="your-api-key" \
|
|
45
|
+
npx -y simpleshop-mcp-unofficial@latest
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### MCP client config (Claude Desktop / Claude Code)
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"mcpServers": {
|
|
53
|
+
"simpleshop": {
|
|
54
|
+
"command": "npx",
|
|
55
|
+
"args": ["-y", "simpleshop-mcp-unofficial@latest"],
|
|
56
|
+
"env": {
|
|
57
|
+
"SIMPLESHOP_LOGIN": "user@example.com",
|
|
58
|
+
"SIMPLESHOP_API_KEY": "your-api-key",
|
|
59
|
+
"SIMPLESHOP_READ_ONLY": "false",
|
|
60
|
+
"SIMPLESHOP_ENABLE_DESTRUCTIVE_TOOLS": "false"
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
> **Recommendation:** for production use, pin the major version (`simpleshop-mcp-unofficial@1`) instead of `@latest`.
|
|
68
|
+
|
|
69
|
+
## Configuration
|
|
70
|
+
|
|
71
|
+
| Variable | Required | Default | Description |
|
|
72
|
+
|---|---|---|---|
|
|
73
|
+
| `SIMPLESHOP_LOGIN` | yes | — | Your SimpleShop account e-mail |
|
|
74
|
+
| `SIMPLESHOP_API_KEY` | yes | — | API key from your SimpleShop settings |
|
|
75
|
+
| `SIMPLESHOP_BASE_URL` | no | `https://api.simpleshop.cz/2.0/` | API endpoint (override for testing only) |
|
|
76
|
+
| `SIMPLESHOP_READ_ONLY` | no | `false` | Disable all write tools |
|
|
77
|
+
| `SIMPLESHOP_ENABLE_DESTRUCTIVE_TOOLS` | no | `false` | Allow `delete_*` tools |
|
|
78
|
+
| `SIMPLESHOP_ENABLE_EMAIL_TOOLS` | no | `false` | Allow `send_invoice_email` |
|
|
79
|
+
| `SIMPLESHOP_REQUIRE_CONFIRMATION` | no | `true` | Require `confirm: true` for destructive/email actions |
|
|
80
|
+
| `SIMPLESHOP_REQUEST_TIMEOUT_MS` | no | `30000` | HTTP request timeout |
|
|
81
|
+
| `SIMPLESHOP_MAX_RETRIES` | no | `3` | Retry budget for 5xx/429 |
|
|
82
|
+
| `SIMPLESHOP_RATE_LIMIT_RPS` | no | `5` | Client-side rate limit |
|
|
83
|
+
| `SIMPLESHOP_LOG_LEVEL` | no | `info` | `trace` / `debug` / `info` / `warn` / `error` |
|
|
84
|
+
| `SIMPLESHOP_LOG_FORMAT` | no | `json` | `json` / `pretty` |
|
|
85
|
+
| `SIMPLESHOP_TELEMETRY` | no | `disabled` | Opt-in OpenTelemetry export (`disabled` / `local` / `otlp`) |
|
|
86
|
+
|
|
87
|
+
The full table is in [`CLAUDE.md`](CLAUDE.md) section 6.
|
|
88
|
+
|
|
89
|
+
## Security modes
|
|
90
|
+
|
|
91
|
+
| Mode | Read | Write | Email | Destructive |
|
|
92
|
+
|---|---|---|---|---|
|
|
93
|
+
| `read-only` | ✓ | ✗ | ✗ | ✗ |
|
|
94
|
+
| `safe-write` (recommended default) | ✓ | ✓ | ✗ | ✗ |
|
|
95
|
+
| `email-write` | ✓ | ✓ | ✓ | ✗ |
|
|
96
|
+
| `full` | ✓ | ✓ | ✓ | ✓ |
|
|
97
|
+
|
|
98
|
+
Toggle the modes through the env flags listed above. See [`docs/architecture.md`](docs/architecture.md) for rationale.
|
|
99
|
+
|
|
100
|
+
## Roadmap
|
|
101
|
+
|
|
102
|
+
| Phase | Goal | Version |
|
|
103
|
+
|---|---|---|
|
|
104
|
+
| 0 | Bootstrap (this repo) | — |
|
|
105
|
+
| 1 | Core MVP (read-only tools, test connection) | `0.1.0-alpha` |
|
|
106
|
+
| 2 | Write tools (create/update invoices, contacts) | `0.2.0` |
|
|
107
|
+
| 3 | E-mail + destructive tools (gated) | `0.3.0` |
|
|
108
|
+
| 4 | MCP resources + prompts | `0.4.0` |
|
|
109
|
+
| 5 | Helper tools, Docker, registries | `1.0.0` |
|
|
110
|
+
|
|
111
|
+
Detailed plan: [`docs/requirements/prd.md`](docs/requirements/prd.md).
|
|
112
|
+
|
|
113
|
+
## Documentation
|
|
114
|
+
|
|
115
|
+
- [`CLAUDE.md`](CLAUDE.md) — comprehensive design and decision document (Czech).
|
|
116
|
+
- [`docs/architecture.md`](docs/architecture.md) — layers, data flow, key decisions.
|
|
117
|
+
- [`docs/conventions.md`](docs/conventions.md) — naming, commit, branch and code conventions.
|
|
118
|
+
- [`docs/gotchas.md`](docs/gotchas.md) — surprising behaviour and workarounds.
|
|
119
|
+
- [`docs/api/`](docs/api/) — per-module mapping to SimpleShop endpoints.
|
|
120
|
+
- [`docs/requirements/prd.md`](docs/requirements/prd.md) — product requirements and decision log.
|
|
121
|
+
|
|
122
|
+
## Privacy
|
|
123
|
+
|
|
124
|
+
- The server runs locally on your machine.
|
|
125
|
+
- API credentials are passed via environment variables and never logged.
|
|
126
|
+
- No telemetry by default (opt-in OpenTelemetry export only).
|
|
127
|
+
- The audit log (if enabled) is written to your local filesystem — you control it.
|
|
128
|
+
|
|
129
|
+
See [`SECURITY.md`](SECURITY.md) for vulnerability reporting.
|
|
130
|
+
|
|
131
|
+
## Related resources
|
|
132
|
+
|
|
133
|
+
- [SimpleShop API documentation (Apiary)](https://simpleshopcz.docs.apiary.io/)
|
|
134
|
+
- [Official SimpleShop PHP SDK](https://github.com/redbitcz/simpleshop-api-php-sdk)
|
|
135
|
+
- [Redbit support article on the API](https://podpora.redbit.cz/navod/api-ve-vyfakturuj-cz-a-simpleshopu/)
|
|
136
|
+
- [Model Context Protocol](https://modelcontextprotocol.io/)
|
|
137
|
+
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
|
|
138
|
+
|
|
139
|
+
## Contributing
|
|
140
|
+
|
|
141
|
+
Pull requests welcome — please read [`CONTRIBUTING.md`](CONTRIBUTING.md) first.
|
|
142
|
+
By participating in this project you agree to abide by the [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
143
|
+
|
|
144
|
+
## License
|
|
145
|
+
|
|
146
|
+
[MIT](LICENSE) © 2026 Pavel Ungr.
|
|
147
|
+
|
|
148
|
+
"SimpleShop" and "Simpleshop" are trademarks of Redbit s.r.o. and are used here solely to describe API compatibility.
|
package/dist/index.d.ts
ADDED