base64-lite 1.0.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,12 @@
1
+ # Changelog
2
+
3
+ What changed in base64-lite, newest first.
4
+
5
+ ## 1.0.0 - 2026-11-10
6
+
7
+ - First release.
8
+ - Encodes or decodes Base64 for text and local files. Optional URL-safe alphabet and data-URI output.
9
+ - `--action auto` (default) decodes if the input looks like Base64, otherwise it encodes. You can force encode or decode.
10
+ - `--json` gives one clean object for scripts and AI agents. `--quiet` hides the tip line.
11
+ - A free MCP server with two read-only tools: `convert_text` and `convert_file`.
12
+ - Needs Python 3.10 or newer.
@@ -0,0 +1,9 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 tidybyte
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
6
+
7
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8
+
9
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,4 @@
1
+ include CHANGELOG.md
2
+ include llms.txt
3
+ include server.json
4
+ recursive-include tests *.py *.txt *.b64
@@ -0,0 +1,197 @@
1
+ Metadata-Version: 2.4
2
+ Name: base64-lite
3
+ Version: 1.0.0
4
+ Summary: Encode or decode Base64 for text and local files. URL-safe and data-URI options. Local CLI and MCP server.
5
+ Author: Tidy Byte Tools
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/tidybytetools/base64-lite
8
+ Project-URL: Documentation, https://github.com/tidybytetools/base64-lite#readme
9
+ Project-URL: Source, https://github.com/tidybytetools/base64-lite
10
+ Project-URL: Issues, https://github.com/tidybytetools/base64-lite/issues
11
+ Project-URL: Changelog, https://github.com/tidybytetools/base64-lite/blob/main/CHANGELOG.md
12
+ Project-URL: Apify, https://apify.com/tidybytetools/base64-encode-decode
13
+ Keywords: base64,encode,decode,data-uri,url-safe,cli,mcp,mcp-server
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Environment :: Console
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Intended Audience :: End Users/Desktop
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3 :: Only
21
+ Classifier: Programming Language :: Python :: 3.10
22
+ Classifier: Programming Language :: Python :: 3.11
23
+ Classifier: Programming Language :: Python :: 3.12
24
+ Classifier: Programming Language :: Python :: 3.13
25
+ Classifier: Topic :: Utilities
26
+ Classifier: Topic :: Text Processing
27
+ Requires-Python: >=3.10
28
+ Description-Content-Type: text/markdown
29
+ License-File: LICENSE
30
+ Requires-Dist: mcp<2,>=1.10
31
+ Dynamic: license-file
32
+
33
+ <p>
34
+ <a href="https://github.com/tidybytetools">
35
+ <picture>
36
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tidybytetools/base64-lite/main/assets/tidybytetools-lockup-dark.png">
37
+ <img alt="Tidy Byte Tools" src="https://raw.githubusercontent.com/tidybytetools/base64-lite/main/assets/tidybytetools-lockup-light.png" height="44">
38
+ </picture>
39
+ </a>
40
+ </p>
41
+
42
+ # base64-lite
43
+
44
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/tidybytetools/base64-lite/blob/main/LICENSE)
45
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
46
+ [![MCP server](https://img.shields.io/badge/MCP-stdio-purple.svg)](#use-it-from-claude-desktop-or-cursor-mcp)
47
+ [![Tests](https://github.com/tidybytetools/base64-lite/actions/workflows/tests.yml/badge.svg)](https://github.com/tidybytetools/base64-lite/actions/workflows/tests.yml)
48
+
49
+ Free tool that encodes or decodes Base64 for text and local files. Optional URL-safe alphabet and data-URI output.
50
+
51
+ Need it at scale or from an AI agent? Use the Apify version: **[base64-encode-decode on Apify](https://apify.com/tidybytetools/base64-encode-decode)**
52
+
53
+ Plain code, not AI, so the same input always gives the same output. Runs on your own computer. MIT license. Works with Python 3.10 and newer, on Windows, Mac and Linux.
54
+
55
+ ## Links
56
+
57
+ - **[Apify (no-install cloud version)](https://apify.com/tidybytetools/base64-encode-decode)** — pay only for what you use, about $0.001 per unique item. Failed items are free. (This listing goes public this week.)
58
+
59
+ <!-- mcp-name: io.github.tidybytetools/base64-lite -->
60
+
61
+ ## Before and after
62
+
63
+ Before (plain text):
64
+
65
+ ```
66
+ hello world
67
+ ```
68
+
69
+ After (Base64):
70
+
71
+ ```
72
+ aGVsbG8gd29ybGQ=
73
+ ```
74
+
75
+ Decode works the other way, including data URIs like `data:text/plain;base64,aGVsbG8gd29ybGQ=`.
76
+
77
+ ## Install
78
+
79
+ ```
80
+ pip install git+https://github.com/tidybytetools/base64-lite
81
+ ```
82
+
83
+ Or use pipx, which keeps it in its own space:
84
+
85
+ ```
86
+ pipx install git+https://github.com/tidybytetools/base64-lite
87
+ ```
88
+
89
+ Or just download `base64_lite.py` and run it with `python3`. That one file uses only Python's standard library. (Installing with pip also adds the `mcp` package, which the MCP server needs.)
90
+
91
+ ## Use it
92
+
93
+ ```
94
+ printf 'hello world' | base64-lite --action encode
95
+ base64-lite photo.png --action encode --data-uri
96
+ printf 'aGVsbG8gd29ybGQ=' | base64-lite --action decode
97
+ base64-lite note.b64 --action decode
98
+ base64-lite file.bin --action decode --output out.bin # when the bytes are not text
99
+ printf 'hello world' | base64-lite --json # {"ok": true, "action": "encode", "base64": "..."}
100
+ ```
101
+
102
+ `--action auto` (the default) decodes if the input looks like Base64, otherwise it encodes. Use `--action encode` or `--action decode` when you already know the direction. `--url-safe` uses `-` and `_` instead of `+` and `/` when encoding. Decoding always accepts both forms.
103
+
104
+ From Python:
105
+
106
+ ```python
107
+ from base64_lite import convert
108
+ convert("hello world", None, action="encode")["base64"] # 'aGVsbG8gd29ybGQ='
109
+ ```
110
+
111
+ When you run it in a terminal it prints one short line about the Apify version to stderr after the result. It never goes into your output, it only shows when you are looking at a terminal, and `--quiet` turns it off.
112
+
113
+ ## Known limits
114
+
115
+ - **`auto` can guess wrong** on short or unusual strings. Use `encode` or `decode` when you already know the direction.
116
+ - **Local files only.** This free tool does not fetch file links from the internet. The Apify version does.
117
+ - **5 MB cap in the MCP file tool.** The command line will read a larger local file, but very large jobs are a better fit for Apify.
118
+ - **It does not inspect decoded bytes** for viruses or hidden data.
119
+
120
+ ## Lite vs Apify
121
+
122
+ | | lite (free, this repo) | [base64-encode-decode on Apify](https://apify.com/tidybytetools/base64-encode-decode) |
123
+ |---|---|---|
124
+ | Encode and decode text or files | yes, on your computer | yes, in the cloud |
125
+ | URL-safe alphabet and data URIs | yes | yes |
126
+ | Fetch file links | no | yes |
127
+ | Many items in one run | you can loop on your own | yes, and repeats in the same run are free |
128
+ | MCP server for local AI apps | yes | use Apify MCP for the cloud tool |
129
+ | Price | free | $0.001 per unique item. Failed items are free |
130
+
131
+ ## Use it from Claude Desktop or Cursor (MCP)
132
+
133
+ There is a small free MCP server built in. It gives your AI app two tools. Both only read. They never write or change files, and they never use the internet. It needs [uv](https://docs.astral.sh/uv/).
134
+
135
+ Run it by hand to check it starts (it waits quietly for an app to talk to it):
136
+
137
+ ```
138
+ uvx --from git+https://github.com/tidybytetools/base64-lite base64-lite mcp
139
+ ```
140
+
141
+ Claude Desktop (`claude_desktop_config.json`) or Cursor (`~/.cursor/mcp.json`):
142
+
143
+ ```json
144
+ {
145
+ "mcpServers": {
146
+ "base64-lite": {
147
+ "command": "uvx",
148
+ "args": ["--from", "git+https://github.com/tidybytetools/base64-lite", "base64-lite", "mcp"]
149
+ }
150
+ }
151
+ }
152
+ ```
153
+
154
+ `uvx --from git+https://github.com/tidybytetools/base64-lite base64-lite-mcp` starts the same server.
155
+
156
+ Tools:
157
+
158
+ - `convert_text(text, action="auto", url_safe=false, data_uri=false)`: for text or Base64 in the chat.
159
+ - `convert_file(path, action="auto", url_safe=false, data_uri=false)`: for a local file, up to 5 MB. For decode, the file must be UTF-8 text of Base64.
160
+
161
+ Encoded results include `base64` (and `dataUri` if you asked). Decoded results include `text` when the bytes are UTF-8, or `isText` false if they are not.
162
+
163
+ ## For AI agents
164
+
165
+ - **Use when:** you need to encode text or a local file to Base64, or decode Base64 / a data URI.
166
+ - **Don't use when:** you need to fetch a file from a URL, or the file is bigger than 5 MB in MCP. Use the Apify version for those jobs.
167
+ - **Input:** text on stdin or a file path. Optional `--action auto|encode|decode`, `--url-safe`, `--data-uri`, `--output FILE`.
168
+ - **MCP:** `uvx --from git+https://github.com/tidybytetools/base64-lite base64-lite mcp` gives two read-only tools, `convert_text` and `convert_file`.
169
+ - **Output:** with `--json`, one object such as `{"ok": true, "action": "encode", "base64": "...", "bytesIn": 11}`. On error `ok` is false. Exit code 0 ok, 1 error.
170
+ - Hint lines go to stderr only, and only in a terminal, so stdout is always clean. See also [`llms.txt`](https://github.com/tidybytetools/base64-lite/blob/main/llms.txt).
171
+
172
+ ## Tests
173
+
174
+ ```
175
+ pip install "mcp>=1.10,<2"
176
+ python3 -m unittest discover tests
177
+ ```
178
+
179
+ The MCP tests are skipped if `mcp` is not installed.
180
+
181
+ ## FAQ
182
+
183
+ **What input does it take?**
184
+ Text on stdin, or a local file. Use `--action encode` or `--action decode` if you already know the direction.
185
+
186
+ **Do my files leave my computer?**
187
+ No. The tool runs on your computer and never uses the internet.
188
+
189
+ **How is this different from the Apify version?**
190
+ The Apify version runs in the cloud, can fetch file links, and can process many items in one run. This lite tool is free and local.
191
+
192
+ **Does it work with AI apps?**
193
+ Yes. It includes a free MCP server. No API key.
194
+
195
+ ## License
196
+
197
+ MIT. See `LICENSE`.
@@ -0,0 +1,165 @@
1
+ <p>
2
+ <a href="https://github.com/tidybytetools">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tidybytetools/base64-lite/main/assets/tidybytetools-lockup-dark.png">
5
+ <img alt="Tidy Byte Tools" src="https://raw.githubusercontent.com/tidybytetools/base64-lite/main/assets/tidybytetools-lockup-light.png" height="44">
6
+ </picture>
7
+ </a>
8
+ </p>
9
+
10
+ # base64-lite
11
+
12
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/tidybytetools/base64-lite/blob/main/LICENSE)
13
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
14
+ [![MCP server](https://img.shields.io/badge/MCP-stdio-purple.svg)](#use-it-from-claude-desktop-or-cursor-mcp)
15
+ [![Tests](https://github.com/tidybytetools/base64-lite/actions/workflows/tests.yml/badge.svg)](https://github.com/tidybytetools/base64-lite/actions/workflows/tests.yml)
16
+
17
+ Free tool that encodes or decodes Base64 for text and local files. Optional URL-safe alphabet and data-URI output.
18
+
19
+ Need it at scale or from an AI agent? Use the Apify version: **[base64-encode-decode on Apify](https://apify.com/tidybytetools/base64-encode-decode)**
20
+
21
+ Plain code, not AI, so the same input always gives the same output. Runs on your own computer. MIT license. Works with Python 3.10 and newer, on Windows, Mac and Linux.
22
+
23
+ ## Links
24
+
25
+ - **[Apify (no-install cloud version)](https://apify.com/tidybytetools/base64-encode-decode)** — pay only for what you use, about $0.001 per unique item. Failed items are free. (This listing goes public this week.)
26
+
27
+ <!-- mcp-name: io.github.tidybytetools/base64-lite -->
28
+
29
+ ## Before and after
30
+
31
+ Before (plain text):
32
+
33
+ ```
34
+ hello world
35
+ ```
36
+
37
+ After (Base64):
38
+
39
+ ```
40
+ aGVsbG8gd29ybGQ=
41
+ ```
42
+
43
+ Decode works the other way, including data URIs like `data:text/plain;base64,aGVsbG8gd29ybGQ=`.
44
+
45
+ ## Install
46
+
47
+ ```
48
+ pip install git+https://github.com/tidybytetools/base64-lite
49
+ ```
50
+
51
+ Or use pipx, which keeps it in its own space:
52
+
53
+ ```
54
+ pipx install git+https://github.com/tidybytetools/base64-lite
55
+ ```
56
+
57
+ Or just download `base64_lite.py` and run it with `python3`. That one file uses only Python's standard library. (Installing with pip also adds the `mcp` package, which the MCP server needs.)
58
+
59
+ ## Use it
60
+
61
+ ```
62
+ printf 'hello world' | base64-lite --action encode
63
+ base64-lite photo.png --action encode --data-uri
64
+ printf 'aGVsbG8gd29ybGQ=' | base64-lite --action decode
65
+ base64-lite note.b64 --action decode
66
+ base64-lite file.bin --action decode --output out.bin # when the bytes are not text
67
+ printf 'hello world' | base64-lite --json # {"ok": true, "action": "encode", "base64": "..."}
68
+ ```
69
+
70
+ `--action auto` (the default) decodes if the input looks like Base64, otherwise it encodes. Use `--action encode` or `--action decode` when you already know the direction. `--url-safe` uses `-` and `_` instead of `+` and `/` when encoding. Decoding always accepts both forms.
71
+
72
+ From Python:
73
+
74
+ ```python
75
+ from base64_lite import convert
76
+ convert("hello world", None, action="encode")["base64"] # 'aGVsbG8gd29ybGQ='
77
+ ```
78
+
79
+ When you run it in a terminal it prints one short line about the Apify version to stderr after the result. It never goes into your output, it only shows when you are looking at a terminal, and `--quiet` turns it off.
80
+
81
+ ## Known limits
82
+
83
+ - **`auto` can guess wrong** on short or unusual strings. Use `encode` or `decode` when you already know the direction.
84
+ - **Local files only.** This free tool does not fetch file links from the internet. The Apify version does.
85
+ - **5 MB cap in the MCP file tool.** The command line will read a larger local file, but very large jobs are a better fit for Apify.
86
+ - **It does not inspect decoded bytes** for viruses or hidden data.
87
+
88
+ ## Lite vs Apify
89
+
90
+ | | lite (free, this repo) | [base64-encode-decode on Apify](https://apify.com/tidybytetools/base64-encode-decode) |
91
+ |---|---|---|
92
+ | Encode and decode text or files | yes, on your computer | yes, in the cloud |
93
+ | URL-safe alphabet and data URIs | yes | yes |
94
+ | Fetch file links | no | yes |
95
+ | Many items in one run | you can loop on your own | yes, and repeats in the same run are free |
96
+ | MCP server for local AI apps | yes | use Apify MCP for the cloud tool |
97
+ | Price | free | $0.001 per unique item. Failed items are free |
98
+
99
+ ## Use it from Claude Desktop or Cursor (MCP)
100
+
101
+ There is a small free MCP server built in. It gives your AI app two tools. Both only read. They never write or change files, and they never use the internet. It needs [uv](https://docs.astral.sh/uv/).
102
+
103
+ Run it by hand to check it starts (it waits quietly for an app to talk to it):
104
+
105
+ ```
106
+ uvx --from git+https://github.com/tidybytetools/base64-lite base64-lite mcp
107
+ ```
108
+
109
+ Claude Desktop (`claude_desktop_config.json`) or Cursor (`~/.cursor/mcp.json`):
110
+
111
+ ```json
112
+ {
113
+ "mcpServers": {
114
+ "base64-lite": {
115
+ "command": "uvx",
116
+ "args": ["--from", "git+https://github.com/tidybytetools/base64-lite", "base64-lite", "mcp"]
117
+ }
118
+ }
119
+ }
120
+ ```
121
+
122
+ `uvx --from git+https://github.com/tidybytetools/base64-lite base64-lite-mcp` starts the same server.
123
+
124
+ Tools:
125
+
126
+ - `convert_text(text, action="auto", url_safe=false, data_uri=false)`: for text or Base64 in the chat.
127
+ - `convert_file(path, action="auto", url_safe=false, data_uri=false)`: for a local file, up to 5 MB. For decode, the file must be UTF-8 text of Base64.
128
+
129
+ Encoded results include `base64` (and `dataUri` if you asked). Decoded results include `text` when the bytes are UTF-8, or `isText` false if they are not.
130
+
131
+ ## For AI agents
132
+
133
+ - **Use when:** you need to encode text or a local file to Base64, or decode Base64 / a data URI.
134
+ - **Don't use when:** you need to fetch a file from a URL, or the file is bigger than 5 MB in MCP. Use the Apify version for those jobs.
135
+ - **Input:** text on stdin or a file path. Optional `--action auto|encode|decode`, `--url-safe`, `--data-uri`, `--output FILE`.
136
+ - **MCP:** `uvx --from git+https://github.com/tidybytetools/base64-lite base64-lite mcp` gives two read-only tools, `convert_text` and `convert_file`.
137
+ - **Output:** with `--json`, one object such as `{"ok": true, "action": "encode", "base64": "...", "bytesIn": 11}`. On error `ok` is false. Exit code 0 ok, 1 error.
138
+ - Hint lines go to stderr only, and only in a terminal, so stdout is always clean. See also [`llms.txt`](https://github.com/tidybytetools/base64-lite/blob/main/llms.txt).
139
+
140
+ ## Tests
141
+
142
+ ```
143
+ pip install "mcp>=1.10,<2"
144
+ python3 -m unittest discover tests
145
+ ```
146
+
147
+ The MCP tests are skipped if `mcp` is not installed.
148
+
149
+ ## FAQ
150
+
151
+ **What input does it take?**
152
+ Text on stdin, or a local file. Use `--action encode` or `--action decode` if you already know the direction.
153
+
154
+ **Do my files leave my computer?**
155
+ No. The tool runs on your computer and never uses the internet.
156
+
157
+ **How is this different from the Apify version?**
158
+ The Apify version runs in the cloud, can fetch file links, and can process many items in one run. This lite tool is free and local.
159
+
160
+ **Does it work with AI apps?**
161
+ Yes. It includes a free MCP server. No API key.
162
+
163
+ ## License
164
+
165
+ MIT. See `LICENSE`.
@@ -0,0 +1,197 @@
1
+ Metadata-Version: 2.4
2
+ Name: base64-lite
3
+ Version: 1.0.0
4
+ Summary: Encode or decode Base64 for text and local files. URL-safe and data-URI options. Local CLI and MCP server.
5
+ Author: Tidy Byte Tools
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/tidybytetools/base64-lite
8
+ Project-URL: Documentation, https://github.com/tidybytetools/base64-lite#readme
9
+ Project-URL: Source, https://github.com/tidybytetools/base64-lite
10
+ Project-URL: Issues, https://github.com/tidybytetools/base64-lite/issues
11
+ Project-URL: Changelog, https://github.com/tidybytetools/base64-lite/blob/main/CHANGELOG.md
12
+ Project-URL: Apify, https://apify.com/tidybytetools/base64-encode-decode
13
+ Keywords: base64,encode,decode,data-uri,url-safe,cli,mcp,mcp-server
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Environment :: Console
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Intended Audience :: End Users/Desktop
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3 :: Only
21
+ Classifier: Programming Language :: Python :: 3.10
22
+ Classifier: Programming Language :: Python :: 3.11
23
+ Classifier: Programming Language :: Python :: 3.12
24
+ Classifier: Programming Language :: Python :: 3.13
25
+ Classifier: Topic :: Utilities
26
+ Classifier: Topic :: Text Processing
27
+ Requires-Python: >=3.10
28
+ Description-Content-Type: text/markdown
29
+ License-File: LICENSE
30
+ Requires-Dist: mcp<2,>=1.10
31
+ Dynamic: license-file
32
+
33
+ <p>
34
+ <a href="https://github.com/tidybytetools">
35
+ <picture>
36
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tidybytetools/base64-lite/main/assets/tidybytetools-lockup-dark.png">
37
+ <img alt="Tidy Byte Tools" src="https://raw.githubusercontent.com/tidybytetools/base64-lite/main/assets/tidybytetools-lockup-light.png" height="44">
38
+ </picture>
39
+ </a>
40
+ </p>
41
+
42
+ # base64-lite
43
+
44
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/tidybytetools/base64-lite/blob/main/LICENSE)
45
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
46
+ [![MCP server](https://img.shields.io/badge/MCP-stdio-purple.svg)](#use-it-from-claude-desktop-or-cursor-mcp)
47
+ [![Tests](https://github.com/tidybytetools/base64-lite/actions/workflows/tests.yml/badge.svg)](https://github.com/tidybytetools/base64-lite/actions/workflows/tests.yml)
48
+
49
+ Free tool that encodes or decodes Base64 for text and local files. Optional URL-safe alphabet and data-URI output.
50
+
51
+ Need it at scale or from an AI agent? Use the Apify version: **[base64-encode-decode on Apify](https://apify.com/tidybytetools/base64-encode-decode)**
52
+
53
+ Plain code, not AI, so the same input always gives the same output. Runs on your own computer. MIT license. Works with Python 3.10 and newer, on Windows, Mac and Linux.
54
+
55
+ ## Links
56
+
57
+ - **[Apify (no-install cloud version)](https://apify.com/tidybytetools/base64-encode-decode)** — pay only for what you use, about $0.001 per unique item. Failed items are free. (This listing goes public this week.)
58
+
59
+ <!-- mcp-name: io.github.tidybytetools/base64-lite -->
60
+
61
+ ## Before and after
62
+
63
+ Before (plain text):
64
+
65
+ ```
66
+ hello world
67
+ ```
68
+
69
+ After (Base64):
70
+
71
+ ```
72
+ aGVsbG8gd29ybGQ=
73
+ ```
74
+
75
+ Decode works the other way, including data URIs like `data:text/plain;base64,aGVsbG8gd29ybGQ=`.
76
+
77
+ ## Install
78
+
79
+ ```
80
+ pip install git+https://github.com/tidybytetools/base64-lite
81
+ ```
82
+
83
+ Or use pipx, which keeps it in its own space:
84
+
85
+ ```
86
+ pipx install git+https://github.com/tidybytetools/base64-lite
87
+ ```
88
+
89
+ Or just download `base64_lite.py` and run it with `python3`. That one file uses only Python's standard library. (Installing with pip also adds the `mcp` package, which the MCP server needs.)
90
+
91
+ ## Use it
92
+
93
+ ```
94
+ printf 'hello world' | base64-lite --action encode
95
+ base64-lite photo.png --action encode --data-uri
96
+ printf 'aGVsbG8gd29ybGQ=' | base64-lite --action decode
97
+ base64-lite note.b64 --action decode
98
+ base64-lite file.bin --action decode --output out.bin # when the bytes are not text
99
+ printf 'hello world' | base64-lite --json # {"ok": true, "action": "encode", "base64": "..."}
100
+ ```
101
+
102
+ `--action auto` (the default) decodes if the input looks like Base64, otherwise it encodes. Use `--action encode` or `--action decode` when you already know the direction. `--url-safe` uses `-` and `_` instead of `+` and `/` when encoding. Decoding always accepts both forms.
103
+
104
+ From Python:
105
+
106
+ ```python
107
+ from base64_lite import convert
108
+ convert("hello world", None, action="encode")["base64"] # 'aGVsbG8gd29ybGQ='
109
+ ```
110
+
111
+ When you run it in a terminal it prints one short line about the Apify version to stderr after the result. It never goes into your output, it only shows when you are looking at a terminal, and `--quiet` turns it off.
112
+
113
+ ## Known limits
114
+
115
+ - **`auto` can guess wrong** on short or unusual strings. Use `encode` or `decode` when you already know the direction.
116
+ - **Local files only.** This free tool does not fetch file links from the internet. The Apify version does.
117
+ - **5 MB cap in the MCP file tool.** The command line will read a larger local file, but very large jobs are a better fit for Apify.
118
+ - **It does not inspect decoded bytes** for viruses or hidden data.
119
+
120
+ ## Lite vs Apify
121
+
122
+ | | lite (free, this repo) | [base64-encode-decode on Apify](https://apify.com/tidybytetools/base64-encode-decode) |
123
+ |---|---|---|
124
+ | Encode and decode text or files | yes, on your computer | yes, in the cloud |
125
+ | URL-safe alphabet and data URIs | yes | yes |
126
+ | Fetch file links | no | yes |
127
+ | Many items in one run | you can loop on your own | yes, and repeats in the same run are free |
128
+ | MCP server for local AI apps | yes | use Apify MCP for the cloud tool |
129
+ | Price | free | $0.001 per unique item. Failed items are free |
130
+
131
+ ## Use it from Claude Desktop or Cursor (MCP)
132
+
133
+ There is a small free MCP server built in. It gives your AI app two tools. Both only read. They never write or change files, and they never use the internet. It needs [uv](https://docs.astral.sh/uv/).
134
+
135
+ Run it by hand to check it starts (it waits quietly for an app to talk to it):
136
+
137
+ ```
138
+ uvx --from git+https://github.com/tidybytetools/base64-lite base64-lite mcp
139
+ ```
140
+
141
+ Claude Desktop (`claude_desktop_config.json`) or Cursor (`~/.cursor/mcp.json`):
142
+
143
+ ```json
144
+ {
145
+ "mcpServers": {
146
+ "base64-lite": {
147
+ "command": "uvx",
148
+ "args": ["--from", "git+https://github.com/tidybytetools/base64-lite", "base64-lite", "mcp"]
149
+ }
150
+ }
151
+ }
152
+ ```
153
+
154
+ `uvx --from git+https://github.com/tidybytetools/base64-lite base64-lite-mcp` starts the same server.
155
+
156
+ Tools:
157
+
158
+ - `convert_text(text, action="auto", url_safe=false, data_uri=false)`: for text or Base64 in the chat.
159
+ - `convert_file(path, action="auto", url_safe=false, data_uri=false)`: for a local file, up to 5 MB. For decode, the file must be UTF-8 text of Base64.
160
+
161
+ Encoded results include `base64` (and `dataUri` if you asked). Decoded results include `text` when the bytes are UTF-8, or `isText` false if they are not.
162
+
163
+ ## For AI agents
164
+
165
+ - **Use when:** you need to encode text or a local file to Base64, or decode Base64 / a data URI.
166
+ - **Don't use when:** you need to fetch a file from a URL, or the file is bigger than 5 MB in MCP. Use the Apify version for those jobs.
167
+ - **Input:** text on stdin or a file path. Optional `--action auto|encode|decode`, `--url-safe`, `--data-uri`, `--output FILE`.
168
+ - **MCP:** `uvx --from git+https://github.com/tidybytetools/base64-lite base64-lite mcp` gives two read-only tools, `convert_text` and `convert_file`.
169
+ - **Output:** with `--json`, one object such as `{"ok": true, "action": "encode", "base64": "...", "bytesIn": 11}`. On error `ok` is false. Exit code 0 ok, 1 error.
170
+ - Hint lines go to stderr only, and only in a terminal, so stdout is always clean. See also [`llms.txt`](https://github.com/tidybytetools/base64-lite/blob/main/llms.txt).
171
+
172
+ ## Tests
173
+
174
+ ```
175
+ pip install "mcp>=1.10,<2"
176
+ python3 -m unittest discover tests
177
+ ```
178
+
179
+ The MCP tests are skipped if `mcp` is not installed.
180
+
181
+ ## FAQ
182
+
183
+ **What input does it take?**
184
+ Text on stdin, or a local file. Use `--action encode` or `--action decode` if you already know the direction.
185
+
186
+ **Do my files leave my computer?**
187
+ No. The tool runs on your computer and never uses the internet.
188
+
189
+ **How is this different from the Apify version?**
190
+ The Apify version runs in the cloud, can fetch file links, and can process many items in one run. This lite tool is free and local.
191
+
192
+ **Does it work with AI apps?**
193
+ Yes. It includes a free MCP server. No API key.
194
+
195
+ ## License
196
+
197
+ MIT. See `LICENSE`.
@@ -0,0 +1,19 @@
1
+ CHANGELOG.md
2
+ LICENSE
3
+ MANIFEST.in
4
+ README.md
5
+ base64_lite.py
6
+ base64_lite_mcp.py
7
+ llms.txt
8
+ pyproject.toml
9
+ server.json
10
+ base64_lite.egg-info/PKG-INFO
11
+ base64_lite.egg-info/SOURCES.txt
12
+ base64_lite.egg-info/dependency_links.txt
13
+ base64_lite.egg-info/entry_points.txt
14
+ base64_lite.egg-info/requires.txt
15
+ base64_lite.egg-info/top_level.txt
16
+ tests/test_lite.py
17
+ tests/test_mcp.py
18
+ tests/fixtures/hello.b64
19
+ tests/fixtures/hello.txt
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ base64-lite = base64_lite:main
3
+ base64-lite-mcp = base64_lite_mcp:main
@@ -0,0 +1 @@
1
+ mcp<2,>=1.10
@@ -0,0 +1,2 @@
1
+ base64_lite
2
+ base64_lite_mcp
@@ -0,0 +1,215 @@
1
+ #!/usr/bin/env python3
2
+ """base64-lite (MIT): encode or decode Base64 for text and local files.
3
+
4
+ This file uses only the Python standard library. The MCP server
5
+ (base64_lite_mcp.py) needs the mcp package.
6
+
7
+ Need it at scale or from an AI agent? Use the Apify version:
8
+ https://apify.com/tidybytetools/base64-encode-decode
9
+ """
10
+ from __future__ import annotations
11
+
12
+ import argparse
13
+ import base64
14
+ import json
15
+ import mimetypes
16
+ import os
17
+ import re
18
+ import sys
19
+
20
+ __version__ = "1.0.0"
21
+ APIFY_URL = "https://apify.com/tidybytetools/base64-encode-decode"
22
+ PRO_LINE = f"Need it at scale or from an AI agent? Use the Apify version: {APIFY_URL}"
23
+
24
+ B64_RE = re.compile(r"^[A-Za-z0-9+/_-]+={0,2}$")
25
+ DATA_URI_RE = re.compile(r"^data:([^;,]+)?(?:;charset=[^;,]+)?(;base64)?,", re.I)
26
+
27
+
28
+ def looks_like_base64(text: str) -> bool:
29
+ s = "".join(str(text).split())
30
+ if s.lower().startswith("data:") and ";base64," in s.lower():
31
+ s = s.split(",", 1)[1]
32
+ if len(s) < 4 or len(s) % 4 != 0:
33
+ return False
34
+ if not B64_RE.match(s):
35
+ return False
36
+ # Plain short words can accidentally match. Require padding or a typical alphabet mix.
37
+ if s.endswith("="):
38
+ return True
39
+ has_plus = any(c in s for c in "+/_-")
40
+ return has_plus or len(s) >= 16
41
+
42
+
43
+ def _decode_bytes(s: str) -> bytes:
44
+ raw = "".join(s.split())
45
+ m = DATA_URI_RE.match(raw)
46
+ if m:
47
+ raw = raw[m.end():]
48
+ pad = (-len(raw)) % 4
49
+ raw = raw + ("=" * pad)
50
+ alt = raw.replace("-", "+").replace("_", "/")
51
+ try:
52
+ return base64.b64decode(alt, validate=False)
53
+ except Exception as e:
54
+ raise ValueError("This text is not valid Base64.") from e
55
+
56
+
57
+ def encode_bytes(data: bytes, url_safe: bool = False, data_uri: bool = False, mime: str | None = None) -> dict:
58
+ if url_safe:
59
+ token = base64.urlsafe_b64encode(data).decode("ascii")
60
+ else:
61
+ token = base64.b64encode(data).decode("ascii")
62
+ rec = {
63
+ "action": "encode",
64
+ "base64": token,
65
+ "bytesIn": len(data),
66
+ "ok": True,
67
+ }
68
+ if data_uri:
69
+ # data URIs always use the standard alphabet, not the URL-safe one
70
+ std = base64.b64encode(data).decode("ascii")
71
+ rec["dataUri"] = f"data:{mime or 'application/octet-stream'};base64,{std}"
72
+ rec["mime"] = mime or "application/octet-stream"
73
+ return rec
74
+
75
+
76
+ def decode_text(text: str) -> dict:
77
+ data = _decode_bytes(text)
78
+ try:
79
+ as_text = data.decode("utf-8")
80
+ text_ok = True
81
+ except UnicodeDecodeError:
82
+ as_text = None
83
+ text_ok = False
84
+ return {
85
+ "action": "decode",
86
+ "bytesOut": len(data),
87
+ "text": as_text,
88
+ "isText": text_ok,
89
+ "ok": True,
90
+ "_raw": data,
91
+ }
92
+
93
+
94
+ def convert(
95
+ text: str | None,
96
+ data: bytes | None,
97
+ action: str = "auto",
98
+ url_safe: bool = False,
99
+ data_uri: bool = False,
100
+ filename: str | None = None,
101
+ ) -> dict:
102
+ action = (action or "auto").lower()
103
+ if action not in ("auto", "encode", "decode"):
104
+ raise ValueError("Action must be auto, encode, or decode.")
105
+ mime = mimetypes.guess_type(filename)[0] if filename else None
106
+ if data is not None and text is None:
107
+ if action == "decode":
108
+ try:
109
+ text = data.decode("utf-8")
110
+ except UnicodeDecodeError as e:
111
+ raise ValueError("This file is not UTF-8 text, so it cannot be decoded as Base64.") from e
112
+ return decode_text(text)
113
+ return encode_bytes(data, url_safe=url_safe, data_uri=data_uri, mime=mime)
114
+ if text is None:
115
+ raise ValueError("Nothing to convert.")
116
+ if action == "encode":
117
+ return encode_bytes(text.encode("utf-8"), url_safe=url_safe, data_uri=data_uri, mime="text/plain")
118
+ if action == "decode":
119
+ return decode_text(text)
120
+ if looks_like_base64(text):
121
+ try:
122
+ return decode_text(text)
123
+ except ValueError:
124
+ return encode_bytes(text.encode("utf-8"), url_safe=url_safe, data_uri=data_uri, mime="text/plain")
125
+ return encode_bytes(text.encode("utf-8"), url_safe=url_safe, data_uri=data_uri, mime="text/plain")
126
+
127
+
128
+ def public_result(rec: dict) -> dict:
129
+ """Drop internal keys such as raw decoded bytes."""
130
+ return {k: v for k, v in rec.items() if not k.startswith("_")}
131
+
132
+
133
+ def run_mcp():
134
+ """Start the stdio MCP server (needs the mcp package, which pip installs for you)."""
135
+ try:
136
+ import base64_lite_mcp
137
+ except ImportError as e:
138
+ print(f"error: the MCP server needs the mcp package ({e}). Run: pip install git+https://github.com/tidybytetools/base64-lite", file=sys.stderr)
139
+ return 1
140
+ base64_lite_mcp.main()
141
+ return 0
142
+
143
+
144
+ def main(argv=None):
145
+ argv = sys.argv[1:] if argv is None else argv
146
+ if argv == ["mcp"]:
147
+ return run_mcp()
148
+ p = argparse.ArgumentParser(
149
+ prog="base64-lite",
150
+ description="Encode or decode Base64 for text and local files. Run `base64-lite mcp` to start the MCP server (to read a file named mcp, use ./mcp).",
151
+ epilog=PRO_LINE,
152
+ )
153
+ p.add_argument("file", nargs="?", help="input file (default: stdin)")
154
+ p.add_argument("-a", "--action", default="auto", choices=["auto", "encode", "decode"], help="auto decodes if the input looks like Base64, otherwise it encodes")
155
+ p.add_argument("--url-safe", action="store_true", help="use the URL-safe alphabet (- and _) when encoding; decoding always accepts both")
156
+ p.add_argument("--data-uri", action="store_true", help="when encoding, also build a data: URI")
157
+ p.add_argument("-o", "--output", help="write decoded bytes to this file (useful when the result is not text)")
158
+ p.add_argument("--json", action="store_true", help="machine-readable envelope: {ok, action, ...}")
159
+ p.add_argument("--indent", type=int, default=2)
160
+ p.add_argument("-q", "--quiet", action="store_true", help="don't print the one-line note about the Apify version")
161
+ p.add_argument("--version", action="version", version=__version__)
162
+ a = p.parse_args(argv)
163
+ try:
164
+ filename = None
165
+ text = None
166
+ data = None
167
+ if a.file:
168
+ filename = a.file
169
+ with open(a.file, "rb") as f:
170
+ data = f.read()
171
+ else:
172
+ raw = sys.stdin.buffer.read()
173
+ if not raw:
174
+ raise ValueError("Nothing to convert. Pass a file or pipe text.")
175
+ # stdin: treat as text when we can, else as bytes to encode
176
+ try:
177
+ text = raw.decode("utf-8")
178
+ except UnicodeDecodeError:
179
+ data = raw
180
+ rec = convert(text, data, action=a.action, url_safe=a.url_safe, data_uri=a.data_uri, filename=filename)
181
+ raw_out = rec.get("_raw")
182
+ if a.output:
183
+ payload = raw_out if rec.get("action") == "decode" else rec["base64"].encode("ascii")
184
+ parent = os.path.dirname(os.path.abspath(a.output))
185
+ if parent:
186
+ os.makedirs(parent, exist_ok=True)
187
+ with open(a.output, "wb") as f:
188
+ f.write(payload)
189
+ pub = public_result(rec)
190
+ if a.json:
191
+ print(json.dumps(pub, indent=a.indent, ensure_ascii=False))
192
+ elif rec["action"] == "encode":
193
+ print(rec["dataUri"] if a.data_uri and rec.get("dataUri") else rec["base64"])
194
+ else:
195
+ if rec["isText"]:
196
+ sys.stdout.write(rec["text"])
197
+ if rec["text"] and not rec["text"].endswith("\n"):
198
+ sys.stdout.write("\n")
199
+ elif a.output:
200
+ print(f"wrote {rec['bytesOut']} binary bytes to {a.output}", file=sys.stderr)
201
+ else:
202
+ raise ValueError("Decoded bytes are not UTF-8 text. Re-run with --output FILE or --json.")
203
+ if not a.quiet and not a.json and sys.stderr.isatty():
204
+ print(PRO_LINE, file=sys.stderr)
205
+ return 0
206
+ except Exception as e:
207
+ if getattr(a, "json", False):
208
+ print(json.dumps({"ok": False, "error": str(e)}))
209
+ return 1
210
+ print(f"error: {e}", file=sys.stderr)
211
+ return 1
212
+
213
+
214
+ if __name__ == "__main__":
215
+ sys.exit(main())
@@ -0,0 +1,100 @@
1
+ """Free MCP server for base64-lite (stdio).
2
+
3
+ Run: uvx --from git+https://github.com/tidybytetools/base64-lite base64-lite mcp
4
+ or: uvx --from git+https://github.com/tidybytetools/base64-lite base64-lite-mcp
5
+ """
6
+ import os
7
+ from typing import Annotated, Literal
8
+ from pydantic import Field
9
+ from mcp.server.fastmcp import FastMCP
10
+ from mcp.types import ToolAnnotations
11
+ import base64_lite as lite
12
+
13
+ MAX_BYTES = 5_000_000 # 5 MB is plenty for local text and small files
14
+
15
+ mcp = FastMCP("base64-lite")
16
+
17
+ READ_ONLY = dict(
18
+ readOnlyHint=True, # only reads; never writes or changes anything
19
+ destructiveHint=False,
20
+ idempotentHint=True, # same input always gives the same result
21
+ openWorldHint=False, # no network; works on the text or local file you give it
22
+ )
23
+
24
+ Action = Annotated[
25
+ Literal["auto", "encode", "decode"],
26
+ Field(description='What to do. "auto" (default) decodes if the input looks like Base64, otherwise it encodes. Use "encode" or "decode" when you already know the direction.'),
27
+ ]
28
+
29
+
30
+ def _check_file(path: str):
31
+ path = os.path.expanduser(path)
32
+ if not os.path.isfile(path):
33
+ raise FileNotFoundError(f"file not found: {path}")
34
+ if os.path.getsize(path) > MAX_BYTES:
35
+ raise ValueError("file is bigger than 5 MB")
36
+ with open(path, "rb") as f:
37
+ return path, f.read()
38
+
39
+
40
+ @mcp.tool(
41
+ title="Encode or decode Base64 text",
42
+ annotations=ToolAnnotations(title="Encode or decode Base64 text", **READ_ONLY),
43
+ )
44
+ def convert_text(
45
+ text: Annotated[str, Field(description="The text to encode, or the Base64 (or data URI) to decode.")],
46
+ action: Action = "auto",
47
+ url_safe: Annotated[bool, Field(description="If true, encode with - and _ instead of + and /. Decoding always accepts both.")] = False,
48
+ data_uri: Annotated[bool, Field(description="If true, encoded results also include a data: URI.")] = False,
49
+ ) -> dict:
50
+ """Encode pasted text to Base64, or decode Base64 (or a data URI) back to text.
51
+
52
+ Use this when you have text or a Base64 string in the conversation. It is plain
53
+ code, not an AI model, so the same input always gives the same output and nothing
54
+ is made up. Do not use it for a file on disk (use convert_file for files), and do
55
+ not use auto on short or unusual strings if you already know the direction — pass
56
+ encode or decode instead.
57
+
58
+ Returns a result object. Encoded results include "action", "base64", "bytesIn",
59
+ and "dataUri" plus "mime" when data_uri is true. Decoded results include "action",
60
+ "bytesOut", "isText", and "text" (UTF-8 text, or null if the bytes are not text).
61
+ """
62
+ if action not in ("auto", "encode", "decode"):
63
+ raise ValueError("action must be auto, encode or decode")
64
+ return lite.public_result(lite.convert(text, None, action=action, url_safe=url_safe, data_uri=data_uri))
65
+
66
+
67
+ @mcp.tool(
68
+ title="Encode or decode a local file as Base64",
69
+ annotations=ToolAnnotations(title="Encode or decode a local file as Base64", **READ_ONLY),
70
+ )
71
+ def convert_file(
72
+ path: Annotated[str, Field(description="Full path to a local file, up to 5 MB. For decode, the file must be UTF-8 text of Base64.")],
73
+ action: Action = "auto",
74
+ url_safe: Annotated[bool, Field(description="If true, encode with - and _ instead of + and /. Decoding always accepts both.")] = False,
75
+ data_uri: Annotated[bool, Field(description="If true, encoded results also include a data: URI. The MIME type is guessed from the file name when we can.")] = False,
76
+ ) -> dict:
77
+ """Read a local file and encode its bytes to Base64, or decode a Base64 text file.
78
+
79
+ Use this when the data is in a file on this computer, so you don't have to paste
80
+ it. The file is only read, never changed. Files larger than 5 MB are rejected;
81
+ use the Apify version for bigger jobs. For decode, the file must be UTF-8 text
82
+ containing Base64 (or a data URI), not a binary file.
83
+
84
+ path: full path to a file, up to 5 MB.
85
+
86
+ Returns the same result object as convert_text. If the decoded bytes are not
87
+ UTF-8 text, "isText" is false and "text" is null.
88
+ """
89
+ if action not in ("auto", "encode", "decode"):
90
+ raise ValueError("action must be auto, encode or decode")
91
+ path, data = _check_file(path)
92
+ return lite.public_result(lite.convert(None, data, action=action, url_safe=url_safe, data_uri=data_uri, filename=path))
93
+
94
+
95
+ def main():
96
+ mcp.run()
97
+
98
+
99
+ if __name__ == "__main__":
100
+ main()
@@ -0,0 +1,19 @@
1
+ # base64-lite
2
+
3
+ > Free, MIT-licensed, Python tool (the converter is one standard-library file; the MCP server needs the mcp package) that encodes or decodes Base64 for text and local files. Optional URL-safe alphabet and data-URI output.
4
+
5
+ - Install: `pip install git+https://github.com/tidybytetools/base64-lite` (or download base64_lite.py)
6
+ - CLI: `base64-lite file --action encode|decode|auto`. Reads stdin if no file. `--url-safe`, `--data-uri`, `--output FILE` for decoded binary, `--json` prints `{"ok": true, "action": "encode", "base64": "..."}`. Exit 0 ok, 1 error.
7
+ - Python: `from base64_lite import convert; convert("hello world", None, action="encode")`.
8
+ - MCP: `uvx --from git+https://github.com/tidybytetools/base64-lite base64-lite mcp` exposes two read-only tools: `convert_text(text, action="auto", url_safe=false, data_uri=false)` and `convert_file(path, ...)` for local files up to 5 MB.
9
+
10
+ ## Use when
11
+ - You need to encode text or a local file to Base64, or decode Base64 / a data URI.
12
+
13
+ ## Don't use when
14
+ - You need to fetch a file from a URL, or the file is bigger than 5 MB in MCP. Use the Apify version: https://apify.com/tidybytetools/base64-encode-decode
15
+ - You already know the direction and the string is short or unusual — pass action encode or decode, not auto.
16
+
17
+ ## Links
18
+ - [README](https://github.com/tidybytetools/base64-lite/blob/main/README.md)
19
+ - [Apify version](https://apify.com/tidybytetools/base64-encode-decode)
@@ -0,0 +1,47 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "base64-lite"
7
+ version = "1.0.0"
8
+ description = "Encode or decode Base64 for text and local files. URL-safe and data-URI options. Local CLI and MCP server."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{name = "Tidy Byte Tools"}]
13
+ requires-python = ">=3.10"
14
+ dependencies = [
15
+ "mcp>=1.10,<2",
16
+ ]
17
+ keywords = ["base64", "encode", "decode", "data-uri", "url-safe", "cli", "mcp", "mcp-server"]
18
+ classifiers = [
19
+ "Development Status :: 4 - Beta",
20
+ "Environment :: Console",
21
+ "Intended Audience :: Developers",
22
+ "Intended Audience :: End Users/Desktop",
23
+ "Operating System :: OS Independent",
24
+ "Programming Language :: Python :: 3",
25
+ "Programming Language :: Python :: 3 :: Only",
26
+ "Programming Language :: Python :: 3.10",
27
+ "Programming Language :: Python :: 3.11",
28
+ "Programming Language :: Python :: 3.12",
29
+ "Programming Language :: Python :: 3.13",
30
+ "Topic :: Utilities",
31
+ "Topic :: Text Processing",
32
+ ]
33
+
34
+ [project.urls]
35
+ Homepage = "https://github.com/tidybytetools/base64-lite"
36
+ Documentation = "https://github.com/tidybytetools/base64-lite#readme"
37
+ Source = "https://github.com/tidybytetools/base64-lite"
38
+ Issues = "https://github.com/tidybytetools/base64-lite/issues"
39
+ Changelog = "https://github.com/tidybytetools/base64-lite/blob/main/CHANGELOG.md"
40
+ Apify = "https://apify.com/tidybytetools/base64-encode-decode"
41
+
42
+ [project.scripts]
43
+ base64-lite = "base64_lite:main"
44
+ base64-lite-mcp = "base64_lite_mcp:main"
45
+
46
+ [tool.setuptools]
47
+ py-modules = ["base64_lite", "base64_lite_mcp"]
@@ -0,0 +1,31 @@
1
+ {
2
+ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
3
+ "name": "io.github.tidybytetools/base64-lite",
4
+ "title": "base64-lite",
5
+ "description": "Encode or decode Base64 for text and local files. URL-safe and data-URI options. Local CLI and MCP server.",
6
+ "repository": {
7
+ "url": "https://github.com/tidybytetools/base64-lite",
8
+ "source": "github"
9
+ },
10
+ "websiteUrl": "https://github.com/tidybytetools/base64-lite",
11
+ "version": "1.0.0",
12
+ "packages": [
13
+ {
14
+ "registryType": "pypi",
15
+ "registryBaseUrl": "https://pypi.org",
16
+ "identifier": "base64-lite",
17
+ "version": "1.0.0",
18
+ "runtimeHint": "uvx",
19
+ "transport": {
20
+ "type": "stdio"
21
+ },
22
+ "packageArguments": [
23
+ {
24
+ "type": "positional",
25
+ "value": "mcp",
26
+ "description": "Starts the MCP server instead of the command-line tool."
27
+ }
28
+ ]
29
+ }
30
+ ]
31
+ }
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1 @@
1
+ aGVsbG8gd29ybGQ=
@@ -0,0 +1 @@
1
+ hello world
@@ -0,0 +1,140 @@
1
+ import io, os, sys, tempfile, unittest
2
+ from contextlib import redirect_stdout, redirect_stderr
3
+ sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
4
+ import base64_lite as b64
5
+
6
+ class T(unittest.TestCase):
7
+ def test_encode_hello(self):
8
+ r = b64.convert("hello world", None, action="encode")
9
+ self.assertEqual(r["action"], "encode")
10
+ self.assertEqual(r["base64"], "aGVsbG8gd29ybGQ=")
11
+ self.assertEqual(r["bytesIn"], 11)
12
+
13
+ def test_decode_hello(self):
14
+ r = b64.convert("aGVsbG8gd29ybGQ=", None, action="decode")
15
+ self.assertEqual(r["action"], "decode")
16
+ self.assertEqual(r["text"], "hello world")
17
+ self.assertTrue(r["isText"])
18
+
19
+ def test_auto_decode(self):
20
+ r = b64.convert("aGVsbG8gd29ybGQ=", None, action="auto")
21
+ self.assertEqual(r["action"], "decode")
22
+ self.assertEqual(r["text"], "hello world")
23
+
24
+ def test_auto_encode_plain(self):
25
+ r = b64.convert("hello world", None, action="auto")
26
+ self.assertEqual(r["action"], "encode")
27
+ self.assertEqual(r["base64"], "aGVsbG8gd29ybGQ=")
28
+
29
+ def test_url_safe_and_data_uri(self):
30
+ r = b64.convert("hi?", None, action="encode", url_safe=True, data_uri=True)
31
+ self.assertTrue("-" in r["base64"] or "_" in r["base64"] or r["base64"].endswith("="))
32
+ self.assertTrue(r["dataUri"].startswith("data:text/plain;base64,"))
33
+ # data URI uses the standard alphabet
34
+ self.assertNotIn("-", r["dataUri"].split(",", 1)[1])
35
+ # decode accepts the URL-safe form
36
+ back = b64.convert(r["base64"], None, action="decode")
37
+ self.assertEqual(back["text"], "hi?")
38
+
39
+ def test_file_encode(self):
40
+ r = b64.convert(None, b"\x00\x01\x02", action="encode", data_uri=True, filename="x.bin")
41
+ self.assertEqual(r["bytesIn"], 3)
42
+ self.assertIn("base64", r)
43
+
44
+ def test_looks_like(self):
45
+ self.assertTrue(b64.looks_like_base64("aGVsbG8gd29ybGQ="))
46
+ self.assertFalse(b64.looks_like_base64("hello world"))
47
+
48
+ def test_decode_data_uri(self):
49
+ r = b64.convert("data:text/plain;base64,aGVsbG8=", None, action="decode")
50
+ self.assertEqual(r["text"], "hello")
51
+
52
+ def test_decode_binary_is_not_text(self):
53
+ rec = b64.encode_bytes(b"\x00\xff")
54
+ r = b64.convert(rec["base64"], None, action="decode")
55
+ self.assertFalse(r["isText"])
56
+ self.assertIsNone(r["text"])
57
+ self.assertEqual(r["_raw"], b"\x00\xff")
58
+
59
+ def test_public_result_drops_raw(self):
60
+ r = b64.public_result(b64.convert("aGVsbG8=", None, action="decode"))
61
+ self.assertNotIn("_raw", r)
62
+ self.assertEqual(r["text"], "hello")
63
+
64
+ def test_bad_action(self):
65
+ with self.assertRaises(ValueError):
66
+ b64.convert("hello", None, action="flip")
67
+
68
+ def test_nothing(self):
69
+ with self.assertRaises(ValueError):
70
+ b64.convert(None, None)
71
+
72
+ def run_main(self, argv, stdin=b"", stdin_text=None):
73
+ out, err = io.StringIO(), io.StringIO()
74
+ raw = stdin_text.encode("utf-8") if stdin_text is not None else stdin
75
+ old = sys.stdin
76
+ sys.stdin = io.TextIOWrapper(io.BytesIO(raw), encoding="utf-8")
77
+ # also expose .buffer for binary stdin reads
78
+ try:
79
+ with redirect_stdout(out), redirect_stderr(err):
80
+ code = b64.main(argv)
81
+ finally:
82
+ sys.stdin = old
83
+ return code, out.getvalue(), err.getvalue()
84
+
85
+ def test_cli_json_encode(self):
86
+ code, out, err = self.run_main(["--json", "--action", "encode"], stdin_text="hello world")
87
+ self.assertEqual(code, 0)
88
+ self.assertIn('"ok": true', out)
89
+ self.assertIn("aGVsbG8gd29ybGQ=", out)
90
+ self.assertNotIn("apify.com", out)
91
+
92
+ def test_cli_plain_encode(self):
93
+ code, out, err = self.run_main(["--action", "encode"], stdin_text="hello world")
94
+ self.assertEqual(code, 0)
95
+ self.assertEqual(out.strip(), "aGVsbG8gd29ybGQ=")
96
+
97
+ def test_cli_plain_decode(self):
98
+ code, out, err = self.run_main(["--action", "decode"], stdin_text="aGVsbG8gd29ybGQ=")
99
+ self.assertEqual(code, 0)
100
+ self.assertEqual(out.strip(), "hello world")
101
+
102
+ def test_cli_help_has_apify_link(self):
103
+ out = io.StringIO()
104
+ with redirect_stdout(out), self.assertRaises(SystemExit):
105
+ b64.main(["--help"])
106
+ self.assertIn("https://apify.com/tidybytetools/base64-encode-decode", out.getvalue())
107
+
108
+ def test_bad_file(self):
109
+ code, out, err = self.run_main(["--json", "/nope/missing.txt"], stdin_text="")
110
+ self.assertEqual(code, 1)
111
+ self.assertIn('"ok": false', out)
112
+
113
+ def test_cli_output_binary(self):
114
+ rec = b64.encode_bytes(b"\x00\xff")
115
+ with tempfile.TemporaryDirectory() as td:
116
+ dest = os.path.join(td, "out.bin")
117
+ code, out, err = self.run_main(["--action", "decode", "--output", dest], stdin_text=rec["base64"])
118
+ self.assertEqual(code, 0)
119
+ with open(dest, "rb") as f:
120
+ self.assertEqual(f.read(), b"\x00\xff")
121
+
122
+ def test_cli_file_encode(self):
123
+ with tempfile.TemporaryDirectory() as td:
124
+ path = os.path.join(td, "hello.txt")
125
+ with open(path, "w", encoding="utf-8") as f:
126
+ f.write("hello world")
127
+ code, out, err = self.run_main(["--action", "encode", path])
128
+ self.assertEqual(code, 0)
129
+ self.assertEqual(out.strip(), "aGVsbG8gd29ybGQ=")
130
+
131
+ def test_version(self):
132
+ out = io.StringIO()
133
+ with redirect_stdout(out), self.assertRaises(SystemExit) as ctx:
134
+ b64.main(["--version"])
135
+ self.assertIn(ctx.exception.code, (0, None))
136
+ self.assertIn("1.0.0", out.getvalue())
137
+
138
+
139
+ if __name__ == "__main__":
140
+ unittest.main()
@@ -0,0 +1,69 @@
1
+ """Starts the MCP server over stdio (both ways it can start), lists tools, and calls them."""
2
+ import asyncio, json, os, sys, unittest
3
+ HERE = os.path.dirname(os.path.abspath(__file__))
4
+ ROOT = os.path.dirname(HERE)
5
+
6
+ try:
7
+ from mcp import ClientSession, StdioServerParameters
8
+ from mcp.client.stdio import stdio_client
9
+ except ImportError:
10
+ ClientSession = None
11
+
12
+ READ_ONLY = {"readOnlyHint": True, "destructiveHint": False, "idempotentHint": True, "openWorldHint": False}
13
+
14
+
15
+ def _data(res):
16
+ """The tool result as Python data (structured content if present, else the JSON text)."""
17
+ if res.structuredContent is not None:
18
+ sc = res.structuredContent
19
+ return sc.get("result", sc) if set(sc) == {"result"} else sc
20
+ return json.loads(res.content[0].text)
21
+
22
+
23
+ async def _session(args, fn):
24
+ params = StdioServerParameters(command=sys.executable, args=args, cwd=ROOT)
25
+ async with stdio_client(params) as (r, w):
26
+ async with ClientSession(r, w) as s:
27
+ await s.initialize()
28
+ return await fn(s)
29
+
30
+
31
+ @unittest.skipIf(ClientSession is None, "mcp not installed")
32
+ class MCP(unittest.TestCase):
33
+ def test_tools_and_annotations(self):
34
+ async def go(s):
35
+ return (await s.list_tools()).tools
36
+ tools = asyncio.run(_session([os.path.join(ROOT, "base64_lite_mcp.py")], go))
37
+ self.assertEqual(sorted(t.name for t in tools), ["convert_file", "convert_text"])
38
+ for t in tools:
39
+ self.assertTrue(t.title)
40
+ self.assertIn("Use this when", t.description)
41
+ for k, v in READ_ONLY.items():
42
+ self.assertIs(getattr(t.annotations, k), v, f"{t.name} {k}")
43
+
44
+ def test_calls(self):
45
+ async def go(s):
46
+ enc = await s.call_tool("convert_text", {"text": "hello world", "action": "encode"})
47
+ dec = await s.call_tool("convert_text", {"text": "aGVsbG8gd29ybGQ=", "action": "decode"})
48
+ auto = await s.call_tool("convert_text", {"text": "hello world"})
49
+ f = await s.call_tool("convert_file", {"path": os.path.join(HERE, "fixtures", "hello.txt"), "action": "encode"})
50
+ missing = await s.call_tool("convert_file", {"path": "/nope/missing.bin"})
51
+ bad = await s.call_tool("convert_text", {"text": "hello", "action": "flip"})
52
+ return enc, dec, auto, f, missing, bad
53
+ enc, dec, auto, f, missing, bad = asyncio.run(_session([os.path.join(ROOT, "base64_lite_mcp.py")], go))
54
+ self.assertEqual(_data(enc)["base64"], "aGVsbG8gd29ybGQ=")
55
+ self.assertEqual(_data(dec)["text"], "hello world")
56
+ self.assertEqual(_data(auto)["action"], "encode")
57
+ self.assertEqual(_data(f)["base64"], "aGVsbG8gd29ybGQ=")
58
+ self.assertTrue(missing.isError)
59
+ self.assertTrue(bad.isError)
60
+
61
+ def test_cli_mcp_subcommand_starts_server(self):
62
+ async def go(s):
63
+ return [t.name for t in (await s.list_tools()).tools]
64
+ names = asyncio.run(_session([os.path.join(ROOT, "base64_lite.py"), "mcp"], go))
65
+ self.assertIn("convert_text", names)
66
+
67
+
68
+ if __name__ == "__main__":
69
+ unittest.main()