aisync is a local CLI for Multi-Agent Context Management, Coordination & Observability across AI coding tools. I maintain it, and it ships an MCP server (aisync mcp). While preparing it for the official MCP registry I found that uvx <package-name> failed for it, and the reason applies to any Python MCP server whose command name differs from its PyPI name. This post is what I ran and what I did not run.
The PyPI package is aisync-cli; the command it installs is aisync. With HOME pointed at a temp directory (so nothing from my real setup was reused), on 0.2.10:
uvx aisync-cli@0.2.10 --version
An executable named `aisync-cli` is not provided by package `aisync-cli`.
The following executables are available:
- aisync
Use `uvx --from aisync-cli aisync` instead.
Exit code 1. uvx <name> looks for an executable with the same name as the package. A registry entry that names aisync-cli as its PyPI identifier points at exactly that form.
The MCP SDK is an optional extra in this package (aisync-cli[mcp]). With the right executable but no extra:
uvx --from aisync-cli@0.2.10 aisync mcp
It exits with code 2 and prints error: the MCP server needs the official SDK: pip install 'aisync-cli[mcp]' (mcp>=2.3). With the extra (--from 'aisync-cli[mcp]@0.2.10') the server answers an initialize request and exits cleanly when stdin closes.
Two small changes in 0.2.11:
uvx aisync-cli finds an executable: in pyproject.toml, aisync-cli = "ai_sync.cli:main" next to aisync = ....--with "mcp>=2.3,<3", plus the positional argument mcp.
uvx aisync-cli@0.2.11 --version
uvx --with "mcp>=2.3,<3" aisync-cli@0.2.11 mcp
Both ran in a temp HOME against the version published on PyPI.
The registry's server.json for a PyPI package, as I wrote it:
{
"name": "io.github.MaxonT/aisync",
"version": "0.2.11",
"packages": [{
"registryType": "pypi",
"identifier": "aisync-cli",
"version": "0.2.11",
"runtimeHint": "uvx",
"runtimeArguments": [{"type": "named", "name": "--with", "value": "mcp>=2.3,<3"}],
"packageArguments": [{"type": "positional", "value": "mcp"}],
"transport": {"type": "stdio"}
}]
}
($schema, title, description and repository are left out here.) The registry checks ownership of a PyPI package by looking for mcp-name: io.github.MaxonT/aisync in the package README, which becomes the PyPI description. I put it in an HTML comment in README.md and read it back from the PyPI JSON after the release. mcp-publisher validate printed server.json is valid; it validates against the live registry, so it is a stronger check than the JSON schema alone.
runtimeHint, runtimeArguments and packageArguments. I read the schema descriptions and assumed the arguments go before the package name and the package arguments after it. The local runs above use that shape; no real client was involved.
Run uvx <your-pypi-name> --version in a clean directory. If the executable name differs, add a console script with the package name, and check whether your server needs an extra before uvx can start it.
pip install aisync-cli
This post and the test runs were written and tested by an AI agent (Claude Code) for the maintainer. The outputs above are copied from those runs.