ventilatepro-cli 0.1.1__tar.gz → 0.3.0__tar.gz

{ventilatepro_cli-0.1.1 → ventilatepro_cli-0.3.0}/PKG-INFO

@@ -1,16 +1,17 @@
 Metadata-Version: 2.4
 Name: ventilatepro-cli
-Version: 0.1.1
+Version: 0.3.0
 Summary: VentilatePro CLI
 Project-URL: Homepage, https://ventilatepro.com/exam/cli/
 Project-URL: Documentation, https://ventilatepro.com/exam/cli/
 Project-URL: Support, https://ventilatepro.com/exam/support/
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: typer>=0.16.0
 Requires-Dist: requests>=2.32.0
 Requires-Dist: keyring>=25.6.0
 Requires-Dist: platformdirs>=4.3.0
+Requires-Dist: mcp>=1.23.0
 
 # VentilatePro CLI
 
@@ -42,10 +43,62 @@ pip install -e .
 ```bash
 ventilatepro auth login --url http://localhost:8000
 ventilatepro projects list
+ventilatepro projects show 1
+ventilatepro rooms list --project 1
+ventilatepro ahus list --project 1
+ventilatepro systems hierarchy --project 1
+ventilatepro calc status --project 1
+ventilatepro calc ahu-properties --ahu 1
+ventilatepro design-day context --project 1
 ventilatepro notes create --project 1 --body "Captured from terminal"
 ventilatepro notes sync
+ventilatepro mcp doctor
+ventilatepro-mcp
 ```
 
+`ventilatepro-mcp` starts the local stdio MCP server for Codex, Claude Desktop,
+and other MCP clients. It uses the same saved base URL and CLI token created by
+`ventilatepro auth login`.
+
+## MCP setup
+
+1. In the VentilatePro web app, open Account Settings and create a CLI token with
+   the `Agent Editor` preset.
+2. Log in locally:
+
+```bash
+ventilatepro auth login --url https://app.ventilatepro.com --token vpcli_...
+```
+
+3. Confirm the local setup:
+
+```bash
+ventilatepro mcp doctor
+```
+
+4. Add the stdio server to Codex:
+
+```bash
+codex mcp add ventilatepro -- ventilatepro-mcp
+```
+
+For JSON-based MCP clients, use:
+
+```json
+{
+  "mcpServers": {
+    "ventilatepro": {
+      "command": "ventilatepro-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+If the client cannot find `ventilatepro-mcp`, run `where ventilatepro-mcp` on
+Windows or `which ventilatepro-mcp` on macOS/Linux and use the full path as the
+command.
+
 If the hidden token prompt is awkward in your terminal, use either:
 
 ```bash

ventilatepro_cli-0.3.0/README.md

@@ -0,0 +1,99 @@
+# VentilatePro CLI
+
+VentilatePro CLI is a local command-line client for authenticating to VentilatePro and creating or syncing notes through the scoped CLI API.
+
+## Install
+
+Published releases install from PyPI:
+
+```bash
+pipx install ventilatepro-cli
+```
+
+Upgrade an existing install:
+
+```bash
+pipx upgrade ventilatepro-cli
+```
+
+Local development install:
+
+```bash
+cd ventilatepro-cli
+pip install -e .
+```
+
+## Commands
+
+```bash
+ventilatepro auth login --url http://localhost:8000
+ventilatepro projects list
+ventilatepro projects show 1
+ventilatepro rooms list --project 1
+ventilatepro ahus list --project 1
+ventilatepro systems hierarchy --project 1
+ventilatepro calc status --project 1
+ventilatepro calc ahu-properties --ahu 1
+ventilatepro design-day context --project 1
+ventilatepro notes create --project 1 --body "Captured from terminal"
+ventilatepro notes sync
+ventilatepro mcp doctor
+ventilatepro-mcp
+```
+
+`ventilatepro-mcp` starts the local stdio MCP server for Codex, Claude Desktop,
+and other MCP clients. It uses the same saved base URL and CLI token created by
+`ventilatepro auth login`.
+
+## MCP setup
+
+1. In the VentilatePro web app, open Account Settings and create a CLI token with
+   the `Agent Editor` preset.
+2. Log in locally:
+
+```bash
+ventilatepro auth login --url https://app.ventilatepro.com --token vpcli_...
+```
+
+3. Confirm the local setup:
+
+```bash
+ventilatepro mcp doctor
+```
+
+4. Add the stdio server to Codex:
+
+```bash
+codex mcp add ventilatepro -- ventilatepro-mcp
+```
+
+For JSON-based MCP clients, use:
+
+```json
+{
+  "mcpServers": {
+    "ventilatepro": {
+      "command": "ventilatepro-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+If the client cannot find `ventilatepro-mcp`, run `where ventilatepro-mcp` on
+Windows or `which ventilatepro-mcp` on macOS/Linux and use the full path as the
+command.
+
+If the hidden token prompt is awkward in your terminal, use either:
+
+```bash
+ventilatepro auth login --url https://ventilatepro.com --token-prompt-visible
+```
+
+or pipe the token through stdin:
+
+```bash
+printf '%s' "$VPCLI_TOKEN" | ventilatepro auth login --url https://ventilatepro.com --token-stdin
+```
+
+See the hosted install guide at `https://ventilatepro.com/exam/cli/`, plus [docs/commands.md](./docs/commands.md), [docs/auth.md](./docs/auth.md), [docs/api.md](./docs/api.md), and [docs/releasing.md](./docs/releasing.md) in this repo.

{ventilatepro_cli-0.1.1 → ventilatepro_cli-0.3.0}/pyproject.toml

@@ -6,13 +6,14 @@ build-backend = "setuptools.build_meta"
 name = "ventilatepro-cli"
 dynamic = ["version"]
 description = "VentilatePro CLI"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 readme = "README.md"
 dependencies = [
   "typer>=0.16.0",
   "requests>=2.32.0",
   "keyring>=25.6.0",
   "platformdirs>=4.3.0",
+  "mcp>=1.23.0",
 ]
 
 [project.urls]
@@ -22,6 +23,7 @@ Support = "https://ventilatepro.com/exam/support/"
 
 [project.scripts]
 ventilatepro = "ventilatepro.cli:main"
+ventilatepro-mcp = "ventilatepro.mcp_server:main"
 
 [tool.setuptools.packages.find]
 where = ["."]

{ventilatepro_cli-0.1.1 → ventilatepro_cli-0.3.0}/tests/test_cli.py

@@ -101,6 +101,41 @@ class CliTests(unittest.TestCase):
                 os.environ.pop(config.CONFIG_ENV_VAR, None)
                 os.environ.pop(config.DATA_ENV_VAR, None)
 
+    def test_mcp_doctor_json_reports_ok_status(self):
+        doctor_payload = {
+            "status": "ok",
+            "checks": [
+                {"name": "saved_login", "ok": True, "required": True, "message": "Saved login found."},
+                {"name": "mcp_catalog", "ok": True, "required": True, "message": "MCP catalog loaded."},
+            ],
+            "summary": {"mcp_catalog": {"tools": 17}},
+            "next_steps": [],
+        }
+
+        with mock.patch("ventilatepro.mcp_cli.run_doctor", return_value=doctor_payload):
+            result = self.runner.invoke(app, ["mcp", "doctor", "--json"])
+
+        self.assertEqual(result.exit_code, 0)
+        payload = json.loads(result.stdout)
+        self.assertEqual(payload["status"], "ok")
+        self.assertEqual(payload["summary"]["mcp_catalog"]["tools"], 17)
+
+    def test_mcp_doctor_exits_nonzero_on_required_failure(self):
+        doctor_payload = {
+            "status": "failed",
+            "checks": [
+                {"name": "saved_login", "ok": False, "required": True, "message": "Run login first."},
+            ],
+            "summary": {},
+            "next_steps": ["Run login first."],
+        }
+
+        with mock.patch("ventilatepro.mcp_cli.run_doctor", return_value=doctor_payload):
+            result = self.runner.invoke(app, ["mcp", "doctor"])
+
+        self.assertEqual(result.exit_code, 1)
+        self.assertIn("FAIL saved_login", result.output)
+
     def test_notes_create_queues_on_network_error(self):
         with tempfile.TemporaryDirectory() as tmpdir:
             os.environ[config.CONFIG_ENV_VAR] = tmpdir
@@ -286,3 +321,238 @@ class CliTests(unittest.TestCase):
             tags=["field", "urgent"],
             query="terminal",
         )
+
+    def test_projects_list_json_outputs_paginated_payload(self):
+        fake_client = mock.Mock()
+        fake_client.projects_list.return_value = {
+            "count": 1,
+            "limit": 20,
+            "offset": 0,
+            "results": [
+                {
+                    "id": 1,
+                    "name": "CLI Project",
+                }
+            ],
+        }
+
+        with mock.patch.object(auth, "get_authenticated_client", return_value=(fake_client, "http://localhost:8000")):
+            result = self.runner.invoke(app, ["projects", "list", "--json"])
+
+        self.assertEqual(result.exit_code, 0)
+        payload = json.loads(result.stdout)
+        self.assertEqual(payload["results"][0]["name"], "CLI Project")
+        fake_client.projects_list.assert_called_once_with(limit=20, offset=0, query=None)
+
+    def test_projects_show_calls_api_client(self):
+        fake_client = mock.Mock()
+        fake_client.project_show.return_value = {
+            "id": 7,
+            "name": "Hospital South Wing",
+            "counts": {"rooms": 3, "zones": 2, "ahus": 1},
+            "location": "Los Angeles",
+            "time_zone": "America/Los_Angeles",
+        }
+
+        with mock.patch.object(auth, "get_authenticated_client", return_value=(fake_client, "http://localhost:8000")):
+            result = self.runner.invoke(app, ["projects", "show", "7"])
+
+        self.assertEqual(result.exit_code, 0)
+        self.assertIn("Hospital South Wing", result.stdout)
+        fake_client.project_show.assert_called_once_with(7)
+
+    def test_projects_create_reads_json_payload_from_inline_data(self):
+        fake_client = mock.Mock()
+        fake_client.project_create.return_value = {
+            "operation": "created",
+            "project": {"id": 9, "name": "CLI Write Project"},
+        }
+
+        with mock.patch.object(auth, "get_authenticated_client", return_value=(fake_client, "http://localhost:8000")):
+            result = self.runner.invoke(
+                app,
+                ["projects", "create", "--data", '{"name":"CLI Write Project","time_zone":"America/Los_Angeles"}', "--json"],
+            )
+
+        self.assertEqual(result.exit_code, 0)
+        fake_client.project_create.assert_called_once_with(
+            {"name": "CLI Write Project", "time_zone": "America/Los_Angeles"}
+        )
+
+    def test_notes_update_passes_patch_payload_to_api_client(self):
+        fake_client = mock.Mock()
+        fake_client.update_note.return_value = {
+            "operation": "updated",
+            "note": {"note_ref": "general-info:1"},
+        }
+
+        with mock.patch.object(auth, "get_authenticated_client", return_value=(fake_client, "http://localhost:8000")):
+            result = self.runner.invoke(
+                app,
+                [
+                    "notes",
+                    "update",
+                    "general-info:1",
+                    "--project",
+                    "1",
+                    "--title",
+                    "Updated note",
+                    "--tags",
+                    "field,urgent",
+                    "--json",
+                ],
+            )
+
+        self.assertEqual(result.exit_code, 0)
+        fake_client.update_note.assert_called_once_with(
+            "general-info:1",
+            project=1,
+            payload={"title": "Updated note", "tags": ["field", "urgent"]},
+        )
+
+    def test_rooms_delete_requires_yes_confirmation(self):
+        fake_client = mock.Mock()
+
+        with mock.patch.object(auth, "get_authenticated_client", return_value=(fake_client, "http://localhost:8000")):
+            result = self.runner.invoke(app, ["rooms", "delete", "12"])
+
+        self.assertNotEqual(result.exit_code, 0)
+        self.assertIn("requires --yes", result.output)
+        fake_client.delete_room.assert_not_called()
+
+    def test_rooms_list_passes_filters_to_api_client(self):
+        fake_client = mock.Mock()
+        fake_client.list_rooms.return_value = {
+            "project_id": 1,
+            "count": 0,
+            "limit": 5,
+            "offset": 10,
+            "results": [],
+        }
+
+        with mock.patch.object(auth, "get_authenticated_client", return_value=(fake_client, "http://localhost:8000")):
+            result = self.runner.invoke(
+                app,
+                [
+                    "rooms",
+                    "list",
+                    "--project",
+                    "1",
+                    "--limit",
+                    "5",
+                    "--offset",
+                    "10",
+                    "--query",
+                    "operating",
+                    "--json",
+                ],
+            )
+
+        self.assertEqual(result.exit_code, 0)
+        fake_client.list_rooms.assert_called_once_with(1, limit=5, offset=10, query="operating")
+
+    def test_terminal_units_create_includes_zone_in_payload(self):
+        fake_client = mock.Mock()
+        fake_client.create_terminal_unit.return_value = {
+            "operation": "created",
+            "terminal_unit": {"id": 3, "tag": "TU-CLI"},
+        }
+
+        with mock.patch.object(auth, "get_authenticated_client", return_value=(fake_client, "http://localhost:8000")):
+            result = self.runner.invoke(
+                app,
+                [
+                    "terminal-units",
+                    "create",
+                    "--zone",
+                    "7",
+                    "--data",
+                    '{"tag":"TU-CLI","unit_type":"FCU"}',
+                    "--json",
+                ],
+            )
+
+        self.assertEqual(result.exit_code, 0)
+        fake_client.create_terminal_unit.assert_called_once_with(
+            {"zone": 7, "tag": "TU-CLI", "unit_type": "FCU"}
+        )
+
+    def test_zones_bulk_assign_ahu_accepts_assignment_list(self):
+        fake_client = mock.Mock()
+        fake_client.assign_zones_to_ahu.return_value = {
+            "operation": "assigned",
+            "updated": 2,
+            "errors": 0,
+        }
+
+        with mock.patch.object(auth, "get_authenticated_client", return_value=(fake_client, "http://localhost:8000")):
+            result = self.runner.invoke(
+                app,
+                [
+                    "zones",
+                    "bulk-assign-ahu",
+                    "--project",
+                    "1",
+                    "--data",
+                    '[{"zone_id":1,"ahu_id":2},{"zone_id":3,"ahu_id":2}]',
+                    "--json",
+                ],
+            )
+
+        self.assertEqual(result.exit_code, 0)
+        fake_client.assign_zones_to_ahu.assert_called_once_with(
+            {
+                "project": 1,
+                "assignments": [
+                    {"zone_id": 1, "ahu_id": 2},
+                    {"zone_id": 3, "ahu_id": 2},
+                ],
+            }
+        )
+
+    def test_calc_recalculate_stale_passes_mode_scope_and_force(self):
+        fake_client = mock.Mock()
+        fake_client.calc_recalculate_stale.return_value = {
+            "message": "Queued stale recalculation.",
+        }
+
+        with mock.patch.object(auth, "get_authenticated_client", return_value=(fake_client, "http://localhost:8000")):
+            result = self.runner.invoke(
+                app,
+                [
+                    "calc",
+                    "recalculate-stale",
+                    "--project",
+                    "1",
+                    "--scope",
+                    "zones",
+                    "--mode",
+                    "sync",
+                    "--force",
+                    "--json",
+                ],
+            )
+
+        self.assertEqual(result.exit_code, 0)
+        fake_client.calc_recalculate_stale.assert_called_once_with(1, scope="zones", mode="sync", force=True)
+
+    def test_design_day_run_reads_json_payload_from_file(self):
+        fake_client = mock.Mock()
+        fake_client.design_day_run.return_value = {
+            "id": 42,
+            "state": "QUEUED",
+        }
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            payload_path = os.path.join(tmpdir, "design-day-request.json")
+            with open(payload_path, "w", encoding="utf-8") as handle:
+                json.dump({"zones": [{"zone_id": 1}]}, handle)
+
+            with mock.patch.object(auth, "get_authenticated_client", return_value=(fake_client, "http://localhost:8000")):
+                result = self.runner.invoke(
+                    app,
+                    ["design-day", "run", "--project", "1", "--input", payload_path, "--json"],
+                )
+
+        self.assertEqual(result.exit_code, 0)
+        fake_client.design_day_run.assert_called_once_with(1, {"zones": [{"zone_id": 1}]})

ventilatepro_cli-0.3.0/tests/test_mcp_server.py

@@ -0,0 +1,73 @@
+import asyncio
+import unittest
+from unittest import mock
+
+from ventilatepro.mcp_server import _requires_confirmation, build_server
+
+
+class FakeClient:
+    def __init__(self):
+        self.calls = []
+
+    def schemas(self):
+        return {"schemas": {"api_request": {"description": "ok"}}}
+
+    def schema(self, schema_key):
+        return {"key": schema_key}
+
+    def auth_me(self):
+        return {"username": "agent", "scopes": ["projects:read"]}
+
+    def projects_list(self, *, limit=20, offset=0, query=None):
+        return {"count": 0, "limit": limit, "offset": offset, "query": query, "results": []}
+
+    def cli_proxy(self, method, api_path, *, json_payload=None, params=None):
+        self.calls.append((method, api_path, json_payload, params))
+        return {"method": method, "path": api_path, "payload": json_payload, "params": params}
+
+
+class McpServerTests(unittest.TestCase):
+    def test_tool_catalog_contains_core_tools(self):
+        async def run():
+            server = build_server()
+            tools = await server.list_tools()
+            names = {tool.name for tool in tools}
+            self.assertIn("vp_whoami", names)
+            self.assertIn("vp_api_request", names)
+            self.assertIn("vp_list_entities", names)
+            self.assertIn("vp_run_workflow", names)
+
+        asyncio.run(run())
+
+    def test_api_request_tool_uses_cli_proxy(self):
+        async def run():
+            server = build_server()
+            fake_client = FakeClient()
+            with mock.patch(
+                "ventilatepro.mcp_server.auth.get_authenticated_client",
+                return_value=(fake_client, "http://localhost:8000"),
+            ):
+                _content, structured = await server.call_tool(
+                    "vp_api_request",
+                    {
+                        "method": "GET",
+                        "path": "projects/1/",
+                        "params": {"include": "summary"},
+                    },
+                )
+
+            self.assertEqual(structured["result"]["path"], "projects/1/")
+            self.assertEqual(fake_client.calls[0], ("GET", "projects/1/", None, {"include": "summary"}))
+
+        asyncio.run(run())
+
+    def test_guarded_operations_require_confirmation(self):
+        self.assertTrue(_requires_confirmation("DELETE", "rooms/1/", None))
+        self.assertTrue(_requires_confirmation("POST", "projects/1/recalculate-stale/", {}))
+        self.assertTrue(_requires_confirmation("POST", "projects/1/design-day/run/", {}))
+        self.assertTrue(_requires_confirmation("PATCH", "projects/1/", {"force": True}))
+        self.assertFalse(_requires_confirmation("GET", "projects/1/", None))
+
+
+if __name__ == "__main__":
+    unittest.main()

{ventilatepro_cli-0.1.1 → ventilatepro_cli-0.3.0}/ventilatepro/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.1"
+__version__ = "0.3.0"