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.
@@ -0,0 +1,6 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.egg-info/
4
+ dist/
5
+ build/
6
+ .pytest_cache/
@@ -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,7 @@
1
+ """MCP server for libscanner.com: codes in images, GS1 strings and code images.
2
+
3
+ The server holds no recognition logic: every tool is a call to the libscanner
4
+ HTTP API (https://api.libscanner.com/openapi.json).
5
+ """
6
+
7
+ __version__ = "0.1.0"
@@ -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)