Skip to content

Commit 3a41c48

Browse files
committed
docs: simplify the CLI and MCP setup section
- lead with uv tool install, the mcp extra includes the base package - fold the pip, uv add and uvx variants into a details element - move the editable-install caveat to a Notes for developers section - document running the server from a local checkout via uvx --from
1 parent 3d91d92 commit 3a41c48

1 file changed

Lines changed: 38 additions & 26 deletions

File tree

‎docs/cli-and-mcp.md‎

Lines changed: 38 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -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
2933
other 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

3836
Both adapters need an instance and credentials. The quickest start is a
3937
gitignored `.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

Comments
 (0)