netbox-rack-design-mcp 0.1.0__tar.gz

netbox_rack_design_mcp-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Petr Voronov
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

netbox_rack_design_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: netbox-rack-design-mcp
+Version: 0.1.0
+Summary: Read-only MCP server for the netbox-rack-design plugin: execution plan, simulation and smart-hands work orders for Claude.
+Author-email: Petr Voronov <ravenrs@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Source, https://github.com/ravenrs/netbox-rack-design
+Keywords: netbox,netbox-plugin,mcp,claude
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp[cli]<2,>=1.2
+Requires-Dist: httpx>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# netbox-rack-design-mcp
+
+Read-only MCP server (stdio) for the [netbox-rack-design](https://github.com/ravenrs/netbox-rack-design)
+NetBox plugin. Set `NETBOX_URL` and `NETBOX_TOKEN`, then run `netbox-rack-design-mcp`.
+Setup for Claude Desktop and Claude Code: see `docs/mcp.md` in the plugin repository.

netbox_rack_design_mcp-0.1.0/README.md

@@ -0,0 +1,5 @@
+# netbox-rack-design-mcp
+
+Read-only MCP server (stdio) for the [netbox-rack-design](https://github.com/ravenrs/netbox-rack-design)
+NetBox plugin. Set `NETBOX_URL` and `NETBOX_TOKEN`, then run `netbox-rack-design-mcp`.
+Setup for Claude Desktop and Claude Code: see `docs/mcp.md` in the plugin repository.

netbox_rack_design_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "netbox-rack-design-mcp"
+version = "0.1.0"
+description = "Read-only MCP server for the netbox-rack-design plugin: execution plan, simulation and smart-hands work orders for Claude."
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{name = "Petr Voronov", email = "ravenrs@gmail.com"}]
+keywords = ["netbox", "netbox-plugin", "mcp", "claude"]
+requires-python = ">=3.10"
+dependencies = [
+    "mcp[cli]>=1.2,<2",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.urls]
+Source = "https://github.com/ravenrs/netbox-rack-design"
+
+[project.scripts]
+netbox-rack-design-mcp = "netbox_rack_design_mcp.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

netbox_rack_design_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

netbox_rack_design_mcp-0.1.0/src/netbox_rack_design_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Read-only MCP server for the netbox-rack-design NetBox plugin."""
+
+__version__ = "0.1.0"

netbox_rack_design_mcp-0.1.0/src/netbox_rack_design_mcp/client.py

@@ -0,0 +1,58 @@
+"""Thin NetBox REST client. The token is only ever put in the Authorization header."""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+
+API_ROOT = "/api/plugins/rack-design"
+
+
+class NetBoxError(RuntimeError):
+    """A NetBox call failed. The message never contains the token."""
+
+
+def auth_header(token: str) -> str:
+    # NetBox 4.5+ v2 tokens look like "nbt_<key>.<secret>" and use Bearer;
+    # older (v1) tokens use the "Token" scheme.
+    return f"Bearer {token}" if token.startswith("nbt_") else f"Token {token}"
+
+
+class NetBoxClient:
+    def __init__(self, url: str, token: str, *, transport: httpx.BaseTransport | None = None,
+                 verify: bool = True, timeout: float = 60.0):
+        self._http = httpx.Client(
+            base_url=url.rstrip("/"),
+            headers={"Authorization": auth_header(token), "Accept": "application/json"},
+            transport=transport,
+            verify=verify,
+            timeout=timeout,
+        )
+
+    @classmethod
+    def from_env(cls) -> NetBoxClient:
+        url = os.environ.get("NETBOX_URL", "").strip()
+        token = os.environ.get("NETBOX_TOKEN", "").strip()
+        if not url or not token:
+            raise NetBoxError("Set NETBOX_URL and NETBOX_TOKEN in the MCP server environment.")
+        verify = os.environ.get("NETBOX_VERIFY_SSL", "true").strip().lower() not in ("0", "false", "no")
+        return cls(url, token, verify=verify)
+
+    def request(self, method: str, path: str, *, params=None, json=None):
+        clean = {k: v for k, v in (params or {}).items() if v is not None}
+        try:
+            resp = self._http.request(method, f"{API_ROOT}/{path}", params=clean, json=json)
+        except httpx.HTTPError as exc:
+            raise NetBoxError(f"NetBox request failed: {type(exc).__name__}") from None
+        if resp.status_code >= 400:
+            raise NetBoxError(f"NetBox answered {resp.status_code} for {method} {path}: {resp.text[:500]}")
+        if "json" in resp.headers.get("content-type", ""):
+            return resp.json()
+        return resp.text
+
+    def get(self, path: str, **params):
+        return self.request("GET", path, params=params)
+
+    def post(self, path: str, body):
+        return self.request("POST", path, json=body)

netbox_rack_design_mcp-0.1.0/src/netbox_rack_design_mcp/server.py

@@ -0,0 +1,293 @@
+"""FastMCP stdio server. Read-only: nothing here changes a design in NetBox."""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+
+from mcp.server.fastmcp import FastMCP
+
+from .client import NetBoxClient
+
+# stdout carries the MCP protocol; every log line goes to stderr.
+logging.basicConfig(stream=sys.stderr, level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+logging.getLogger("httpx").setLevel(logging.WARNING)  # its request lines would show URLs
+log = logging.getLogger("netbox_rack_design_mcp")
+
+DEFAULT_TICKET_FORMAT = """\
+DEFAULT SMART-HANDS TICKET FORMAT (use it only when the user gave no format of their own):
+1. Header: design, step (number and title), site, rack(s), maintenance window.
+2. Safety notes: power headroom per rack from the simulation ("R12 peaks at 6.7/8 kW"),
+   devices that stay live, the PDU and bank touched, any problems the plan reports.
+3. Numbered actions in the order given, each with device, from/to rack and U, serial and
+   asset tag, power: for a move or add, "Unplug from" power_from (the current PDU outlets) and
+   "Plug into" power_to (the target rack's PDU and bank; the outlet is "any free outlet"
+   when no cable is planned).
+4. A photo or check per action (for example "photo of R12 front after U20 is installed").
+5. A rollback line: how to undo the step if something goes wrong.
+6. What to report back: serials, photos, any deviation from the plan."""
+
+mcp = FastMCP("rack-design")
+
+_client: NetBoxClient | None = None
+
+
+def get_client() -> NetBoxClient:
+    global _client
+    if _client is None:
+        _client = NetBoxClient.from_env()
+    return _client
+
+
+def set_client(client: NetBoxClient | None) -> None:
+    """Install a ready client (tests)."""
+    global _client
+    _client = client
+
+
+@mcp.tool()
+def list_designs(site: str | None = None, status: str | None = None) -> dict:
+    """List rack designs. Read-only.
+
+    site: site slug to filter by (for example "ams1"). status: design status
+    (for example "draft", "approved", "implemented")."""
+    data = get_client().get("designs/", site=site, status=status, limit=100)
+    return {
+        "count": data["count"],
+        "designs": [
+            {k: d.get(k) for k in ("id", "title", "status", "sites", "version", "url", "description")}
+            for d in data["results"]
+        ],
+    }
+
+
+@mcp.tool()
+def get_design(design_id: int) -> dict:
+    """Get one design with all its fields. Read-only."""
+    return get_client().get(f"designs/{design_id}/")
+
+
+def _saved_order(placements: list[dict]) -> dict[int, list[tuple[int, int]]]:
+    """Placement ids per step, in saved order. Blades follow their chassis and are not listed."""
+    by_step: dict[int, list[tuple[int, int]]] = {}
+    for p in placements:
+        step = p.get("step")
+        if not step or p.get("parent_placement") or p.get("base_parent_placement"):
+            continue
+        by_step.setdefault(step["index"], []).append((p.get("step_order") or 0, p["id"]))
+    return by_step
+
+
+def _prune(value):
+    """Drop null / empty values (False and 0 stay): they carry no information for a ticket."""
+    if isinstance(value, dict):
+        out = {k: _prune(v) for k, v in value.items()}
+        return {k: v for k, v in out.items() if v is not None and v != [] and v != {} and v != ""}
+    if isinstance(value, list):
+        return [_prune(v) for v in value]
+    return value
+
+
+_BAD_BANK_STATES = ("warn", "critical", "overload")
+
+
+def _where(loc: dict | None) -> dict | None:
+    """A from/to location reduced to rack, U, face (and chassis/bay for a blade)."""
+    if not loc:
+        return None
+    out = {k: loc.get(k) for k in ("rack", "position", "face", "chassis", "bay") if loc.get(k)}
+    if "position" in out:
+        out["u"] = out.pop("position")
+    return out or None
+
+
+def _action_summary(act: dict) -> dict:
+    out = {
+        "placement_id": act.get("placement_id"),
+        "kind": act.get("kind"),
+        "device": (act.get("device") or {}).get("name"),
+        "from": _where(act.get("from")),
+        "to": _where(act.get("to")),
+    }
+    if act.get("children"):
+        out["blades"] = [(c.get("device") or {}).get("name") for c in act["children"]]
+    return out
+
+
+def _lookup(client: NetBoxClient, design_id: int) -> tuple[dict, dict, list]:
+    """(rack key -> name, placement id -> compact action, unscheduled compact actions),
+    from the saved work order."""
+    order = client.get(f"designs/{design_id}/work-order/", output="json")
+    names: dict[str, str] = {}
+    actions: dict[int, dict] = {}
+    for s in order.get("steps", []):
+        for row in s.get("power", []):
+            names[row["key"]] = row["rack"]
+        for act in s.get("actions", []):
+            actions[act["placement_id"]] = _action_summary(act)
+    unscheduled = [_action_summary(a) for a in order.get("unscheduled", [])]
+    for a in unscheduled:
+        actions[a["placement_id"]] = a
+    return names, actions, unscheduled
+
+
+def _compact_sim(entry: dict, names: dict[str, str]) -> dict:
+    """One simulated step: per rack draw/capacity/util/state, only the hot banks, problems."""
+    racks, problems = [], []
+    for key, data in sorted((entry.get("racks") or {}).items(), key=lambda kv: names.get(kv[0], kv[0])):
+        name = names.get(key, key)
+        power = data.get("power") or {}
+        banks = []
+        for pdu_name, pdu in ((data.get("distribution") or {}).get("pdus") or {}).items():
+            for bank_id, bank in (pdu.get("banks") or {}).items():
+                if bank.get("state") in _BAD_BANK_STATES:
+                    banks.append({
+                        "pdu": pdu_name, "bank": bank_id, "state": bank["state"],
+                        "load_w": round((bank.get("allocated_power") or 0) + (bank.get("planned_power") or 0)),
+                        "limit_w": round(bank.get("max_power") or 0),
+                        "pct": round(bank.get("util_pct") or 0),
+                    })
+        racks.append({
+            "rack": name,
+            "draw_w": round(power.get("draw_w") or 0),
+            "capacity_w": round(power.get("capacity_w") or 0),
+            "util_pct": round(power.get("util_pct") or 0),
+            "state": power.get("state") or "",
+            "hot_banks": banks,
+        })
+        # keep EVERY problem (bank_over / bank_near too); hot_banks is extra detail.
+        problems += [
+            {"rack": name, "code": p.get("code"), "severity": p.get("severity"), "detail": p.get("detail")}
+            for p in data.get("problems") or []
+        ]
+    return {"racks": racks, "problems": problems}
+
+
+@mcp.tool(
+    description=(
+        "Get a design's execution plan as a COMPACT SUMMARY: per step its index, title and "
+        "actions (kind, device, from/to rack and U), plus the simulated power of each touched "
+        "rack (draw_w, capacity_w, util_pct, state), only the PDU banks that are warn/critical/"
+        "overload (hot_banks), and the problems found (code, severity, detail). Raw "
+        "distribution and per-outlet data are left out. Call it with detail=true ONLY when you "
+        "need the full simulation payload (every bank and outlet); that answer is very large "
+        "(>100k characters). For a technician ticket use get_work_order instead. Read-only. "
+        "This tool makes one POST (simulate-steps) with the SAVED order; that POST only "
+        "computes the simulation and changes nothing in NetBox."
+    )
+)
+def get_execution_plan(design_id: int, detail: bool = False) -> dict:
+    client = get_client()
+    steps = sorted(client.get("design-steps/", design_id=design_id, limit=0)["results"],
+                   key=lambda s: s["index"])
+    placements = client.get("placements/", design_id=design_id, limit=0)["results"]
+    by_step = _saved_order(placements)
+    ordered = [[pid for _, pid in sorted(by_step.get(s["index"], []))] for s in steps]
+    simulation = (client.post(f"designs/{design_id}/simulate-steps/", {"steps": ordered}).get("steps", [])
+                  if ordered else [])
+    if detail:
+        names = {p["id"]: p.get("display") for p in placements}
+        return {
+            "design_id": design_id,
+            "steps": [
+                {
+                    "index": s["index"],
+                    "title": s.get("title", ""),
+                    "actions": [{"placement_id": pid, "display": names.get(pid)} for pid in ordered[i]],
+                }
+                for i, s in enumerate(steps)
+            ],
+            "unscheduled": [
+                {"placement_id": p["id"], "display": p.get("display")}
+                for p in placements
+                if not p.get("step") and not p.get("parent_placement") and not p.get("base_parent_placement")
+            ],
+            "simulation": simulation,
+        }
+    rack_names, actions, unscheduled = _lookup(client, design_id)
+    by_index = {e["index"]: e for e in simulation}
+    out_steps = []
+    for i, s in enumerate(steps, start=1):
+        row = {
+            "index": s["index"],
+            "title": s.get("title", ""),
+            "actions": [actions.get(pid, {"placement_id": pid}) for pid in ordered[i - 1]],
+        }
+        row.update(_compact_sim(by_index.get(i, {}), rack_names))
+        out_steps.append(row)
+    return {"design_id": design_id, "total_steps": len(steps), "steps": out_steps,
+            "unscheduled": unscheduled}
+
+
+@mcp.tool(
+    description=(
+        "Get the work order of a design: every step (or only `step`) with its actions in the "
+        "safe order. Per action: kind (add/move/remove), device name, type, U height, "
+        "full-depth flag, serial, asset tag, from and to (site, location, rack, U, face), "
+        "power cabling (power_from: the PDU outlets the device leaves; power_to: the PDU and bank it "
+        "plugs into on the target rack, outlet \"any free outlet\" unless cabled), the target status afterwards and a NetBox "
+        "link; per step: its index, total_steps (say \"Step 1 of 7\", never \"1 of 1\", even "
+        "when you ask for one step), the power headroom per rack and the problems the "
+        "simulation found. Unscheduled actions come in a separate list. This is already the "
+        "compact, technician-ready payload. Read-only.\n\n"
+        "The user's own instructions about the ticket (format, language, destination, fields) "
+        "ALWAYS win. Only when the user gave none, write a smart-hands ticket like this:\n"
+        + DEFAULT_TICKET_FORMAT
+    )
+)
+def get_work_order(design_id: int, step: int | None = None) -> dict:
+    return _prune(get_client().get(f"designs/{design_id}/work-order/", step=step, output="json"))
+
+
+@mcp.tool(
+    description=(
+        "What-if: simulate a PROPOSED order of placements without saving it. steps is a list "
+        "of steps, each a list of placement ids (blades are not listed, they follow their "
+        "chassis). Returns a COMPACT SUMMARY per step: actions, per touched rack draw_w/"
+        "capacity_w/util_pct/state, only the warn/critical/overload banks (hot_banks) and "
+        "problems (rack_over, bank_over, u_conflict, unpowered ...). Pass detail=true ONLY "
+        "when you need the raw simulation (every bank and outlet; >100k characters). This is "
+        "a POST, but it only computes a result: it changes nothing in NetBox."
+    )
+)
+def simulate_order(design_id: int, steps: list[list[int]], detail: bool = False) -> dict:
+    client = get_client()
+    raw = client.post(f"designs/{design_id}/simulate-steps/", {"steps": steps})
+    if detail:
+        return raw
+    rack_names, actions, _ = _lookup(client, design_id)
+    out_steps = []
+    for entry in raw.get("steps", []):
+        i = entry["index"]
+        row = {
+            "index": i,
+            "actions": [actions.get(pid, {"placement_id": pid}) for pid in (steps[i - 1] if i <= len(steps) else [])],
+        }
+        row.update(_compact_sim(entry, rack_names))
+        out_steps.append(row)
+    return {"design_id": design_id, "total_steps": len(steps), "steps": out_steps}
+
+
+@mcp.prompt()
+def smart_hands_ticket(design_id: int, step: int, instructions: str = "") -> str:
+    """Write a smart-hands ticket for one step of a design's plan (Claude Code)."""
+    order = _prune(get_client().get(f"designs/{design_id}/work-order/", step=step, output="json"))
+    if instructions.strip():
+        rules = ("Follow these instructions from the user for the ticket; they replace any "
+                 "default format:\n" + instructions.strip())
+    else:
+        rules = "The user gave no format. " + DEFAULT_TICKET_FORMAT
+    return (
+        f"Write a smart-hands ticket for step {step} of design {design_id}.\n\n{rules}\n\n"
+        f"Work order (JSON):\n{json.dumps(order, indent=2)}"
+    )
+
+
+def main() -> None:
+    log.info("starting netbox-rack-design-mcp (stdio)")
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

netbox_rack_design_mcp-0.1.0/src/netbox_rack_design_mcp.egg-info/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: netbox-rack-design-mcp
+Version: 0.1.0
+Summary: Read-only MCP server for the netbox-rack-design plugin: execution plan, simulation and smart-hands work orders for Claude.
+Author-email: Petr Voronov <ravenrs@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Source, https://github.com/ravenrs/netbox-rack-design
+Keywords: netbox,netbox-plugin,mcp,claude
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp[cli]<2,>=1.2
+Requires-Dist: httpx>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# netbox-rack-design-mcp
+
+Read-only MCP server (stdio) for the [netbox-rack-design](https://github.com/ravenrs/netbox-rack-design)
+NetBox plugin. Set `NETBOX_URL` and `NETBOX_TOKEN`, then run `netbox-rack-design-mcp`.
+Setup for Claude Desktop and Claude Code: see `docs/mcp.md` in the plugin repository.

netbox_rack_design_mcp-0.1.0/src/netbox_rack_design_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/netbox_rack_design_mcp/__init__.py
+src/netbox_rack_design_mcp/client.py
+src/netbox_rack_design_mcp/server.py
+src/netbox_rack_design_mcp.egg-info/PKG-INFO
+src/netbox_rack_design_mcp.egg-info/SOURCES.txt
+src/netbox_rack_design_mcp.egg-info/dependency_links.txt
+src/netbox_rack_design_mcp.egg-info/entry_points.txt
+src/netbox_rack_design_mcp.egg-info/requires.txt
+src/netbox_rack_design_mcp.egg-info/top_level.txt
+tests/test_tools.py

netbox_rack_design_mcp-0.1.0/src/netbox_rack_design_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

netbox_rack_design_mcp-0.1.0/src/netbox_rack_design_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+netbox-rack-design-mcp = netbox_rack_design_mcp.server:main

netbox_rack_design_mcp-0.1.0/src/netbox_rack_design_mcp.egg-info/requires.txt

@@ -0,0 +1,5 @@
+mcp[cli]<2,>=1.2
+httpx>=0.27
+
+[test]
+pytest>=8

netbox_rack_design_mcp-0.1.0/src/netbox_rack_design_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+netbox_rack_design_mcp

netbox_rack_design_mcp-0.1.0/tests/test_tools.py

@@ -0,0 +1,241 @@
+import json
+
+import httpx
+import pytest
+
+from netbox_rack_design_mcp import server
+from netbox_rack_design_mcp.client import NetBoxClient, NetBoxError, auth_header
+
+TOKEN = "s3cret-token-value"
+
+
+class Recorder:
+    def __init__(self, routes):
+        self.routes = routes  # {(method, path): json-able or callable}
+        self.calls = []
+
+    def __call__(self, request: httpx.Request) -> httpx.Response:
+        self.calls.append(request)
+        key = (request.method, request.url.path)
+        if key not in self.routes:
+            return httpx.Response(404, json={"detail": "not found"})
+        body = self.routes[key]
+        return httpx.Response(200, json=body(request) if callable(body) else body)
+
+
+def install(routes):
+    rec = Recorder(routes)
+    server.set_client(NetBoxClient("https://nb.example", TOKEN, transport=httpx.MockTransport(rec)))
+    return rec
+
+
+@pytest.fixture(autouse=True)
+def _reset():
+    yield
+    server.set_client(None)
+
+
+API = "/api/plugins/rack-design/"
+
+
+def test_list_designs_passes_filters_and_trims():
+    rec = install({("GET", API + "designs/"): {
+        "count": 1, "results": [{"id": 3, "title": "Q3", "status": "draft", "sites": [], "extra": 1}]}})
+    out = server.list_designs(site="ams1", status="draft")
+    assert out["count"] == 1 and out["designs"][0]["title"] == "Q3"
+    assert "extra" not in out["designs"][0]
+    req = rec.calls[0]
+    assert req.url.params["site"] == "ams1" and req.url.params["status"] == "draft"
+
+
+def test_list_designs_omits_unset_filters():
+    rec = install({("GET", API + "designs/"): {"count": 0, "results": []}})
+    server.list_designs()
+    assert "site" not in rec.calls[0].url.params and "status" not in rec.calls[0].url.params
+
+
+def test_get_design():
+    install({("GET", API + "designs/7/"): {"id": 7, "title": "X"}})
+    assert server.get_design(7)["title"] == "X"
+
+
+def test_get_work_order_sends_step_and_json_format():
+    rec = install({("GET", API + "designs/7/work-order/"): {"steps": []}})
+    assert server.get_work_order(7, step=2) == {}
+    params = rec.calls[0].url.params
+    assert params["step"] == "2" and params["output"] == "json"
+
+
+def test_get_work_order_without_step_omits_it():
+    rec = install({("GET", API + "designs/7/work-order/"): {"steps": []}})
+    server.get_work_order(7)
+    assert "step" not in rec.calls[0].url.params
+
+
+def _plan_routes(n_steps=2):
+    """A realistic Rebalance-sized plan: n steps, 2 racks, 2 PDUs x 12 banks with outlets."""
+    steps = {"results": [{"index": i, "title": f"Window {i}"} for i in range(n_steps, 0, -1)]}
+    placements, wo_steps, sim_steps = [], [], []
+    for i in range(1, n_steps + 1):
+        pid = 100 + i
+        placements.append({"id": pid, "display": f"Move: srv-{i}", "step": {"index": i}, "step_order": 1})
+        wo_steps.append({
+            "index": i, "total_steps": n_steps,
+            "power": [{"rack": "A1", "key": "r:1"}, {"rack": "A2", "key": "r:2"}],
+            "actions": [{"placement_id": pid, "kind": "move", "device": {"name": f"srv-{i}", "serial": "S" * 40},
+                         "from": {"rack": "A1", "position": "10", "face": "front", "site": "FRA"},
+                         "to": {"rack": "A2", "position": "20", "face": "front", "site": "FRA"},
+                         "children": [], "power": {"cabling": [{"outlet": "o"}] * 4}}],
+        })
+        racks = {}
+        for key, name in (("r:1", "A1"), ("r:2", "A2")):
+            pdus = {}
+            for pdu in ("pdu-a", "pdu-b"):
+                banks = {}
+                for b in range(1, 13):
+                    banks[str(b)] = {
+                        "allocated_power": 100.0 * b, "planned_power": 0.0, "max_power": 1500.0,
+                        "util_pct": 100.0 * b / 1500 * 100, "state": "warn" if b == 12 else "ok",
+                        "outlets": {str(o): {"name": f"o{o}", "device": "x" * 30, "power": 12.5}
+                                    for o in range(1, 25)},
+                    }
+                pdus[pdu] = {"banks": banks}
+            racks[key] = {
+                "power": {"draw_w": 5000.4, "capacity_w": 8000, "util_pct": 62.5, "state": "ok"},
+                "distribution": {"pdus": pdus}, "distribution_status": {"state": "ok"},
+                "problems": [{"code": "rack_near", "severity": "warning", "detail": f"{name}: 5000 W of 8000 W"},
+                         {"code": "bank_near", "severity": "warning", "detail": "dup of hot_banks"}],
+            }
+        sim_steps.append({"index": i, "racks": racks})
+    placements.append({"id": 14, "display": "loose", "step": None})
+    routes = {
+        ("GET", API + "design-steps/"): steps,
+        ("GET", API + "placements/"): {"results": placements},
+        ("GET", API + "designs/5/work-order/"): {"steps": wo_steps, "unscheduled": [
+            {"placement_id": 14, "kind": "add", "device": {"name": "loose"}, "from": None,
+             "to": {"rack": "A1", "position": "5"}, "children": []}]},
+        ("POST", API + "designs/5/simulate-steps/"): {"steps": sim_steps},
+    }
+    return routes, sim_steps
+
+
+def test_get_execution_plan_posts_the_saved_order_and_is_compact():
+    routes, _ = _plan_routes(2)
+    rec = install(routes)
+    out = server.get_execution_plan(5)
+    post = [c for c in rec.calls if c.method == "POST"][0]
+    assert json.loads(post.content) == {"steps": [[101], [102]]}
+    assert [s["index"] for s in out["steps"]] == [1, 2] and out["total_steps"] == 2
+    step = out["steps"][0]
+    assert step["title"] == "Window 1"
+    assert step["actions"] == [{
+        "placement_id": 101, "kind": "move", "device": "srv-1",
+        "from": {"rack": "A1", "face": "front", "u": "10"},
+        "to": {"rack": "A2", "face": "front", "u": "20"}}]
+    a1 = step["racks"][0]
+    assert (a1["rack"], a1["draw_w"], a1["capacity_w"], a1["util_pct"], a1["state"]) == ("A1", 5000, 8000, 62, "ok")
+    assert len(a1["hot_banks"]) == 2 and a1["hot_banks"][0]["bank"] == "12"
+    assert set(a1["hot_banks"][0]) == {"pdu", "bank", "state", "load_w", "limit_w", "pct"}
+    assert step["problems"][0] == {"rack": "A1", "code": "rack_near", "severity": "warning",
+                                   "detail": "A1: 5000 W of 8000 W"}
+    # every problem is kept, bank_near included; hot_banks is extra detail
+    assert [p["code"] for p in step["problems"]] == ["rack_near", "bank_near", "rack_near", "bank_near"]
+    assert [u["placement_id"] for u in out["unscheduled"]] == [14]
+    assert "distribution" not in json.dumps(out) and "outlets" not in json.dumps(out)
+
+
+def test_get_execution_plan_detail_returns_the_full_simulation():
+    routes, sim = _plan_routes(2)
+    install(routes)
+    out = server.get_execution_plan(5, detail=True)
+    assert out["simulation"] == sim
+    assert [a["placement_id"] for a in out["steps"][0]["actions"]] == [101]
+    assert [u["placement_id"] for u in out["unscheduled"]] == [14]
+
+
+def test_compact_plan_of_a_rebalance_sized_design_stays_small():
+    routes, _ = _plan_routes(7)
+    install(routes)
+    compact = len(json.dumps(server.get_execution_plan(5)))
+    full = len(json.dumps(server.get_execution_plan(5, detail=True)))
+    assert compact < 9000, compact
+    assert full > 10 * compact
+
+
+def test_simulate_order_is_compact_by_default_and_detail_gives_raw():
+    routes, sim = _plan_routes(7)
+    rec = install(routes)
+    out = server.simulate_order(5, [[101], [102]])
+    assert json.loads([c for c in rec.calls if c.method == "POST"][0].content) == {"steps": [[101], [102]]}
+    assert len(json.dumps(out)) < 9000
+    assert out["steps"][0]["racks"][1]["rack"] == "A2"
+    assert out["steps"][0]["actions"][0]["device"] == "srv-1"
+    assert server.simulate_order(5, [[101]], detail=True) == {"steps": sim}
+
+
+def test_http_error_is_reported_without_the_token():
+    install({})
+    with pytest.raises(NetBoxError) as exc:
+        server.get_design(1)
+    assert "404" in str(exc.value)
+    assert TOKEN not in str(exc.value)
+
+
+def test_token_only_in_authorization_header():
+    rec = install({("GET", API + "designs/1/"): {}})
+    server.get_design(1)
+    req = rec.calls[0]
+    assert req.headers["authorization"] == f"Token {TOKEN}"
+    assert TOKEN not in str(req.url)
+
+
+def test_v2_token_uses_bearer():
+    assert auth_header("nbt_abc.def") == "Bearer nbt_abc.def"
+    assert auth_header("plain") == "Token plain"
+
+
+def test_missing_env_is_a_clear_error(monkeypatch):
+    monkeypatch.delenv("NETBOX_URL", raising=False)
+    monkeypatch.delenv("NETBOX_TOKEN", raising=False)
+    with pytest.raises(NetBoxError, match="NETBOX_URL"):
+        NetBoxClient.from_env()
+
+
+def test_tools_are_registered_and_work_order_description_has_the_default_format():
+    import asyncio
+
+    tools = {t.name: t for t in asyncio.run(server.mcp.list_tools())}
+    assert set(tools) == {
+        "list_designs", "get_design", "get_execution_plan", "get_work_order", "simulate_order"}
+    desc = tools["get_work_order"].description
+    assert "ALWAYS win" in desc
+    for word in ("Header", "Safety notes", "photo", "rollback", "report back"):
+        assert word.lower() in desc.lower()
+    assert "changes nothing" in tools["simulate_order"].description
+    assert "changes nothing" in tools["get_execution_plan"].description
+    for name in ("get_execution_plan", "simulate_order"):
+        assert "COMPACT" in tools[name].description and "detail=true" in tools[name].description
+    assert "total_steps" in desc
+
+
+def test_prompt_uses_user_instructions_over_default():
+    install({("GET", API + "designs/5/work-order/"): {"steps": [{"index": 1}]}})
+    text = server.smart_hands_ticket(5, 1, instructions="Write it in Jira wiki markup.")
+    assert "Jira wiki markup" in text and "DEFAULT SMART-HANDS" not in text
+    assert '"index": 1' in text
+
+
+def test_prompt_falls_back_to_default_format():
+    install({("GET", API + "designs/5/work-order/"): {"steps": []}})
+    assert "DEFAULT SMART-HANDS" in server.smart_hands_ticket(5, 1)
+
+
+def test_work_order_drops_empty_values_but_keeps_false_and_zero():
+    install({("GET", API + "designs/7/work-order/"): {
+        "total_steps": 3, "steps": [{"index": 1, "total_steps": 3, "problems": [], "actions": [
+            {"placement_id": 1, "stale": False, "bay": None, "children": [], "to": {"u": 0, "face": ""}}]}]}})
+    out = server.get_work_order(7)
+    assert out["total_steps"] == 3 and out["steps"][0]["total_steps"] == 3
+    act = out["steps"][0]["actions"][0]
+    assert act == {"placement_id": 1, "stale": False, "to": {"u": 0}}
+    assert "problems" not in out["steps"][0]