libscanner-mcp 0.1.0__tar.gz
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.
- libscanner_mcp-0.1.0/.gitignore +6 -0
- libscanner_mcp-0.1.0/Dockerfile +23 -0
- libscanner_mcp-0.1.0/LICENSE +21 -0
- libscanner_mcp-0.1.0/PKG-INFO +178 -0
- libscanner_mcp-0.1.0/README.md +150 -0
- libscanner_mcp-0.1.0/pyproject.toml +47 -0
- libscanner_mcp-0.1.0/server.json +41 -0
- libscanner_mcp-0.1.0/src/libscanner_mcp/__init__.py +7 -0
- libscanner_mcp-0.1.0/src/libscanner_mcp/api.py +169 -0
- libscanner_mcp-0.1.0/src/libscanner_mcp/cli.py +76 -0
- libscanner_mcp-0.1.0/src/libscanner_mcp/limits.py +111 -0
- libscanner_mcp-0.1.0/src/libscanner_mcp/server.py +449 -0
- libscanner_mcp-0.1.0/tests/test_server.py +607 -0
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Облачный вид сервера MCP — https://mcp.libscanner.com/mcp (Streamable HTTP за nginx).
|
|
2
|
+
# Сервис без состояния: каждый запрос самостоятельный, логики распознавания
|
|
3
|
+
# в нём нет — только вызовы api.libscanner.com.
|
|
4
|
+
FROM python:3.12-slim
|
|
5
|
+
|
|
6
|
+
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
|
|
7
|
+
|
|
8
|
+
WORKDIR /app
|
|
9
|
+
COPY pyproject.toml README.md LICENSE ./
|
|
10
|
+
COPY src ./src
|
|
11
|
+
RUN pip install --no-cache-dir ".[cloud]"
|
|
12
|
+
|
|
13
|
+
# Не от root: сервису не нужны ни файлы, ни привилегии.
|
|
14
|
+
RUN useradd --system --no-create-home mcp
|
|
15
|
+
USER mcp
|
|
16
|
+
|
|
17
|
+
EXPOSE 8000
|
|
18
|
+
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
|
|
19
|
+
CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=2).status == 200 else 1)"
|
|
20
|
+
|
|
21
|
+
# Адрес клиента для лимита вызовов без входа приходит в X-Real-IP от nginx;
|
|
22
|
+
# имена хоста — в LIBSCANNER_MCP_ALLOWED_HOSTS.
|
|
23
|
+
CMD ["libscanner-mcp", "--http", "--host", "0.0.0.0", "--port", "8000"]
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 libscanner
|
|
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.
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: libscanner-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: MCP server for libscanner: read and generate DataMatrix, QR and barcodes, parse GS1 and Chestny ZNAK marking codes
|
|
5
|
+
Project-URL: Homepage, https://libscanner.com/api/
|
|
6
|
+
Project-URL: Documentation, https://libscanner.com/docs/api/?lang=mcp
|
|
7
|
+
Author-email: libscanner <libscanner@yandex.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: barcode,chestny-znak,datamatrix,gs1,mcp,model-context-protocol,qr
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Topic :: Multimedia :: Graphics :: Capture :: Scanners
|
|
18
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
19
|
+
Requires-Python: >=3.11
|
|
20
|
+
Requires-Dist: httpx2<3,>=2.16
|
|
21
|
+
Requires-Dist: mcp<3,>=2.3
|
|
22
|
+
Provides-Extra: cloud
|
|
23
|
+
Requires-Dist: mcp[cli]<3,>=2.3; extra == 'cloud'
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: anyio>=4; extra == 'dev'
|
|
26
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# libscanner MCP server
|
|
30
|
+
|
|
31
|
+
<!-- mcp-name: com.libscanner/barcode -->
|
|
32
|
+
|
|
33
|
+
An [MCP](https://modelcontextprotocol.io) server that lets Claude, ChatGPT and coding agents read and
|
|
34
|
+
create barcodes through the [libscanner API](https://libscanner.com/api/):
|
|
35
|
+
|
|
36
|
+
| Tool | What it does |
|
|
37
|
+
|---|---|
|
|
38
|
+
| `decode_code` | Reads DataMatrix, QR Code, Code 128, GS1-128 and EAN/UPC codes in a JPEG or PNG image. Returns the exact text of every code (the GS separator is the real character U+001D), its symbology and corners, the GS1 fields and a structure check |
|
|
39
|
+
| `parse_gs1` | Parses a code string as GS1 and checks its structure without an image: application identifiers, the GTIN check digit, Chestny ZNAK («Честный знак») verification fields 91/92/93, a missing GS separator, an expired date |
|
|
40
|
+
| `generate_code` | Creates a DataMatrix image (PNG), optionally validated as GS1 DataMatrix or as a Chestny ZNAK marking code, or a QR Code for links and text |
|
|
41
|
+
| `get_usage` | The plan of the API key and the remaining limits |
|
|
42
|
+
|
|
43
|
+
Documentation: <https://libscanner.com/docs/api/?lang=mcp>.
|
|
44
|
+
|
|
45
|
+
The server contains no recognition logic. Every tool is one call to `https://api.libscanner.com/v1`
|
|
46
|
+
([OpenAPI](https://api.libscanner.com/openapi.json)); the readers are the same ones that are sold as the
|
|
47
|
+
[dmr and unir libraries](https://libscanner.com/).
|
|
48
|
+
|
|
49
|
+
The tools check the *format* of a marking code. They do not query the status of an item in a government
|
|
50
|
+
marking system.
|
|
51
|
+
|
|
52
|
+
## API key
|
|
53
|
+
|
|
54
|
+
Create a free key at <https://libscanner.com/cabinet/api> (300 requests a month, 30 a day). Paid plans and
|
|
55
|
+
limits are on the [API page](https://libscanner.com/api/#pricing).
|
|
56
|
+
|
|
57
|
+
## Local server (stdio)
|
|
58
|
+
|
|
59
|
+
The local server runs on your machine, so `decode_code` can read an image **file** (`image_path`) and
|
|
60
|
+
`generate_code` can save the PNG (`output_path`). This is the way to use it from coding agents.
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
LIBSCANNER_API_KEY=lsk_live_... uvx libscanner-mcp
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
**Claude Code**
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
claude mcp add libscanner --env LIBSCANNER_API_KEY=lsk_live_... -- uvx libscanner-mcp
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
**Claude Desktop, Cursor** (`claude_desktop_config.json`, `.cursor/mcp.json`)
|
|
73
|
+
|
|
74
|
+
```json
|
|
75
|
+
{
|
|
76
|
+
"mcpServers": {
|
|
77
|
+
"libscanner": {
|
|
78
|
+
"command": "uvx",
|
|
79
|
+
"args": ["libscanner-mcp"],
|
|
80
|
+
"env": { "LIBSCANNER_API_KEY": "lsk_live_..." }
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**VS Code** (`.vscode/mcp.json`)
|
|
87
|
+
|
|
88
|
+
```json
|
|
89
|
+
{
|
|
90
|
+
"servers": {
|
|
91
|
+
"libscanner": {
|
|
92
|
+
"type": "stdio",
|
|
93
|
+
"command": "uvx",
|
|
94
|
+
"args": ["libscanner-mcp"],
|
|
95
|
+
"env": { "LIBSCANNER_API_KEY": "${input:libscanner-key}" }
|
|
96
|
+
}
|
|
97
|
+
},
|
|
98
|
+
"inputs": [{ "id": "libscanner-key", "type": "promptString", "description": "libscanner API key", "password": true }]
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Safety of the file parameters:
|
|
103
|
+
|
|
104
|
+
- `image_path` is sent to the API only if the file is a JPEG or PNG (checked by its signature) of at most 8 MB.
|
|
105
|
+
Any other file is refused before anything leaves the machine.
|
|
106
|
+
- `output_path` must end in `.png`, must not exist yet (nothing is overwritten) and its folder must exist.
|
|
107
|
+
- Both must be paths on this machine: network paths (`\\host\share\…`, `//host/…`) are refused before they are
|
|
108
|
+
touched — on Windows merely opening one sends the user's NTLM hash to that host.
|
|
109
|
+
|
|
110
|
+
## Cloud server (Streamable HTTP)
|
|
111
|
+
|
|
112
|
+
`https://mcp.libscanner.com/mcp` — nothing to install. The API key travels in a header:
|
|
113
|
+
|
|
114
|
+
```sh
|
|
115
|
+
claude mcp add --transport http libscanner https://mcp.libscanner.com/mcp --header "Authorization: Bearer lsk_live_..."
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
```json
|
|
119
|
+
{
|
|
120
|
+
"mcpServers": {
|
|
121
|
+
"libscanner": {
|
|
122
|
+
"url": "https://mcp.libscanner.com/mcp",
|
|
123
|
+
"headers": { "Authorization": "Bearer lsk_live_..." }
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Without a key `parse_gs1` and `generate_code` still work, with a small daily limit per address — enough to
|
|
130
|
+
try the server.
|
|
131
|
+
|
|
132
|
+
The cloud server cannot see files attached to a chat: `decode_code` takes a public link (`image_url`).
|
|
133
|
+
`image_base64` exists only for tiny images (up to 64 KB), because a model writes tool arguments character
|
|
134
|
+
by character.
|
|
135
|
+
|
|
136
|
+
## Images and storage
|
|
137
|
+
|
|
138
|
+
JPEG and PNG up to 8 MB, 4096 px on a side and 16 megapixels. On paid plans images are not stored. On the
|
|
139
|
+
free plan images in which no code was read are kept for up to a year to improve recognition. Decoded codes
|
|
140
|
+
are never stored. Details: <https://libscanner.com/api/#storage>.
|
|
141
|
+
|
|
142
|
+
## Running the cloud flavour yourself
|
|
143
|
+
|
|
144
|
+
```sh
|
|
145
|
+
pip install "libscanner-mcp[cloud]"
|
|
146
|
+
LIBSCANNER_MCP_ALLOWED_HOSTS=mcp.example.com libscanner-mcp --http --host 0.0.0.0 --port 8000
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
| Variable | Meaning |
|
|
150
|
+
|---|---|
|
|
151
|
+
| `LIBSCANNER_API_URL` | API address, `https://api.libscanner.com` by default |
|
|
152
|
+
| `LIBSCANNER_API_KEY` | local server: the key of the user |
|
|
153
|
+
| `LIBSCANNER_MCP_ALLOWED_HOSTS` | cloud: public host names of the server, comma-separated. Requests under any other `Host` are rejected (DNS rebinding protection) |
|
|
154
|
+
| `LIBSCANNER_MCP_ANONYMOUS_API_KEY` | cloud: the key that pays for calls without sign-in (`parse_gs1`, `generate_code`). Not set — such calls are refused |
|
|
155
|
+
| `LIBSCANNER_MCP_ANONYMOUS_DAILY_LIMIT` | cloud: calls without sign-in per client address (IPv6: per /64) a day, 20 by default |
|
|
156
|
+
| `LIBSCANNER_MCP_ANONYMOUS_NETWORK_DAILY_LIMIT` | cloud: the same per network — IPv4 /24, IPv6 /48 — 200 by default |
|
|
157
|
+
| `LIBSCANNER_MCP_ANONYMOUS_TOTAL_DAILY_LIMIT` | cloud: all calls without sign-in a day (except the shared counter below), 5000 by default |
|
|
158
|
+
| `LIBSCANNER_MCP_SHARED_DAILY_LIMIT` | cloud: one shared daily counter for clients whose requests come from the provider's addresses (claude.ai), 2000 by default |
|
|
159
|
+
|
|
160
|
+
The reverse proxy in front of the server must pass the client address in `X-Real-IP`, overwriting whatever
|
|
161
|
+
the client sent: the limit of calls without sign-in is counted by it. A call without sign-in that the API
|
|
162
|
+
did not serve — the rate or plan limit of the service key, a failure on the API side — is not counted.
|
|
163
|
+
The service key needs the `generate` scope only (`parse_gs1` needs none); give it a plan of its own, since
|
|
164
|
+
the per-key rate limit of the API applies to all calls without sign-in together.
|
|
165
|
+
|
|
166
|
+
The cloud server logs warnings and the access log only (address, path, status): at the INFO level the SDK
|
|
167
|
+
would log the text of failed tool calls, which may quote the caller's data.
|
|
168
|
+
|
|
169
|
+
## Development
|
|
170
|
+
|
|
171
|
+
```sh
|
|
172
|
+
uv venv && uv pip install -e ".[cloud,dev]"
|
|
173
|
+
pytest
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
## License
|
|
177
|
+
|
|
178
|
+
MIT. Chestny ZNAK («Честный знак») and GS1 are trademarks of their respective owners.
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# libscanner MCP server
|
|
2
|
+
|
|
3
|
+
<!-- mcp-name: com.libscanner/barcode -->
|
|
4
|
+
|
|
5
|
+
An [MCP](https://modelcontextprotocol.io) server that lets Claude, ChatGPT and coding agents read and
|
|
6
|
+
create barcodes through the [libscanner API](https://libscanner.com/api/):
|
|
7
|
+
|
|
8
|
+
| Tool | What it does |
|
|
9
|
+
|---|---|
|
|
10
|
+
| `decode_code` | Reads DataMatrix, QR Code, Code 128, GS1-128 and EAN/UPC codes in a JPEG or PNG image. Returns the exact text of every code (the GS separator is the real character U+001D), its symbology and corners, the GS1 fields and a structure check |
|
|
11
|
+
| `parse_gs1` | Parses a code string as GS1 and checks its structure without an image: application identifiers, the GTIN check digit, Chestny ZNAK («Честный знак») verification fields 91/92/93, a missing GS separator, an expired date |
|
|
12
|
+
| `generate_code` | Creates a DataMatrix image (PNG), optionally validated as GS1 DataMatrix or as a Chestny ZNAK marking code, or a QR Code for links and text |
|
|
13
|
+
| `get_usage` | The plan of the API key and the remaining limits |
|
|
14
|
+
|
|
15
|
+
Documentation: <https://libscanner.com/docs/api/?lang=mcp>.
|
|
16
|
+
|
|
17
|
+
The server contains no recognition logic. Every tool is one call to `https://api.libscanner.com/v1`
|
|
18
|
+
([OpenAPI](https://api.libscanner.com/openapi.json)); the readers are the same ones that are sold as the
|
|
19
|
+
[dmr and unir libraries](https://libscanner.com/).
|
|
20
|
+
|
|
21
|
+
The tools check the *format* of a marking code. They do not query the status of an item in a government
|
|
22
|
+
marking system.
|
|
23
|
+
|
|
24
|
+
## API key
|
|
25
|
+
|
|
26
|
+
Create a free key at <https://libscanner.com/cabinet/api> (300 requests a month, 30 a day). Paid plans and
|
|
27
|
+
limits are on the [API page](https://libscanner.com/api/#pricing).
|
|
28
|
+
|
|
29
|
+
## Local server (stdio)
|
|
30
|
+
|
|
31
|
+
The local server runs on your machine, so `decode_code` can read an image **file** (`image_path`) and
|
|
32
|
+
`generate_code` can save the PNG (`output_path`). This is the way to use it from coding agents.
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
LIBSCANNER_API_KEY=lsk_live_... uvx libscanner-mcp
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
**Claude Code**
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
claude mcp add libscanner --env LIBSCANNER_API_KEY=lsk_live_... -- uvx libscanner-mcp
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
**Claude Desktop, Cursor** (`claude_desktop_config.json`, `.cursor/mcp.json`)
|
|
45
|
+
|
|
46
|
+
```json
|
|
47
|
+
{
|
|
48
|
+
"mcpServers": {
|
|
49
|
+
"libscanner": {
|
|
50
|
+
"command": "uvx",
|
|
51
|
+
"args": ["libscanner-mcp"],
|
|
52
|
+
"env": { "LIBSCANNER_API_KEY": "lsk_live_..." }
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**VS Code** (`.vscode/mcp.json`)
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"servers": {
|
|
63
|
+
"libscanner": {
|
|
64
|
+
"type": "stdio",
|
|
65
|
+
"command": "uvx",
|
|
66
|
+
"args": ["libscanner-mcp"],
|
|
67
|
+
"env": { "LIBSCANNER_API_KEY": "${input:libscanner-key}" }
|
|
68
|
+
}
|
|
69
|
+
},
|
|
70
|
+
"inputs": [{ "id": "libscanner-key", "type": "promptString", "description": "libscanner API key", "password": true }]
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Safety of the file parameters:
|
|
75
|
+
|
|
76
|
+
- `image_path` is sent to the API only if the file is a JPEG or PNG (checked by its signature) of at most 8 MB.
|
|
77
|
+
Any other file is refused before anything leaves the machine.
|
|
78
|
+
- `output_path` must end in `.png`, must not exist yet (nothing is overwritten) and its folder must exist.
|
|
79
|
+
- Both must be paths on this machine: network paths (`\\host\share\…`, `//host/…`) are refused before they are
|
|
80
|
+
touched — on Windows merely opening one sends the user's NTLM hash to that host.
|
|
81
|
+
|
|
82
|
+
## Cloud server (Streamable HTTP)
|
|
83
|
+
|
|
84
|
+
`https://mcp.libscanner.com/mcp` — nothing to install. The API key travels in a header:
|
|
85
|
+
|
|
86
|
+
```sh
|
|
87
|
+
claude mcp add --transport http libscanner https://mcp.libscanner.com/mcp --header "Authorization: Bearer lsk_live_..."
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
```json
|
|
91
|
+
{
|
|
92
|
+
"mcpServers": {
|
|
93
|
+
"libscanner": {
|
|
94
|
+
"url": "https://mcp.libscanner.com/mcp",
|
|
95
|
+
"headers": { "Authorization": "Bearer lsk_live_..." }
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Without a key `parse_gs1` and `generate_code` still work, with a small daily limit per address — enough to
|
|
102
|
+
try the server.
|
|
103
|
+
|
|
104
|
+
The cloud server cannot see files attached to a chat: `decode_code` takes a public link (`image_url`).
|
|
105
|
+
`image_base64` exists only for tiny images (up to 64 KB), because a model writes tool arguments character
|
|
106
|
+
by character.
|
|
107
|
+
|
|
108
|
+
## Images and storage
|
|
109
|
+
|
|
110
|
+
JPEG and PNG up to 8 MB, 4096 px on a side and 16 megapixels. On paid plans images are not stored. On the
|
|
111
|
+
free plan images in which no code was read are kept for up to a year to improve recognition. Decoded codes
|
|
112
|
+
are never stored. Details: <https://libscanner.com/api/#storage>.
|
|
113
|
+
|
|
114
|
+
## Running the cloud flavour yourself
|
|
115
|
+
|
|
116
|
+
```sh
|
|
117
|
+
pip install "libscanner-mcp[cloud]"
|
|
118
|
+
LIBSCANNER_MCP_ALLOWED_HOSTS=mcp.example.com libscanner-mcp --http --host 0.0.0.0 --port 8000
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
| Variable | Meaning |
|
|
122
|
+
|---|---|
|
|
123
|
+
| `LIBSCANNER_API_URL` | API address, `https://api.libscanner.com` by default |
|
|
124
|
+
| `LIBSCANNER_API_KEY` | local server: the key of the user |
|
|
125
|
+
| `LIBSCANNER_MCP_ALLOWED_HOSTS` | cloud: public host names of the server, comma-separated. Requests under any other `Host` are rejected (DNS rebinding protection) |
|
|
126
|
+
| `LIBSCANNER_MCP_ANONYMOUS_API_KEY` | cloud: the key that pays for calls without sign-in (`parse_gs1`, `generate_code`). Not set — such calls are refused |
|
|
127
|
+
| `LIBSCANNER_MCP_ANONYMOUS_DAILY_LIMIT` | cloud: calls without sign-in per client address (IPv6: per /64) a day, 20 by default |
|
|
128
|
+
| `LIBSCANNER_MCP_ANONYMOUS_NETWORK_DAILY_LIMIT` | cloud: the same per network — IPv4 /24, IPv6 /48 — 200 by default |
|
|
129
|
+
| `LIBSCANNER_MCP_ANONYMOUS_TOTAL_DAILY_LIMIT` | cloud: all calls without sign-in a day (except the shared counter below), 5000 by default |
|
|
130
|
+
| `LIBSCANNER_MCP_SHARED_DAILY_LIMIT` | cloud: one shared daily counter for clients whose requests come from the provider's addresses (claude.ai), 2000 by default |
|
|
131
|
+
|
|
132
|
+
The reverse proxy in front of the server must pass the client address in `X-Real-IP`, overwriting whatever
|
|
133
|
+
the client sent: the limit of calls without sign-in is counted by it. A call without sign-in that the API
|
|
134
|
+
did not serve — the rate or plan limit of the service key, a failure on the API side — is not counted.
|
|
135
|
+
The service key needs the `generate` scope only (`parse_gs1` needs none); give it a plan of its own, since
|
|
136
|
+
the per-key rate limit of the API applies to all calls without sign-in together.
|
|
137
|
+
|
|
138
|
+
The cloud server logs warnings and the access log only (address, path, status): at the INFO level the SDK
|
|
139
|
+
would log the text of failed tool calls, which may quote the caller's data.
|
|
140
|
+
|
|
141
|
+
## Development
|
|
142
|
+
|
|
143
|
+
```sh
|
|
144
|
+
uv venv && uv pip install -e ".[cloud,dev]"
|
|
145
|
+
pytest
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## License
|
|
149
|
+
|
|
150
|
+
MIT. Chestny ZNAK («Честный знак») and GS1 are trademarks of their respective owners.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "libscanner-mcp"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "MCP server for libscanner: read and generate DataMatrix, QR and barcodes, parse GS1 and Chestny ZNAK marking codes"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.11"
|
|
13
|
+
authors = [{ name = "libscanner", email = "libscanner@yandex.com" }]
|
|
14
|
+
keywords = ["mcp", "datamatrix", "qr", "barcode", "gs1", "chestny-znak", "model-context-protocol"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 4 - Beta",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Programming Language :: Python :: 3.11",
|
|
20
|
+
"Programming Language :: Python :: 3.12",
|
|
21
|
+
"Programming Language :: Python :: 3.13",
|
|
22
|
+
"Topic :: Multimedia :: Graphics :: Capture :: Scanners",
|
|
23
|
+
"Topic :: Software Development :: Libraries",
|
|
24
|
+
]
|
|
25
|
+
dependencies = [
|
|
26
|
+
"mcp>=2.3,<3",
|
|
27
|
+
"httpx2>=2.16,<3",
|
|
28
|
+
]
|
|
29
|
+
|
|
30
|
+
[project.optional-dependencies]
|
|
31
|
+
# Облачный вид (Streamable HTTP за nginx) — uvicorn идёт вместе с mcp[cli].
|
|
32
|
+
cloud = ["mcp[cli]>=2.3,<3"]
|
|
33
|
+
dev = ["pytest>=8", "anyio>=4"]
|
|
34
|
+
|
|
35
|
+
[project.urls]
|
|
36
|
+
Homepage = "https://libscanner.com/api/"
|
|
37
|
+
Documentation = "https://libscanner.com/docs/api/?lang=mcp"
|
|
38
|
+
|
|
39
|
+
[project.scripts]
|
|
40
|
+
libscanner-mcp = "libscanner_mcp.cli:main"
|
|
41
|
+
|
|
42
|
+
[tool.hatch.build.targets.wheel]
|
|
43
|
+
packages = ["src/libscanner_mcp"]
|
|
44
|
+
|
|
45
|
+
[tool.pytest.ini_options]
|
|
46
|
+
testpaths = ["tests"]
|
|
47
|
+
pythonpath = ["src"]
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
3
|
+
"name": "com.libscanner/barcode",
|
|
4
|
+
"title": "libscanner: DataMatrix, QR and barcodes",
|
|
5
|
+
"description": "Read and create DataMatrix, QR and barcodes; parse GS1 and Chestny ZNAK marking codes.",
|
|
6
|
+
"websiteUrl": "https://libscanner.com/docs/api/?lang=mcp",
|
|
7
|
+
"version": "0.1.0",
|
|
8
|
+
"remotes": [
|
|
9
|
+
{
|
|
10
|
+
"type": "streamable-http",
|
|
11
|
+
"url": "https://mcp.libscanner.com/mcp",
|
|
12
|
+
"headers": [
|
|
13
|
+
{
|
|
14
|
+
"name": "Authorization",
|
|
15
|
+
"description": "Bearer <libscanner API key>. Optional: without it only parse_gs1 and generate_code work, with a small daily limit. Get a free key at https://libscanner.com/cabinet/api",
|
|
16
|
+
"isRequired": false,
|
|
17
|
+
"isSecret": true
|
|
18
|
+
}
|
|
19
|
+
]
|
|
20
|
+
}
|
|
21
|
+
],
|
|
22
|
+
"packages": [
|
|
23
|
+
{
|
|
24
|
+
"registryType": "pypi",
|
|
25
|
+
"identifier": "libscanner-mcp",
|
|
26
|
+
"version": "0.1.0",
|
|
27
|
+
"transport": {
|
|
28
|
+
"type": "stdio"
|
|
29
|
+
},
|
|
30
|
+
"environmentVariables": [
|
|
31
|
+
{
|
|
32
|
+
"name": "LIBSCANNER_API_KEY",
|
|
33
|
+
"description": "libscanner API key (lsk_live_...). Get a free key at https://libscanner.com/cabinet/api",
|
|
34
|
+
"isRequired": true,
|
|
35
|
+
"format": "string",
|
|
36
|
+
"isSecret": true
|
|
37
|
+
}
|
|
38
|
+
]
|
|
39
|
+
}
|
|
40
|
+
]
|
|
41
|
+
}
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
"""Thin client for the libscanner HTTP API (https://api.libscanner.com/v1)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import base64
|
|
7
|
+
import http.cookiejar
|
|
8
|
+
from dataclasses import dataclass
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
import httpx2
|
|
12
|
+
|
|
13
|
+
from . import __version__
|
|
14
|
+
|
|
15
|
+
DEFAULT_API_URL = "https://api.libscanner.com"
|
|
16
|
+
USER_AGENT = f"libscanner-mcp/{__version__}"
|
|
17
|
+
|
|
18
|
+
# The API accepts JPEG and PNG up to 8 MB.
|
|
19
|
+
MAX_IMAGE_BYTES = 8_000_000
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def _no_cookies() -> http.cookiejar.CookieJar:
|
|
23
|
+
return http.cookiejar.CookieJar(policy=http.cookiejar.DefaultCookiePolicy(allowed_domains=[]))
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class ApiError(Exception):
|
|
27
|
+
"""An error answer of the API, or no answer at all.
|
|
28
|
+
|
|
29
|
+
`code` is the stable machine-readable code of the API (INVALID_KEY,
|
|
30
|
+
DAY_LIMIT, IMAGE_TOO_LARGE ...); NETWORK when the API did not answer.
|
|
31
|
+
"""
|
|
32
|
+
|
|
33
|
+
def __init__(self, status: int, code: str, message: str, *, retry_after: int | None = None,
|
|
34
|
+
usage: dict[str, Any] | None = None) -> None:
|
|
35
|
+
super().__init__(message)
|
|
36
|
+
self.status = status
|
|
37
|
+
self.code = code
|
|
38
|
+
self.message = message
|
|
39
|
+
self.retry_after = retry_after
|
|
40
|
+
self.usage = usage
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
@dataclass(frozen=True)
|
|
44
|
+
class GeneratedCode:
|
|
45
|
+
png: bytes
|
|
46
|
+
width: int | None
|
|
47
|
+
height: int | None
|
|
48
|
+
# Symbol size in modules, rows x columns ("26x26"); None when unknown.
|
|
49
|
+
size: str | None
|
|
50
|
+
usage: dict[str, Any] | None
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class LibscannerApi:
|
|
54
|
+
"""One instance per server; the API key is passed with every call.
|
|
55
|
+
|
|
56
|
+
The key is never stored on the instance: in the cloud server each request
|
|
57
|
+
carries the key of its own user.
|
|
58
|
+
"""
|
|
59
|
+
|
|
60
|
+
def __init__(self, base_url: str = DEFAULT_API_URL, *, transport: httpx2.AsyncBaseTransport | None = None,
|
|
61
|
+
timeout: float = 40.0) -> None:
|
|
62
|
+
self._base_url = base_url.rstrip("/")
|
|
63
|
+
self._transport = transport
|
|
64
|
+
self._timeout = timeout
|
|
65
|
+
# One connection pool for all calls (keep-alive: no new TLS handshake
|
|
66
|
+
# per tool call). A client belongs to an event loop, so it is created
|
|
67
|
+
# lazily in the loop that uses it and re-created if the loop changes.
|
|
68
|
+
self._http: httpx2.AsyncClient | None = None
|
|
69
|
+
self._http_loop: asyncio.AbstractEventLoop | None = None
|
|
70
|
+
|
|
71
|
+
def _client(self) -> httpx2.AsyncClient:
|
|
72
|
+
loop = asyncio.get_running_loop()
|
|
73
|
+
if self._http is None or self._http.is_closed or self._http_loop is not loop:
|
|
74
|
+
self._http = httpx2.AsyncClient(
|
|
75
|
+
base_url=self._base_url,
|
|
76
|
+
transport=self._transport,
|
|
77
|
+
timeout=self._timeout,
|
|
78
|
+
headers={"User-Agent": USER_AGENT},
|
|
79
|
+
# The client is shared by every user of the cloud server: a cookie
|
|
80
|
+
# set in an answer to one user (by the API or a proxy in front of
|
|
81
|
+
# it) must never travel with the requests of another. The jar
|
|
82
|
+
# accepts nothing and sends nothing.
|
|
83
|
+
cookies=_no_cookies(),
|
|
84
|
+
)
|
|
85
|
+
self._http_loop = loop
|
|
86
|
+
return self._http
|
|
87
|
+
|
|
88
|
+
async def aclose(self) -> None:
|
|
89
|
+
"""Close the connection pool (server shutdown)."""
|
|
90
|
+
if self._http is not None:
|
|
91
|
+
await self._http.aclose()
|
|
92
|
+
self._http = None
|
|
93
|
+
|
|
94
|
+
async def _send(self, key: str, method: str, path: str, **kwargs: Any) -> httpx2.Response:
|
|
95
|
+
# The key goes with the request, never onto the shared client.
|
|
96
|
+
headers = {**kwargs.pop("headers", {}), "Authorization": f"Bearer {key}"}
|
|
97
|
+
try:
|
|
98
|
+
response = await self._client().request(method, path, headers=headers, **kwargs)
|
|
99
|
+
except httpx2.HTTPError as exc:
|
|
100
|
+
# The text of the exception may contain the URL but never the key
|
|
101
|
+
# (the key travels in a header).
|
|
102
|
+
raise ApiError(0, "NETWORK", f"The libscanner API did not answer: {type(exc).__name__}") from exc
|
|
103
|
+
if response.status_code >= 400:
|
|
104
|
+
raise _error_from(response)
|
|
105
|
+
return response
|
|
106
|
+
|
|
107
|
+
async def decode(self, key: str, *, image: bytes | None = None, image_url: str | None = None,
|
|
108
|
+
mode: str = "single", symbologies: str | None = None, gs1: bool = True,
|
|
109
|
+
lang: str = "en") -> dict[str, Any]:
|
|
110
|
+
"""POST /v1/decode: exactly one of `image` (JPEG/PNG bytes) and `image_url`."""
|
|
111
|
+
if (image is None) == (image_url is None):
|
|
112
|
+
raise ValueError("pass exactly one of image and image_url")
|
|
113
|
+
params: dict[str, Any] = {"mode": mode, "gs1": "true" if gs1 else "false", "lang": lang}
|
|
114
|
+
if symbologies:
|
|
115
|
+
params["symbologies"] = symbologies
|
|
116
|
+
if image is not None:
|
|
117
|
+
response = await self._send(key, "POST", "/v1/decode", params=params, content=image,
|
|
118
|
+
headers={"Content-Type": "application/octet-stream"})
|
|
119
|
+
else:
|
|
120
|
+
response = await self._send(key, "POST", "/v1/decode", json={**params, "image_url": image_url,
|
|
121
|
+
"gs1": gs1})
|
|
122
|
+
return response.json()
|
|
123
|
+
|
|
124
|
+
async def generate(self, key: str, *, data: str, symbology: str = "datamatrix", gs1: str = "off",
|
|
125
|
+
ecc: str | None = None, module_px: int | None = None, lang: str = "en") -> GeneratedCode:
|
|
126
|
+
"""POST /v1/generate: the PNG image of the code with its dimensions."""
|
|
127
|
+
body: dict[str, Any] = {"data": data, "symbology": symbology, "gs1": gs1, "lang": lang}
|
|
128
|
+
if ecc is not None:
|
|
129
|
+
body["ecc"] = ecc
|
|
130
|
+
if module_px is not None:
|
|
131
|
+
body["module_px"] = module_px
|
|
132
|
+
response = await self._send(key, "POST", "/v1/generate", json=body, headers={"Accept": "application/json"})
|
|
133
|
+
answer = response.json()
|
|
134
|
+
return GeneratedCode(
|
|
135
|
+
png=base64.b64decode(answer["image_base64"]),
|
|
136
|
+
width=answer.get("width"),
|
|
137
|
+
height=answer.get("height"),
|
|
138
|
+
size=answer.get("size"),
|
|
139
|
+
usage=answer.get("usage"),
|
|
140
|
+
)
|
|
141
|
+
|
|
142
|
+
async def parse(self, key: str, *, code: str, lang: str = "en") -> dict[str, Any]:
|
|
143
|
+
"""POST /v1/gs1/parse: GS1 fields and a structure check of the code string."""
|
|
144
|
+
response = await self._send(key, "POST", "/v1/gs1/parse", json={"code": code, "lang": lang})
|
|
145
|
+
return response.json()
|
|
146
|
+
|
|
147
|
+
async def usage(self, key: str) -> dict[str, Any]:
|
|
148
|
+
"""GET /v1/usage: the plan and the remaining limits."""
|
|
149
|
+
response = await self._send(key, "GET", "/v1/usage")
|
|
150
|
+
return response.json()
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def _error_from(response: httpx2.Response) -> ApiError:
|
|
154
|
+
code = f"HTTP_{response.status_code}"
|
|
155
|
+
message = f"The libscanner API answered {response.status_code}"
|
|
156
|
+
usage = None
|
|
157
|
+
try:
|
|
158
|
+
body = response.json()
|
|
159
|
+
error = body.get("error") or {}
|
|
160
|
+
code = str(error.get("code") or code)
|
|
161
|
+
message = str(error.get("message") or message)
|
|
162
|
+
usage = body.get("usage")
|
|
163
|
+
except (ValueError, AttributeError):
|
|
164
|
+
pass # not JSON (a proxy error page) - the status is all we know
|
|
165
|
+
retry_after = None
|
|
166
|
+
header = response.headers.get("Retry-After", "")
|
|
167
|
+
if header.isdigit():
|
|
168
|
+
retry_after = int(header)
|
|
169
|
+
return ApiError(response.status_code, code, message, retry_after=retry_after, usage=usage)
|