@@ -8,32 +8,30 @@ differ in exactly one way: only the CLI accepts filesystem paths.
88
99## Setup
1010
11- Installing osw provides the ` osw ` command; the ` osw[mcp] ` extra adds the
12- ` osw-mcp ` server:
11+ Install one of the two; the second includes the first:
1312
14- === "uv (recommended)"
13+ ``` bash
14+ uv tool install osw # the `osw` command
15+ uv tool install " osw[mcp]" # the same, plus the `osw-mcp` server
16+ ```
1517
16- ```bash
17- uv add osw
18- uv add "osw[mcp]"
19- ```
18+ <details markdown =" 1 " >
19+ <summary >Other ways to install</summary >
2020
21- === "pip"
21+ ``` bash
22+ pip install " osw[mcp]" # into the active environment
23+ uv add " osw[mcp]" # as a dependency of the current uv project
24+ uvx --from " osw[mcp]" osw-mcp # run the server without installing it
25+ ```
2226
23- ```bash
24- pip install osw
25- pip install "osw[mcp]"
26- ```
27+ ` uvx ` is what the registration examples further down use, so the server needs
28+ no install of its own.
29+
30+ </ details >
2731
2832` osw[mcp] ` is not part of ` osw[all] ` , see [ Design notes] ( #design-notes ) . The
2933other extras are listed in the
30- [ Get Started guide] ( get-started.md#optional-extras ) . The server also runs
31- without being installed at all, which is what the registration examples below
32- do:
33-
34- ``` bash
35- uvx --from " osw[mcp]" osw-mcp
36- ```
34+ [ Get Started guide] ( get-started.md#optional-extras ) .
3735
3836Both adapters need an instance and credentials. The quickest start is a
3937gitignored ` .env ` file in your project root:
@@ -209,13 +207,6 @@ instance:
209207 local provenance ledger. It deletes those without extra prompting, but refuses
210208 to delete anything it did not create unless the caller passes
211209 ` confirm_external_delete=true ` .
212- - ** Editable checkouts:** ` create_or_update_entity ` and ` export_entity_jsonld `
213- call ` fetch_schema ` , which regenerates ` src/osw/model/entity.py ` inside the
214- installed package. With a normal, non-editable install this writes into
215- site-packages and is harmless, but a server run from an editable source
216- checkout modifies that file in your working tree. The read tools
217- (` get_entity ` , ` get_slot ` , ` get_category_schema ` , ...) read raw page slots and
218- never trigger it.
219210
220211## Configuration
221212
@@ -329,3 +320,24 @@ Why the two adapters are shaped the way they are:
329320 ([#139](https://github.com/OpenSemanticLab/osw-python/issues/139)).
330321 Installing the server standalone, for example via `uvx`, avoids the question
331322 entirely.
323+
324+ # # Notes for developers
325+
326+ To try an unreleased branch against a real client, point `uvx` at the checkout
327+ instead of at PyPI. Everything else about the registration stays the same :
328+
329+ ` ` ` bash
330+ uvx --reinstall --from "/abs/path/to/osw-python[mcp]" osw-mcp
331+ ` ` `
332+
333+ ` --reinstall` is what picks up your latest edits, since `uvx` caches the wheel
334+ it builds. In a JSON `args` array, a Windows path needs forward slashes or
335+ doubled backslashes.
336+
337+ Prefer that over an editable install for the server. `create_or_update_entity`
338+ and `export_entity_jsonld` call `fetch_schema`, which regenerates
339+ `src/osw/model/entity.py` inside the installed package : ` uvx` builds a
340+ non-editable wheel, so the write lands in the uv cache, while under
341+ ` pip install -e` or `uv sync` it lands in your working tree. The read tools
342+ (`get_entity`, `get_slot`, `get_category_schema`, ...) read raw page slots and
343+ never trigger it.
0 commit comments