Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
from __future__ import annotations
import json
import os
import sys
from pathlib import Path
_REPO_ROOT = Path(__file__).resolve().parents[2]
if str(_REPO_ROOT) not in sys.path:
sys.path.insert(0, str(_REPO_ROOT))
import pytest
from typer.testing import CliRunner
import unsloth_cli
import unsloth_cli.commands.mcp as mcp_mod
CANARY = "sk-unsloth-LEAKCANARY0123456789"
URL = "http://127.0.0.1:18799/mcp/"
POSIX = pytest.mark.skipif(os.name == "nt", reason = "POSIX file modes")
tomllib = pytest.importorskip("tomllib") if sys.version_info >= (3, 11) else None
@pytest.fixture
def home(tmp_path, monkeypatch):
for var, sub in (("HOME", "home"), ("CLAUDE_CONFIG_DIR", "claude"), ("CODEX_HOME", "codex")):
(tmp_path / sub).mkdir()
monkeypatch.setenv(var, str(tmp_path / sub))
monkeypatch.delenv("UNSLOTH_STUDIO_URL", raising = False)
monkeypatch.delenv("WSL_DISTRO_NAME", raising = False)
monkeypatch.setenv("UNSLOTH_API_KEY", CANARY)
monkeypatch.setattr(mcp_mod, "find_studio_server", lambda *a, **k: None)
monkeypatch.setattr(mcp_mod, "_which_with_install_dirs", lambda name: None)
return tmp_path
@pytest.fixture
def fake_claude(home, monkeypatch):
"""A `claude` binary that records argv and edits .claude.json the way the real one does."""
calls = []
path = home / "claude" / ".claude.json"
def run(argv, **kwargs):
calls.append(list(argv))
data = json.loads(path.read_text()) if path.exists() else {}
servers = data.setdefault("mcpServers", {})
if argv[2] == "remove":
servers.pop(argv[-1], None)
else:
name, url, header = argv[7], argv[8], argv[10]
key, value = header.split(": ", 1)
servers[name] = {"type": "http", "url": url, "headers": {key: value}}
path.write_text(json.dumps(data))
return mcp_mod.subprocess.CompletedProcess(argv, 0, "", "")
monkeypatch.setattr(mcp_mod, "_which_with_install_dirs", lambda name: "/opt/bin/claude")
monkeypatch.setattr(mcp_mod.subprocess, "run", run)
return calls
def _add(*args):
return CliRunner().invoke(unsloth_cli.app, ["mcp", "add", *args])
def _mode(path):
return path.stat().st_mode & 0o777
# Pure renderers
@pytest.mark.parametrize(
"base",
["http://h:1", "http://h:1/", "http://h:1/mcp", "http://h:1/mcp/", " http://h:1// "],
)
def test_mcp_url_normalises_to_trailing_slash(base):
assert mcp_mod.mcp_url(base) == "http://h:1/mcp/"
def test_entries_reference_the_env_var_only():
assert mcp_mod.claude_entry(URL, "MY_KEY") == {
"type": "http",
"url": URL,
"headers": {"Authorization": "Bearer ${MY_KEY}"},
}
merged = mcp_mod.cursor_merge({"mcpServers": {"o": {}}, "k": 1}, "s", URL, "V")
assert merged["k"] == 1 and merged["mcpServers"]["o"] == {}
assert merged["mcpServers"]["s"] == {
"url": URL,
"headers": {"Authorization": "Bearer ${env:V}"},
}
snippet = mcp_mod.generic_snippet("s", URL, "V")["mcpServers"]["s"]
assert snippet["headers"] == {"Authorization": "Bearer ${V}"}
EXPECTED = {"url": URL, "bearer_token_env_var": "V", "tool_timeout_sec": 300}
EXISTING = (
'model = "o3"\n\n'
"[mcp_servers.other]\n"
'command = "x"\n\n'
"[mcp_servers.unsloth-studio]\n"
'url = "http://old/mcp/"\n\n'
"[mcp_servers.unsloth-studio.env]\n"
'A = "1"\n\n'
'[profiles."p"]\n'
"x = 1\n"
)
def test_codex_merge_replaces_in_place_and_drops_subtables():
new = mcp_mod.codex_merge(EXISTING, "unsloth-studio", URL, "UNSLOTH_API_KEY", 300)
assert new == (
'model = "o3"\n\n'
"[mcp_servers.other]\n"
'command = "x"\n\n'
"[mcp_servers.unsloth-studio]\n"
f'url = "{URL}"\n'
'bearer_token_env_var = "UNSLOTH_API_KEY"\n'
"tool_timeout_sec = 300\n\n"
'[profiles."p"]\n'
"x = 1\n"
)
assert mcp_mod.codex_merge(new, "unsloth-studio", URL, "UNSLOTH_API_KEY", 300) == new
@pytest.mark.parametrize(
"header", ['[mcp_servers."unsloth-studio"]', "[ mcp_servers . 'unsloth-studio' ]"]
)
def test_codex_merge_matches_quoted_headers(header):
new = mcp_mod.codex_merge(f'{header}\nurl = "x"\n', "unsloth-studio", URL, "V", 300)
assert new.count("unsloth-studio") == 1
def test_codex_merge_appends_and_keeps_other_tables_byte_identical():
old = '# mine\n[mcp_servers.unsloth-studio-2]\nurl = "y"\n'
new = mcp_mod.codex_merge(old, "unsloth-studio", URL, "V", 300)
assert new.startswith(old + "\n[mcp_servers.unsloth-studio]\n")
assert mcp_mod.codex_merge("", "s", URL, "V", 300).startswith("[mcp_servers.s]\n")
@pytest.mark.skipif(tomllib is None, reason = "needs tomllib")
@pytest.mark.parametrize(
"old",
[
'mcp_servers = { unsloth-studio = { url = "x" } }\n',
'mcp_servers.unsloth-studio.url = "x"\n',
"[mcp_servers]\nunsloth-studio = { url = 'x' }\n",
"[broken\n",
],
)
def test_codex_check_refuses_other_forms_and_invalid_toml(old):
new = mcp_mod.codex_merge(old, "unsloth-studio", URL, "V", 300)
with pytest.raises(ValueError):
mcp_mod.codex_check(old, new, "unsloth-studio", EXPECTED)
def test_codex_check_without_a_toml_parser_refuses_an_inline_table(monkeypatch):
monkeypatch.setattr(mcp_mod, "_toml_loads", lambda: None)
for old, ok in (
('mcp_servers = { unsloth-studio = { url = "x" } }\n', False),
(EXISTING, True),
):
new = mcp_mod.codex_merge(old, "unsloth-studio", URL, "V", 300)
try:
mcp_mod.codex_check(old, new, "unsloth-studio", EXPECTED)
assert ok
except ValueError:
assert not ok
# The command
def test_mcp_is_registered_on_the_cli():
result = CliRunner().invoke(unsloth_cli.app, ["mcp", "add", "--help"])
assert result.exit_code == 0, result.output
for agent in ("claude-code", "codex", "cursor", "generic"):
assert agent in result.output
assert "--api-key" not in result.output
@POSIX
@pytest.mark.skipif(tomllib is None, reason = "needs tomllib")
def test_codex_writes_once_then_reports_unchanged(home):
path = home / "codex" / "config.toml"
result = _add("codex", "--url", "http://127.0.0.1:18799")
assert result.exit_code == 0, result.output
assert "Unsloth Studio MCP set up for codex" in result.output
assert _mode(path) == 0o600
assert tomllib.loads(path.read_text())["mcp_servers"]["unsloth-studio"] == {
"url": URL,
"bearer_token_env_var": "UNSLOTH_API_KEY",
"tool_timeout_sec": 300,
}
before = path.stat().st_mtime_ns
result = _add("codex", "--url", "http://127.0.0.1:18799")
assert result.exit_code == 0 and "unchanged" in result.output
assert path.stat().st_mtime_ns == before
@POSIX
@pytest.mark.parametrize("mode", [0o644, 0o400])
def test_existing_file_keeps_its_mode(home, mode):
path = home / "codex" / "config.toml"
path.write_text(EXISTING)
path.chmod(mode)
result = _add("codex", "--url", URL, "--timeout", "600")
assert result.exit_code == 0, result.output
assert _mode(path) == mode
assert "tool_timeout_sec = 600" in path.read_text()
assert "[mcp_servers.unsloth-studio.env]" not in path.read_text()
def test_dry_run_prints_a_diff_and_writes_nothing(home, fake_claude):
path = home / "codex" / "config.toml"
path.write_text(EXISTING)
stat = path.stat()
result = _add("codex", "--url", URL, "--dry-run")
assert result.exit_code == 0, result.output
assert "+bearer_token_env_var" in result.output and "Dry run" in result.output
assert path.read_text() == EXISTING and path.stat().st_mtime_ns == stat.st_mtime_ns
result = _add("cursor", "--url", URL, "--dry-run")
assert result.exit_code == 0 and not (home / "home" / ".cursor").exists()
result = _add("claude-code", "--url", URL, "--dry-run")
assert result.exit_code == 0, result.output
assert "Would run: /opt/bin/claude mcp add" in result.output
assert fake_claude == [] and not (home / "claude" / ".claude.json").exists()
def test_codex_refuses_an_inline_table_and_leaves_the_file(home):
path = home / "codex" / "config.toml"
old = 'mcp_servers = { unsloth-studio = { url = "x" } }\n'
path.write_text(old)
result = _add("codex", "--url", URL)
assert result.exit_code == 1
assert "[mcp_servers.unsloth-studio]" in result.output
assert path.read_text() == old
@POSIX
def test_symlinked_config_is_refused(home):
target = home / "real.json"
target.write_text("{}")
(home / "home" / ".cursor").mkdir()
(home / "home" / ".cursor" / "mcp.json").symlink_to(target)
result = _add("cursor", "--url", URL)
assert result.exit_code == 1 and "symlink" in result.output
assert target.read_text() == "{}"
@POSIX
def test_cursor_reads_jsonc_and_keeps_other_servers(home):
path = home / "home" / ".cursor" / "mcp.json"
path.parent.mkdir()
path.write_text('{\n // mine\n "mcpServers": {"other": {"url": "x"},},\n}\n')
result = _add("cursor", "--url", URL)
assert result.exit_code == 0, result.output
data = json.loads(path.read_text())
assert data["mcpServers"]["other"] == {"url": "x"}
assert data["mcpServers"]["unsloth-studio"] == {
"url": URL,
"headers": {"Authorization": "Bearer ${env:UNSLOTH_API_KEY}"},
}
assert "unchanged" in _add("cursor", "--url", URL).output
@pytest.mark.parametrize("text", ["[1, 2]", "{nope"])
def test_unparseable_json_is_refused(home, text):
path = home / "home" / ".cursor" / "mcp.json"
path.parent.mkdir()
path.write_text(text)
result = _add("cursor", "--url", URL)
assert result.exit_code == 1 and "Couldn't parse" in result.output
assert path.read_text() == text
@POSIX
def test_claude_without_the_binary_writes_the_json_directly(home):
path = home / "claude" / ".claude.json"
result = _add("claude-code", "--url", "http://127.0.0.1:18799")
assert result.exit_code == 0, result.output
assert "Claude Code was not found" in result.output
assert json.loads(path.read_text())["mcpServers"]["unsloth-studio"] == {
"type": "http",
"url": URL,
"headers": {"Authorization": "Bearer ${UNSLOTH_API_KEY}"},
}
assert _mode(path) == 0o600
assert "unchanged" in _add("claude-code", "--url", URL).output
def test_claude_shells_out_with_list_args(home, fake_claude):
result = _add("claude-code", "--url", URL, "--env-var", "MY_KEY")
assert result.exit_code == 0, result.output
argv = "/opt/bin/claude mcp add --transport http --scope user unsloth-studio".split()
assert fake_claude == [argv + [URL, "--header", "Authorization: Bearer ${MY_KEY}"]]
assert "Check the result" not in result.output
fake_claude.clear()
assert "unchanged" in _add("claude-code", "--url", URL, "--env-var", "MY_KEY").output
assert fake_claude == []
result = _add("claude-code", "--url", "http://127.0.0.1:9/", "--env-var", "MY_KEY")
assert result.exit_code == 0, result.output
assert [argv[2] for argv in fake_claude] == ["remove", "add"]
assert fake_claude[0][-3:] == ["--scope", "user", "unsloth-studio"]
def test_claude_failure_and_unparseable_config_exit_1(home, fake_claude, monkeypatch):
path = home / "claude" / ".claude.json"
path.write_text("{broken")
assert _add("claude-code", "--url", URL).exit_code == 1
assert fake_claude == [] and path.read_text() == "{broken"
path.unlink()
failed = lambda argv, **k: mcp_mod.subprocess.CompletedProcess(argv, 1, "", "boom")
monkeypatch.setattr(mcp_mod.subprocess, "run", failed)
result = _add("claude-code", "--url", URL)
assert result.exit_code == 1 and "boom" in result.output
def test_generic_prints_or_merges(home):
result = _add("generic", "--url", URL)
assert result.exit_code == 0, result.output
assert '"Authorization": "Bearer ${UNSLOTH_API_KEY}"' in result.output
out = home / "agent.json"
out.write_text('{"mcpServers": {"a": {}}, "x": 1}')
assert _add("generic", "--url", URL, "--output", str(out)).exit_code == 0
data = json.loads(out.read_text())
assert data["x"] == 1 and set(data["mcpServers"]) == {"a", "unsloth-studio"}
def test_codex_merge_keeps_comments_about_the_next_table():
old = '[mcp_servers.unsloth-studio]\nurl = "old"\n\n# the work proxy\n[mcp_servers.work]\nurl = "w"\n'
new = mcp_mod.codex_merge(old, "unsloth-studio", URL, "K", 300)
assert "\n\n# the work proxy\n[mcp_servers.work]\n" in new and 'url = "old"' not in new
def test_dry_run_never_prints_a_key_already_in_a_config(home, fake_claude):
# Older hand-written entries may hold a literal key in any spelling; other servers hold their own.
literal = {
"url": "u",
"headers": {"Authorization": "bearer sk-OLDKEY1", "X-Api-Key": "OLDKEY2"},
}
other = {"command": "gh-mcp", "env": {"GITHUB_TOKEN": "ghp_OLDKEY3"}}
servers = {"mcpServers": {"unsloth-studio": literal, "github": other}}
cursor = home / "home" / ".cursor" / "mcp.json"
cursor.parent.mkdir()
cursor.write_text(json.dumps(servers, indent = 4))
(home / "claude" / ".claude.json").write_text(json.dumps(servers))
(home / "codex" / "config.toml").write_text(
'[mcp_servers.github]\nbearer_token = "ghp_OLDKEY3"\n\n'
'[mcp_servers.unsloth-studio]\nurl = "u"\nbearer_token = """sk-OLDKEY1"""\n'
'http_headers = { "X-Api-Key" = "OLDKEY2" }\n'
)
for agent in ("cursor", "claude-code", "codex"):
result = _add(agent, "--url", URL, "--dry-run")
assert result.exit_code == 0, result.output
assert "OLDKEY" not in result.output, (agent, result.output)
assert "its old values are not shown" in result.output, agent
assert "${UNSLOTH_API_KEY}" in result.output or "UNSLOTH_API_KEY" in result.output
assert fake_claude == []
def test_a_non_object_mcp_servers_is_left_alone(home):
path = home / "home" / ".cursor" / "mcp.json"
path.parent.mkdir()
path.write_text('{"mcpServers": ["mine"]}')
result = _add("cursor", "--url", URL)
assert result.exit_code == 1 and "not an object" in result.output
assert path.read_text() == '{"mcpServers": ["mine"]}'
def test_generic_output_must_be_json(home):
out = home / "agent.toml"
out.write_text("[x]\n")
result = _add("generic", "--url", URL, "--output", str(out))
assert result.exit_code == 1 and ".json" in result.output
assert out.read_text() == "[x]\n"
def test_a_failed_add_after_remove_says_the_entry_is_gone(home, fake_claude, monkeypatch):
(home / "claude" / ".claude.json").write_text(
json.dumps({"mcpServers": {"unsloth-studio": {"url": "old"}}})
)
fake = mcp_mod.subprocess.run
def run(argv, **kwargs):
if argv[2] == "add":
return mcp_mod.subprocess.CompletedProcess(argv, 1, "", "add broke")
return fake(argv, **kwargs)
monkeypatch.setattr(mcp_mod.subprocess, "run", run)
result = _add("claude-code", "--url", URL)
assert result.exit_code == 1 and "add broke" in result.output
assert "already removed" in result.output
BAD = ["--env-var=BAD-NAME", "--env-var=$(id)", "--name=a b", "--name=x]\n[y", "--url=file:///e"]
@pytest.mark.parametrize("arg", BAD)
def test_bad_input_is_refused(home, arg):
result = _add("codex", "--url", URL, arg)
assert result.exit_code == 1, result.output
assert not (home / "codex" / "config.toml").exists()
def test_timeout_below_the_wait_cap_is_rejected(home):
assert _add("codex", "--url", URL, "--timeout", "120").exit_code == 2
def test_url_falls_back_to_env_then_discovery_then_default(home, monkeypatch):
assert mcp_mod._resolve_base(None) == "http://127.0.0.1:8888"
monkeypatch.setattr(mcp_mod, "find_studio_server", lambda *a, **k: "http://127.0.0.1:9000")
assert mcp_mod._resolve_base(None) == "http://127.0.0.1:9000"
monkeypatch.setenv("UNSLOTH_STUDIO_URL", "http://box:1")
assert mcp_mod._resolve_base(None) == "http://box:1"
assert mcp_mod._resolve_base("http://x:2") == "http://x:2"
def test_the_key_never_leaks(home, fake_claude, monkeypatch):
assert "is not set" not in _add("generic", "--url", URL).output
outputs = []
for agent in ("claude-code", "codex", "cursor", "generic"):
for extra in (["--dry-run"], []):
result = _add(agent, "--url", URL, *extra)
assert result.exit_code == 0, result.output
outputs.append(result.output)
outputs.append(_add("generic", "--url", URL, "--output", str(home / "g.json")).output)
assert fake_claude, "the claude stub should have run"
assert all("LEAKCANARY" not in " ".join(argv) for argv in fake_claude)
assert all("LEAKCANARY" not in text for text in outputs)
for path in home.rglob("*"):
if path.is_file():
assert "LEAKCANARY" not in path.read_text(), path
monkeypatch.delenv("UNSLOTH_API_KEY")
assert "UNSLOTH_API_KEY is not set" in _add("cursor", "--url", URL).output
@pytest.mark.parametrize(
"old",
[
# A header inside a multi-line string: the splice would cut the string and the keys after it.
'model = "o3"\nnotes = """\n[mcp_servers.unsloth-studio]\nkeep me\n"""\nsandbox = "x"\n',
# A nested array line inside the table would be left behind as broken TOML.
'[mcp_servers.unsloth-studio]\nurl = "x"\nm = [\n [1, 2],\n]\n',
],
)
def test_codex_check_without_a_toml_parser_refuses_unsafe_splices(monkeypatch, old):
monkeypatch.setattr(mcp_mod, "_toml_loads", lambda: None)
new = mcp_mod.codex_merge(old, "unsloth-studio", URL, "V", 300)
assert new != old
with pytest.raises(ValueError):
mcp_mod.codex_check(old, new, "unsloth-studio", EXPECTED)