Skip to content

fix: pin generated MCP uvx package spec (fix #186) #221

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
koriyoshi2041 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

fix: pin generated MCP uvx package spec (fix #186) #221

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e725f1c
fix installer mcp package pin
koriyoshi2041 Jul 8, 2026
99917e1
render pinned mcp package in templates
koriyoshi2041 Jul 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ semble search "deployment guide" ./my-project --content docs # or: config, all
semble find-related src/auth.py 42 ./my-project
```

`--content` accepts `code` (default), `docs`, `config`, or `all`. `path` defaults to the current directory when omitted; git URLs are accepted. If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.
`--content` accepts `code` (default), `docs`, `config`, or `all`. `path` defaults to the current directory when omitted; git URLs are accepted. If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]@0.4.2" semble` in its place.

@greptile-apps greptile-apps Bot Jul 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Manual Docs Pin Goes Stale

This public install command is tied to the current literal version, so a later release or checkout can still instruct users to install semble[mcp]@0.4.2. Users following the README would get an older MCP package than the Semble version whose docs they are reading unless the docs pin is generated or checked against semble.version.__version__.


<details>
<summary>Controlling which files are indexed</summary>
Expand Down
36 changes: 18 additions & 18 deletions docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ semble install --agent claude pi --type mcp subagent --yes
<summary>Claude Code</summary>

```bash
claude mcp add semble -s user -- uvx --from "semble[mcp]" semble
claude mcp add semble -s user -- uvx --from "semble[mcp]@0.4.2" semble
```

</details>
Expand All @@ -66,7 +66,7 @@ Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project):
"mcpServers": {
"semble": {
"command": "uvx",
"args": ["--from", "semble[mcp]", "semble"]
"args": ["--from", "semble[mcp]@0.4.2", "semble"]
}
}
}
Expand All @@ -82,7 +82,7 @@ Add to `~/.codex/config.toml`:
```toml
[mcp_servers.semble]
command = "uvx"
args = ["--from", "semble[mcp]", "semble"]
args = ["--from", "semble[mcp]@0.4.2", "semble"]
```

</details>
Expand All @@ -97,7 +97,7 @@ Add to `~/.config/opencode/opencode.jsonc`:
"mcp": {
"semble": {
"type": "local",
"command": ["uvx", "--from", "semble[mcp]", "semble"]
"command": ["uvx", "--from", "semble[mcp]@0.4.2", "semble"]
}
}
}
Expand All @@ -115,7 +115,7 @@ Add to `.vscode/mcp.json` in your project (or your user profile's `mcp.json`):
"servers": {
"semble": {
"command": "uvx",
"args": ["--from", "semble[mcp]", "semble"]
"args": ["--from", "semble[mcp]@0.4.2", "semble"]
}
}
}
Expand All @@ -133,7 +133,7 @@ Add to `~/.copilot/mcp-config.json`:
"mcpServers": {
"semble": {
"command": "uvx",
"args": ["--from", "semble[mcp]", "semble"]
"args": ["--from", "semble[mcp]@0.4.2", "semble"]
}
}
}
Expand All @@ -151,7 +151,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
"mcpServers": {
"semble": {
"command": "uvx",
"args": ["--from", "semble[mcp]", "semble"]
"args": ["--from", "semble[mcp]@0.4.2", "semble"]
}
}
}
Expand All @@ -169,7 +169,7 @@ Add to `~/.gemini/settings.json`:
"mcpServers": {
"semble": {
"command": "uvx",
"args": ["--from", "semble[mcp]", "semble"]
"args": ["--from", "semble[mcp]@0.4.2", "semble"]
}
}
}
Expand All @@ -187,7 +187,7 @@ Add to `~/.kiro/settings/mcp.json` (or `.kiro/settings/mcp.json` in your project
"mcpServers": {
"semble": {
"command": "uvx",
"args": ["--from", "semble[mcp]", "semble"]
"args": ["--from", "semble[mcp]@0.4.2", "semble"]
}
}
}
Expand All @@ -206,7 +206,7 @@ Add to `~/.config/zed/settings.json` (or `.zed/settings.json` in your project):
"semble": {
"source": "custom",
"command": "uvx",
"args": ["--from", "semble[mcp]", "semble"]
"args": ["--from", "semble[mcp]@0.4.2", "semble"]
}
}
}
Expand All @@ -224,7 +224,7 @@ Add to `~/.reasonix/config.json` (the backwards-compatible MCP config path read
"mcpServers": {
"semble": {
"command": "uvx",
"args": ["--from", "semble[mcp]", "semble"]
"args": ["--from", "semble[mcp]@0.4.2", "semble"]
}
}
}
Expand All @@ -248,7 +248,7 @@ Then add to `~/.pi/agent/mcp.json`:
"mcpServers": {
"semble": {
"command": "uvx",
"args": ["--from", "semble[mcp]", "semble"]
"args": ["--from", "semble[mcp]@0.4.2", "semble"]
}
}
}
Expand All @@ -266,7 +266,7 @@ Add to `~/.gemini/config/mcp_config.json`:
"mcpServers": {
"semble": {
"command": "uvx",
"args": ["--from", "semble[mcp]", "semble"]
"args": ["--from", "semble[mcp]@0.4.2", "semble"]
}
}
}
Expand All @@ -284,7 +284,7 @@ Add to `~/.commandcode/mcp.json`:
"mcpServers": {
"semble": {
"command": "uvx",
"args": ["--from", "semble[mcp]", "semble"]
"args": ["--from", "semble[mcp]@0.4.2", "semble"]
}
}
}
Expand All @@ -293,7 +293,7 @@ Add to `~/.commandcode/mcp.json`:
Or use the CLI:

```bash
cmd mcp add --scope user semble -- uvx --from "semble[mcp]" semble
cmd mcp add --scope user semble -- uvx --from "semble[mcp]@0.4.2" semble
```

</details>
Expand All @@ -309,7 +309,7 @@ Add to `~/.zcode/cli/config.json` under the nested `mcp.servers` key (or use Set
"servers": {
"semble": {
"command": "uvx",
"args": ["--from", "semble[mcp]", "semble"],
"args": ["--from", "semble[mcp]@0.4.2", "semble"],
"type": "stdio"
}
}
Expand All @@ -322,7 +322,7 @@ Add to `~/.zcode/cli/config.json` under the nested `mcp.servers` key (or use Set
By default the MCP server indexes only code files. To also index documentation, config, or everything, append `--content docs`, `--content config`, or `--content all` to the server command. For example, in Claude Code:

```bash
claude mcp add semble -s user -- uvx --from "semble[mcp]" semble --content all
claude mcp add semble -s user -- uvx --from "semble[mcp]@0.4.2" semble --content all
```

### Instructions (AGENTS.md / CLAUDE.md)
Expand Down Expand Up @@ -358,7 +358,7 @@ semble find-related src/auth.py 42 ./my-project

`path` defaults to the current directory when omitted; git URLs are accepted.

If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.
If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]@0.4.2" semble` in its place.

### Workflow

Expand Down
2 changes: 1 addition & 1 deletion src/semble/agents/antigravity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ semble find-related src/auth.py 42 ./my-project

`path` defaults to the current directory when omitted; git URLs are accepted.

If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.
If `semble` is not on `$PATH`, use `uvx --from "{{MCP_PACKAGE_SPEC}}" semble` in its place.

### Workflow

Expand Down
2 changes: 1 addition & 1 deletion src/semble/agents/claude.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ semble find-related src/auth.py 42 ./my-project

`path` defaults to the current directory when omitted; git URLs are accepted.

If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.
If `semble` is not on `$PATH`, use `uvx --from "{{MCP_PACKAGE_SPEC}}" semble` in its place.

### Workflow

Expand Down
2 changes: 1 addition & 1 deletion src/semble/agents/codex.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ semble find-related src/auth.py 42 ./my-project

`path` defaults to the current directory when omitted; git URLs are accepted.

If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.
If `semble` is not on `$PATH`, use `uvx --from "{{MCP_PACKAGE_SPEC}}" semble` in its place.

### Workflow

Expand Down
2 changes: 1 addition & 1 deletion src/semble/agents/commandcode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ semble find-related src/auth.py 42 ./my-project

`path` defaults to the current directory when omitted; git URLs are accepted.

If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.
If `semble` is not on `$PATH`, use `uvx --from "{{MCP_PACKAGE_SPEC}}" semble` in its place.

### Workflow

Expand Down
2 changes: 1 addition & 1 deletion src/semble/agents/copilot.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ semble find-related src/auth.py 42 ./my-project

`path` defaults to the current directory when omitted; git URLs are accepted.

If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.
If `semble` is not on `$PATH`, use `uvx --from "{{MCP_PACKAGE_SPEC}}" semble` in its place.

### Workflow

Expand Down
2 changes: 1 addition & 1 deletion src/semble/agents/cursor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ semble find-related src/auth.py 42 ./my-project

`path` defaults to the current directory when omitted; git URLs are accepted.

If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.
If `semble` is not on `$PATH`, use `uvx --from "{{MCP_PACKAGE_SPEC}}" semble` in its place.

### Workflow

Expand Down
2 changes: 1 addition & 1 deletion src/semble/agents/gemini.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ semble find-related src/auth.py 42 ./my-project

`path` defaults to the current directory when omitted; git URLs are accepted.

If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.
If `semble` is not on `$PATH`, use `uvx --from "{{MCP_PACKAGE_SPEC}}" semble` in its place.

### Workflow

Expand Down
2 changes: 1 addition & 1 deletion src/semble/agents/kiro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ semble find-related src/auth.py 42 ./my-project

`path` defaults to the current directory when omitted; git URLs are accepted.

If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.
If `semble` is not on `$PATH`, use `uvx --from "{{MCP_PACKAGE_SPEC}}" semble` in its place.

### Workflow

Expand Down
2 changes: 1 addition & 1 deletion src/semble/agents/opencode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ semble find-related src/auth.py 42 ./my-project

`path` defaults to the current directory when omitted; git URLs are accepted.

If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.
If `semble` is not on `$PATH`, use `uvx --from "{{MCP_PACKAGE_SPEC}}" semble` in its place.

### Workflow

Expand Down
2 changes: 1 addition & 1 deletion src/semble/agents/pi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ semble find-related src/auth.py 42 ./my-project

`path` defaults to the current directory when omitted; git URLs are accepted.

If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.
If `semble` is not on `$PATH`, use `uvx --from "{{MCP_PACKAGE_SPEC}}" semble` in its place.

### Workflow

Expand Down
2 changes: 1 addition & 1 deletion src/semble/agents/reasonix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ semble find-related src/auth.py 42 ./my-project

`path` defaults to the current directory when omitted; git URLs are accepted.

If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.
If `semble` is not on `$PATH`, use `uvx --from "{{MCP_PACKAGE_SPEC}}" semble` in its place.

### Workflow

Expand Down
2 changes: 1 addition & 1 deletion src/semble/agents/zcode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ semble find-related src/auth.py 42 ./my-project

`path` defaults to the current directory when omitted; git URLs are accepted.

If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.
If `semble` is not on `$PATH`, use `uvx --from "{{MCP_PACKAGE_SPEC}}" semble` in its place.

### Workflow

Expand Down
13 changes: 8 additions & 5 deletions src/semble/installer/agents.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@
from pathlib import Path
from typing import Literal

from semble.version import __version__

_HOME = Path.home()

Action = Literal["created", "updated", "unchanged", "not-found", "removed", "error", "skipped"]
Expand All @@ -24,28 +26,29 @@ class IntegrationType(str, Enum):

SEMBLE_START = "<!-- SEMBLE_START -->"
SEMBLE_END = "<!-- SEMBLE_END -->"
_MCP_PACKAGE_SPEC = f"semble[mcp]@{__version__}"

_STDIO_SERVER_CONFIG: dict[str, object] = {
"command": "uvx",
"args": ["--from", "semble[mcp]", "semble"],
"args": ["--from", _MCP_PACKAGE_SPEC, "semble"],
"type": "stdio",
}

_OPENCODE_SERVER_CONFIG: dict[str, object] = {
"command": ["uvx", "--from", "semble[mcp]", "semble"],
"command": ["uvx", "--from", _MCP_PACKAGE_SPEC, "semble"],
"type": "local", # opencode uses "local"/"remote", not "stdio"
"enabled": True,
}

_BARE_STDIO_SERVER_CONFIG: dict[str, object] = { # Windsurf: command/args only, no "type"
"command": "uvx",
"args": ["--from", "semble[mcp]", "semble"],
"args": ["--from", _MCP_PACKAGE_SPEC, "semble"],
}

_ZED_SERVER_CONFIG: dict[str, object] = { # Zed requires "source": "custom" for manual servers
"source": "custom",
"command": "uvx",
"args": ["--from", "semble[mcp]", "semble"],
"args": ["--from", _MCP_PACKAGE_SPEC, "semble"],
}

INSTRUCTIONS = f"""\
Expand All @@ -70,7 +73,7 @@ class IntegrationType(str, Enum):
semble search "save model to disk" ./my-project --top-k 10
```

The index is built on first run and cached automatically. If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble`.
The index is built on first run and cached automatically. If `semble` is not on `$PATH`, use `uvx --from "{_MCP_PACKAGE_SPEC}" semble`.

### Workflow

Expand Down
4 changes: 2 additions & 2 deletions src/semble/installer/config.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,13 @@
from tree_sitter import Node, Parser
from tree_sitter_language_pack import SupportedLanguage, download, get_parser

from semble.installer.agents import SEMBLE_END, SEMBLE_START, Action
from semble.installer.agents import _MCP_PACKAGE_SPEC, SEMBLE_END, SEMBLE_START, Action

JsonObjectResult = tuple[Node, bytes] | Literal["skipped", "error"]
_T = TypeVar("_T")

_CODEX_MCP_HEADER = "[mcp_servers.semble]"
_CODEX_MCP_BLOCK = '[mcp_servers.semble]\ncommand = "uvx"\nargs = ["--from", "semble[mcp]", "semble"]\n'
_CODEX_MCP_BLOCK = f'[mcp_servers.semble]\ncommand = "uvx"\nargs = ["--from", "{_MCP_PACKAGE_SPEC}", "semble"]\n'

_json5_parser_cache: Parser | None | bool = False # False = not yet attempted

Expand Down
4 changes: 3 additions & 1 deletion src/semble/installer/installer.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
import questionary

from semble.installer.agents import (
_MCP_PACKAGE_SPEC,
AGENTS,
INSTRUCTIONS,
AgentTarget,
Expand All @@ -27,6 +28,7 @@
)

_T = TypeVar("_T")
_MCP_PACKAGE_SPEC_PLACEHOLDER = "{{MCP_PACKAGE_SPEC}}"

_GREEN = "\033[32m"
_DIM = "\033[2m"
Expand Down Expand Up @@ -96,7 +98,7 @@ def _apply_subagent(agent: AgentTarget, mode: Mode) -> WriteResult | None:
dest.parent.mkdir(parents=True, exist_ok=True)
try:
src = files("semble").joinpath(f"agents/{agent.id}{dest.suffix}").read_text(encoding="utf-8")
dest.write_text(src, encoding="utf-8")
dest.write_text(src.replace(_MCP_PACKAGE_SPEC_PLACEHOLDER, _MCP_PACKAGE_SPEC), encoding="utf-8")
except Exception:
return WriteResult(dest, "error")
return WriteResult(dest, "updated" if existed else "created")
Expand Down
Loading