Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

22.1 KB
Raw Blame
import json
from pathlib import Path

import pytest

from fastmcp.cli.install import install_app
from fastmcp.cli.install.claude_desktop import install_claude_desktop
from fastmcp.cli.install.mcp_json import install_mcp_json
from fastmcp.cli.install.shared import validate_server_name
from fastmcp.cli.install.stdio import install_stdio


class TestInstallApp:
    """Test the install subapp."""

    def test_install_app_exists(self):
        """Test that the install app is properly configured."""
        # install_app.name is a tuple in cyclopts
        assert "install" in install_app.name
        assert "Install MCP servers" in install_app.help

    def test_install_commands_registered(self):
        """Test that all install commands are registered."""
        # Check that the app has the expected help text and structure
        # This is a simpler check that doesn't rely on internal methods
        assert hasattr(install_app, "help")
        assert "Install MCP servers" in install_app.help

        # We can test that the commands parse without errors
        try:
            install_app.parse_args(["claude-code", "--help"])
            install_app.parse_args(["claude-desktop", "--help"])
            install_app.parse_args(["cursor", "--help"])
            install_app.parse_args(["gemini-cli", "--help"])
            install_app.parse_args(["goose", "--help"])
            install_app.parse_args(["mcp-json", "--help"])
            install_app.parse_args(["stdio", "--help"])
        except SystemExit:
            # Help commands exit with 0, that's expected
            pass


class TestClaudeCodeInstall:
    """Test claude-code install command."""

    def test_claude_code_basic(self):
        """Test basic claude-code install command parsing."""
        # Parse command with correct parameter names
        command, bound, _ = install_app.parse_args(
            ["claude-code", "server.py", "--name", "test-server"]
        )

        # Verify parsing was successful
        assert command is not None
        assert bound.arguments["server_spec"] == "server.py"
        assert bound.arguments["server_name"] == "test-server"

    def test_claude_code_with_options(self):
        """Test claude-code install with various options."""
        command, bound, _ = install_app.parse_args(
            [
                "claude-code",
                "server.py",
                "--name",
                "test-server",
                "--with",
                "package1",
                "--with",
                "package2",
                "--env",
                "VAR1=value1",
            ]
        )

        assert bound.arguments["with_packages"] == ["package1", "package2"]
        assert bound.arguments["env_vars"] == ["VAR1=value1"]

    def test_claude_code_with_new_options(self):
        """Test claude-code install with new uv options."""
        from pathlib import Path

        command, bound, _ = install_app.parse_args(
            [
                "claude-code",
                "server.py",
                "--python",
                "3.11",
                "--project",
                "/workspace",
                "--with-requirements",
                "requirements.txt",
            ]
        )

        assert bound.arguments["python"] == "3.11"
        assert bound.arguments["project"] == Path("/workspace")
        assert bound.arguments["with_requirements"] == Path("requirements.txt")


class TestClaudeDesktopInstall:
    """Test claude-desktop install command."""

    def test_claude_desktop_basic(self):
        """Test basic claude-desktop install command parsing."""
        command, bound, _ = install_app.parse_args(
            ["claude-desktop", "server.py", "--name", "test-server"]
        )

        assert command is not None
        assert bound.arguments["server_spec"] == "server.py"
        assert bound.arguments["server_name"] == "test-server"

    def test_claude_desktop_with_env_vars(self):
        """Test claude-desktop install with environment variables."""
        command, bound, _ = install_app.parse_args(
            [
                "claude-desktop",
                "server.py",
                "--name",
                "test-server",
                "--env",
                "VAR1=value1",
                "--env",
                "VAR2=value2",
            ]
        )

        assert bound.arguments["env_vars"] == ["VAR1=value1", "VAR2=value2"]

    def test_claude_desktop_with_new_options(self):
        """Test claude-desktop install with new uv options."""
        from pathlib import Path

        command, bound, _ = install_app.parse_args(
            [
                "claude-desktop",
                "server.py",
                "--python",
                "3.10",
                "--project",
                "/my/project",
                "--with-requirements",
                "reqs.txt",
            ]
        )

        assert bound.arguments["python"] == "3.10"
        assert bound.arguments["project"] == Path("/my/project")
        assert bound.arguments["with_requirements"] == Path("reqs.txt")

    def test_claude_desktop_with_config_path(self):
        """Test claude-desktop install with custom config path."""
        command, bound, _ = install_app.parse_args(
            ["claude-desktop", "server.py", "--config-path", "/custom/path/Claude"]
        )

        assert bound.arguments["config_path"] == Path("/custom/path/Claude")

    def test_claude_desktop_without_config_path(self):
        """Test claude-desktop install without config path defaults to None."""
        command, bound, _ = install_app.parse_args(["claude-desktop", "server.py"])

        assert bound.arguments.get("config_path") is None


class TestClaudeDesktopConfigFile:
    """Claude Desktop only creates its config file once the user opens Edit Config."""

    @pytest.fixture
    def server_file(self, tmp_path: Path) -> Path:
        server_file = tmp_path / "server.py"
        server_file.write_text(
            "from fastmcp import FastMCP\n\nmcp = FastMCP('demo')\n", encoding="utf-8"
        )
        return server_file

    @pytest.fixture
    def config_dir(self, tmp_path: Path) -> Path:
        config_dir = tmp_path / "claude"
        config_dir.mkdir()
        return config_dir

    @pytest.mark.parametrize("existing", [None, "", "  \n\t\n"])
    def test_install_creates_missing_or_blank_config_file(
        self, server_file: Path, config_dir: Path, existing: str | None
    ):
        config_file = config_dir / "claude_desktop_config.json"
        if existing is not None:
            config_file.write_text(existing, encoding="utf-8")

        assert install_claude_desktop(
            server_file, "mcp", "demo", config_path=config_dir
        )

        saved = json.loads(config_file.read_text(encoding="utf-8"))
        assert list(saved["mcpServers"]) == ["demo"]
        assert saved["mcpServers"]["demo"]["args"][-1] == f"{server_file.resolve()}:mcp"

    def test_install_keeps_other_settings_in_existing_config_file(
        self, server_file: Path, config_dir: Path
    ):
        config_file = config_dir / "claude_desktop_config.json"
        config_file.write_text(
            json.dumps(
                {
                    "preferences": {"theme": "dark"},
                    "mcpServers": {"other": {"command": "npx", "args": ["other"]}},
                }
            ),
            encoding="utf-8",
        )

        assert install_claude_desktop(
            server_file, "mcp", "demo", config_path=config_dir
        )

        saved = json.loads(config_file.read_text(encoding="utf-8"))
        assert saved["preferences"] == {"theme": "dark"}
        assert saved["mcpServers"]["other"]["command"] == "npx"
        assert saved["mcpServers"]["demo"]["args"][-1] == f"{server_file.resolve()}:mcp"


class TestInstallConfigEncoding:
    """MCP config files are UTF-8 (RFC 8259), so installers must not decode them via the locale."""

    def test_claude_desktop_preserves_non_ascii_values_from_existing_config(
        self, tmp_path: Path
    ):
        """Re-installing a server must not rewrite its env values through the locale codec."""
        import json

        from fastmcp.cli.install.claude_desktop import install_claude_desktop

        server_file = tmp_path / "server.py"
        server_file.write_text(
            "from fastmcp import FastMCP\n\nmcp = FastMCP('demo')\n", encoding="utf-8"
        )
        config_dir = tmp_path / "claude"
        config_dir.mkdir()
        config = config_dir / "claude_desktop_config.json"
        api_key = "ΠŸΡ€ΠΈΠ²Π΅Ρ‚-ΠΊΠ»ΡŽΡ‡"
        config.write_text(
            json.dumps(
                {
                    "mcpServers": {
                        "demo": {
                            "command": "uvx",
                            "args": ["some-package"],
                            "env": {"API_KEY": api_key},
                        }
                    }
                },
                ensure_ascii=False,
                indent=2,
            ),
            encoding="utf-8",
        )

        assert install_claude_desktop(
            server_file, "mcp", "demo", config_path=config_dir
        )

        saved = json.loads(config.read_text(encoding="utf-8"))
        assert saved["mcpServers"]["demo"]["env"]["API_KEY"] == api_key

    async def test_process_common_args_reads_json_spec_as_utf8(self, tmp_path: Path):
        """A fastmcp.json spec with a non-ASCII path must survive the read."""
        import json

        from fastmcp.cli.install.shared import process_common_args

        server_file = tmp_path / "ζœεŠ‘ε™¨.py"
        server_file.write_text(
            "from fastmcp import FastMCP\n\nmcp = FastMCP('demo')\n", encoding="utf-8"
        )
        spec = tmp_path / "fastmcp.json"
        spec.write_text(
            json.dumps({"source": {"path": server_file.name}}, ensure_ascii=False),
            encoding="utf-8",
        )

        file, _, _, _, _ = await process_common_args(str(spec), None, [], [], None)
        assert file.name == "ζœεŠ‘ε™¨.py"


class TestCursorInstall:
    """Test cursor install command."""

    def test_cursor_basic(self):
        """Test basic cursor install command parsing."""
        command, bound, _ = install_app.parse_args(
            ["cursor", "server.py", "--name", "test-server"]
        )

        assert command is not None
        assert bound.arguments["server_spec"] == "server.py"
        assert bound.arguments["server_name"] == "test-server"

    def test_cursor_with_options(self):
        """Test cursor install with options."""
        command, bound, _ = install_app.parse_args(
            ["cursor", "server.py", "--name", "test-server"]
        )

        assert bound.arguments["server_spec"] == "server.py"
        assert bound.arguments["server_name"] == "test-server"


class TestGooseInstall:
    """Test goose install command."""

    def test_goose_basic(self):
        """Test basic goose install command parsing."""
        command, bound, _ = install_app.parse_args(
            ["goose", "server.py", "--name", "test-server"]
        )

        assert command is not None
        assert bound.arguments["server_spec"] == "server.py"
        assert bound.arguments["server_name"] == "test-server"

    def test_goose_with_options(self):
        """Test goose install with various options."""
        command, bound, _ = install_app.parse_args(
            [
                "goose",
                "server.py",
                "--name",
                "test-server",
                "--with",
                "package1",
                "--with",
                "package2",
                "--env",
                "VAR1=value1",
            ]
        )

        assert bound.arguments["with_packages"] == ["package1", "package2"]
        assert bound.arguments["env_vars"] == ["VAR1=value1"]

    def test_goose_with_python(self):
        """Test goose install with --python option."""
        command, bound, _ = install_app.parse_args(
            [
                "goose",
                "server.py",
                "--python",
                "3.11",
            ]
        )

        assert bound.arguments["python"] == "3.11"


class TestMcpJsonInstall:
    """Test mcp-json install command."""

    def test_mcp_json_basic(self):
        """Test basic mcp-json install command parsing."""
        command, bound, _ = install_app.parse_args(
            ["mcp-json", "server.py", "--name", "test-server"]
        )

        assert command is not None
        assert bound.arguments["server_spec"] == "server.py"
        assert bound.arguments["server_name"] == "test-server"

    def test_mcp_json_with_copy(self):
        """Test mcp-json install with copy to clipboard option."""
        command, bound, _ = install_app.parse_args(
            ["mcp-json", "server.py", "--name", "test-server", "--copy"]
        )

        assert bound.arguments["copy"] is True

    def test_install_mcp_json_stdout_is_valid_json(
        self, tmp_path: Path, capsys: pytest.CaptureFixture[str]
    ):
        """Long paths and bracketed values must reach stdout unchanged."""
        server_dir = tmp_path / "a-long-directory-name" / "another-long-directory-name"
        server_dir.mkdir(parents=True)
        server_file = server_dir / "server.py"
        server_file.write_text("# placeholder")

        result = install_mcp_json(
            file=server_file,
            server_object=None,
            name="test-server",
            env_vars={"PATTERN": "[red]value[/red]"},
        )

        assert result is True
        config = json.loads(capsys.readouterr().out)
        server_config = config["test-server"]
        assert server_config["args"][-1] == str(server_file.resolve())
        assert server_config["env"] == {"PATTERN": "[red]value[/red]"}


class TestStdioInstall:
    """Test stdio install command."""

    def test_stdio_basic(self):
        """Test basic stdio install command parsing."""
        command, bound, _ = install_app.parse_args(["stdio", "server.py"])

        assert command is not None
        assert bound.arguments["server_spec"] == "server.py"

    def test_stdio_with_copy(self):
        """Test stdio install with copy to clipboard option."""
        command, bound, _ = install_app.parse_args(["stdio", "server.py", "--copy"])

        assert bound.arguments["copy"] is True

    def test_stdio_with_packages(self):
        """Test stdio install with additional packages."""
        command, bound, _ = install_app.parse_args(
            ["stdio", "server.py", "--with", "requests", "--with", "httpx"]
        )

        assert bound.arguments["with_packages"] == ["requests", "httpx"]

    def test_install_stdio_generates_command(self, tmp_path: Path):
        """Test that install_stdio produces a shell command containing fastmcp run."""
        server_file = tmp_path / "server.py"
        server_file.write_text("# placeholder")

        # Capture stdout
        import io
        import sys

        captured = io.StringIO()
        old_stdout = sys.stdout
        sys.stdout = captured
        try:
            result = install_stdio(file=server_file, server_object=None)
        finally:
            sys.stdout = old_stdout

        assert result is True
        output = captured.getvalue()
        assert "fastmcp" in output
        assert "run" in output
        assert str(server_file.resolve()) in output

    def test_install_stdio_with_object(self, tmp_path: Path):
        """Test that install_stdio includes the :object suffix."""
        server_file = tmp_path / "server.py"
        server_file.write_text("# placeholder")

        import io
        import sys

        captured = io.StringIO()
        old_stdout = sys.stdout
        sys.stdout = captured
        try:
            result = install_stdio(file=server_file, server_object="app")
        finally:
            sys.stdout = old_stdout

        assert result is True
        output = captured.getvalue()
        assert f"{server_file.resolve()}:app" in output


class TestGeminiCliInstall:
    """Test gemini-cli install command."""

    def test_gemini_cli_basic(self):
        """Test basic gemini-cli install command parsing."""
        # Parse command with correct parameter names
        command, bound, _ = install_app.parse_args(
            ["gemini-cli", "server.py", "--name", "test-server"]
        )

        # Verify parsing was successful
        assert command is not None
        assert bound.arguments["server_spec"] == "server.py"
        assert bound.arguments["server_name"] == "test-server"

    def test_gemini_cli_with_options(self):
        """Test gemini-cli install with various options."""
        command, bound, _ = install_app.parse_args(
            [
                "gemini-cli",
                "server.py",
                "--name",
                "test-server",
                "--with",
                "package1",
                "--with",
                "package2",
                "--env",
                "VAR1=value1",
            ]
        )

        assert bound.arguments["with_packages"] == ["package1", "package2"]
        assert bound.arguments["env_vars"] == ["VAR1=value1"]

    def test_gemini_cli_with_new_options(self):
        """Test gemini-cli install with new uv options."""
        from pathlib import Path

        command, bound, _ = install_app.parse_args(
            [
                "gemini-cli",
                "server.py",
                "--python",
                "3.11",
                "--project",
                "/workspace",
                "--with-requirements",
                "requirements.txt",
            ]
        )

        assert bound.arguments["python"] == "3.11"
        assert bound.arguments["project"] == Path("/workspace")
        assert bound.arguments["with_requirements"] == Path("requirements.txt")


class TestInstallCommandParsing:
    """Test command parsing and error handling."""

    def test_install_minimal_args(self):
        """Test install commands with minimal required arguments."""
        # Each command should work with just a server spec
        commands_to_test = [
            ["claude-code", "server.py"],
            ["claude-desktop", "server.py"],
            ["cursor", "server.py"],
            ["gemini-cli", "server.py"],
            ["goose", "server.py"],
            ["stdio", "server.py"],
        ]

        for cmd_args in commands_to_test:
            command, bound, _ = install_app.parse_args(cmd_args)
            assert command is not None
            assert bound.arguments["server_spec"] == "server.py"

    def test_mcp_json_minimal(self):
        """Test that mcp-json works with minimal arguments."""
        # Should work with just server spec
        command, bound, _ = install_app.parse_args(["mcp-json", "server.py"])
        assert command is not None
        assert bound.arguments["server_spec"] == "server.py"

    def test_stdio_minimal(self):
        """Test that stdio works with minimal arguments."""
        command, bound, _ = install_app.parse_args(["stdio", "server.py"])
        assert command is not None
        assert bound.arguments["server_spec"] == "server.py"

    def test_python_option(self):
        """Test --python option for all install commands."""
        commands_to_test = [
            ["claude-code", "server.py", "--python", "3.11"],
            ["claude-desktop", "server.py", "--python", "3.11"],
            ["cursor", "server.py", "--python", "3.11"],
            ["gemini-cli", "server.py", "--python", "3.11"],
            ["goose", "server.py", "--python", "3.11"],
            ["mcp-json", "server.py", "--python", "3.11"],
            ["stdio", "server.py", "--python", "3.11"],
        ]

        for cmd_args in commands_to_test:
            command, bound, _ = install_app.parse_args(cmd_args)
            assert command is not None
            assert bound.arguments["python"] == "3.11"

    def test_with_requirements_option(self):
        """Test --with-requirements option for all install commands."""
        commands_to_test = [
            ["claude-code", "server.py", "--with-requirements", "requirements.txt"],
            ["claude-desktop", "server.py", "--with-requirements", "requirements.txt"],
            ["cursor", "server.py", "--with-requirements", "requirements.txt"],
            ["gemini-cli", "server.py", "--with-requirements", "requirements.txt"],
            ["mcp-json", "server.py", "--with-requirements", "requirements.txt"],
            ["stdio", "server.py", "--with-requirements", "requirements.txt"],
        ]

        for cmd_args in commands_to_test:
            command, bound, _ = install_app.parse_args(cmd_args)
            assert command is not None
            assert str(bound.arguments["with_requirements"]) == "requirements.txt"

    def test_project_option(self):
        """Test --project option for all install commands."""
        commands_to_test = [
            ["claude-code", "server.py", "--project", "/path/to/project"],
            ["claude-desktop", "server.py", "--project", "/path/to/project"],
            ["cursor", "server.py", "--project", "/path/to/project"],
            ["gemini-cli", "server.py", "--project", "/path/to/project"],
            ["mcp-json", "server.py", "--project", "/path/to/project"],
            ["stdio", "server.py", "--project", "/path/to/project"],
        ]

        for cmd_args in commands_to_test:
            command, bound, _ = install_app.parse_args(cmd_args)
            assert command is not None
            assert str(bound.arguments["project"]) == str(Path("/path/to/project"))


class TestServerNameValidation:
    """Test server name validation rejects shell metacharacters."""

    @pytest.mark.parametrize(
        "name",
        [
            "my-server",
            "my_server",
            "My Server",
            "server.v2",
            "test123",
        ],
    )
    def test_valid_names(self, name: str):
        assert validate_server_name(name) == name

    @pytest.mark.parametrize(
        "name",
        [
            "test&calc",
            "test|whoami",
            "test;ls",
            "test$(id)",
            "test`id`",
            'test"quoted',
            "test>file",
            "test<file",
            "test\n",
            "test\r\n",
        ],
    )
    def test_rejects_shell_metacharacters(self, name: str):
        with pytest.raises(SystemExit):
            validate_server_name(name)