Problem
Users who configure a global exclude-newer in ~/.config/uv/uv.toml (a popular supply-chain hardening pattern, e.g. exclude-newer = "7 days") will silently miss new libtmux-mcp releases when running uvx libtmux-mcp or installing the server into Claude Code / Cursor / Codex / etc. Because libtmux-mcp is pre-alpha and shipping frequently, this is more than a theoretical concern — a fresh release can be invisible to anyone running with a 7-day or 30-day cooldown.
Today the docs say nothing about this. A repo-wide rg 'exclude-newer|UV_EXCLUDE_NEWER|cooldown|UV_NO_CONFIG' only matches pyproject.toml, which is developer-facing (the [tool.uv.exclude-newer-package] exemption block for gp-* workspace pins).
Proposed doc additions
1. docs/topics/troubleshooting.md — primary
Add a new symptom-based section that matches the page's existing Symptoms / Cause / Fix pattern. Suggested heading: "Old version of libtmux-mcp keeps running".
Content outline:
- How to detect:
uvx libtmux-mcp --version shows an older release than PyPI.
- Root cause: a global
exclude-newer cooldown in the user's uv config filters newly-uploaded distributions out of the resolver.
- Three escape hatches, in order of preference:
UV_NO_CONFIG=1 in the MCP host's env block — skips uv config discovery for this server only. Recommended because it's portable across MCP hosts and documents intent.
--no-config flag on the uvx invocation — same effect, requires editing args rather than env.
--exclude-newer 9999-01-01 (or UV_EXCLUDE_NEWER=9999-01-01) — overrides just the cutoff while leaving other uv config (indexes, cache dirs) intact. Useful if the user actually wants to keep most of their uv config.
- Caveat: the cooldown exists as a supply-chain defense — bypassing it for an MCP that auto-launches every Claude Code session reintroduces the very risk window the cooldown closes. Suggest
uv tool install libtmux-mcp once (cooldown applies at install time) and pointing the MCP at the installed binary as a middle ground.
2. docs/installation.md — secondary
Short cross-reference under the "Run without installing" tab pointing at the new troubleshooting section. One sentence; full detail belongs in troubleshooting.
3. docs/clients.md — optional
Could add UV_NO_CONFIG to the example env blocks for users who want it baked into their MCP host config from the start. Deferrable.
Acceptance
References
Problem
Users who configure a global
exclude-newerin~/.config/uv/uv.toml(a popular supply-chain hardening pattern, e.g.exclude-newer = "7 days") will silently miss newlibtmux-mcpreleases when runninguvx libtmux-mcpor installing the server into Claude Code / Cursor / Codex / etc. Because libtmux-mcp is pre-alpha and shipping frequently, this is more than a theoretical concern — a fresh release can be invisible to anyone running with a 7-day or 30-day cooldown.Today the docs say nothing about this. A repo-wide
rg 'exclude-newer|UV_EXCLUDE_NEWER|cooldown|UV_NO_CONFIG'only matchespyproject.toml, which is developer-facing (the[tool.uv.exclude-newer-package]exemption block forgp-*workspace pins).Proposed doc additions
1.
docs/topics/troubleshooting.md— primaryAdd a new symptom-based section that matches the page's existing Symptoms / Cause / Fix pattern. Suggested heading: "Old version of
libtmux-mcpkeeps running".Content outline:
uvx libtmux-mcp --versionshows an older release than PyPI.exclude-newercooldown in the user's uv config filters newly-uploaded distributions out of the resolver.UV_NO_CONFIG=1in the MCP host'senvblock — skips uv config discovery for this server only. Recommended because it's portable across MCP hosts and documents intent.--no-configflag on theuvxinvocation — same effect, requires editingargsrather thanenv.--exclude-newer 9999-01-01(orUV_EXCLUDE_NEWER=9999-01-01) — overrides just the cutoff while leaving other uv config (indexes, cache dirs) intact. Useful if the user actually wants to keep most of their uv config.uv tool install libtmux-mcponce (cooldown applies at install time) and pointing the MCP at the installed binary as a middle ground.2.
docs/installation.md— secondaryShort cross-reference under the "Run without installing" tab pointing at the new troubleshooting section. One sentence; full detail belongs in troubleshooting.
3.
docs/clients.md— optionalCould add
UV_NO_CONFIGto the exampleenvblocks for users who want it baked into their MCP host config from the start. Deferrable.Acceptance
just build-docs).CHANGESgets a one-line entry under the "Documentation" subsection of the unreleased0.1.xblock, consistent with the0.1.0a2doc-entry pattern.References
uv lock [--check]andexclude-newerastral-sh/uv#18775