pythonparts-mcp 0.2.0__py3-none-any.whl

pythonparts_mcp-0.2.0.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.5
+Name: pythonparts-mcp
+Version: 0.2.0
+Summary: MCP server exposing the ALLPLAN Python runtime to AI coding assistants
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=3.0
+Requires-Dist: pyright>=1.1
+Requires-Dist: pywin32>=306; sys_platform == 'win32'
+Description-Content-Type: text/markdown
+
+# PythonParts Local MCP Server
+
+An MCP server that exposes the local ALLPLAN Python runtime to AI coding assistants.
+It is started once per ALLPLAN version and gives any MCP-compatible agent accurate,
+live information about the interpreter, import paths, installed packages, and type
+correctness — without guessing or hallucinating.
+
+Transport: **stdio** (spawned as a subprocess by the MCP client).  
+Protocol: [Model Context Protocol](https://modelcontextprotocol.io/) via `FastMCP`.  
+Release history: [CHANGELOG.md](CHANGELOG.md).
+
+---
+
+## Prerequisites
+
+- [**uv**](https://docs.astral.sh/uv/getting-started/installation/) — Python package manager used to run the server without a manual install step.
+
+  ```powershell
+  winget install astral-sh.uv
+  ```
+
+---
+
+## Attaching to your AI agent
+
+Add the following entry to your MCP configuration:
+
+```json
+"pythonparts-local-mcp": {
+  "type": "stdio",
+  "command": "uvx",
+  "args": [
+    "--index", "https://test.pypi.org/simple",
+    "--index-strategy", "unsafe-best-match",
+    "pythonparts-mcp",
+    "--allplan-version", "2026",
+    "--std-path", "X:\\Path\\To\\Allplan\\Std",
+    "--usr-path", "X:\\Path\\To\\Allplan\\Usr\\Local"
+  ]
+}
+```
+
+**Arguments:**
+
+| Argument | Description | Example |
+|---|---|---|
+| `--allplan-version` | Installed ALLPLAN version | `2026` |
+| `--std-path` | Path to ALLPLAN's `Std` directory | `C:\Data\Allplan\Allplan 2026\Std` |
+| `--usr-path` | Path to ALLPLAN's user directory. Located under `Usr\<username>` or `Usr\Local` depending on your ALLPLAN configuration. | `C:\Users\Jane\Nemetschek\Allplan\2026\Usr\Local` |
+
+The `prg` and `etc` paths are resolved automatically from the Windows registry.
+
+---
+
+## Available Tools
+
+### `get_allplan_info()`
+
+Returns the installed ALLPLAN version string and the four resolved file-system paths (`prg`, `etc`, `std`, `usr`). No input required.
+
+```json
+{
+  "ok": true,
+  "data": {
+    "version": "2026.0.0",
+    "paths": {
+      "prg": "C:\\Program Files\\Allplan\\Allplan 2026\\Prg",
+      "etc": "C:\\ProgramData\\Nemetschek\\Allplan\\2026\\etc",
+      "std": "X:\\Path\\To\\Allplan\\Std",
+      "usr": "X:\\Path\\To\\Allplan\\Usr\\Local"
+    }
+  }
+}
+```
+
+### `get_python_env_info()`
+
+Returns the path to the ALLPLAN-embedded Python interpreter, its version, and the ordered `sys.path` ALLPLAN uses when executing PythonParts scripts. No input required.
+
+```json
+{
+  "ok": true,
+  "data": {
+    "interpreter_path": "C:\\...\\Prg\\Python\\python.exe",
+    "python_version": "3.11.9",
+    "sys_path": ["C:\\...\\Prg\\Python", "..."]
+  }
+}
+```
+
+### `list_site_packages()`
+
+Lists all Python packages installed in the ALLPLAN-embedded Python environment, deduplicated and sorted alphabetically. No input required.
+
+```json
+{
+  "ok": true,
+  "data": [
+    {"name": "requests", "version": "2.31.0"},
+    {"name": "shapely", "version": null}
+  ]
+}
+```
+
+### `typecheck_file(file_path: str)`
+
+Type-checks a `.py` file against the ALLPLAN runtime using Pyright. Input: absolute path to the file.
+
+```json
+{
+  "ok": true,
+  "data": {
+    "error_count": 2,
+    "warning_count": 0,
+    "diagnostics": [
+      {
+        "severity": "error",
+        "message": "...",
+        "file": "C:\\...\\main.py",
+        "line": 12,
+        "column": 5,
+        "rule": "reportMissingImports"
+      }
+    ]
+  }
+}
+```
+
+### `inspect_symbol(symbol: str)`
+
+Inspects a Python symbol in the live ALLPLAN runtime — returns its category, signature, docstring, and public members. Use this to verify a symbol exists and discover its API before writing code against it.
+
+Input: dotted Python path to the symbol.
+
+```json
+{
+  "ok": true,
+  "data": {
+    "symbol": "NemAll_Python_Geometry.Point3D",
+    "category": "class",
+    "module": "NemAll_Python_Geometry",
+    "docstring": "...",
+    "signature": null,
+    "members": ["X", "Y", "Z", "..."]
+
+
+
+  }
+}
+```
+
+### `run_snippet_in_sandbox(code: str)`
+
+Runs a Python snippet against the ALLPLAN libraries in a **separate process, outside ALLPLAN**, and returns its `print()` output. ALLPLAN does not need to be running, and the snippet cannot touch the open drawing or project data. This is the tool to reach for when verifying geometry math or API behaviour.
+
+The ALLPLAN interface modules are pre-imported as globals (`AllplanGeometry`, `AllplanBasisElements`, …). There is no document and no coordinate input, so `document` and `coord_input` are **not** available — anything that needs the open drawing, the project or user settings will fail or return a meaningless value.
+
+Globals do not persist between calls, so each snippet must be self-contained. The first call spends a second or two loading the ALLPLAN DLLs; the process is then reused. Snippets are abandoned after 60 seconds.
+
+Snippets must not show a user interface — `AllplanUtility.ShowMessageBox`, file dialogs and the like. There is no ALLPLAN window to host them, so the call never returns and the snippet runs into the timeout.
+
+```json
+{
+  "ok": true,
+  "data": {
+    "output": "(30000.0, NemAll_Python_Geometry.eServiceResult.POSITIVE_ORIENTATION)\n"
+  }
+}
+```

pythonparts_mcp-0.2.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+server/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+server/__main__.py,sha256=4tG2TUYNKgY-ZslQIWiDKkJESe5eptLI99k5bYct8YU,3078
+server/config.py,sha256=2GHe6kmP4ngv3lXvt1aQZb734uRoj3IPqbiSIXneSd8,1455
+server/paths.py,sha256=JImoZD92bdLy4g9LLdoIGMLF6gSzzN2X1DvWlztCv3A,2720
+server/pyright_config.py,sha256=ADKEeDibT0m28JcgRc91VFHxS9EQqOX38RSvRLJvNfo,2241
+server/registry.py,sha256=l0en2fqnjaV7ksFepqFayMJ0WMn4JqjaQFTxab0bOYs,2127
+server/worker.py,sha256=krjPZvMQI6NfXzZidmP5vLCZlBUlj7GZJmjgQ9g18Pk,6645
+server/tools/__init__.py,sha256=7o6-OuNXkQUFWNpHvEGKc8Yh2cu2PrPrTpFmhTdiAIY,718
+server/tools/_introspect_worker.py,sha256=-g_AzB7lclXRJUhcnb-rBzq5A2OeFAjm6lhTpXVCpeU,18914
+server/tools/_sandbox_worker.py,sha256=6Og6yDXgaQZmnZWh6_spP7jbBoorUwI1m0BhZ55TQo4,7357
+server/tools/connector.py,sha256=ugAvhWShzYahFwJLTt-q-bZ1s3lOm5JSQzmhxspr28o,2892
+server/tools/inspect_symbol.py,sha256=XB5OZu_NHd74FEnevX8wj9l21FCMTK19qeVyj3FguD4,2825
+server/tools/run_snippet_in_allplan.py,sha256=0FM9htz7O5mhPyv1Fd3MwuHg-9_9nQFbfhNyAvGJrv4,3668
+server/tools/run_snippet_in_sandbox.py,sha256=SlVQ8X2tuY2303TUzbpr9nexcp3ctaNSimNfDMx6CPA,3594
+server/tools/runtime_context.py,sha256=09avnd85iyjydJ2PGqowfCR0bdKVFDZ_KtpT67en_r4,5516
+server/tools/typecheck.py,sha256=uSFpoGdNG1HiDB0ZB1zBRSG74pWPndn801YQYEfpvsY,4879
+pythonparts_mcp-0.2.0.dist-info/METADATA,sha256=zY4dLDJiMzXRCZMBXdaSIi44JBc2MlzE5LOfaNQ4KzU,5402
+pythonparts_mcp-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pythonparts_mcp-0.2.0.dist-info/entry_points.txt,sha256=Z0Y7jP5IsuOEXyhbwWRZKMyqKwunlM-pbdThqFwUjXs,57
+pythonparts_mcp-0.2.0.dist-info/RECORD,,

pythonparts_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pythonparts_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pythonparts-mcp = server.__main__:main

server/__main__.py

@@ -0,0 +1,101 @@
+"""
+PythonParts Local MCP Server — entry point.
+
+Usage:
+    python -m server --allplan-version 2026 --std-path "C:\\..." --usr-path "C:\\..."
+    python -m server --allplan-version 2026 --product-name Allplan --std-path "C:\\..." --usr-path "C:\\..."
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from fastmcp import FastMCP
+
+from .config import get_config, init_config
+from .pyright_config import setup_pyright_config
+from .registry import AllplanNotInstalledError, read_install_paths
+from .tools.inspect_symbol import register_inspect_symbol_tools
+# from .tools.run_snippet_in_allplan import register_run_snippet_in_allplan_tools
+from .tools.run_snippet_in_sandbox import register_run_snippet_in_sandbox_tools
+from .tools.runtime_context import register_runtime_context_tools
+from .tools.typecheck import register_typecheck_tools
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="PythonParts Local MCP Server")
+    parser.add_argument(
+        "--allplan-version",
+        required=True,
+        help="ALLPLAN version, e.g. 2026",
+    )
+    parser.add_argument(
+        "--product-name",
+        default="Allplan",
+        help="Registry product name (default: Allplan)",
+    )
+    parser.add_argument(
+        "--std-path",
+        required=True,
+        type=Path,
+        help="ALLPLAN 'std' directory path",
+    )
+    parser.add_argument(
+        "--usr-path",
+        required=True,
+        type=Path,
+        help="ALLPLAN 'usr' directory path",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    # stdout is the MCP stdio transport — never log there. Log everything to a file instead.
+    log_path = Path(__file__).resolve().parent.parent / "server.log"
+    logging.basicConfig(
+        filename=log_path,
+        encoding="utf-8",
+        level=logging.DEBUG,
+    )
+    
+    logger = logging.getLogger(__name__)
+    logger.info("Starting PythonParts Local MCP Server")
+
+    args = parse_args()
+
+    try:
+        prg, etc, program_name = read_install_paths(
+            product_name=args.product_name,
+            allplan_version=args.allplan_version,
+        )
+    except AllplanNotInstalledError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    init_config(
+        allplan_version=args.allplan_version,
+        product_name=args.product_name,
+        prg=prg,
+        etc=etc,
+        std=args.std_path,
+        usr=args.usr_path,
+        program_name=program_name,
+    )
+
+    setup_pyright_config(get_config())
+
+    mcp = FastMCP("PythonParts local MCP")
+    register_runtime_context_tools(mcp)
+    register_typecheck_tools(mcp)
+    register_inspect_symbol_tools(mcp)
+    # Withheld from the public release: it executes code in the user's live ALLPLAN session.
+    # register_run_snippet_in_allplan_tools(mcp)
+    register_run_snippet_in_sandbox_tools(mcp)
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

server/config.py

@@ -0,0 +1,58 @@
+"""
+AllplanConfig dataclass and module-level singleton.
+
+All tools access the runtime configuration through `get_config()`.
+`init_config()` must be called once at server startup before any tool is invoked.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+# Fixed port owned by the Vibe Coding Connector PythonPart running inside ALLPLAN.
+CONNECTOR_BASE_URL = "http://localhost:9731"
+
+
+@dataclass(frozen=True)
+class AllplanConfig:
+    allplan_version: str
+    product_name: str
+    prg: Path
+    etc: Path
+    std: Path
+    usr: Path
+    program_name: str
+
+
+_config: AllplanConfig | None = None
+
+
+def init_config(
+    allplan_version: str,
+    product_name: str,
+    prg: Path,
+    etc: Path,
+    std: Path,
+    usr: Path,
+    program_name: str,
+) -> AllplanConfig:
+    """Initialize the global config singleton. Call once at startup."""
+    global _config
+    _config = AllplanConfig(
+        allplan_version=allplan_version,
+        product_name=product_name,
+        prg=prg,
+        etc=etc,
+        std=std,
+        usr=usr,
+        program_name=program_name,
+    )
+    return _config
+
+
+def get_config() -> AllplanConfig:
+    """Return the active config. Raises RuntimeError if not yet initialized."""
+    if _config is None:
+        raise RuntimeError("Server config has not been initialized. Call init_config() first.")
+    return _config

server/paths.py

@@ -0,0 +1,87 @@
+"""
+Path helpers derived from the ALLPLAN installation config.
+
+Shared by multiple tools — import from here rather than duplicating.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .config import AllplanConfig
+
+
+def interpreter_path(prg: Path) -> Path:
+    """Return the path to the ALLPLAN-embedded Python interpreter."""
+    return prg / "Python" / "python.exe"
+
+
+def framework_version(cfg: AllplanConfig) -> str:
+    """Return the ALLPLAN's product version from the executable."""
+    import win32api  # stdlib-level on Windows; lazy-imported for non-Windows testability
+
+    program_path = cfg.prg / cfg.program_name
+
+    # Get available language code
+    translation = win32api.GetFileVersionInfo(
+        str(program_path), "\\VarFileInfo\\Translation")
+    lang, codepage = translation[0] if translation else (1033, 1252)
+
+    # Format as hex string
+    lang_code = f"{lang:04x}{codepage:04x}"
+
+    # Access StringFileInfo with the correct language code
+    product_version = win32api.GetFileVersionInfo(
+        str(program_path),
+        f"\\StringFileInfo\\{lang_code}\\ProductVersion"
+    )
+    return product_version
+
+
+def build_sys_path(cfg: AllplanConfig) -> list[str]:
+    """Reconstruct the ``sys.path`` that ALLPLAN injects into its embedded Python runtime.
+
+    The order follows the observed path order on a live installation.
+    Per-project (prj) entries are intentionally omitted.
+
+    Args:
+        cfg: Active ALLPLAN configuration.
+
+    Returns:
+        Ordered list of path strings matching ALLPLAN's runtime ``sys.path``.
+    """
+    prg = cfg.prg
+    etc = cfg.etc
+    std = cfg.std
+    usr = cfg.usr
+
+    paths: list[Path] = [
+        # Interpreter roots
+        prg / "Python",
+        prg / "Python" / "Lib",
+        # Site-packages per hierarchy
+        std / "PythonParts-site-packages",
+        usr / "PythonParts-site-packages",
+        etc / "PythonParts-site-packages",
+        # Standard Python lib paths
+        prg / "Python" / "Lib" / "site-packages",
+        prg / "Python" / "DLLs",
+        # Framework paths (etc)
+        etc / "PythonPartsFramework",
+        etc / "PythonPartsFramework" / "GeneralScripts",
+        etc / "PythonPartsScripts",
+        etc / "PythonPartsExampleScripts",
+        etc / "Scripts",
+        # Script paths per hierarchy (std / usr)
+        std / "PythonPartsScripts",
+        std / "VisualScripts",
+        std / "Scripts",
+        usr / "PythonPartsScripts",
+        usr / "PythonPartsExampleScripts",
+        usr / "VisualScripts",
+        usr / "Scripts",
+        # Prg root
+        prg,
+    ]
+
+    return [str(p) for p in paths]

server/pyright_config.py

@@ -0,0 +1,67 @@
+"""
+Manages the temporary pyrightconfig.json used for type-checking against the
+ALLPLAN runtime. The config directory is created at server startup and
+deleted automatically on shutdown via atexit.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import shutil
+import tempfile
+from pathlib import Path
+
+from .config import AllplanConfig
+from .paths import build_sys_path, interpreter_path
+
+_pyright_config_dir: Path | None = None
+_python_interpreter: str | None = None
+
+
+def get_python_interpreter() -> str:
+    """Return the ALLPLAN interpreter path for use as the pyright --pythonpath argument."""
+    if _python_interpreter is None:
+        raise RuntimeError("Pyright config has not been set up. Call setup_pyright_config() first.")
+    return _python_interpreter
+
+
+def setup_pyright_config(cfg: AllplanConfig) -> Path:
+    """Create a temp directory with a ``pyrightconfig.json`` for the given ALLPLAN install.
+
+    Registers cleanup of the temp directory via ``atexit`` so it is removed on
+    server shutdown without requiring explicit teardown in tool code.
+
+    Args:
+        cfg: Active ALLPLAN configuration.
+
+    Returns:
+        Path to the temp directory. Pass this to ``--project`` when invoking pyright.
+    """
+    global _pyright_config_dir, _python_interpreter
+
+    _python_interpreter = str(interpreter_path(cfg.prg))
+    tmpdir = Path(tempfile.mkdtemp(prefix="pythonparts-mcp-pyright-"))
+    atexit.register(shutil.rmtree, str(tmpdir), True)
+
+    config = {
+        "stubPath": str(cfg.etc / "PythonPartsFramework" / "InterfaceStubs"),
+        "extraPaths": build_sys_path(cfg),
+        "typeCheckingMode": "basic",
+        "reportMissingModuleSource": "none",
+    }
+
+    (tmpdir / "pyrightconfig.json").write_text(
+        json.dumps(config, indent=2),
+        encoding="utf-8",
+    )
+
+    _pyright_config_dir = tmpdir
+    return tmpdir
+
+
+def get_pyright_config_dir() -> Path:
+    """Return the temp project dir. Raises if ``setup_pyright_config`` was not called."""
+    if _pyright_config_dir is None:
+        raise RuntimeError("Pyright config has not been set up. Call setup_pyright_config() first.")
+    return _pyright_config_dir

server/registry.py

@@ -0,0 +1,59 @@
+"""
+Windows registry reader for ALLPLAN installation paths.
+
+Reads `prg` and `etc` paths from:
+    HKLM\\SOFTWARE\\NEMETSCHEK\\{product_name}\\{version}.0\\InstallRoot
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class AllplanNotInstalledError(Exception):
+    """Raised when the requested ALLPLAN version is not found in the registry."""
+
+
+def _format_version(allplan_version: str) -> str:
+    """Convert a version string like '2026' to '2026.0' for registry lookup."""
+    return f"{allplan_version}.0"
+
+
+def read_install_paths(product_name: str, allplan_version: str) -> tuple[Path, Path, str]:
+    """Read the ``prg``, ``etc``, and program name from the Windows registry.
+
+    Args:
+        product_name: Registry product name, e.g. ``"Allplan"``.
+        allplan_version: Version string as supplied by the user, e.g. ``"2026"``.
+
+    Returns:
+        A ``(prg_path, etc_path, program_name)`` tuple.
+
+    Raises:
+        AllplanNotInstalledError: If the registry key does not exist (product not installed).
+    """
+    import winreg  # stdlib on Windows; imported here to allow import on non-Windows for testing
+
+    version_str = _format_version(allplan_version)
+    key_path = f"SOFTWARE\\NEMETSCHEK\\{product_name}\\{version_str}\\InstallRoot"
+
+    try:
+        key = winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, key_path)
+    except FileNotFoundError:
+        raise AllplanNotInstalledError(
+            f"{product_name} {version_str} is not installed"
+        ) from None
+
+    try:
+        program_data_drive, _ = winreg.QueryValueEx(key, "ProgramDataDrive")
+        program_data_path, _ = winreg.QueryValueEx(key, "ProgramDataPath")
+        program_drive, _ = winreg.QueryValueEx(key, "ProgramDrive")
+        program_path, _ = winreg.QueryValueEx(key, "ProgramPath")
+        program_name, _ = winreg.QueryValueEx(key, "ProgramName")
+    finally:
+        winreg.CloseKey(key)
+
+    etc_path = Path(program_data_drive + program_data_path) / "etc"
+    prg_path = Path(program_drive + program_path)
+
+    return prg_path, etc_path, program_name

server/tools/__init__.py

@@ -0,0 +1,23 @@
+"""Shared helpers and constants used across all tool modules."""
+
+from __future__ import annotations
+
+from mcp.types import ToolAnnotations
+
+# Shared annotations for read-only, idempotent, non-destructive tools.
+# Import this constant instead of duplicating the ToolAnnotations call in each module.
+READ_ONLY_TOOL_ANNOTATIONS = ToolAnnotations(
+    readOnlyHint=True,
+    destructiveHint=False,
+    idempotentHint=True,
+    openWorldHint=True,
+)
+
+# Shared annotations for tools that can mutate the open ALLPLAN document (e.g. run arbitrary code).
+MUTATING_TOOL_ANNOTATIONS = ToolAnnotations(
+    readOnlyHint=False,
+    destructiveHint=True,
+    idempotentHint=False,
+    openWorldHint=True,
+)
+