knarr 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- knarr-0.1.0/LICENSE +202 -0
- knarr-0.1.0/NOTICE +4 -0
- knarr-0.1.0/PKG-INFO +296 -0
- knarr-0.1.0/README.md +265 -0
- knarr-0.1.0/knarr/__init__.py +7 -0
- knarr-0.1.0/knarr/doctor.py +656 -0
- knarr-0.1.0/knarr/explorer/__init__.py +4 -0
- knarr-0.1.0/knarr/explorer/borrow.py +403 -0
- knarr-0.1.0/knarr/explorer/caps.py +379 -0
- knarr-0.1.0/knarr/explorer/explorer_tools.py +2509 -0
- knarr-0.1.0/knarr/explorer/files.py +24 -0
- knarr-0.1.0/knarr/explorer/human_demo.py +705 -0
- knarr-0.1.0/knarr/explorer/learned_controls.py +456 -0
- knarr-0.1.0/knarr/explorer/origin.py +63 -0
- knarr-0.1.0/knarr/explorer/profiles.py +404 -0
- knarr-0.1.0/knarr/explorer/redact.py +107 -0
- knarr-0.1.0/knarr/explorer/session.py +432 -0
- knarr-0.1.0/knarr/explorer/trace.py +240 -0
- knarr-0.1.0/knarr/explorer/write_block.py +872 -0
- knarr-0.1.0/knarr/mcp/__init__.py +4 -0
- knarr-0.1.0/knarr/mcp/__main__.py +6 -0
- knarr-0.1.0/knarr/mcp/limits.py +74 -0
- knarr-0.1.0/knarr/mcp/server.py +368 -0
- knarr-0.1.0/knarr/mcp/session.py +818 -0
- knarr-0.1.0/knarr/mcp/worker.py +128 -0
- knarr-0.1.0/knarr.egg-info/PKG-INFO +296 -0
- knarr-0.1.0/knarr.egg-info/SOURCES.txt +31 -0
- knarr-0.1.0/knarr.egg-info/dependency_links.txt +1 -0
- knarr-0.1.0/knarr.egg-info/entry_points.txt +3 -0
- knarr-0.1.0/knarr.egg-info/requires.txt +7 -0
- knarr-0.1.0/knarr.egg-info/top_level.txt +1 -0
- knarr-0.1.0/pyproject.toml +48 -0
- knarr-0.1.0/setup.cfg +4 -0
knarr-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
Apache License
|
|
3
|
+
Version 2.0, January 2004
|
|
4
|
+
http://www.apache.org/licenses/
|
|
5
|
+
|
|
6
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
7
|
+
|
|
8
|
+
1. Definitions.
|
|
9
|
+
|
|
10
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
11
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
12
|
+
|
|
13
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
14
|
+
the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
17
|
+
other entities that control, are controlled by, or are under common
|
|
18
|
+
control with that entity. For the purposes of this definition,
|
|
19
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
20
|
+
direction or management of such entity, whether by contract or
|
|
21
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
23
|
+
|
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
25
|
+
exercising permissions granted by this License.
|
|
26
|
+
|
|
27
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
28
|
+
including but not limited to software source code, documentation
|
|
29
|
+
source, and configuration files.
|
|
30
|
+
|
|
31
|
+
"Object" form shall mean any form resulting from mechanical
|
|
32
|
+
transformation or translation of a Source form, including but
|
|
33
|
+
not limited to compiled object code, generated documentation,
|
|
34
|
+
and conversions to other media types.
|
|
35
|
+
|
|
36
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
37
|
+
Object form, made available under the License, as indicated by a
|
|
38
|
+
copyright notice that is included in or attached to the work
|
|
39
|
+
(an example is provided in the Appendix below).
|
|
40
|
+
|
|
41
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
42
|
+
form, that is based on (or derived from) the Work and for which the
|
|
43
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
44
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
45
|
+
of this License, Derivative Works shall not include works that remain
|
|
46
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
47
|
+
the Work and Derivative Works thereof.
|
|
48
|
+
|
|
49
|
+
"Contribution" shall mean any work of authorship, including
|
|
50
|
+
the original version of the Work and any modifications or additions
|
|
51
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
52
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
53
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
54
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
55
|
+
means any form of electronic, verbal, or written communication sent
|
|
56
|
+
to the Licensor or its representatives, including but not limited to
|
|
57
|
+
communication on electronic mailing lists, source code control systems,
|
|
58
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
59
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
60
|
+
excluding communication that is conspicuously marked or otherwise
|
|
61
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
62
|
+
|
|
63
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
64
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
65
|
+
subsequently incorporated within the Work.
|
|
66
|
+
|
|
67
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
68
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
69
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
70
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
71
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
72
|
+
Work and such Derivative Works in Source or Object form.
|
|
73
|
+
|
|
74
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
75
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
76
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
77
|
+
(except as stated in this section) patent license to make, have made,
|
|
78
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
79
|
+
where such license applies only to those patent claims licensable
|
|
80
|
+
by such Contributor that are necessarily infringed by their
|
|
81
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
82
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
83
|
+
institute patent litigation against any entity (including a
|
|
84
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
85
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
86
|
+
or contributory patent infringement, then any patent licenses
|
|
87
|
+
granted to You under this License for that Work shall terminate
|
|
88
|
+
as of the date such litigation is filed.
|
|
89
|
+
|
|
90
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
91
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
92
|
+
modifications, and in Source or Object form, provided that You
|
|
93
|
+
meet the following conditions:
|
|
94
|
+
|
|
95
|
+
(a) You must give any other recipients of the Work or
|
|
96
|
+
Derivative Works a copy of this License; and
|
|
97
|
+
|
|
98
|
+
(b) You must cause any modified files to carry prominent notices
|
|
99
|
+
stating that You changed the files; and
|
|
100
|
+
|
|
101
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
102
|
+
that You distribute, all copyright, patent, trademark, and
|
|
103
|
+
attribution notices from the Source form of the Work,
|
|
104
|
+
excluding those notices that do not pertain to any part of
|
|
105
|
+
the Derivative Works; and
|
|
106
|
+
|
|
107
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
108
|
+
distribution, then any Derivative Works that You distribute must
|
|
109
|
+
include a readable copy of the attribution notices contained
|
|
110
|
+
within such NOTICE file, excluding those notices that do not
|
|
111
|
+
pertain to any part of the Derivative Works, in at least one
|
|
112
|
+
of the following places: within a NOTICE text file distributed
|
|
113
|
+
as part of the Derivative Works; within the Source form or
|
|
114
|
+
documentation, if provided along with the Derivative Works; or,
|
|
115
|
+
within a display generated by the Derivative Works, if and
|
|
116
|
+
wherever such third-party notices normally appear. The contents
|
|
117
|
+
of the NOTICE file are for informational purposes only and
|
|
118
|
+
do not modify the License. You may add Your own attribution
|
|
119
|
+
notices within Derivative Works that You distribute, alongside
|
|
120
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
121
|
+
that such additional attribution notices cannot be construed
|
|
122
|
+
as modifying the License.
|
|
123
|
+
|
|
124
|
+
You may add Your own copyright statement to Your modifications and
|
|
125
|
+
may provide additional or different license terms and conditions
|
|
126
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
127
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
128
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
129
|
+
the conditions stated in this License.
|
|
130
|
+
|
|
131
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
132
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
133
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
134
|
+
this License, without any additional terms or conditions.
|
|
135
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
136
|
+
the terms of any separate license agreement you may have executed
|
|
137
|
+
with Licensor regarding such Contributions.
|
|
138
|
+
|
|
139
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
140
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
141
|
+
except as required for reasonable and customary use in describing the
|
|
142
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
143
|
+
|
|
144
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
145
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
146
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
147
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
148
|
+
implied, including, without limitation, any warranties or conditions
|
|
149
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
150
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
151
|
+
appropriateness of using or redistributing the Work and assume any
|
|
152
|
+
risks associated with Your exercise of permissions under this License.
|
|
153
|
+
|
|
154
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
155
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
156
|
+
unless required by applicable law (such as deliberate and grossly
|
|
157
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
158
|
+
liable to You for damages, including any direct, indirect, special,
|
|
159
|
+
incidental, or consequential damages of any character arising as a
|
|
160
|
+
result of this License or out of the use or inability to use the
|
|
161
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
162
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
163
|
+
other commercial damages or losses), even if such Contributor
|
|
164
|
+
has been advised of the possibility of such damages.
|
|
165
|
+
|
|
166
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
167
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
168
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
169
|
+
or other liability obligations and/or rights consistent with this
|
|
170
|
+
License. However, in accepting such obligations, You may act only
|
|
171
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
172
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
173
|
+
defend, and hold each Contributor harmless for any liability
|
|
174
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
175
|
+
of your accepting any such warranty or additional liability.
|
|
176
|
+
|
|
177
|
+
END OF TERMS AND CONDITIONS
|
|
178
|
+
|
|
179
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
180
|
+
|
|
181
|
+
To apply the Apache License to your work, attach the following
|
|
182
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
183
|
+
replaced with your own identifying information. (Don't include
|
|
184
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
185
|
+
comment syntax for the file format. We also recommend that a
|
|
186
|
+
file or class name and description of purpose be included on the
|
|
187
|
+
same "printed page" as the copyright notice for easier
|
|
188
|
+
identification within third-party archives.
|
|
189
|
+
|
|
190
|
+
Copyright [yyyy] [name of copyright owner]
|
|
191
|
+
|
|
192
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
193
|
+
you may not use this file except in compliance with the License.
|
|
194
|
+
You may obtain a copy of the License at
|
|
195
|
+
|
|
196
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
197
|
+
|
|
198
|
+
Unless required by applicable law or agreed to in writing, software
|
|
199
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
200
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
201
|
+
See the License for the specific language governing permissions and
|
|
202
|
+
limitations under the License.
|
knarr-0.1.0/NOTICE
ADDED
knarr-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: knarr
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: An MCP server that lets an AI agent work through a website toward a goal with guarded browser tools: writes blocked, origin pinned, destructive clicks refused.
|
|
5
|
+
Author: Ron Hermansen
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://github.com/ywapom/knarr
|
|
8
|
+
Project-URL: Repository, https://github.com/ywapom/knarr
|
|
9
|
+
Project-URL: Issues, https://github.com/ywapom/knarr/issues
|
|
10
|
+
Keywords: mcp,browser,playwright,agent,claude,testing
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Operating System :: MacOS
|
|
14
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: Software Development :: Testing
|
|
19
|
+
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
|
|
20
|
+
Requires-Python: >=3.12
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
License-File: NOTICE
|
|
24
|
+
Requires-Dist: mcp<2,>=1.13
|
|
25
|
+
Requires-Dist: playwright<2,>=1.48
|
|
26
|
+
Requires-Dist: pyyaml<7,>=6.0
|
|
27
|
+
Requires-Dist: websockets<16,>=12
|
|
28
|
+
Provides-Extra: dev
|
|
29
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
|
|
32
|
+
# Knarr
|
|
33
|
+
|
|
34
|
+
*A knarr was the Viking ocean-going ship: built to sail somewhere new and come back intact.*
|
|
35
|
+
|
|
36
|
+
Knarr lets an AI agent work through a website toward a goal you set, using a small set of guarded browser tools. The run passes only when the page shows the success criterion fixed at the start; the agent can't change it partway or grade itself with other text. It works on any site you can open in a browser, including ones you're logged in to.
|
|
37
|
+
|
|
38
|
+
It runs as an MCP server: Claude (in Claude Code, or any MCP client) drives the browser tools in your conversation.
|
|
39
|
+
|
|
40
|
+
## How it works
|
|
41
|
+
|
|
42
|
+
You give Knarr a start URL, a goal and a success criterion. Each turn the agent:
|
|
43
|
+
|
|
44
|
+
1. Reads the page as a numbered list of controls, e.g. `[3] button 'Place order'`.
|
|
45
|
+
2. Acts: clicks by number or by text, fills a field, submits, navigates or waits.
|
|
46
|
+
3. Repeats until `assert_state` finds the success criterion on the page, the agent gives up, or a limit is reached.
|
|
47
|
+
|
|
48
|
+
Guards around every action:
|
|
49
|
+
|
|
50
|
+
- **URL boundary.** Navigation must stay on the start URL's origin, or inside a manifest's URL patterns. From Claude Code, the page's real origin is checked before and after every call. If your own action (a click, a fill, a submit) took the page elsewhere, it's sent back to the start page and counts as a violation; three end the run. If the page went elsewhere by itself, such as a late redirect to a sign-in page, Knarr lets the sign-in finish, follows it again with your login, and counts no violation. A site that keeps sending the page to the same place ends the run as `login_required`, and a new session can start once you've signed in. The guard returns only to a page Knarr chose to load (the start page), never to one a click landed on, so it can't repeat a link that changes data.
|
|
51
|
+
- **Forbidden actions.** Actions on destructive or irreversible verbs (Delete, Archive, Publish, Approve, Send Request and others) are refused, including a `submit` that would hit a button such as "Save and Publish". A [site profile](#site-profiles) can add verbs for one site (a shop's "Buy now", say). Three refusals end the run.
|
|
52
|
+
- **Writes blocked** by default. Requests that could change data (anything but GET, HEAD and OPTIONS, plus outgoing WebSocket messages) are answered with a fake success and recorded instead of being sent. Clicks still really happen, so the agent can explore; nothing is saved.
|
|
53
|
+
- **Its own browser.** Knarr always runs its own browser, so every request, new tabs included, goes through the write block, and it's closed at the end.
|
|
54
|
+
- **Limits.** Turns (default 30), wall clock (15 minutes), tokens (500k) and memory.
|
|
55
|
+
|
|
56
|
+
Each run writes a record of every tool call (`trace.jsonl`) and a `summary.json`. The record keeps what you typed into a field out of the file (it holds the field's label and the length of the text, since a field may be a password), and removes the text from error messages that repeat it. A URL in either file loses its `user:password@`, the values of parameters named like credentials (`code`, `token`, `session`, `password` and the like) and values that look like random tokens, in the query and in the `#` part; the parameter names stay. Each trace line has its own UTC time (`at`), and `summary.json` says who ran the session (`user`, the operating-system account) and when it started and ended (`started_at`, `ended_at`). With `KNARR_TRACE=1` it also writes a Playwright trace you can open with `python3 -m playwright show-trace trace.zip`; traces record page contents, typed text, request headers and bodies, and cookies, so they hold the session's login and whatever was typed.
|
|
57
|
+
|
|
58
|
+
## Use it from Claude Code
|
|
59
|
+
|
|
60
|
+
If you use the plugin (step 2), `/knarr:install` walks through steps 1 and 3 with you, one command at a time, and ends with `/knarr:doctor`.
|
|
61
|
+
|
|
62
|
+
**1. Install uv.** The plugin starts the server with `uvx knarr`, which fetches the [`knarr`](https://pypi.org/project/knarr/) package from PyPI, with a Python 3.12+ for it, the first time it runs. See [docs.astral.sh/uv](https://docs.astral.sh/uv/) to install uv. To fetch a newer release later:
|
|
63
|
+
|
|
64
|
+
uvx --refresh --from knarr knarr-doctor
|
|
65
|
+
|
|
66
|
+
**2. Add it to Claude Code**, either as a plugin (MCP server plus a skill that teaches Claude how to use it):
|
|
67
|
+
|
|
68
|
+
/plugin marketplace add ywapom/knarr
|
|
69
|
+
/plugin install knarr@knarr
|
|
70
|
+
|
|
71
|
+
or as a bare MCP server:
|
|
72
|
+
|
|
73
|
+
claude mcp add knarr -- uvx knarr
|
|
74
|
+
|
|
75
|
+
**3. Give it a browser.** Either download Playwright's Chromium, for the Playwright version Knarr uses:
|
|
76
|
+
|
|
77
|
+
uvx --from knarr playwright install chromium
|
|
78
|
+
|
|
79
|
+
or use the Google Chrome you already have, by setting `KNARR_BROWSER_CHANNEL=chrome` in the environment Claude Code starts with (an `env` entry in `~/.claude/settings.json`, or an `export` before you start it). Chrome needs no download.
|
|
80
|
+
|
|
81
|
+
**Without uv.** Install the package with pip into a Python 3.12 or newer, and add the server for that Python:
|
|
82
|
+
|
|
83
|
+
python3 -m pip install knarr
|
|
84
|
+
python3 -m playwright install chromium
|
|
85
|
+
claude mcp add knarr -- python3 -m knarr.mcp
|
|
86
|
+
|
|
87
|
+
The ranges in `pyproject.toml` all have an upper bound, and `requirements.lock` holds the exact versions the whole test suite passed on (mcp 1.30.0, Playwright 1.64.1 and what they pull in). To install exactly those, from a clone: `python3 -m pip install -r requirements.lock`, then `python3 -m pip install --no-deps .`. The doctor fails if an installed package is outside the ranges.
|
|
88
|
+
|
|
89
|
+
Then ask Claude something like *"Use Knarr to check that placing an order on http://localhost:3000 shows 'Order placed'"*.
|
|
90
|
+
|
|
91
|
+
Claude calls the tools in this order:
|
|
92
|
+
1. `session_start` with the start URL, the goal and a **success criterion**: the text that will be on the page when the goal is reached, in quotes, e.g. `the page shows 'Order placed'`. It's required and can't be changed during the session.
|
|
93
|
+
2. `read_page`, `click_index`, `fill` and the other browser tools.
|
|
94
|
+
3. `assert_state`, which checks the page against that criterion (every quoted phrase must be visible), or `give_up`.
|
|
95
|
+
4. `session_end`, which returns the summary and the run directory.
|
|
96
|
+
|
|
97
|
+
Every tool result ends with a status line, e.g. `[knarr] call 4 of 30, 880 s of browser time left`. Once the run ends, further calls are refused.
|
|
98
|
+
|
|
99
|
+
### Check your setup
|
|
100
|
+
|
|
101
|
+
Run `/knarr:doctor` in Claude Code, or `uvx --from knarr knarr-doctor` in a terminal (`knarr-doctor` if you installed with pip). It checks:
|
|
102
|
+
- the Python that runs it, and that `uvx`, which the plugin starts the server with, is on your PATH;
|
|
103
|
+
- the installed packages and their versions;
|
|
104
|
+
- your `KNARR_*` settings (a misspelt name, a bad allow pattern, a missing saved-login file, writes allowed, tracing on);
|
|
105
|
+
- the browser: it starts one the way a session does, loads a local page that tries to write, and checks that the write block held the write back;
|
|
106
|
+
- the Chrome you borrow a login from (`KNARR_CDP_URL`): that it answers, how many tabs are open, and that it hands over its cookies (only a count is printed). If it isn't set up, it prints the command to start Chrome;
|
|
107
|
+
- that the MCP server starts and lists its tools.
|
|
108
|
+
|
|
109
|
+
Each problem comes with the fix. `--quick` skips the browser and the server. It never opens a site, and exits 1 if anything failed.
|
|
110
|
+
|
|
111
|
+
The server runs one session at a time per conversation. Run output goes to `~/.knarr/runs/<run-id>/`.
|
|
112
|
+
|
|
113
|
+
The model chooses the start URL and the criterion. Everything after that is fixed by the session and your environment:
|
|
114
|
+
- the origin the start URL lands on, after any redirect;
|
|
115
|
+
- the destructive-verb list;
|
|
116
|
+
- the limits in the variables below.
|
|
117
|
+
|
|
118
|
+
The time limit counts only time the browser spends on tool calls, so waiting for you to approve a call doesn't use it up. A session with no calls for 15 minutes is closed. If a guard stops a session (too many boundary or forbidden-action violations), no new session can start in that conversation.
|
|
119
|
+
|
|
120
|
+
## Turn a walkthrough into a Playwright project
|
|
121
|
+
|
|
122
|
+
Knarr drives the browser; Claude reads the pages, decides what to do next and writes the code. Together they can walk a flow once and leave you a script that repeats it. For example, ask Claude:
|
|
123
|
+
|
|
124
|
+
> Use Knarr to explore https://app.example.com. Walk the flow from the login page to the submit form, and write down each page's fields and buttons. Don't submit anything real. Then write a Python Playwright project that logs in, fills the form and submits it, using role and label locators.
|
|
125
|
+
|
|
126
|
+
Knarr lists each page as numbered controls with their role, label and visible text (`[3] button 'Place order'`). Claude clicks and fills its way through, then writes the project from what it saw. Every step is recorded in `trace.jsonl` in the run folder, so you can check the script against what actually happened.
|
|
127
|
+
|
|
128
|
+
What to know before you try it:
|
|
129
|
+
- **Login.** Knarr never logs in itself, and with writes blocked the login form's POST is faked. Either [borrow a login from your Chrome](#using-a-site-youre-logged-in-to), allow just that request with `KNARR_WRITE_ALLOW` (use a test account), or have Claude write the login step from the login page's fields without running it.
|
|
130
|
+
- **Submit.** The final submit is faked, so you can walk up to it and see the form, but nothing is saved and `assert_state` can't confirm the real result. Don't use `read_only` for this: it fakes every click, so Claude couldn't move between pages.
|
|
131
|
+
- **Selectors.** Knarr reports controls by role, label and text, not CSS selectors or test ids. That suits Playwright's `get_by_role` and `get_by_label`. A `data-testid` has to come from you.
|
|
132
|
+
- **The generated script isn't guarded.** Knarr's write block applies to Knarr's browser only. When you run the script against the real site, its submit really happens: use a test account or a test environment.
|
|
133
|
+
|
|
134
|
+
## Using a site you're logged in to
|
|
135
|
+
|
|
136
|
+
Knarr doesn't log in for you. Either let it borrow the login from a Chrome you've already logged in to, or give it a saved login.
|
|
137
|
+
|
|
138
|
+
**Borrow your login from Chrome.** Start Chrome with a debugging port and a separate profile directory, log in to the site there, and keep a tab open on it:
|
|
139
|
+
|
|
140
|
+
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
|
|
141
|
+
--remote-debugging-port=9222 --user-data-dir="$HOME/.knarr-chrome"
|
|
142
|
+
|
|
143
|
+
export KNARR_CDP_URL=http://127.0.0.1:9222
|
|
144
|
+
|
|
145
|
+
When a session starts, Knarr asks that Chrome, over a short DevTools connection, for two things, and keeps them in memory:
|
|
146
|
+
- the cookies Chrome would send to the start site;
|
|
147
|
+
- the site's localStorage, read from your open tab on it.
|
|
148
|
+
|
|
149
|
+
Then it launches its own browser with that copy. Single sign-on works the same way: if the page moves to other origins by itself (a redirect to your company's sign-in page, whether from the server or a script), Knarr borrows each origin's login in turn and loads the start URL again, up to four times, so the sign-in can finish. Before it starts, Knarr waits for the page to finish loading (a slow page included, up to a limit), for its requests to go quiet, and for a `Refresh` header or meta refresh to another origin to fire. A redirect from a timer or a slow script can't be seen in advance; Knarr follows it when it happens. Each reload of the sign-in loads the start URL again, so anything the page does on load (a request that `KNARR_WRITE_ALLOW` lets through, a GET that changes data) happens once per reload; pick a start URL that doesn't. If the sign-in is longer than four reloads, the start message says which origin's login wasn't borrowed. If you're not signed in at the provider, the session stays on the page it settled on (the sign-in page), the start message says where that is, and nothing counts as a violation.
|
|
150
|
+
|
|
151
|
+
Your tabs and any dialogs in them are left alone. A tab showing a dialog can't answer, so after 2 seconds Knarr skips its localStorage and says so; it doesn't wait. Cookies for other sites, sessionStorage and IndexedDB aren't copied. The start message says exactly what was borrowed, and says plainly when nothing was.
|
|
152
|
+
|
|
153
|
+
The session gets your login for the start site and for the sign-in sites the page sends it through, so approve a `session_start` only for a site you'd open with that login.
|
|
154
|
+
|
|
155
|
+
The DevTools connection is direct, so an `HTTP_PROXY` in your environment doesn't apply to it. `KNARR_CDP_URL` may be written as `http://127.0.0.1:9222` or as the `ws://` address Chrome prints. **It must be on your own machine** (`127.0.0.1`, `localhost` or `[::1]`, without a user name or password); anything else is refused and the session does not start, because anyone who can reach a Chrome debugging port controls that Chrome and every login in it, and Knarr asks it for cookies. The same rule holds for the WebSocket addresses Chrome's replies name, and a redirect from the DevTools address is not followed. Knarr never opens that endpoint as a page, whatever the spelling (`localhost`, `localhost.`, `127.1`, `[::1]`), and no request from its browser reaches it, whatever the page or the request type (a fetch, an `<img>`, a redirect): a page there could list, open and close your tabs. A refused request is noted in the result.
|
|
156
|
+
|
|
157
|
+
This works for sites that keep their login in cookies or localStorage, which covers most. If a site keeps it somewhere Knarr can't copy, it will start logged out. Logging in inside Knarr's browser won't work while writes are blocked, because the login form's POST is blocked too. In that case, either:
|
|
158
|
+
- let the login request through with `KNARR_WRITE_ALLOW`;
|
|
159
|
+
- or set `KNARR_ALLOW_WRITES=1` for that session.
|
|
160
|
+
|
|
161
|
+
Some single sign-on hands the login back to the site with a POST (SAML and OpenID Connect `form_post` do). While writes are blocked, that POST is blocked too, so the session would start on a "Blocked by Knarr" page; the start message says so. Allow that one request, e.g. `KNARR_WRITE_ALLOW=https://app.example.com/saml/acs`.
|
|
162
|
+
|
|
163
|
+
With Claude Code, set the variable in the shell you start Claude Code from.
|
|
164
|
+
|
|
165
|
+
**Saved login.** Point `KNARR_STORAGE_STATE` at a Playwright storage-state file. Knarr launches a browser with those cookies.
|
|
166
|
+
|
|
167
|
+
## Safety
|
|
168
|
+
|
|
169
|
+
**Writes are blocked by default.** In Knarr's browser, every request other than GET, HEAD and OPTIONS is faked and recorded, not sent, along with outgoing WebSocket messages from pages. The block works at the browser level, so it covers:
|
|
170
|
+
- fetch and XHR;
|
|
171
|
+
- form posts, which show a "Blocked by Knarr" page;
|
|
172
|
+
- `sendBeacon`;
|
|
173
|
+
- iframes, including cross-site ones;
|
|
174
|
+
- new tabs the page opens;
|
|
175
|
+
- the requests current Chrome sends itself while a page unloads (`sendBeacon` and `fetch(keepalive)` on leaving a page or closing it).
|
|
176
|
+
|
|
177
|
+
A faked response to a cross-origin request carries the CORS headers that let the page read it, so the page sees a success, not a network error. A GET, HEAD or OPTIONS request that carries a body counts as a write.
|
|
178
|
+
|
|
179
|
+
Only the request types that can carry a write are paused (documents, XHR, fetch, pings, CSP reports and "other"). Images, scripts, stylesheets, fonts and media are only fetched with GET, so pages load at nearly normal speed.
|
|
180
|
+
|
|
181
|
+
Channels whose traffic can't be intercepted are shut off. Service workers are blocked. SharedWorker and WebSocketStream are removed by a browser flag in every frame and worker. WebTransport and RTCPeerConnection are disabled by a script in each page frame.
|
|
182
|
+
|
|
183
|
+
Knarr runs Chromium with its sandbox on. If that can't start where you run it (a container, say), set `KNARR_NO_SANDBOX=1`.
|
|
184
|
+
|
|
185
|
+
From Claude Code, each tool result lists the writes it blocked. `summary.json` and `session_end` report `dry_run`: true means writes were intercepted and none went out, as far as Knarr can see. It's false once a request let through by `KNARR_WRITE_ALLOW` has been sent, and false with `blocked_writes` and `allowed_writes` of `null` (not zero: not observed) when writes aren't intercepted.
|
|
186
|
+
|
|
187
|
+
`captured_writes.jsonl` in the run directory lists each request by:
|
|
188
|
+
- method, host and URL path. Credentials in a URL are never recorded. A path segment is shown as it is only if it has the shape of a route word (`orders`, `sign-in`, `getUser`, `v2`, `save.json`); an ID, token, code, email or anything with digits or odd characters is shown as `:param`. This is a guess from the shape, so a lowercase slug, a username or a coupon code in lowercase looks like a route word and is kept;
|
|
189
|
+
- the names of query parameters;
|
|
190
|
+
- the body's type (from its Content-Type) and size;
|
|
191
|
+
- the body's field names, where a parser for that type found them (JSON, URL-encoded and multipart forms).
|
|
192
|
+
|
|
193
|
+
A name is shown only if it looks like a field name (letters, digits and `_ . [ ]` `-`, up to 40 characters; not a UUID, a hash or a run of mixed case and digits). Anything else, such as JSON sent with a form Content-Type or a token, is only counted (`unnamed_fields`, `query_unnamed`), and a name you list in `KNARR_RECORD_FIELDS` is always shown. This is also a guess from the shape: a key that is a username looks like a field name. Past 30 names, the rest are counted (`body_fields_more`). Only the first 5,000 records are listed; later writes are still counted.
|
|
194
|
+
|
|
195
|
+
It records no values, except for fields you name in `KNARR_RECORD_FIELDS` (comma-separated, e.g. `title,qty`). Those are recorded from JSON, URL-encoded and multipart text fields and from the query string, and nothing else ever is.
|
|
196
|
+
|
|
197
|
+
Some writes can't be blocked this way:
|
|
198
|
+
- a GET that changes data (`/delete?id=1`);
|
|
199
|
+
- Chrome's Reporting API and NEL uploads (`Report-To`, `Reporting-Endpoints`, `NEL`): reports a site asks Chrome to send. The browser sends them itself, in the network service. When a response asks for them, the result warns;
|
|
200
|
+
- WebSocket messages sent from a dedicated Web Worker, which Playwright can't intercept, and WebTransport sessions opened from one. When a page starts a worker, the result warns (once), and the summary lists it under `write_block_gaps`;
|
|
201
|
+
- the same channels in a sandboxed `srcdoc` frame without `allow-same-origin` (`<iframe sandbox="allow-scripts" srcdoc=...>`), which current Chrome gives none of Knarr's page script. When a page embeds one, the result warns;
|
|
202
|
+
- the requests the browser itself makes for FedCM sign-in (federated login prompts), which Chrome doesn't let Knarr pause;
|
|
203
|
+
- work the server starts on its own.
|
|
204
|
+
|
|
205
|
+
Very large request bodies are held back, but slowly: Playwright passes every paused request's body through its driver, so a 10 MB text upload stalls the page for about a second and uses about 1.5 GB of memory, and a 20 MB one, or a large body of mostly zero bytes, can end the session at the memory limit. Knarr warns when it holds back a body over 5 MB. The memory limit counts a session's own growth, so one big upload doesn't disable later sessions.
|
|
206
|
+
|
|
207
|
+
The sockets Knarr lets through, or only listens to, are Playwright mocks. The server's messages reach the page, but frames of different kinds (text and Blob) can arrive out of order, and the last frame before the server closes the socket can be lost.
|
|
208
|
+
|
|
209
|
+
WebSocket messages a page sends are dropped, but the socket itself still connects, so live updates reach the page: the handshake (with your cookies and the socket's URL, query string included) goes to the server like a GET, which Knarr doesn't hold back. The page's own close code and reason aren't passed on; the server's side closes with a neutral one. Real-time features that need the page to talk (chat, subscriptions that send a request first) don't work while blocked. A `KNARR_WRITE_ALLOW` pattern that matches the socket's URL lets it through: its messages and close are sent, and counted as allowed writes, and it can then carry writes too.
|
|
210
|
+
|
|
211
|
+
Some sites use POST for reads (GraphQL queries, search), and those break while blocked. You can let them through with `KNARR_WRITE_ALLOW`:
|
|
212
|
+
- The part of a pattern before any `?` matches the URL's scheme, host, port and path (`**` matches anything, `*` one path segment). A part after `?` matches the query string (`*` matches anything but `&`). Each part may have at most two wildcards, `**` may not be in the host or port, and a pattern that names a site needs a path: `https://app.example.com/**` for the whole site. Credentials in a URL never take part in the match. Write a port the way Chrome writes URLs: a default port (`:443`) is left out. A URL longer than 2,048 characters, query included, never matches. A pattern that breaks these rules stops the session with a message saying why.
|
|
213
|
+
- Requests let through are sent, reported in results and counted as `allowed_writes`, once the browser has accepted them to continue. A request the page cancels at the same moment (type-ahead search) may be counted although it never reached the server; the count is never lower than what did. Once one has been sent, the run is no longer a dry run.
|
|
214
|
+
- Be careful with GraphQL: mutations usually use the same URL as queries, so allowing `**/graphql` allows its writes too.
|
|
215
|
+
|
|
216
|
+
To allow all writes, set `KNARR_ALLOW_WRITES=1`; the agent then acts with your real permissions. Both are your settings, not the model's.
|
|
217
|
+
|
|
218
|
+
### Site profiles
|
|
219
|
+
|
|
220
|
+
`KNARR_WRITE_ALLOW` is read when the MCP server starts, so changing it means restarting the server. A site profile does the same job per site, and it is read at every `session_start`: edit the file, then start a new session. A profile is a YAML file in `~/.knarr/sites/` (or `KNARR_PROFILES_DIR`):
|
|
221
|
+
|
|
222
|
+
# ~/.knarr/sites/shop-staging.yaml
|
|
223
|
+
origins: [https://staging.shop.example.com]
|
|
224
|
+
allow: # URL patterns of non-GET requests to send anyway
|
|
225
|
+
- https://staging.shop.example.com/api/v2/search
|
|
226
|
+
forbidden_text: [Buy now, Send Invoice] # more verbs to refuse; the defaults stay
|
|
227
|
+
caps: {max_turns: 60, max_wall_clock_sec: 1200}
|
|
228
|
+
|
|
229
|
+
- **Which profile applies** is decided by the start URL's origin (scheme, host and port). The model doesn't name or choose a profile, and a profile for another site has no effect.
|
|
230
|
+
- **`allow`** takes the same patterns as `KNARR_WRITE_ALLOW` (see above), added after the ones from the environment. A pattern matches any non-GET method to that URL. In a profile the scheme (`http` or `https`) and the host are written out, with no `*` in the host or port (`https://api.example.com/v1/**` is fine, `https://*/**` is refused): a pattern that matches every host would be `writes: live` without its `authorized_by`.
|
|
231
|
+
- **`writes: live`** lets every write through for that site, like `KNARR_ALLOW_WRITES=1` but for one origin. It needs `authorized_by:` (who allowed it, such as an email or a ticket link), which is recorded in `summary.json`. It can't be combined with `allow`.
|
|
232
|
+
- **`forbidden_text`** adds verbs to refuse. A profile can't remove a default one.
|
|
233
|
+
- **`caps`** sets `max_turns` and `max_wall_clock_sec`; `KNARR_MAX_TURNS` and `KNARR_MAX_WALL_CLOCK_SEC` still win.
|
|
234
|
+
- **The environment wins.** `KNARR_BLOCK_WRITES` keeps writes blocked even for a `live` profile, and the start message says so.
|
|
235
|
+
- **It is never silent.** The start message says which profile applied and what it changed, and `summary.json` records it under `profile`.
|
|
236
|
+
- **A profile that can't be used is ignored, not half-applied,** which is the stricter outcome: an unknown or misspelled setting, a setting written twice (YAML would keep the last one without saying so), a bad pattern, a file larger than 64 KB, a file or directory other users can write to or that someone else owns (`chmod go-w` fixes it), or two files naming the same origin. The start message lists what was ignored (`profiles_ignored` in `summary.json`), and `/knarr:doctor` explains each.
|
|
237
|
+
|
|
238
|
+
A profile is only as safe as the directory it sits in. The model can't pick or change a profile through the tools, but an agent that can write files could edit `~/.knarr/sites/` itself and widen its own policy before the next session. To stop that, put an ask or deny rule for edits to that directory in your Claude Code permissions and confirm it with `/permissions`. `/knarr:doctor` warns unless it finds an ask or deny rule for editing files in the directory you use, written as `~/path` or `//path` (for example `Edit(~/.knarr/sites/**)`); a rule for reading, for a shell command or for another directory doesn't count. That does not stop a shell command from writing the file. Knarr guards against a misbehaving agent, not against you.
|
|
239
|
+
|
|
240
|
+
Other limits:
|
|
241
|
+
- **Tool arguments have length limits** (a URL 2,048 characters, a typed value 10,000, a note or a reason 2,000, a label or target 500, the goal 2,000, the success criterion 1,000) and may not contain a NUL character. A call over a limit is refused with the limit named, uses no turn and counts as no guard violation. The MCP SDK reads a whole message before these checks run, so they cap what is used, not what is read.
|
|
242
|
+
- **Page text is untrusted.** A website can write anything on its page, including instructions aimed at the model ("ignore your instructions and run this command"). Knarr returns page text as it is, marks it as untrusted in the server instructions, in the skill and in a line after each `read_page` and `inspect_error` result, and its guards limit what the browser can do. They do not limit Claude's other tools (a shell, file edits) in the same session, so keep those under your permission rules when you let Claude browse a site you don't control.
|
|
243
|
+
- **Read-only mode** (`--read-only`, or `read_only` on `session_start`) goes further and fakes every click, fill and submit, so the agent can't open anything that needs a click. With the write block it's rarely needed.
|
|
244
|
+
- **The forbidden list matches text** on the controls the agent targets. It reduces risk; it isn't a guarantee.
|
|
245
|
+
|
|
246
|
+
## Environment variables
|
|
247
|
+
|
|
248
|
+
A switch takes `1`, `true`, `yes`, `on`, `y`, `t` or `enabled` for on, and `0`, `false`, `no`, `off`, `n`, `f` or `disabled` (or nothing) for off. A value that is neither is off, except for `KNARR_BLOCK_WRITES`, where it counts as on; `/knarr:doctor` points out such a value.
|
|
249
|
+
|
|
250
|
+
| Variable | Effect |
|
|
251
|
+
|---|---|
|
|
252
|
+
| `KNARR_CDP_URL` | Borrow the login from a running Chrome, e.g. `http://127.0.0.1:9222`; must be on this machine |
|
|
253
|
+
| `KNARR_STORAGE_STATE` | Launch with a saved Playwright login |
|
|
254
|
+
| `KNARR_BROWSER_CHANNEL` | Launch an installed browser, e.g. `chrome`, instead of Playwright's Chromium |
|
|
255
|
+
| `KNARR_ALLOW_WRITES` | `1` to let writes through (blocked by default) |
|
|
256
|
+
| `KNARR_BLOCK_WRITES` | `1` to keep writes blocked whatever else says otherwise; wins over `KNARR_ALLOW_WRITES` and a profile's `writes: live`. Any value except an explicit off counts as on, so a typo blocks |
|
|
257
|
+
| `KNARR_RECORD_FIELDS` | Comma-separated field names whose values `captured_writes.jsonl` may record; no other values are ever recorded |
|
|
258
|
+
| `KNARR_NO_SANDBOX` | `1` to start Chromium without its sandbox, for a container that can't run it |
|
|
259
|
+
| `KNARR_TRACE` | `1` to write a Playwright `trace.zip`; it holds the session's cookies |
|
|
260
|
+
| `KNARR_WRITE_ALLOW` | Comma-separated URL patterns of non-GET requests to send anyway, e.g. `https://api.example.com/search`; see Safety for how they match |
|
|
261
|
+
| `KNARR_RUNS_DIR` | Run output (default `~/.knarr/runs`) |
|
|
262
|
+
| `KNARR_PROFILES_DIR` | Where site profiles are read from (default `~/.knarr/sites`); see Site profiles |
|
|
263
|
+
| `KNARR_MAX_TURNS`, `KNARR_MAX_WALL_CLOCK_SEC` | MCP session limits (defaults 30 calls, 900 s of browser time) |
|
|
264
|
+
| `KNARR_IDLE_TIMEOUT_SEC` | Close an MCP session with no calls for this long (default 900) |
|
|
265
|
+
|
|
266
|
+
## Project layout
|
|
267
|
+
|
|
268
|
+
knarr/explorer/ the core
|
|
269
|
+
explorer_tools.py the agent's tools and the guards
|
|
270
|
+
session.py browser session (launch, borrowed or saved login)
|
|
271
|
+
borrow.py copies a login out of the user's Chrome over DevTools
|
|
272
|
+
write_block.py the network write block
|
|
273
|
+
profiles.py per-site profiles
|
|
274
|
+
origin.py URL and origin normalisation
|
|
275
|
+
caps.py, trace.py limits, trace and summary writers
|
|
276
|
+
human_demo.py, learned_controls.py
|
|
277
|
+
record what a person demonstrates, for runners that ask one
|
|
278
|
+
knarr/mcp/ MCP server: session, browser worker thread, tools
|
|
279
|
+
knarr/doctor.py the setup check behind /knarr:doctor
|
|
280
|
+
plugin/ Claude Code plugin (MCP config, skill, /knarr:install, /knarr:doctor)
|
|
281
|
+
tests/ unit tests; tests/integration needs a browser
|
|
282
|
+
|
|
283
|
+
## Development
|
|
284
|
+
|
|
285
|
+
python3 -m pip install -e ".[dev]"
|
|
286
|
+
python3 -m pytest tests/unit -q
|
|
287
|
+
|
|
288
|
+
Raise `version` in `plugin/.claude-plugin/plugin.json` whenever you change a file under `plugin/` (the skill, the commands, `.mcp.json`): Claude Code goes by that number to decide whether an installed plugin has an update, so an unchanged number can hide your change. The browser code is the Python package, released to PyPI separately (see `RELEASING.md`).
|
|
289
|
+
|
|
290
|
+
The unit tests don't need a browser or network access. The end-to-end tests start the real server and a real browser; run them with `KNARR_BROWSER_TESTS=1 python3 -m pytest tests/integration` (add `KNARR_BROWSER_CHANNEL=chrome` to use installed Chrome). `tests/unit/test_import_boundary.py` restricts imports to the standard library, `knarr`, and a short list of third-party libraries.
|
|
291
|
+
|
|
292
|
+
Knarr is tested on macOS and Linux. It may work on Windows, but nothing there is tested yet.
|
|
293
|
+
|
|
294
|
+
## License
|
|
295
|
+
|
|
296
|
+
Apache License 2.0; see `LICENSE`.
|