benchling-toolkit 0.4.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.
- benchling_toolkit-0.4.0/LICENSE +22 -0
- benchling_toolkit-0.4.0/PKG-INFO +576 -0
- benchling_toolkit-0.4.0/README.md +535 -0
- benchling_toolkit-0.4.0/contracts/list-parameters.json +32 -0
- benchling_toolkit-0.4.0/contracts/openapi-manifest.json +48 -0
- benchling_toolkit-0.4.0/pyproject.toml +130 -0
- benchling_toolkit-0.4.0/schemas/change-spec.schema.json +173 -0
- benchling_toolkit-0.4.0/schemas/envelope.schema.json +30 -0
- benchling_toolkit-0.4.0/setup.cfg +4 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/__init__.py +6 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/api.py +219 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/auth.py +133 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/change_spec.py +436 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/cli.py +840 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/config.py +57 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/credentials.py +257 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/environment.py +188 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/errors.py +104 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/export.py +662 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/keychain.py +323 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/listing.py +487 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/mcp_server.py +847 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/models.py +290 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/plans/__init__.py +13 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/plans/base.py +60 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/plans/document.py +298 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/plans/fields.py +300 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/plans/planner.py +318 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/plans/repository.py +105 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/plans/result_update.py +845 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/plans/results.py +184 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/plans/table.py +241 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/py.typed +0 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/redact.py +67 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/runtime.py +82 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/services.py +1206 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit/tls.py +10 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit.egg-info/PKG-INFO +576 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit.egg-info/SOURCES.txt +64 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit.egg-info/dependency_links.txt +1 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit.egg-info/entry_points.txt +2 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit.egg-info/requires.txt +16 -0
- benchling_toolkit-0.4.0/src/benchling_toolkit.egg-info/top_level.txt +1 -0
- benchling_toolkit-0.4.0/tests/test_api_client.py +231 -0
- benchling_toolkit-0.4.0/tests/test_auth.py +55 -0
- benchling_toolkit-0.4.0/tests/test_change_spec.py +180 -0
- benchling_toolkit-0.4.0/tests/test_cli_commands.py +696 -0
- benchling_toolkit-0.4.0/tests/test_config_home.py +87 -0
- benchling_toolkit-0.4.0/tests/test_contract_requests.py +288 -0
- benchling_toolkit-0.4.0/tests/test_credentials.py +1252 -0
- benchling_toolkit-0.4.0/tests/test_demo.py +20 -0
- benchling_toolkit-0.4.0/tests/test_environment.py +352 -0
- benchling_toolkit-0.4.0/tests/test_export.py +1541 -0
- benchling_toolkit-0.4.0/tests/test_interview_docs.py +105 -0
- benchling_toolkit-0.4.0/tests/test_listing.py +425 -0
- benchling_toolkit-0.4.0/tests/test_mcp_server.py +928 -0
- benchling_toolkit-0.4.0/tests/test_openapi_drift.py +482 -0
- benchling_toolkit-0.4.0/tests/test_planner_safety.py +92 -0
- benchling_toolkit-0.4.0/tests/test_plans_document.py +370 -0
- benchling_toolkit-0.4.0/tests/test_plans_fields.py +185 -0
- benchling_toolkit-0.4.0/tests/test_plans_result_update.py +611 -0
- benchling_toolkit-0.4.0/tests/test_plans_results.py +174 -0
- benchling_toolkit-0.4.0/tests/test_plans_table.py +222 -0
- benchling_toolkit-0.4.0/tests/test_results_rows.py +167 -0
- benchling_toolkit-0.4.0/tests/test_services.py +439 -0
- benchling_toolkit-0.4.0/tests/test_skill_md.py +153 -0
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 John Amodeo
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
|
@@ -0,0 +1,576 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: benchling-toolkit
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: Safe, auditable tools for AI agents working in Benchling
|
|
5
|
+
Author-email: John Amodeo <120539773+jmamodeo@users.noreply.github.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/jmamodeo/benchling-toolkit
|
|
8
|
+
Project-URL: Repository, https://github.com/jmamodeo/benchling-toolkit
|
|
9
|
+
Project-URL: Issues, https://github.com/jmamodeo/benchling-toolkit/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/jmamodeo/benchling-toolkit/blob/main/CHANGELOG.md
|
|
11
|
+
Keywords: benchling,eln,cli,mcp,model-context-protocol,lab-automation,laboratory-informatics
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Scientific/Engineering
|
|
21
|
+
Classifier: Typing :: Typed
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Requires-Dist: filelock>=3.16
|
|
26
|
+
Requires-Dist: httpx<1,>=0.27
|
|
27
|
+
Requires-Dist: keyring<26,>=25
|
|
28
|
+
Requires-Dist: mcp<3,>=1.13
|
|
29
|
+
Requires-Dist: pydantic<3,>=2.8
|
|
30
|
+
Requires-Dist: typer<1,>=0.12
|
|
31
|
+
Requires-Dist: truststore<1,>=0.10
|
|
32
|
+
Provides-Extra: dev
|
|
33
|
+
Requires-Dist: jsonschema<5,>=4.23; extra == "dev"
|
|
34
|
+
Requires-Dist: mypy<2,>=1.11; extra == "dev"
|
|
35
|
+
Requires-Dist: pytest<10,>=8.3; extra == "dev"
|
|
36
|
+
Requires-Dist: pytest-asyncio<2,>=0.24; extra == "dev"
|
|
37
|
+
Requires-Dist: pytest-cov<8,>=5; extra == "dev"
|
|
38
|
+
Requires-Dist: pyyaml<7,>=6; extra == "dev"
|
|
39
|
+
Requires-Dist: ruff>=0.6; extra == "dev"
|
|
40
|
+
Dynamic: license-file
|
|
41
|
+
|
|
42
|
+
# benchling-toolkit
|
|
43
|
+
|
|
44
|
+
Safe, auditable tools for AI agents working in Benchling.
|
|
45
|
+
|
|
46
|
+
[](https://github.com/jmamodeo/benchling-toolkit/actions/workflows/ci.yml)
|
|
47
|
+
[](LICENSE)
|
|
48
|
+
[](pyproject.toml)
|
|
49
|
+
[](https://github.com/jmamodeo/benchling-toolkit/actions/workflows/ci.yml)
|
|
50
|
+
|
|
51
|
+
> **Unofficial; not affiliated with or endorsed by Benchling, Inc.** Benchling is a trademark of Benchling, Inc.
|
|
52
|
+
|
|
53
|
+
## Why this exists
|
|
54
|
+
|
|
55
|
+
An electronic lab notebook is a scientific record, so letting an AI agent write to one directly is hard to trust. `benchling-toolkit` is a toolkit of safe, auditable tools that AI agents use to work with a [Benchling](https://www.benchling.com) tenant: a JSON-first CLI and a local [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that is read-only by default. Every change is first previewed as an immutable, checksummed plan that records what will change and the version preconditions it depends on. A separate, explicit step applies it: that step re-checks the preconditions, refuses stale or already-used plans, and records each stage in a local execution journal. The MCP server cannot apply writes unless an operator opts a specific environment in with `--allow-writes`.
|
|
56
|
+
|
|
57
|
+
- Public Benchling API only; it never automates the browser.
|
|
58
|
+
- Four change families: document text, unstructured tables, entry fields, and assay results.
|
|
59
|
+
- Several environments at once. Each one is saved with `benchling auth login`; the client secret stays in the OS keychain.
|
|
60
|
+
- One versioned JSON envelope and stable exit codes for both interfaces.
|
|
61
|
+
|
|
62
|
+
## Demo
|
|
63
|
+
|
|
64
|
+

|
|
65
|
+
|
|
66
|
+
The picture and the [asciinema cast](docs/demo.cast) are a scripted playback of one run of `uv run python scripts/demo.py`. `scripts/render_demo.py` builds both files from that script's stdout. The script runs the real CLI and MCP server against the offline fake API in `tests/fake_benchling.py`, through an in-process HTTP mock. No credentials are used and no network call is made. The cast is an asciinema v2 file assembled from that transcript. It is not a capture from the asciinema recorder, and it is not a live tenant. Plan IDs differ on every run. The transcript below is the same run as the picture.
|
|
67
|
+
|
|
68
|
+
<!-- demo-transcript:start -->
|
|
69
|
+
```console
|
|
70
|
+
# 1. Read an entry (envelope trimmed for readability)
|
|
71
|
+
|
|
72
|
+
$ benchling --env demo entry inspect etr_abc123
|
|
73
|
+
{
|
|
74
|
+
"ok": true,
|
|
75
|
+
"data": {
|
|
76
|
+
"version_id": "ver_1",
|
|
77
|
+
"project_id": "src_abc123"
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
[exit 0]
|
|
81
|
+
|
|
82
|
+
# 2. Preview: reads Benchling, writes nothing remotely
|
|
83
|
+
|
|
84
|
+
$ benchling --env demo changes plan --entry etr_abc123 --family table --spec set-cell-b2.json
|
|
85
|
+
{
|
|
86
|
+
"ok": true,
|
|
87
|
+
"data": {
|
|
88
|
+
"id": "9268199dd92c49a3b0df5be26ebb3dc8",
|
|
89
|
+
"family": "table",
|
|
90
|
+
"env": "demo",
|
|
91
|
+
"preconditions": {
|
|
92
|
+
"entry_version": "ver_1",
|
|
93
|
+
"entry_id": "etr_abc123"
|
|
94
|
+
},
|
|
95
|
+
"guarantees": [
|
|
96
|
+
"server-enforced document version check"
|
|
97
|
+
],
|
|
98
|
+
"warnings": [
|
|
99
|
+
"Updating a cell or appending rows resets table evaluation until Benchling evaluates the table again"
|
|
100
|
+
]
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
[exit 0]
|
|
104
|
+
|
|
105
|
+
remote writes so far: 0
|
|
106
|
+
|
|
107
|
+
# 3. Apply the first plan
|
|
108
|
+
|
|
109
|
+
$ benchling --env demo changes apply 9268199dd92c49a3b0df5be26ebb3dc8
|
|
110
|
+
{
|
|
111
|
+
"ok": true,
|
|
112
|
+
"data": {
|
|
113
|
+
"journal": {
|
|
114
|
+
"status": "succeeded",
|
|
115
|
+
"events": [
|
|
116
|
+
{
|
|
117
|
+
"stage": "apply",
|
|
118
|
+
"status": "started"
|
|
119
|
+
},
|
|
120
|
+
{
|
|
121
|
+
"stage": "update_table_cells",
|
|
122
|
+
"status": "succeeded"
|
|
123
|
+
},
|
|
124
|
+
{
|
|
125
|
+
"stage": "apply",
|
|
126
|
+
"status": "succeeded"
|
|
127
|
+
}
|
|
128
|
+
]
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
[exit 0]
|
|
133
|
+
|
|
134
|
+
# 4. The second plan was previewed against the old entry version: apply is refused
|
|
135
|
+
|
|
136
|
+
$ benchling --env demo changes apply f76d9ec52ca7410a91955867a495b3f5
|
|
137
|
+
{
|
|
138
|
+
"ok": false,
|
|
139
|
+
"error": {
|
|
140
|
+
"code": "conflict",
|
|
141
|
+
"message": "Entry version changed after the plan was created",
|
|
142
|
+
"retryable": false,
|
|
143
|
+
"details": {
|
|
144
|
+
"expected": "ver_1",
|
|
145
|
+
"actual": "ver_2"
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
[exit 5]
|
|
150
|
+
|
|
151
|
+
# 5. A plan cannot be applied twice
|
|
152
|
+
|
|
153
|
+
$ benchling --env demo changes apply 9268199dd92c49a3b0df5be26ebb3dc8
|
|
154
|
+
{
|
|
155
|
+
"ok": false,
|
|
156
|
+
"error": {
|
|
157
|
+
"code": "conflict",
|
|
158
|
+
"message": "Plan has already been applied or attempted",
|
|
159
|
+
"retryable": false,
|
|
160
|
+
"details": {
|
|
161
|
+
"plan_id": "9268199dd92c49a3b0df5be26ebb3dc8",
|
|
162
|
+
"status": "succeeded"
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
[exit 5]
|
|
167
|
+
|
|
168
|
+
remote writes in total: 1
|
|
169
|
+
|
|
170
|
+
# 6. MCP server: read-only unless --allow-writes ENV is passed
|
|
171
|
+
|
|
172
|
+
apply_changes(env="demo", plan_id=...) ->
|
|
173
|
+
{
|
|
174
|
+
"code": "unsupported_capability",
|
|
175
|
+
"message": "MCP writes are disabled for demo; restart with `benchling mcp serve --allow-writes demo`",
|
|
176
|
+
"retryable": false,
|
|
177
|
+
"details": {}
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
<!-- demo-transcript:end -->
|
|
181
|
+
|
|
182
|
+
## Install
|
|
183
|
+
|
|
184
|
+
The distribution name is `benchling-toolkit` and the import package is `benchling_toolkit`. Python 3.11 or newer and [`uv`](https://docs.astral.sh/uv/) are required.
|
|
185
|
+
|
|
186
|
+
Once `benchling-toolkit` is published to PyPI, install the CLI and start the MCP server with:
|
|
187
|
+
|
|
188
|
+
```console
|
|
189
|
+
uv tool install benchling-toolkit
|
|
190
|
+
benchling --help
|
|
191
|
+
|
|
192
|
+
uvx --from benchling-toolkit benchling mcp serve
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
`uv tool install benchling-toolkit` puts `benchling` on PATH. `uvx --from benchling-toolkit benchling mcp serve` runs the server from that package without a separate install; the MCP client config below is that same command.
|
|
196
|
+
|
|
197
|
+
Those are the PyPI forms. They work once the package is published. They are not live yet: `benchling-toolkit` is not on PyPI. Until a release is published, run the same commands against a checkout of this repository:
|
|
198
|
+
|
|
199
|
+
```console
|
|
200
|
+
uv tool install .
|
|
201
|
+
uvx --from . benchling mcp serve
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
`uv sync` in a git checkout installs the package into that project's virtualenv only. It does not put `benchling` on PATH. From a checkout, run `uv run benchling`, or activate `.venv`. Add `--extra dev` to `uv sync` when you need the test and lint tools. Creating the Benchling app, granting it project access, and saving it with `benchling auth login --env NAME` are in the [setup guide](docs/setup.md).
|
|
205
|
+
|
|
206
|
+
## Configuration
|
|
207
|
+
|
|
208
|
+
Create the Benchling app and grant it project access first. Those steps, including separate read and write environments, are in the [setup guide](docs/setup.md).
|
|
209
|
+
|
|
210
|
+
Run `benchling auth login` in your own terminal. The client secret is read from a hidden prompt, or from stdin with `--secret-stdin`, and is never accepted as an argument, so it does not pass through an agent, a shell history entry, or an MCP client config.
|
|
211
|
+
|
|
212
|
+
```console
|
|
213
|
+
benchling auth login --env dev
|
|
214
|
+
# Tenant URL: https://your-tenant.benchling.com
|
|
215
|
+
# Client ID: your-app-client-id
|
|
216
|
+
# Client secret (not echoed):
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Agents and CI can log in with no terminal. Pass the tenant and client ID as flags, and the secret on stdin:
|
|
220
|
+
|
|
221
|
+
```console
|
|
222
|
+
printf '%s' "$BENCHLING_CLIENT_SECRET" | benchling auth login --env dev \
|
|
223
|
+
--tenant-url https://your-tenant.benchling.com \
|
|
224
|
+
--client-id your-app-client-id \
|
|
225
|
+
--secret-stdin
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
`--tenant-url` accepts `https://host`, a bare host, or the same URL with a trailing `/api/v2` or `/api/v3` (those suffixes and a trailing slash are removed). `http://` is rejected. If a flag is missing and there is no terminal, login exits with one error that names `--tenant-url`, `--client-id`, and `--secret-stdin`. It does not fall back to `getpass` on a pipe, so you will not see echo warnings.
|
|
229
|
+
|
|
230
|
+
Login requests an OAuth `client_credentials` token before it saves anything. On success it writes the tenant URL and client ID to `environments.json` (mode 0600) under the state directory, and stores the client secret in the OS keychain under the service name `benchling-toolkit`. The username in the keychain is the environment name. Access tokens stay in process memory and are renewed before expiry in a long-running MCP process. If no usable keychain is available, login fails with the cause, one fix command, and a pointer to Headless Linux. There is no plaintext file fallback. A 401 says `Benchling at https://<tenant> rejected the client ID or secret.`
|
|
231
|
+
|
|
232
|
+
The toolkit acts as the **app**, with the app's permissions and audit identity, not the signed-in browser user. Profiles saved by previous versions are never read.
|
|
233
|
+
|
|
234
|
+
Environment names use lowercase letters and digits, start with a letter, and are at most 32 characters. The environment is required on every API command; there is no default. `-e` is short for `--env`.
|
|
235
|
+
|
|
236
|
+
```console
|
|
237
|
+
benchling auth login --env test
|
|
238
|
+
benchling auth status
|
|
239
|
+
benchling --env dev auth status --check
|
|
240
|
+
benchling --env test doctor
|
|
241
|
+
benchling auth logout --env dev
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
`auth status` is the only way to list saved environments. It shows each tenant URL without a trailing slash and whether a keychain secret is present. It never prints the secret. `--check` requests a token and puts the specific failure in the top-level message (for example `Client secret is not in the keychain; run benchling auth login --env dev`). `doctor` makes read-only API checks. When a check fails, the envelope is `ok: false`, the process exits 3, and each failed check includes a hint. `auth logout` removes the `environments.json` record and the keychain secret; it does not revoke the app in Benchling. Logging out an environment that was never configured says that it is not configured.
|
|
245
|
+
|
|
246
|
+
## Headless Linux
|
|
247
|
+
|
|
248
|
+
Linux servers and agent machines often have no Secret Service on the session bus. `benchling` will not write the client secret to a plaintext file. Install a provider if it is missing (`gnome-keyring` and `dbus` on Debian/Ubuntu), then unlock a keyring and run the login in that same session. Pipe the keyring password on stdin so it is not a shell argument:
|
|
249
|
+
|
|
250
|
+
```console
|
|
251
|
+
dbus-run-session -- sh -c '
|
|
252
|
+
printf "%s\n" "$KEYRING_PASSWORD" | gnome-keyring-daemon --unlock --components=secrets
|
|
253
|
+
printf "%s" "$BENCHLING_CLIENT_SECRET" | benchling auth login --env dev \
|
|
254
|
+
--tenant-url https://your-tenant.benchling.com \
|
|
255
|
+
--client-id your-app-client-id \
|
|
256
|
+
--secret-stdin
|
|
257
|
+
'
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
A wrong `KEYRING_PASSWORD` for an existing login keyring makes the first keyring call hang; use the right password, or remove `~/.local/share/keyrings/login.keyring` for a fresh scratch setup.
|
|
261
|
+
|
|
262
|
+
Do not capture `gnome-keyring-daemon --unlock` with `$(...)` or backticks. The daemon does not exit, and the child keeps the substitution's pipe open, so the shell waits forever:
|
|
263
|
+
|
|
264
|
+
```console
|
|
265
|
+
# Hangs. Do not do this.
|
|
266
|
+
eval "$(printf '%s\n' "$KEYRING_PASSWORD" | gnome-keyring-daemon --unlock --components=secrets)"
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
`dbus-run-session` sets `DBUS_SESSION_BUS_ADDRESS` for that shell only. When the shell exits, the bus exits with it, and a secret stored there is gone. `gnome-keyring-daemon --unlock` does not print `DBUS_SESSION_BUS_ADDRESS`. Do not look for the address in its output.
|
|
270
|
+
|
|
271
|
+
MCP, later shells, and cron need a bus that stays up. Create one with `dbus-daemon`, then unlock the keyring on it. `dbus-daemon --print-address` prints the address and exits. Command substitution is safe for that command. It is not safe for `gnome-keyring-daemon --unlock`.
|
|
272
|
+
|
|
273
|
+
```console
|
|
274
|
+
runtime="${XDG_RUNTIME_DIR:-/tmp/benchling-bus-$UID}"
|
|
275
|
+
mkdir -p "$runtime"
|
|
276
|
+
chmod 700 "$runtime"
|
|
277
|
+
export DBUS_SESSION_BUS_ADDRESS="$(dbus-daemon --session --fork --print-address --address="unix:path=${runtime}/bus")"
|
|
278
|
+
printf '%s\n' "$KEYRING_PASSWORD" | gnome-keyring-daemon --unlock --components=secrets
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
Put that same `DBUS_SESSION_BUS_ADDRESS` in the environment of later shells, cron, and the MCP client config `env` block.
|
|
282
|
+
|
|
283
|
+
If `systemctl --user status` works, a user bus is often already listening at `unix:path=$XDG_RUNTIME_DIR/bus`. Export `DBUS_SESSION_BUS_ADDRESS` to that socket, then unlock the keyring. SSH and cron do not receive the user session's environment on their own. `loginctl enable-linger "$USER"` keeps the systemd user session after logout so that bus can stay up.
|
|
284
|
+
|
|
285
|
+
If the collection is locked, or the session bus has no `org.freedesktop.secrets` name, the error is the cause, one `dbus-run-session` command that unlocks the keyring and logs in inside that shell, and a pointer here. During `auth login` that command uses the environment name, the normalized tenant URL, and the client ID you passed, or the ones already saved for that environment. A value you did not supply stays a placeholder (`--env dev`, `https://your-tenant.benchling.com`, `CLIENT`). `$KEYRING_PASSWORD` and `$BENCHLING_CLIENT_SECRET` stay shell variables. `auth status`, `mcp serve`, and other commands keep the placeholders. If no provider is installed, the command is `sudo apt-get install -y gnome-keyring dbus`. The note about the MCP client `env` block and cron is included only when `benchling mcp serve` raises the error. macOS and Windows use the system keychain and do not need this session.
|
|
286
|
+
|
|
287
|
+
`BENCHLING_TOOLKIT_HOME` overrides the state directory (the platform config directory plus `benchling-toolkit` otherwise). It does not hold secrets. HTTPS uses the operating system's certificate trust store, with certificate-chain and hostname verification enabled. No insecure TLS fallback is available.
|
|
288
|
+
|
|
289
|
+
## Least privilege
|
|
290
|
+
|
|
291
|
+
Create two Benchling apps and save them as two environments. The [setup guide](docs/setup.md) covers creating each app, granting it project access, and saving it with `benchling auth login --env NAME`.
|
|
292
|
+
|
|
293
|
+
- A read-only app, via `benchling auth login --env read`. Use this for agents and everyday MCP sessions. Do not pass `--allow-writes read`.
|
|
294
|
+
- A write app, via `benchling auth login --env write`. Start a server that may apply changes with `benchling mcp serve --allow-writes write` only.
|
|
295
|
+
|
|
296
|
+
In Benchling, grant each app access only to the specific projects it should see. Give the read app the Read access policy. Give the write app Write, or Append when it should create records and leave existing ones unchanged. `--allow-writes` is a local switch on the MCP server. It cannot widen the access the Benchling app was given.
|
|
297
|
+
|
|
298
|
+
## Quickstart
|
|
299
|
+
|
|
300
|
+
```console
|
|
301
|
+
uv tool install benchling-toolkit
|
|
302
|
+
benchling auth login --env dev
|
|
303
|
+
benchling auth status
|
|
304
|
+
benchling --env dev doctor
|
|
305
|
+
benchling --env dev entry resolve EXP-0001
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
`uv tool install benchling-toolkit` works once the package is published. Until then, install from a checkout with `uv tool install .`. `auth login` prompts for `https://your-tenant.benchling.com`, the client ID, and the client secret. Run it in your own terminal. App setup is in the [setup guide](docs/setup.md).
|
|
309
|
+
|
|
310
|
+
## CLI examples
|
|
311
|
+
|
|
312
|
+
### Read entries
|
|
313
|
+
|
|
314
|
+
Every command prints a versioned JSON envelope. Diagnostics go to stderr.
|
|
315
|
+
|
|
316
|
+
```console
|
|
317
|
+
benchling --env dev entry resolve EXP-0001
|
|
318
|
+
benchling --env dev entry get etr_abc123 --full
|
|
319
|
+
benchling --env dev entry inspect etr_abc123
|
|
320
|
+
benchling --env dev section get etr_abc123 docpart_section1
|
|
321
|
+
benchling --env dev part get etr_abc123 docpart_text1
|
|
322
|
+
benchling --env dev table get docpart_table1
|
|
323
|
+
benchling --env dev schema get entsch_example
|
|
324
|
+
benchling --env dev schema list
|
|
325
|
+
benchling --env dev schema list --kind run --limit 50
|
|
326
|
+
benchling --env dev entry fields get etr_abc123
|
|
327
|
+
benchling --env dev entry list --project src_example --modified-after 2026-01-01
|
|
328
|
+
benchling --env dev entry list --folder lib_example --name "Example entry"
|
|
329
|
+
benchling --env dev results list --entry etr_abc123
|
|
330
|
+
benchling --env dev results tables etr_abc123
|
|
331
|
+
benchling --env dev results rows docpart_example --limit 50
|
|
332
|
+
benchling --env dev export --kind table --part docpart_table1 --format csv --output measurements.csv
|
|
333
|
+
benchling --env dev export --kind results-table --part docpart_rt1 --format json --output results-table.json
|
|
334
|
+
benchling --env dev export --kind results-table --part strtbl_example --entry etr_abc123 --format csv --output listed-table.csv
|
|
335
|
+
benchling --env dev export --kind assay-results --entry etr_abc123 --schema assaysch_example --format csv --output assay.csv
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
Entry references may be canonical IDs, display IDs, or URLs for the selected tenant. Duplicate section titles must be addressed by part ID.
|
|
339
|
+
|
|
340
|
+
`entry list` and `schema list` are read-only. They return one page, default 50 and at most 100, plus `next_token`. Pass that token back with `--cursor`. `schema list` reads entry schemas, then result schemas, then run schemas, following every upstream page until the page is full or the lists end. `schema get` adds the options of each dropdown field (`/dropdown/{id}` and `/dropdown/{id}/options/items`). There is no separate dropdown command.
|
|
341
|
+
|
|
342
|
+
Every `entry list` filter is applied by Benchling. `routing.client_side` is always empty.
|
|
343
|
+
|
|
344
|
+
- Without `--folder`, and when the name has no comma, the query is V3 `GET /entry/items`. Server-side filters are project (`project.eq`), schema (`schema.eq`), name (`name.anyOf`), and the modified range (`modifiedAt.gte` and `modifiedAt.lte`). That name match is exact and case-insensitive. It is not a substring search. The modified bounds are inclusive. A bare `YYYY-MM-DD` is the start of that UTC day for `--modified-after` and the end of that UTC day for `--modified-before`. A timestamp must include a time zone, such as `2026-06-15T12:00:00Z`. A timestamp with no zone is rejected.
|
|
345
|
+
- V3 entry listing has no folder parameter, and live tenants ignore `folderId` on that route, so this client never sends it there. `--folder` sends the whole query to V2 `GET /entries`. On that route folder (`folderId`), project (`projectId`), schema (`schemaId`), name (`names.anyOf`), and `modifiedAt` are all server-side. V2 takes one `modifiedAt` string; this client sends `>=` and `<=` joined by ` AND ` so the range stays inclusive.
|
|
346
|
+
- A name that contains a comma cannot be one item of `name.anyOf` or `names.anyOf`. Both parameters are comma-separated lists, and the contract documents no escape. That name is sent as V2 `GET /entries` parameter `name`, and the other filters on the same request go to V2 as well. V2 `name` is a single entry name. The contract describes it as the specified name and does not say the comparison is case-insensitive.
|
|
347
|
+
- `modified_at` on entry and schema lists is a UTC timestamp with a `Z` suffix. V2 values that use `+00:00`, and values with another offset, are converted.
|
|
348
|
+
|
|
349
|
+
`results rows PART_ID` reads one page of a results table. It is read-only. The page size defaults to 50 and stops at 100. Pass `next_token` back with `--cursor`. The call is `GET /document-part-results-table/{id}/rows/items` with `pageSize` and `nextToken`. The part is read first, and its `rows` URL must be that path on this tenant. Cells use the same shape as `entry get --full`. `row_count` is the count on the part. `entry get --full` still reads every row of the part.
|
|
350
|
+
|
|
351
|
+
`benchling export` writes an unstructured table (`--kind table`), a results table (`--kind results-table`), or assay results (`--kind assay-results`) to a JSON or CSV file. `--format` is `json` or `csv`. `table` and `results-table` require `--part`. `assay-results` accepts `--entry` and `--schema`, the same filters as `results list`. The command reads every page itself: unstructured-table and results-table rows at `pageSize` 100, and assay results from `GET /result/items` at `pageSize` 100. The printed envelope is a summary only: `row_count`, `columns`, `path`, and `checksum` (SHA-256 of the file bytes). The rows stay in the file, so a large table does not enter an agent's context. A cell is the evaluation when Benchling returned one, otherwise the input. Duplicate column names get a `__2` suffix. An existing file is left unchanged unless `--overwrite` is set. Nothing is written to Benchling. The MCP tool `export` uses the same summary.
|
|
352
|
+
|
|
353
|
+
`--part` takes a `v3_document_part` id (`docpart_…`) from `entry inspect` (the `tables` part ids). `results tables ENTRY` returns a different id: `table_id` is a `v2_structured_table` id (`strtbl_…`, `id_namespace` `v2_structured_table`). Pass that id with `--kind results-table --entry ENTRY` (the same entry). The export reads the entry's document parts and uses the matching results-table part. When no part matches, it reads assay results for that entry and the table's result schema. `--kind table` does not accept a `strtbl_…` id. That is a validation error naming `v3_document_part`. A `strtbl_…` id with no `--entry` is the same kind of error.
|
|
354
|
+
|
|
355
|
+
Assay-result columns are the result's scalar metadata plus one column per schema field. V3 stores those values in `schemaFields` (an array of field-definition ref plus value), not in a top-level `fields` object. The column name is the field's display name. A link or entity reference is written as its id. A multi-value field is a JSON array in CSV. An unset field is empty: CSV writes `""` and JSON writes `null`. `linkedEntityId` is used only when the field is a link and the id is a different entity. An unset field's `linkedEntityId` is often the result's own id, and that id is not written as the value.
|
|
356
|
+
|
|
357
|
+
A results-table or unstructured-table cell is flattened the same way. A link or entity reference becomes its id in both JSON and CSV, so a results table and the assay results for the same record show the same value.
|
|
358
|
+
|
|
359
|
+
### Preview and apply changes
|
|
360
|
+
|
|
361
|
+
A change specification covers one entry and one mutation family. Previewing only reads Benchling and creates a local immutable plan:
|
|
362
|
+
|
|
363
|
+
```console
|
|
364
|
+
benchling --env dev changes plan \
|
|
365
|
+
--entry etr_abc123 \
|
|
366
|
+
--family table \
|
|
367
|
+
--spec examples/table-set-cells.json
|
|
368
|
+
|
|
369
|
+
benchling --env dev changes plan \
|
|
370
|
+
--entry etr_abc123 \
|
|
371
|
+
--family results \
|
|
372
|
+
--csv assay.csv \
|
|
373
|
+
--id-column id \
|
|
374
|
+
--map Ct=Ct \
|
|
375
|
+
--map Note=Note
|
|
376
|
+
|
|
377
|
+
benchling --env dev changes apply PLAN_ID
|
|
378
|
+
benchling --env dev changes status PLAN_ID
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
Supported specifications are documented in [schemas/change-spec.schema.json](schemas/change-spec.schema.json). The four families are:
|
|
382
|
+
|
|
383
|
+
- `document`: insert, delete, move, or replace a text part;
|
|
384
|
+
- `table`: set selected cells or append rows on an unstructured table;
|
|
385
|
+
- `fields`: update fields already present on the entry's assigned schema; and
|
|
386
|
+
- `results`: submit V2 assay result records to an explicit `strtbl_…` table, or update existing results from a CSV file.
|
|
387
|
+
|
|
388
|
+
Field inputs must use a schema field's V3 `systemName` or its field-definition ID and have the shape `{"value": ...}`. Plans show both identifiers, send the field-definition ID, validate value types and constraints, and re-check the affected definitions and values immediately before applying. Result uploads also verify that the table belongs to the selected entry, that every record uses the table's result schema, and that any supplied project IDs are readable. Result upload field keys stay system names.
|
|
389
|
+
|
|
390
|
+
A result update reads a CSV file instead of inline records. `--id-column` is the column that holds the result id (`id` in an assay-result export). Each `--map CSV_COLUMN=FIELD` is required; columns are not guessed from the header. `FIELD` is the export display name, the system name, or the field-definition id. The preview resolves every mapped column to a field-definition id and shows only the values that would change. Unmapped columns, including `createdAt` and `modifiedAt`, are not written. A blank cell clears a value that is present. A blank cell on an empty field is not a change, so an unmodified export round-trips: export writes both null and an empty string as a blank cell. Unknown columns, ambiguous names, and bad rows are one error and nothing is written. Apply re-reads each result and sends `PATCH /result/{id}` with `schemaFields` keyed by field-definition id, and only when `modifiedAt` and the mapped values still match the plan. The CSV is not read again at apply time. The limit is 500 rows. The same specification (`operation`, `csv_path`, `id_column`, `column_map`) is what `plan_changes` accepts.
|
|
391
|
+
|
|
392
|
+
Result submissions remain pending until a person integrates them in Benchling. A table write updates the named cells or appends rows, checked against the entry version, and resets table evaluation until Benchling's browser evaluates it again.
|
|
393
|
+
Table upload plans use local correlation UUIDs; the tenant assigns the actual result IDs. Local UUIDs are not idempotency keys. Caller-supplied result IDs are rejected by the CLI because the tested tenant rejects them on this endpoint despite the public OpenAPI declaration. Notebook table uploads are limited to 500 records. The immediate apply result is `submission_pending`; task success is reported separately as `pending_integration`.
|
|
394
|
+
`changes status` checks Benchling's asynchronous task endpoint after a result submission while retaining the local execution journal as the reconciliation record.
|
|
395
|
+
|
|
396
|
+
## MCP server
|
|
397
|
+
|
|
398
|
+
One server serves every environment saved with `auth login`. The client config carries no secrets; the server reads the same `environments.json` file and OS keychain as the CLI. Log in in your own terminal before starting the server. The shell form of the config below is `uvx --from benchling-toolkit benchling mcp serve`. That command works once the package is published to PyPI. From a checkout, run `uvx --from . benchling mcp serve`.
|
|
399
|
+
|
|
400
|
+
```json
|
|
401
|
+
{
|
|
402
|
+
"mcpServers": {
|
|
403
|
+
"benchling": {
|
|
404
|
+
"command": "uvx",
|
|
405
|
+
"args": ["--from", "benchling-toolkit", "benchling", "mcp", "serve"]
|
|
406
|
+
}
|
|
407
|
+
}
|
|
408
|
+
}
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
On Linux the standard MCP SDK starts the stdio server with only `HOME`, `LOGNAME`, `PATH`, `SHELL`, `TERM` and `USER`. `DBUS_SESSION_BUS_ADDRESS` is not among them, so the server cannot see the keyring and exits before the protocol starts. Put the long-lived session bus from Headless Linux in the client config `env` block. A `dbus-run-session` that has already exited is not a usable value:
|
|
412
|
+
|
|
413
|
+
```json
|
|
414
|
+
{
|
|
415
|
+
"mcpServers": {
|
|
416
|
+
"benchling": {
|
|
417
|
+
"command": "uvx",
|
|
418
|
+
"args": ["--from", "benchling-toolkit", "benchling", "mcp", "serve"],
|
|
419
|
+
"env": {
|
|
420
|
+
"DBUS_SESSION_BUS_ADDRESS": "unix:path=/run/user/1000/bus"
|
|
421
|
+
}
|
|
422
|
+
}
|
|
423
|
+
}
|
|
424
|
+
}
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
Startup failures, including a missing keychain, are a JSON envelope on stderr and a non-zero exit. Stdout is reserved for the MCP protocol. The stderr text names the MCP SDK's default environment and the `env` block. Request logging is off unless you pass `--verbose`.
|
|
428
|
+
|
|
429
|
+
Every tool except `list_environments` takes a required `env` argument, and each call is authenticated with that environment's credentials. Every parameter on every tool has a description in the published input schema. The server is read-only by default. To permit `apply_changes` in specific environments, add `--allow-writes ENV` after `serve` (repeatable, e.g. `--allow-writes dev --allow-writes test`); reads remain available in all environments. `list_entries` and `list_schemas` are reads, so they work without `--allow-writes`. A plan can only be applied or checked in the environment that created it. `plan_changes` remains available because it performs remote reads and writes only an immutable local preview. Its `specification` is a typed object, the same shapes as [schemas/change-spec.schema.json](schemas/change-spec.schema.json): a document or table `operation`, `schema_fields`, inline `assay_results`, or a result update with `operation` `update`, `csv_path`, `id_column`, and `column_map`. A specification that does not match is a `validation_error` in the standard envelope, and nothing is planned. The CLI still passes its JSON file to the planner. Large entry, section, table, result, and schema responses expose offset/limit or cursor pagination and never silently truncate data. `list_entries`, `list_schemas`, and `list_results_table_rows` use `limit` (default 50, maximum 100) and return `next_token` for the following page. `list_results_table_rows` is a read, so it works without `--allow-writes`. `export` reads every page internally and writes a local JSON or CSV file. Its response is the same summary as the CLI (row count, columns, path, SHA-256) and does not include the rows. It does not write to Benchling, and it does not need `--allow-writes`. An existing file is left unchanged unless `overwrite` is true.
|
|
430
|
+
|
|
431
|
+
The CLI and MCP tools share the same versioned envelope. Static schemas for the envelope and change specifications live under [`schemas/`](schemas/). MCP publishes the generated input and output schema for each tool during discovery. Each input parameter includes a description, and `plan_changes` `specification` is the typed union of those change shapes.
|
|
432
|
+
|
|
433
|
+
## Architecture
|
|
434
|
+
|
|
435
|
+
[ARCHITECTURE.md](ARCHITECTURE.md) is the plan, apply, and journal sequence. The [threat model](docs/threat-model.md) covers credentials, stale or replayed plans, write scoping, and agent misuse, including the limits of those controls.
|
|
436
|
+
|
|
437
|
+
[`SKILL.md`](SKILL.md) is the Agent Skills file for this repository. Its frontmatter keeps `name`, `description`, `license`, `compatibility`, and a `metadata` map of strings (`summary`, `version`, `docs_url`). Tags, keywords, and use cases are lists in [`agensi/listing.yaml`](agensi/listing.yaml).
|
|
438
|
+
|
|
439
|
+
```mermaid
|
|
440
|
+
flowchart TD
|
|
441
|
+
Agent["AI agent (MCP client)"] -->|stdio| MCP["MCP server"]
|
|
442
|
+
Operator["Operator or script"] --> CLI["CLI (Typer)"]
|
|
443
|
+
MCP --> SVC["BenchlingService: typed reads"]
|
|
444
|
+
CLI --> SVC
|
|
445
|
+
MCP --> PLANNER["ChangePlanner: plan, apply, status"]
|
|
446
|
+
CLI --> PLANNER
|
|
447
|
+
PLANNER --> SVC
|
|
448
|
+
PLANNER --> STORE[("Local state: plans, journals, apply locks")]
|
|
449
|
+
PLANNER --> API["BenchlingAPI: httpx, retries, pagination"]
|
|
450
|
+
SVC --> API
|
|
451
|
+
API --> AUTH["OAuth client credentials, in-memory tokens"]
|
|
452
|
+
AUTH --> KEY[("OS keychain: client secret")]
|
|
453
|
+
API --> BENCHLING[("Benchling REST V2 and V3")]
|
|
454
|
+
AUTH --> BENCHLING
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
| Module (`src/benchling_toolkit`) | Role |
|
|
458
|
+
|---|---|
|
|
459
|
+
| `cli.py` | Typer command-line interface |
|
|
460
|
+
| `mcp_server.py` | MCP tools, read-only default, write allow-list |
|
|
461
|
+
| `change_spec.py` | Typed `plan_changes` specifications and their validation |
|
|
462
|
+
| `services.py` | Typed read services and entry snapshots |
|
|
463
|
+
| `export.py` | Local JSON or CSV export; the response is a summary, not the rows |
|
|
464
|
+
| `listing.py` | Paged entry, schema, and dropdown discovery |
|
|
465
|
+
| `plans/planner.py` | `ChangePlanner`: plan, apply (under a per-plan file lock), status, journal |
|
|
466
|
+
| `plans/document.py`, `plans/table.py`, `plans/fields.py`, `plans/results.py` | One planning/apply mixin per change family |
|
|
467
|
+
| `plans/result_update.py` | CSV updates of existing results: re-check `modifiedAt`, then `PATCH /result/{id}` |
|
|
468
|
+
| `plans/repository.py` | Plan and journal persistence, checksums, JSON diff |
|
|
469
|
+
| `api.py` | HTTP client for Benchling REST V2/V3: retries for reads, never for writes |
|
|
470
|
+
| `auth.py` | OAuth client-credentials tokens, kept in memory |
|
|
471
|
+
| `credentials.py`, `keychain.py` | Login, logout, status, and OS keychain storage |
|
|
472
|
+
| `environment.py`, `config.py`, `runtime.py` | `environments.json`, state directories, per-environment runtimes |
|
|
473
|
+
| `redact.py` | Removes client secrets and access tokens from errors and journals |
|
|
474
|
+
| `models.py`, `errors.py` | Envelope, plan and journal models, error types and exit codes |
|
|
475
|
+
| `tls.py` | OS trust-store TLS |
|
|
476
|
+
|
|
477
|
+
## Safety model
|
|
478
|
+
|
|
479
|
+
- **Preview, then apply.** `changes plan` only reads Benchling and writes an immutable local plan; nothing changes remotely until `changes apply`. A document move that would leave the entry starting with anything other than a section fails in preview, before a plan is saved. Benchling rejects that shape with HTTP 400 `Entry must start with a section`.
|
|
480
|
+
- **Journals record the HTTP status.** Each apply step stores the raw status Benchling returned (`http_status`) next to the response body. A local failure that never reached the API has no status.
|
|
481
|
+
- **Plans are checksummed and scoped.** A plan stores a SHA-256 of its content, verified on load, and is bound to the environment and tenant that created it. The checksum catches accidental corruption; it is not a signature and does not defend against someone who can already write to your state directory.
|
|
482
|
+
- **Version preconditions.** Document edits and table writes send the entry version observed at preview time, and Benchling answers HTTP 409 if it is stale. Table plans re-check that entry version just before writing. A concurrent edit becomes a conflict instead of an overwrite. Entry field updates have no atomic server-side precondition, so the affected values are compared immediately before writing; this is best effort. CSV result updates re-check each result's `modifiedAt`, entry, schema, and mapped values before any `PATCH /result/{id}`. That PATCH body has no version field, so the check is local. A mismatch writes nothing.
|
|
483
|
+
- **Single use.** A plan with any prior attempt cannot be applied again, and a per-plan file lock stops a CLI and an MCP process from applying the same plan concurrently on one machine.
|
|
484
|
+
- **Writes are never retried.** A write that times out or fails with a server error leaves the journal in `unknown`/`partial` state for a person to reconcile; reads are retried with bounded backoff.
|
|
485
|
+
- **Read-only MCP by default.** `apply_changes` is refused unless the server was started with `--allow-writes ENV` for that environment. `plan_changes` stays available because it only reads Benchling and writes a local preview.
|
|
486
|
+
- **Export writes a local file only.** `export` reads Benchling and writes JSON or CSV on this machine. The response is a summary. An existing file is not replaced unless overwrite is set.
|
|
487
|
+
- **Explicit environment on every call.** There is no default environment, so a command or tool call cannot reach a tenant by omission.
|
|
488
|
+
- **Secrets stay in the OS keychain.** The tenant URL and client ID are stored in `environments.json` with mode 0600. Access tokens stay in process memory. Error envelopes and journals are scrubbed, and TLS verification uses the OS trust store with no insecure fallback. There is no plaintext secret file.
|
|
489
|
+
|
|
490
|
+
## Design decisions and tradeoffs
|
|
491
|
+
|
|
492
|
+
- **Plan/apply instead of one-call edit tools.** An AI agent reviews a concrete diff before anything is written, and a plan that has already been attempted cannot be applied again from this state directory. The cost is an extra step and some local state to manage.
|
|
493
|
+
- **OS keychain, no default environment.** The client secret is stored by the operating system and the target tenant is always explicit. The cost is a keychain dependency and no headless plaintext fallback.
|
|
494
|
+
- **App identity, not user identity.** OAuth client credentials give the toolkit its own permissions and audit identity, separate from any person's. The app must be granted access to each project it touches.
|
|
495
|
+
- **One service layer, two interfaces.** The CLI and MCP server call the same typed services and return the same envelope, so behavior is specified and tested once. The cost is a more verbose, JSON-first CLI.
|
|
496
|
+
- **Honest handling of API limits.** Unstructured table cells are edited one cell at a time, and new rows are inserted at the end of the table; evaluation is reset until Benchling recalculates it. Replacing text is an insert followed by a delete and can end in a reported partial completion.
|
|
497
|
+
- **Local, single-machine state.** Plans, journals, locks, and `environments.json` are plain files under the application directory (`BENCHLING_TOOLKIT_HOME` overrides it). Client secrets are in the OS keychain for that user. Concurrency control does not extend across machines.
|
|
498
|
+
- **Offline tests against a stateful fake.** The suite runs the real client, services and planner against an in-process fake Benchling API instead of stubbing each call. This tests behavior end to end; the cost is that the fake can drift from the real API, which is why the opt-in sandbox exercise exists.
|
|
499
|
+
|
|
500
|
+
## JSON envelope and exit codes
|
|
501
|
+
|
|
502
|
+
Every command and MCP tool returns `{"schema_version": "1.0", "ok": ..., "data": ..., "error": ..., "meta": ...}`. Exit codes:
|
|
503
|
+
|
|
504
|
+
| Code | Meaning |
|
|
505
|
+
|---:|---|
|
|
506
|
+
| 0 | Success |
|
|
507
|
+
| 2 | Input or validation error |
|
|
508
|
+
| 3 | Authentication error |
|
|
509
|
+
| 4 | Access denied or resource not found |
|
|
510
|
+
| 5 | Concurrent modification or reused plan |
|
|
511
|
+
| 6 | Unsupported capability |
|
|
512
|
+
| 7 | Upstream or transport failure |
|
|
513
|
+
| 8 | Partial or unknown write completion |
|
|
514
|
+
|
|
515
|
+
## Testing
|
|
516
|
+
|
|
517
|
+
The test suite is fully offline and needs no credentials. It runs the real client, services, planner, CLI and MCP server against a stateful in-process fake of the Benchling API (`tests/fake_benchling.py`).
|
|
518
|
+
|
|
519
|
+
```console
|
|
520
|
+
uv sync --extra dev
|
|
521
|
+
uv run ruff format --check .
|
|
522
|
+
uv run ruff check .
|
|
523
|
+
uv run mypy
|
|
524
|
+
uv run pytest --cov
|
|
525
|
+
```
|
|
526
|
+
|
|
527
|
+
The suite has 396 test functions (620 collected cases, parametrization included) and reaches 97% branch coverage. CI enforces a `fail_under` floor of 96% in `pyproject.toml`, and also builds the sdist and wheel, runs `twine check`, and smoke-tests the built wheel. CI installs `skills-ref` 0.1.1 and runs its `agentskills validate` command on this directory.
|
|
528
|
+
|
|
529
|
+
### Public OpenAPI drift
|
|
530
|
+
|
|
531
|
+
`.github/workflows/openapi-drift.yml` runs every Monday at 12:00 UTC and from the Actions tab (`workflow_dispatch`). It downloads the public V3 spec from the URL stored in `contracts/openapi-manifest.json` and fails when the SHA-256 differs. The failure names each path in that file's `routes_used` list whose operation or referenced definition changed. The job uses the public spec only: no tenant and no credentials.
|
|
532
|
+
|
|
533
|
+
```console
|
|
534
|
+
uv run python scripts/check_openapi_drift.py
|
|
535
|
+
```
|
|
536
|
+
|
|
537
|
+
`--spec-file` compares a local copy. The script's tests use fixture specs and stay offline.
|
|
538
|
+
|
|
539
|
+
### Opt-in sandbox exercise
|
|
540
|
+
|
|
541
|
+
Offline tests never require credentials. For a live sandbox, run `benchling auth login --env dev` in your own terminal first. The exercise below then creates a plan, pauses for a browser edit to invalidate it, verifies the conflict, and applies and verifies one selected-cell update. Add `--restore` to preview and explicitly restore the original input afterward.
|
|
542
|
+
|
|
543
|
+
```console
|
|
544
|
+
uv run python scripts/sandbox_exercise.py \
|
|
545
|
+
--env dev \
|
|
546
|
+
--entry etr_REPLACE_ME \
|
|
547
|
+
--table-part docpart_REPLACE_ME \
|
|
548
|
+
--row 0 --column 1 \
|
|
549
|
+
--value cli-sandbox-check \
|
|
550
|
+
--restore
|
|
551
|
+
```
|
|
552
|
+
|
|
553
|
+
## Known limitations
|
|
554
|
+
|
|
555
|
+
- **`replace_text` on flattened V3 text parts is verified against fixtures only.** The fix in 0.1.2 that lets `replace_text` accept the flattened `DocumentPartText` shape was built and tested against synthetic fixtures. It has not been verified against a live Benchling tenant, so do not rely on it for production data until it has been checked there (`scripts/live_cli_session.py` and `scripts/sandbox_exercise.py` are provided for that).
|
|
556
|
+
- The V3 Document API is in beta and Benchling may change it.
|
|
557
|
+
- Table cell edits and row inserts reset evaluation until Benchling recalculates the table in the browser. Only unstructured tables are editable. Results tables can be read; other structured tables cannot.
|
|
558
|
+
- Entry field updates are protected by a best-effort value comparison, not an atomic precondition.
|
|
559
|
+
- Replacing text can end in a partial completion that a person must reconcile.
|
|
560
|
+
- Assay result submissions stay pending until a person integrates them in Benchling.
|
|
561
|
+
- State is local to one machine and the package is not published on PyPI.
|
|
562
|
+
- The offline suite uses a synthetic fake; it cannot prove compatibility with every tenant configuration.
|
|
563
|
+
- `entry list --name` is an exact case-insensitive match when the name has no comma (`name.anyOf` on V3, `names.anyOf` on V2 with `--folder`). It does not search substrings. A name that contains a comma is sent as V2 `name`, because those list parameters are comma-separated and document no escape. A modified timestamp must include a time zone. Folder filters use the V2 entry list because the V3 list ignores `folderId`. Listing timestamps are UTC with a `Z` suffix.
|
|
564
|
+
|
|
565
|
+
See the [setup guide](docs/setup.md) before the first login, and [API limitations](docs/api-limitations.md) and the [research record](docs/research.md) before enabling writes against production data.
|
|
566
|
+
|
|
567
|
+
## Citation
|
|
568
|
+
|
|
569
|
+
If you use this software, please cite it. GitHub's "Cite this repository" button uses [`CITATION.cff`](CITATION.cff) for [jmamodeo/benchling-toolkit](https://github.com/jmamodeo/benchling-toolkit).
|
|
570
|
+
|
|
571
|
+
## Contributing, security, license
|
|
572
|
+
|
|
573
|
+
- [Contributing guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md)
|
|
574
|
+
- [Security policy](SECURITY.md)
|
|
575
|
+
- [Changelog](CHANGELOG.md)
|
|
576
|
+
- Licensed under the [MIT License](LICENSE).
|