Skip to content

[docs] Document how to bypass uv exclude-newer cooldowns when running uvx libtmux-mcp #31

@tony

Description

@tony

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:
    1. 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.
    2. --no-config flag on the uvx invocation — same effect, requires editing args rather than env.
    3. --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

  • Both pages render cleanly in the Sphinx build (just build-docs).
  • The troubleshooting entry follows the existing Symptoms / Cause / Fix structure already used on the page.
  • CHANGES gets a one-line entry under the "Documentation" subsection of the unreleased 0.1.x block, consistent with the 0.1.0a2 doc-entry pattern.

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or requestgood first issueGood for newcomers

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions