Skip to content

fix(mcp): include wikitext in the mcp extra, streamline tools docs - #203

Merged
LukasGold merged 4 commits into
mainfrom
docs/uv-tool-install
Sep 22, 2026
Merged

LukasGold merged 4 commits into
mainfrom
docs/uv-tool-install

Conversation

@LukasGold

@LukasGold LukasGold commented Sep 22, 2026

Copy link
Copy Markdown
Contributor

Changes

Packaging

  • pyproject.toml: the mcp extra now requires osw[wikitext], so mwparserfromhell is installed with every MCP install. uv.lock updated accordingly.

docs/tools/index.md

  • Setup now shows one install route, uv tool install "osw[mcp]", with a note on the tool bin directory, uv tool update-shell and quoting the brackets for zsh.
  • pip install, uv add and uvx moved into a collapsed "Other ways to install" block.
  • Editable install guidance removed from this page and moved to the developer notes in mcp.md.

docs/tools/mcp.md

  • New sentence after the intro: a registered server either runs uvx or an installed osw[mcp], with a link to the decision section.
  • "uvx or the installed command" renamed to "Which command to register for the MCP server" and rewritten as two bullets, one per option, each with its cost.
  • The installed-command option now shows the full claude mcp add ... -- osw-mcp entry and its JSON form.
  • "Notes for developers" documents the editable uv tool install (uv tool install --reinstall --editable ".[mcp]"), its four consequences, and when to prefer uvx instead.
  • Caveat added: uvx reuses an installed osw tool whenever that installation satisfies the specification, so an unpinned osw[mcp] runs the installed version.

Rationale

  • The wikitext warning from src/osw/wiki_tools.py appeared on the MCP server's stderr at import time and therefore in every client log. The extra now satisfies the dependency instead of silencing the message.
  • uv tool install "osw[mcp]" puts osw-mcp on PATH, so a client entry can be "command": "osw-mcp" with an empty args array. Changing the version for all servers is then one uv tool upgrade osw, instead of editing every entry that names --from.
  • The tools pages offered several install routes with no guidance on which to choose. There is now one visible path per page and a single place that explains the trade-off.

Verification

  • uv run --isolated --no-project --with "osw[mcp]==2.6.2" python -c "import osw.mcp.server" prints the wikitext warning. The same command against this checkout does not.
  • uv run --isolated --no-project --with "osw==2.6.2" osw-mcp fails with ModuleNotFoundError: No module named 'mcp' at osw/mcp/server.py:16, which is the behaviour described in index.md.
  • uvx -v confirms the reuse caveat: an unpinned osw[mcp] reports Found existing environment for tool osw, while osw[mcp]==2.6.1 installs a fresh environment.
  • uv run zensical build -s reports no issues. The anchor #which-command-to-register-for-the-mcp-server exists in the built HTML and the link from index.md resolves to it.

- register the installed `osw-mcp` command instead of `uvx --from`
- editable install from a checkout for CLI and MCP development
- extras combine, e.g. `osw[mcp,wikitext]`
- when `--reinstall` is needed, and the Windows Scripts lock
- keep the entity model regeneration warning and name the read-only exception
- osw.wiki_tools warns at import time without mwparserfromhell
- on stdio that warning reaches every MCP client's log
- index.md: one install path, no developer instructions
- mcp.md: name both registration options in the intro
- mcp.md: "Which command to register for the MCP server", two options
- mcp.md: the editable developer install now lives in Notes for developers
- drop `osw[mcp,wikitext]`, since `osw[mcp]` now implies it
- uvx runs the installed tool when it satisfies the specification

- an explicit version keeps a server independent of it
@github-actions

Copy link
Copy Markdown
Contributor

Release preview

Merging this PR would release v2.6.3 (current: v2.6.2).

Changelog preview (truncated)
## v2.6.3 (2026-09-22)

### Bug Fixes

- **mcp**: Include the wikitext extra in the mcp extra
  ([`adf50d2`](https://github.com/OpenSemanticLab/osw-python/commit/adf50d21405cbc396491929c6faa54b3de1caf8d))

### Documentation

- **mcp**: Note that uvx reuses an installed osw tool
  ([`c492583`](https://github.com/OpenSemanticLab/osw-python/commit/c492583db6a7a19647a828881b7fd45992697c96))

- **tools**: Document uv tool install for osw and osw-mcp
  ([`d691ef4`](https://github.com/OpenSemanticLab/osw-python/commit/d691ef428eff2735cb92f6ad0ea55363b6361c2a))

- **tools**: Streamline install and registration guidance
  ([`ed18174`](https://github.com/OpenSemanticLab/osw-python/commit/ed1817465d1e9518c9903742276ce5a2352e8066))

Preview via python-semantic-release and conventional commits.

@LukasGold LukasGold self-assigned this Sep 22, 2026
@LukasGold
LukasGold merged commit aafbe22 into main Sep 22, 2026
12 checks passed
@LukasGold
LukasGold deleted the docs/uv-tool-install branch September 22, 2026 14:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant