solidworks-mcp-python 1.5.0__py3-none-any.whl

solidworks_mcp/setup/config_file.py

@@ -0,0 +1,230 @@
+"""Change one server entry in an MCP client's JSON config, and nothing else.
+
+Client config files often hold other servers' secrets (API keys, OAuth
+tokens). Everything here works on the parsed JSON: no function returns,
+prints or logs the file's text or any entry other than the one it was asked
+to change, and an error names only the file, line and column.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+class ConfigFileError(Exception):
+    """A client config file can't be read or safely changed."""
+
+
+@dataclass(frozen=True)
+class EntryChange:
+    """What happened to the server entry in one client's config.
+
+    Attributes:
+        location: Where the entry lives (a file path, or a description).
+        action: ``added``, ``updated``, ``removed`` or ``unchanged``.
+        backup: The copy made before writing, if a file was overwritten.
+        previous: For an ``updated`` entry, the ``command`` it ran before,
+            so the user can see which copy it pointed at. Only the command
+            is kept, never the rest of the entry.
+    """
+
+    location: str
+    action: str
+    backup: Path | None = None
+    previous: str | None = None
+
+
+def read_config(path: Path) -> dict[str, Any]:
+    """Parse a client config file.
+
+    Args:
+        path: The JSON config file.
+
+    Returns:
+        The parsed object; ``{}`` for a missing or empty file.
+
+    Raises:
+        ConfigFileError: The file can't be read, isn't valid JSON, or isn't a
+            JSON object. The message never quotes the file's content.
+    """
+    if not path.exists():
+        return {}
+    try:
+        # utf-8-sig accepts a byte-order mark, which some editors add.
+        text = path.read_text(encoding="utf-8-sig")
+    except (OSError, UnicodeDecodeError) as exc:
+        raise ConfigFileError(f"Can't read {path}: {type(exc).__name__}.") from None
+    if not text.strip():
+        return {}
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        # `from None`: the original exception carries the document text.
+        raise ConfigFileError(
+            f"{path} is not valid JSON (line {exc.lineno}, column {exc.colno}). "
+            "It was left untouched: fix it, or move it aside, and run solidworks-mcp setup again."
+        ) from None
+    if not isinstance(data, dict):
+        raise ConfigFileError(f"{path} does not hold a JSON object; left untouched.")
+    return data
+
+
+def server_entries(path: Path, section: str) -> dict[str, Any]:
+    """Read every server entry in a config, for inspection in code only.
+
+    Callers must not print the entries: they may hold other servers' secrets.
+
+    Args:
+        path: The JSON config file.
+        section: The object that holds the servers (``mcpServers``/``servers``).
+
+    Returns:
+        The entries by name; ``{}`` when the file or section is absent or the
+        section isn't an object.
+    """
+    servers = read_config(path).get(section)
+    return servers if isinstance(servers, dict) else {}
+
+
+def current_entry(path: Path, section: str, name: str) -> Any:
+    """Read one server entry.
+
+    Args:
+        path: The JSON config file.
+        section: The object that holds the servers (``mcpServers``/``servers``).
+        name: The server's key in that object.
+
+    Returns:
+        The entry, or ``None`` when the file, section or key is absent.
+    """
+    return server_entries(path, section).get(name)
+
+
+def set_entry(
+    path: Path,
+    section: str,
+    name: str,
+    entry: dict[str, Any] | None,
+    *,
+    dry_run: bool = False,
+) -> EntryChange:
+    """Set ``section.name`` to ``entry``, or delete it when ``entry`` is None.
+
+    Every other key in the file keeps its value and order. Before writing,
+    the file is backed up; it is then written atomically as UTF-8 without a
+    BOM, and read back to confirm it parses and holds the new entry.
+
+    Args:
+        path: The JSON config file; created, with its folder, if missing.
+        section: The object that holds the servers.
+        name: The server's key in that object.
+        entry: The new entry, or ``None`` to remove it.
+        dry_run: Work out the action but write nothing.
+
+    Returns:
+        What happened (or, with ``dry_run``, what would happen).
+
+    Raises:
+        ConfigFileError: The file can't be parsed, the section isn't an
+            object, or the written file doesn't hold the entry.
+    """
+    data = read_config(path)
+    servers = data.get(section, {})
+    if not isinstance(servers, dict):
+        raise ConfigFileError(
+            f'"{section}" in {path} is not an object; left untouched.'
+        )
+
+    action = _action(servers, name, entry)
+    previous = _command_of(servers.get(name)) if action == "updated" else None
+    if action == "unchanged" or dry_run:
+        return EntryChange(str(path), action, previous=previous)
+
+    if entry is None:
+        del servers[name]
+    else:
+        servers[name] = entry
+    data[section] = servers
+
+    backup = _backup(path)
+    _write_atomically(path, json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+    if current_entry(path, section, name) != entry:
+        raise ConfigFileError(
+            f"{path} did not hold the new entry after writing; "
+            f"restore it from {backup}."
+        )
+    return EntryChange(str(path), action, backup, previous)
+
+
+def _command_of(entry: Any) -> str | None:
+    """An entry's ``command``, if it is a string.
+
+    Args:
+        entry: A server entry.
+
+    Returns:
+        The command, or ``None``.
+    """
+    command = entry.get("command") if isinstance(entry, dict) else None
+    return command if isinstance(command, str) else None
+
+
+def _action(servers: dict[str, Any], name: str, entry: dict[str, Any] | None) -> str:
+    """Name the change that setting ``servers[name] = entry`` would make.
+
+    Args:
+        servers: The current server entries.
+        name: The server's key.
+        entry: The new entry, or ``None`` for a removal.
+
+    Returns:
+        ``added``, ``updated``, ``removed`` or ``unchanged``.
+    """
+    if entry is None:
+        return "removed" if name in servers else "unchanged"
+    if servers.get(name) == entry:
+        return "unchanged"
+    return "updated" if name in servers else "added"
+
+
+def _backup(path: Path) -> Path | None:
+    """Copy ``path`` byte for byte to a timestamped file beside it.
+
+    The timestamp means a second run never overwrites the first backup,
+    which holds the user's original file.
+
+    Args:
+        path: The file about to be overwritten.
+
+    Returns:
+        The backup's path, or ``None`` if there was no file to back up.
+    """
+    if not path.exists():
+        return None
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    backup = path.with_name(f"{path.name}.bak-{stamp}")
+    shutil.copy2(path, backup)
+    return backup
+
+
+def _write_atomically(path: Path, text: str) -> None:
+    """Replace ``path`` with ``text`` so a reader never sees half a file.
+
+    Args:
+        path: The file to write; its folder is created if missing.
+        text: The new content, written as UTF-8 without a BOM.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp = path.with_name(f"{path.name}.tmp")
+    try:
+        temp.write_text(text, encoding="utf-8")
+        # os.replace is atomic on one volume: the old file or the new, never neither.
+        os.replace(temp, path)
+    finally:
+        temp.unlink(missing_ok=True)

solidworks_mcp/setup/handshake.py

@@ -0,0 +1,202 @@
+"""Start the server the way a client will and confirm it lists its tools.
+
+This is the MCP stdio handshake a client performs: ``initialize``, the
+``initialized`` notification, then ``tools/list``. Setup runs it before
+writing any config, so a broken launcher is caught here rather than as a
+silent failure inside the client.
+"""
+
+from __future__ import annotations
+
+import json
+import queue
+import subprocess
+import tempfile
+import threading
+import time
+from dataclasses import dataclass
+from typing import IO, Any
+
+_INITIALIZE = {
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "initialize",
+    "params": {
+        "protocolVersion": "2025-06-18",
+        "capabilities": {},
+        "clientInfo": {"name": "solidworks-mcp-setup", "version": "1"},
+    },
+}
+_INITIALIZED = {"jsonrpc": "2.0", "method": "notifications/initialized"}
+_LIST_TOOLS = {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}
+
+# stdout lines read by the pump thread; None marks the end of the stream.
+_Lines = queue.Queue[bytes | None]
+
+
+@dataclass(frozen=True)
+class HandshakeResult:
+    """The outcome of the start-up check.
+
+    Attributes:
+        ok: Whether the server answered and listed at least one tool.
+        tools: How many tools it listed.
+        message: One line for the user.
+    """
+
+    ok: bool
+    tools: int
+    message: str
+
+
+def check_server(
+    command: str, args: list[str], timeout: float = 90.0
+) -> HandshakeResult:
+    """Start ``command args`` and run the MCP handshake over its stdio.
+
+    The process is always killed afterwards. Its stderr goes to a temporary
+    file: an unread pipe can fill up and stall the server.
+
+    Args:
+        command: The launcher to start.
+        args: Its arguments (setup passes ``--mock``).
+        timeout: Seconds to wait for both replies, in total.
+
+    Returns:
+        Whether it worked, the tool count and a message.
+    """
+    with tempfile.TemporaryFile() as stderr:
+        try:
+            process = subprocess.Popen(
+                [command, *args],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=stderr,
+            )
+        except OSError as exc:
+            return HandshakeResult(
+                False, 0, f"Could not start {command}: {exc.strerror or exc}."
+            )
+        try:
+            return _converse(process, time.monotonic() + timeout)
+        finally:
+            process.kill()
+            process.wait()
+
+
+def _converse(process: subprocess.Popen[bytes], deadline: float) -> HandshakeResult:
+    """Send the handshake and read the two replies.
+
+    Args:
+        process: The started server, with piped stdin and stdout.
+        deadline: ``time.monotonic()`` value to give up at.
+
+    Returns:
+        The check's outcome.
+    """
+    lines = _line_reader(process.stdout)
+    _send(process, _INITIALIZE)
+    if _response(lines, 1, deadline) is None:
+        return _failed(process, "did not answer the MCP initialize request")
+    _send(process, _INITIALIZED)
+    _send(process, _LIST_TOOLS)
+    reply = _response(lines, 2, deadline)
+    if reply is None:
+        return _failed(process, "did not answer the tools/list request")
+    tools = reply.get("result", {}).get("tools")
+    if not isinstance(tools, list) or not tools:
+        return HandshakeResult(False, 0, "The server answered but listed no tools.")
+    return HandshakeResult(
+        True, len(tools), f"The server started and listed {len(tools)} tools."
+    )
+
+
+def _failed(process: subprocess.Popen[bytes], what: str) -> HandshakeResult:
+    """Describe a missing reply, with the exit code if the server has exited.
+
+    Args:
+        process: The server process.
+        what: What it failed to do.
+
+    Returns:
+        A failed result.
+    """
+    # stdout can close a moment before the process has finished exiting, so
+    # give it a second to report its exit code.
+    try:
+        code: int | None = process.wait(timeout=1)
+    except subprocess.TimeoutExpired:
+        code = None
+    exited = f" (it exited with code {code})" if code is not None else ""
+    return HandshakeResult(False, 0, f"The server {what}{exited}.")
+
+
+def _send(process: subprocess.Popen[bytes], message: dict[str, Any]) -> None:
+    """Write one JSON-RPC message as a line on the server's stdin.
+
+    Args:
+        process: The server process.
+        message: The JSON-RPC message.
+    """
+    assert process.stdin is not None
+    try:
+        process.stdin.write((json.dumps(message) + "\n").encode())
+        process.stdin.flush()
+    except OSError:
+        # The server has exited; the missing reply reports it.
+        pass
+
+
+def _line_reader(stream: IO[bytes] | None) -> _Lines:
+    """Read ``stream`` line by line on a daemon thread.
+
+    A thread lets the reader wait with a timeout: ``readline`` on a pipe
+    blocks with no timeout of its own on Windows.
+
+    Args:
+        stream: The server's stdout.
+
+    Returns:
+        A queue of lines, ending with ``None`` when the stream closes.
+    """
+    lines: _Lines = queue.Queue()
+
+    def pump() -> None:
+        """Move each line into the queue, then the end marker."""
+        assert stream is not None
+        for line in iter(stream.readline, b""):
+            lines.put(line)
+        lines.put(None)
+
+    threading.Thread(target=pump, daemon=True).start()
+    return lines
+
+
+def _response(lines: _Lines, request_id: int, deadline: float) -> dict[str, Any] | None:
+    """Wait for the JSON-RPC reply to ``request_id``.
+
+    Lines that aren't JSON (a stray banner) and other messages (log
+    notifications) are skipped.
+
+    Args:
+        lines: The server's stdout lines.
+        request_id: The ``id`` of the request being answered.
+        deadline: ``time.monotonic()`` value to give up at.
+
+    Returns:
+        The reply, or ``None`` on timeout or when the stream ends.
+    """
+    while (remaining := deadline - time.monotonic()) > 0:
+        try:
+            line = lines.get(timeout=remaining)
+        except queue.Empty:
+            return None
+        if line is None:
+            return None
+        try:
+            message = json.loads(line)
+        except ValueError:
+            continue
+        if isinstance(message, dict) and message.get("id") == request_id:
+            return message
+    return None

solidworks_mcp/setup/launcher.py

@@ -0,0 +1,102 @@
+"""The command a client config runs to start this server.
+
+It is always an absolute path, so the config works no matter where the
+client starts it or what its PATH is. Usually it is the launcher in the
+environment setup itself runs from. When that environment is a temporary
+one in uv's cache (``uvx solidworks-mcp-python setup``), it is ``uvx``
+instead, because the cache folder disappears when uv cleans it.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+# The PyPI name; `uvx solidworks-mcp` would install a different project.
+PACKAGE = "solidworks-mcp-python"
+
+# uvx runs a tool from `<uv cache>/archive-v<n>/<hash>/`.
+_UV_ARCHIVE = re.compile(r"archive-v\d+", re.IGNORECASE)
+
+
+def in_uv_cache(python: str) -> bool:
+    """Whether an interpreter lives in a temporary environment in uv's cache.
+
+    ``uv tool install`` environments (under ``uv\\tools``) and project
+    ``.venv`` folders are persistent and don't count.
+
+    Args:
+        python: The interpreter's path.
+
+    Returns:
+        True when a ``cache`` folder holds an ``archive-v<n>`` folder on the
+        path to it.
+    """
+    parts = [part.lower() for part in Path(python).parts]
+    return any(
+        _UV_ARCHIVE.fullmatch(part) and "cache" in parts[:index]
+        for index, part in enumerate(parts)
+    )
+
+
+def find_uvx(
+    uv: str | None = None, which: Callable[[str], str | None] = shutil.which
+) -> str | None:
+    """Find the ``uvx`` launcher, by absolute path.
+
+    Args:
+        uv: The uv executable; defaults to the ``UV`` variable uv sets for
+            the programs it runs.
+        which: PATH lookup, replaceable in tests.
+
+    Returns:
+        ``uvx`` beside uv if it is there, else on the PATH, else ``None``.
+    """
+    uv = uv if uv is not None else os.environ.get("UV")
+    if uv:
+        for name in ("uvx.exe", "uvx"):
+            beside = Path(uv).parent / name
+            if beside.is_file():
+                return str(beside)
+    return which("uvx")
+
+
+def server_command(
+    mock: bool = False,
+    python: str | None = None,
+    lasting: bool = True,
+    uvx_finder: Callable[[], str | None] = find_uvx,
+) -> tuple[str, list[str]]:
+    """The command and arguments that start this server.
+
+    Args:
+        mock: Add ``--mock``, so the server answers without SolidWorks.
+        python: The interpreter to look beside; defaults to ``sys.executable``.
+        lasting: Return a command that outlives a temporary uv environment.
+            ``False`` gives the launcher that runs right now, which is what
+            the start-up check needs.
+        uvx_finder: Finds ``uvx``, replaceable in tests.
+
+    Returns:
+        ``(command, args)``: ``uvx`` running this package when ``lasting`` and
+        the interpreter is in uv's cache; otherwise the ``solidworks-mcp``
+        console script in the environment's scripts folder or, without one,
+        this Python running the server module.
+    """
+    python = python or sys.executable
+    flags = ["--mock"] if mock else []
+    if lasting and in_uv_cache(python):
+        uvx = uvx_finder()
+        if uvx:
+            return uvx, [PACKAGE, *flags]
+    scripts = Path(python).parent
+    # `.exe` on Windows; the bare name elsewhere.
+    for name in ("solidworks-mcp.exe", "solidworks-mcp"):
+        launcher = scripts / name
+        if launcher.is_file():
+            return str(launcher), flags
+    return python, ["-m", "solidworks_mcp.server", *flags]

solidworks_mcp/setup/legacy.py

@@ -0,0 +1,100 @@
+"""Recognise older, hand-made config entries that start this same server.
+
+Before ``solidworks-mcp setup`` existed, the README had people add entries
+under names of their choosing, launched through ``run-mcp.ps1``,
+``start_local_server_claude.py`` and similar. Left in place beside the new
+``solidworks`` entry, they load every tool twice, and the PowerShell ones
+can break the stdio connection.
+
+The rule reads only an entry's ``command`` and ``args``. Secrets live in
+``env`` and ``headers``, which are never looked at. It matches this
+project's own launcher names exactly, so another vendor's SolidWorks server
+is never mistaken for this one.
+"""
+
+from __future__ import annotations
+
+from pathlib import PureWindowsPath
+from typing import Any
+
+from .clients import SERVER_NAME
+
+# Script files that only this project ships.
+_OLD_SCRIPTS = frozenset(
+    {
+        "run-mcp.ps1",
+        "run-mcp-claude.ps1",
+        "start_local_server.py",
+        "start_local_server_claude.py",
+    }
+)
+# This package's console scripts, with or without `.exe`.
+_OUR_LAUNCHERS = frozenset(
+    {
+        "solidworks-mcp",
+        "solidworks-mcp.exe",
+        "solidworks-mcp-python",
+        "solidworks-mcp-python.exe",
+    }
+)
+# `python -m <module>` forms that start this server.
+_OUR_MODULES = frozenset({"solidworks_mcp.server", "solidworks_mcp"})
+
+
+def launcher_name(entry: Any) -> str:
+    """The program file an entry starts, for showing to the user.
+
+    Args:
+        entry: A server entry from a client config.
+
+    Returns:
+        The file name of its ``command`` (e.g. ``powershell.exe``), without the
+        folder; ``?`` if it has none.
+    """
+    command = entry.get("command") if isinstance(entry, dict) else None
+    return (
+        PureWindowsPath(command).name if isinstance(command, str) and command else "?"
+    )
+
+
+def starts_this_server(entry: Any) -> bool:
+    """Whether a config entry launches this project's server.
+
+    Args:
+        entry: A server entry from a client config.
+
+    Returns:
+        True when its command is one of this package's launchers, or its
+        arguments name one of this project's launch scripts or modules.
+    """
+    if not isinstance(entry, dict):
+        return False
+    command = entry.get("command")
+    args = entry.get("args")
+    words = [command] if isinstance(command, str) else []
+    if isinstance(args, list):
+        words += [a for a in args if isinstance(a, str)]
+
+    # PureWindowsPath splits on both / and \, whatever OS this runs on.
+    names = {PureWindowsPath(word).name.lower() for word in words}
+    if names & _OLD_SCRIPTS or names & _OUR_LAUNCHERS:
+        return True
+    # `-m solidworks_mcp.server`: the word after each -m is a module name.
+    modules = {words[i + 1] for i, word in enumerate(words[:-1]) if word == "-m"}
+    return bool(modules & _OUR_MODULES)
+
+
+def old_entries(servers: dict[str, Any]) -> list[str]:
+    """Name every entry, besides ``solidworks``, that starts this server.
+
+    Args:
+        servers: A config's server entries (``mcpServers`` or ``servers``).
+
+    Returns:
+        Their names, in the config's order.
+    """
+    return [
+        name
+        for name, entry in servers.items()
+        if name != SERVER_NAME and starts_this_server(entry)
+    ]