pythonparts-mcp 0.2.0__tar.gz

pythonparts_mcp-0.2.0/.gitignore

@@ -0,0 +1,47 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Environment variables
+.env
+
+# Pyright / type checking
+.pyright/
+
+# pytest
+.pytest_cache/
+htmlcov/
+.coverage
+
+# mypy
+.mypy_cache/
+
+# IDEs
+.vscode/settings.json
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Visual Studio Code
+.vscode/
+
+# Other
+.temp/

pythonparts_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to `pythonparts-mcp` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-09-16
+
+### Added
+
+- **`run_snippet_in_sandbox`** — runs a Python snippet against the ALLPLAN libraries and
+  returns its `print()` output, so an agent can check geometry math or API behaviour instead
+  of guessing at it.
+
+  The snippet runs in a separate process under ALLPLAN's own interpreter, which means
+  ALLPLAN does not need to be running and the snippet cannot reach the user's drawing or
+  project data. The ALLPLAN interface modules are pre-imported as globals; `document` and
+  `coord_input` do not exist, and calls that open a user interface will hang until the
+  60-second timeout. Each call gets a fresh set of globals, so snippets must be
+  self-contained.
+
+  The worker process is started on first use and reused, so only the first call pays for
+  loading the ALLPLAN DLLs.
+
+### Fixed
+
+- `inspect_symbol` declared a 30-second timeout but never applied it, so a wedged worker
+  could hang the server indefinitely. The timeout is now enforced, and a worker that times
+  out, crashes or desyncs is replaced on the next call.
+
+## [0.1.2] — 2026-09-03
+
+### Fixed
+
+- FastMCP imports updated for the current FastMCP release.
+
+## [0.1.1] — 2026-08-06
+
+### Changed
+
+- `get_runtime_context` split into `get_allplan_info`, `get_python_env_info` and
+  `list_site_packages`.
+- `inspect_symbol` now keeps one worker process alive for the lifetime of the server
+  instead of spawning one per call.
+
+### Fixed
+
+- Corrected the declared project dependencies.
+
+## [0.1.0] — 2026-07-23
+
+Initial packaged release, exposing `get_runtime_context`, `typecheck_file` and
+`inspect_symbol`.

pythonparts_mcp-0.2.0/DOCS.md

@@ -0,0 +1,172 @@
+# PythonParts Local MCP Server — Developer Documentation
+
+## Repository Structure
+
+```
+server/
+    __init__.py          empty
+    __main__.py          entry point — arg parsing, startup sequence, tool registration
+    config.py            AllplanConfig dataclass + module-level singleton
+    paths.py             interpreter_path(), framework_version() and build_sys_path() helpers
+    registry.py          Windows registry reader → (prg, etc, program_name)
+    pyright_config.py    writes temp pyrightconfig.json at startup, cleans up on exit
+    worker.py            PersistentWorker — subprocess lifecycle shared by the worker-backed tools
+    tools/
+        __init__.py          READ_ONLY_TOOL_ANNOTATIONS shared constant
+        runtime_context.py   get_runtime_context tool
+        typecheck.py         typecheck_file tool
+        inspect_symbol.py    inspect_symbol tool
+        _introspect_worker.py  worker script run under the ALLPLAN interpreter
+        run_snippet_in_allplan.py  run_snippet_in_allplan tool — NOT REGISTERED, see below
+        run_snippet_in_sandbox.py  run_snippet_in_sandbox tool
+        _sandbox_worker.py   worker script run under the ALLPLAN interpreter
+pyproject.toml
+```
+
+---
+
+## Dependencies
+
+Declared in `pyproject.toml`:
+
+- `fastmcp` — FastMCP framework (provides `mcp.*` imports)
+
+- `pyright` — static type checker (bundled Node binary, invoked via `python -m pyright`)
+- `pywin32` — Windows API bindings (`win32api` used to read the ALLPLAN product version)
+
+---
+
+## Startup Sequence
+
+1. Parse CLI args
+2. Read `prg` and `etc` from Windows registry (`HKLM\SOFTWARE\NEMETSCHEK\{product_name}\{version}.0\InstallRoot`)
+3. If registry key missing → print error to stderr and exit 1
+4. Initialise `AllplanConfig` singleton
+5. Write `pyrightconfig.json` to a temp directory; register `atexit` cleanup
+6. Create `FastMCP` instance, register tools, call `mcp.run()`
+
+---
+
+## The Four ALLPLAN Paths
+
+Everything derives from these four `Path` values stored in `AllplanConfig`:
+
+| Field | Source | Example |
+|---|---|---|
+| `prg` | Registry `ProgramDrive` + `ProgramPath` | `C:\Program Files\Allplan\Allplan 2027\Prg` |
+| `etc` | Registry `ProgramDataDrive` + `ProgramDataPath` + `/etc` | `C:\ProgramData\Nemetschek\Allplan\2027\etc` |
+| `std` | CLI `--std-path` | `C:\Data\Allplan\Allplan 2027\Std` |
+| `usr` | CLI `--usr-path` | `C:\Users\...\Nemetschek\Allplan\2027\Usr\Local` |
+
+`paths.py` derives two shared values from these:
+- `interpreter_path(prg)` → `{prg}/Python/python.exe`
+- `build_sys_path(cfg)` → ordered list of 24 paths matching ALLPLAN's runtime `sys.path`
+
+---
+
+## Tool Implementation Notes
+### Runtime context tools
+
+### `get_runtime_context()`
+- `get_allplan_info()` — ALLPLAN version + resolved (prg/etc/std/usr) paths
+
+- `get_python_env_info()` — embedded interpreter path, version, and derived sys.path
+
+- `list_site_packages()` — installed packages discovered by scanning *site-packages* dirs in sys.path
+
+  (first occurrence wins, matching Python's import resolution order)
+
+### `typecheck_file(file_path: str)`
+
+1. Validates the file exists
+2. Calls `pyright --outputjson --project <tmpdir> --pythonpath <interpreter> <file>`
+   via `python -m pyright` (server's own venv Python) with `stdin=DEVNULL`
+   (critical: prevents pyright from inheriting the MCP server's stdio pipe and hanging)
+3. Extracts JSON from stdout (skips any warning text printed before the `{`)
+4. Filters known false positives before returning
+
+**Pyright config** (written to temp dir at startup):
+```json
+{
+  "stubPath": "{etc}/PythonPartsFramework/InterfaceStubs",
+  "extraPaths": ["... full sys_path list ..."],
+  "typeCheckingMode": "basic",
+  "reportMissingModuleSource": "none"
+}
+```
+The interpreter path is passed as `--pythonpath` (CLI flag), not in the config file —
+`pythonPath` in `pyrightconfig.json` is not recognised by pyright 1.1.x.
+
+**Known false positives suppressed:**
+- `reportAttributeAccessIssue` on `BuildingElement` — its attributes are populated
+  dynamically from `.pyp` files at runtime and cannot be statically verified
+
+`error_count` and `warning_count` are recomputed from the filtered list, so they match the diagnostics array exactly.
+
+### Worker-backed tools (`inspect_symbol`, `run_snippet_in_sandbox`)
+
+ALLPLAN's `NemAll_Python_*` modules are native extensions that only load in the interpreter
+shipped in `Prg\Python`, so these tools cannot run in-process — they drive a subprocess.
+Loading the DLLs costs a second or two, so `PersistentWorker` spawns the worker on first use
+and keeps it alive for the lifetime of the server.
+
+The protocol is one JSON line in, one JSON line out. The first line is an init handshake
+carrying `sys_path`, `prg_plugins`, `allplan_paths_mock` and `etc_pythonparts`; the worker
+sets up the runtime and replies with an ack before accepting requests.
+
+The worker's stdout is drained by a pump thread into a queue, which is what allows a read to
+be given a deadline — there is no `select()` on pipes on Windows. Timeouts, crashes and
+protocol desync all kill the worker and return a structured error; the next request spawns a
+fresh process. A snippet that crashes its worker therefore fails, and the call after it succeeds.
+
+`_sandbox_worker.py` additionally imports the interface modules under the same aliases the
+Vibe Coding Connector's `/execute` route exposes — minus `document` and `coord_input`, which
+cannot exist without a running ALLPLAN. Each snippet is executed with a fresh copy of that
+globals dict, so nothing leaks between invocations.
+
+### `run_snippet_in_allplan` (disabled)
+
+Executes a snippet in the user's live ALLPLAN session by POSTing it to the Vibe Coding
+Connector PythonPart's `/execute` endpoint. Unlike the sandbox it has `document` and
+`coord_input`, and can therefore read and modify real project data.
+
+Its registration in `__main__.py` is commented out, so it is not exposed by the released
+package and is intentionally absent from `README.md`. Re-enabling it means uncommenting the
+import and the `register_run_snippet_in_allplan_tools(mcp)` call — and documenting it again.
+
+---
+
+## Key Design Decisions
+
+| Decision | Rationale |
+|---|---|
+| `stdin=subprocess.DEVNULL` on pyright subprocess | Without this, pyright inherits the MCP server's stdin (the stdio pipe to the MCP client) and hangs indefinitely waiting for input |
+| `pythonPath` as CLI flag, not config key | `pythonPath` in `pyrightconfig.json` is unrecognised in pyright ≥1.1.x; use `--pythonpath` instead |
+| `atexit` for temp dir cleanup | Simpler than FastMCP lifespan hooks; reliable for stdio servers |
+| Filesystem scan instead of `pip list` | ALLPLAN may not have pip; packages are often dropped as folders without going through pip |
+| `sys_path` derived statically | Avoids spawning a subprocess for every `get_runtime_context` call; order matches observed live behaviour |
+| Sandbox runs out-of-process, not in a thread | The ALLPLAN DLLs must be loaded by ALLPLAN's own interpreter, not the server's; a separate process is also what keeps a crashing snippet from taking down the MCP server |
+| Sandbox not gated by `requires_allplan_connector` | It deliberately works with ALLPLAN closed; requiring the connector would defeat the point |
+| Sandbox keeps `MUTATING_TOOL_ANNOTATIONS` | The ALLPLAN document is safe, but the snippet is still arbitrary code with file-system access, so it stays confirmation-gated |
+| Worker stdout drained by a pump thread | Windows cannot `select()` on pipes; queueing the lines is what makes a read deadline possible |
+
+---
+
+## Adding a New Tool
+
+1. Create `server/tools/<name>.py`
+2. Define `register_<name>_tools(mcp: FastMCP) -> None` with `@mcp.tool()` decorated functions inside
+3. Import and call the registration function in `server/__main__.py`
+4. Access shared state via `get_config()` (paths) and `get_pyright_config_dir()` / `get_python_interpreter()` (pyright)
+
+---
+
+## Planned / Not Yet Implemented
+
+From the [original design brief](docs/MCP_Python_Environment_Aware_Tooling_Brief.md):
+
+- `resolve_import` — confirm a module/symbol is importable; where it resolves
+- `run_tests` — targeted test runner
+- `search_repo_usages` — find in-repo usage patterns for a symbol
+- VS Code extension wrapper for distribution (`.vsix` with bundled server)
+- Response caching for `get_runtime_context` (currently re-computed on every call)

pythonparts_mcp-0.2.0/PKG-INFO

@@ -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/PUBLISH.md

@@ -0,0 +1,91 @@
+# Publishing `pythonparts-mcp`
+
+Release uploads authenticate with **PyPI Trusted Publishers (OIDC)**.
+The workflow does not read or pass a PyPI API token.
+
+Workflow: [`.github/workflows/publish-pythonparts-mcp.yml`](../.github/workflows/publish-pythonparts-mcp.yml)
+Package: [`pyproject.toml`](pyproject.toml) (`name = "pythonparts-mcp"`)
+
+A push to `dev` that changes `local-server/` or the publish workflows builds,
+tests, and uploads the `pythonparts-mcp-dist` artifact for 7 days. That run
+is ungated and publishes nowhere. See
+[`.github/workflows/upload-pythonparts-mcp-dev.yml`](../.github/workflows/upload-pythonparts-mcp-dev.yml).
+
+Production publishes only when a `pythonparts-mcp-v*` tag is pushed, and only
+after a `prod` reviewer approves the deployment. The publish job depends on
+the test job, so a failed test, version mismatch, or build does not upload.
+
+## Trusted Publisher (exact match)
+
+PyPI.org must trust this identity. The environment name is part of the
+OIDC claim, so it has to match the GitHub Environment on the publish job.
+TestPyPI is not used for now.
+
+| Field | PyPI.org |
+|---|---|
+| Owner | `Allplan-GmbH` |
+| Repository | `InnovationAI-VibeCoding` |
+| Workflow filename | `publish-pythonparts-mcp.yml` |
+| Environment | `prod` |
+
+The publish job uses the existing `prod` environment. Its required reviewers
+are the people who can deploy to prod, and they decide who can publish.
+Under **Deployment branches and tags** for `prod`, allow the tag
+`pythonparts-mcp-v*`. A rule that only allows branch `main` will reject the
+tag and the publish job will not start.
+
+The publish job can read secrets stored on the `prod` environment, including
+any AWS secrets used by ECS deploys. This workflow does not use those secrets.
+
+### PyPI.org (project does not exist yet)
+
+Register a **pending** publisher while signed in as the account that should
+own the project:
+
+https://pypi.org/manage/account/publishing/
+
+Use environment name `prod`. If a pending publisher was already registered
+with environment `pypi`, delete it and register it again with `prod`.
+Otherwise the upload fails with `invalid-publisher`.
+
+The first successful tag publish creates `pythonparts-mcp` on PyPI.org.
+Do not create the project with an API token first; that skips the pending
+publisher.
+
+Docs: https://docs.pypi.org/trusted-publishers/
+
+## Retire the API token
+
+After the first PyPI.org upload from this workflow succeeds:
+
+1. Delete every `PYPI_*` and `TEST_PYPI_*` API token secret from this
+   repository and from the `Allplan-GmbH` organization Actions secrets.
+2. Revoke that token on PyPI and TestPyPI (Account settings → API tokens).
+3. Remove the service account that minted the token from Owners and
+   Maintainers on the `pythonparts-mcp` project. A human owner has to remain,
+   or the project is left with nobody who can manage it.
+
+## How to publish
+
+### Dev build (artifact)
+
+A push to `dev` that changes this package starts **Upload pythonparts-mcp from dev**.
+Download `pythonparts-mcp-dist` from that run's artifacts. The upload is
+ungated, kept for 7 days, and does not require a version bump. It does not
+publish to a package index.
+
+### Production
+
+1. Set `pyproject.toml` to the release version, for example `0.3.0`.
+2. Tag that exact version and push the tag:
+
+   ```bash
+   git tag pythonparts-mcp-v0.3.0
+   git push origin pythonparts-mcp-v0.3.0
+   ```
+
+3. After a `prod` reviewer approves the deployment, the workflow publishes to
+   https://pypi.org/project/pythonparts-mcp/ only when the tag version equals
+   `project.version`.
+
+Manual runs never publish to any package index.