vmware-debug 2.0.0__tar.gz → 2.1.0__tar.gz

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-debug",
   "displayName": "VMware Debug",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "VMware incident timeline, root-cause routing, local case ledger; no vSphere access. 14 MCP tools.",
   "author": {
     "name": "Wei Zhou",

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-debug==2.0.0",
+        "vmware-debug==2.1.0",
         "vmware-debug-mcp"
       ]
     }

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vmware-debug
-Version: 2.0.0
+Version: 2.1.0
 Summary: VMware diagnostic brain — offline incident triage, log/event correlation, and root-cause routing across the VMware skill family
 Project-URL: Homepage, https://github.com/vmware-skills/VMware-Debug
 Project-URL: Repository, https://github.com/vmware-skills/VMware-Debug
@@ -18,7 +18,7 @@ Requires-Dist: mcp[cli]<2.0,>=1.10
 Requires-Dist: pyyaml<7.0,>=6.0
 Requires-Dist: rich<15.0,>=13.0
 Requires-Dist: typer<1.0,>=0.12
-Requires-Dist: vmware-policy<2.0,>=1.18.1
+Requires-Dist: vmware-policy<2.0,>=1.20.0
 Description-Content-Type: text/markdown
 
 <!-- mcp-name: io.github.vmware-skills/vmware-debug -->
@@ -52,6 +52,23 @@ renames widened), and vmware-pilot ≥ 1.13 translates old names in saved workfl
 If an install older than 2.0 shares that `rules.yaml`, give it vmware-policy ≥ 1.18.2 too: it matches each rule
 against both the old and the new name, so one file serves both.
 
+## Companion Skills
+
+| Need | Skill |
+|---|---|
+| Incident correlation / root cause | **vmware-debug** (this project) |
+| Centralized log search | vmware-log-insight (feed its `search_logs` results here) |
+| vCenter events and alarms | vmware-monitor |
+| Metrics / anomalies | vmware-aria |
+| Executing a fix | vmware-aiops (single op) / vmware-pilot (multi-step, gated) |
+
+## Install
+
+```bash
+uv tool install vmware-debug
+vmware-debug categories          # see which symptom categories it can diagnose
+```
+
 ## MCP tools (14 — 7 read, 7 write)
 
 The seven writes go to the local case ledger only; none reaches a VMware system.
@@ -80,6 +97,26 @@ The seven writes go to the local case ledger only; none reaches a VMware system.
 | `grade_case` | [WRITE] Recompute the conclusion grade from the ledger and record it |
 | `close_case` | [WRITE] Record the final grade, archive, and name what was left open |
 
+**Event envelope**: `{ts, source, severity, entity, text, fields}`. The agent normalizes events from each source
+into this shape before handing them to debug, so debug has zero runtime dependency on the other packages.
+**Keep each event's `event_type` in `fields`** — the classifier matches it as well as the text, and most modern
+vSphere events are `EventEx`: the text is a generic boilerplate sentence, and only `eventTypeId` says what the
+event actually is.
+
+## Security
+
+Offline and credential-free by construction: it connects to no vCenter/NSX/Aria, has no destructive surface on
+VMware, and holds no secret to leak. The only writes are the local case ledger: evidence, gaps, hypotheses and
+grade history are append-only; `timeline.md` is regenerated from the evidence, and `case.json` holds the current
+grade and status. The same holds with several writers: every write to a case first takes that case's lock file
+(`.ledger.lock`, exclusive create), so two processes writing the same case in a shared `$OPS_HOME` are serialized
+instead of dropping each other's entries; every file is written under a temporary name and then moved into place,
+so a reader never sees a half-written file (on a file system without hard links, a new evidence file is instead
+created in place: still never overwritten, but it can be read half-written). A lock left behind by a crashed
+process is reported together with its holder and never deleted automatically; delete it by hand once you have
+confirmed no process is writing that case. Released versions 1.11.3 and earlier do not take this lock, so every
+machine sharing a case directory must upgrade. See [SECURITY.md](SECURITY.md).
+
 ## Offline / Air-Gapped Install (from source)
 
 This project uses the modern PEP 517 build system (hatchling), so there is **no

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/README-CN.md

@@ -10,6 +10,8 @@ VMware skill 家族的**诊断大脑**。你给出症状（报错、日志、变
 它**从不触碰 vSphere**——不连接任何东西，也从不执行修复；唯一的写入是 `$OPS_HOME` 下的本地案卷。修复一律路由给 vmware-aiops（单步）或
 vmware-pilot（多步、带审批门控），完全复刻 vmware-harden → vmware-pilot 的「顾问/执行」分工。
 
+完整的方法论、事件信封约定和症状路由见 [`skills/vmware-debug/SKILL.md`](skills/vmware-debug/SKILL.md)。
+
 ## 升级到 2.0
 
 2.0 把 14 个 MCP 工具中的 13 个改成动词在前（例如 `case_close` → `close_case`, `case_get` → `get_case`, `case_grade` → `grade_case`），完整的新旧名对照表见
@@ -42,7 +44,7 @@ vmware-debug categories          # 看它能诊断哪些症状类别
 **关联**——无状态，看一眼用：
 
 - `build_incident_timeline`：[READ] 把已取到的事件关联成 时间线 + 突刺 + 排序后的根因假设 + 下一步检查建议
-- `list_symptom_categories`：[READ] 症状类别及对应的排查路由（不知道查什么时用它）
+- `list_symptom_categories`：[READ] 列出能识别的症状类别 + 每类该查什么
 
 **调查案卷**——需要持续推理的事件：
 
@@ -75,6 +77,31 @@ debug；debug 因此与其它包零运行时依赖。**请把每条事件的 `ev
 确认没有进程在写该案卷后再手动删除。已发布的 1.11.3 及更早版本不拿这个锁，共享案卷目录的每台机器都要升级。
 详见 [SECURITY.md](SECURITY.md)。
 
+## 离线 / 隔离网络安装（从源码）
+
+本项目使用现代 PEP 517 构建系统（hatchling），所以**按设计就没有 `setup.py`**——这是预期行为，不是缺文件。
+如果你克隆了源码后遇到 `ERROR: File "setup.py" or "setup.cfg" not found ... editable mode
+currently requires a setuptools-based build`，说明你的 `pip` 低于 21.3，无法对非 setuptools 后端做*可编辑*（`-e`）安装。
+可编辑模式只是开发便利，运行这个工具并不需要——任选其一：
+
+```bash
+# 在源码目录里——普通（非可编辑）安装会构建 wheel：
+pip install .              # 不是  pip install -e .
+
+# ……或者先升级 pip，可编辑安装也能用：
+pip install --upgrade pip && pip install -e .
+```
+
+对于**真正隔离网络的主机**，在联网机器上构建 wheel 再拷过去——目标主机就不需要网络：
+
+```bash
+# 在联网机器上，把本包及其依赖收集成 wheel：
+pip wheel . -w dist        # → dist/*.whl   （或：uv build，只构建本包）
+
+# 把 dist/ 拷到隔离主机，然后离线安装：
+pip install --no-index --find-links dist vmware-debug
+```
+
 ## 许可证
 
 MIT。

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/README.md

@@ -29,6 +29,23 @@ renames widened), and vmware-pilot ≥ 1.13 translates old names in saved workfl
 If an install older than 2.0 shares that `rules.yaml`, give it vmware-policy ≥ 1.18.2 too: it matches each rule
 against both the old and the new name, so one file serves both.
 
+## Companion Skills
+
+| Need | Skill |
+|---|---|
+| Incident correlation / root cause | **vmware-debug** (this project) |
+| Centralized log search | vmware-log-insight (feed its `search_logs` results here) |
+| vCenter events and alarms | vmware-monitor |
+| Metrics / anomalies | vmware-aria |
+| Executing a fix | vmware-aiops (single op) / vmware-pilot (multi-step, gated) |
+
+## Install
+
+```bash
+uv tool install vmware-debug
+vmware-debug categories          # see which symptom categories it can diagnose
+```
+
 ## MCP tools (14 — 7 read, 7 write)
 
 The seven writes go to the local case ledger only; none reaches a VMware system.
@@ -57,6 +74,26 @@ The seven writes go to the local case ledger only; none reaches a VMware system.
 | `grade_case` | [WRITE] Recompute the conclusion grade from the ledger and record it |
 | `close_case` | [WRITE] Record the final grade, archive, and name what was left open |
 
+**Event envelope**: `{ts, source, severity, entity, text, fields}`. The agent normalizes events from each source
+into this shape before handing them to debug, so debug has zero runtime dependency on the other packages.
+**Keep each event's `event_type` in `fields`** — the classifier matches it as well as the text, and most modern
+vSphere events are `EventEx`: the text is a generic boilerplate sentence, and only `eventTypeId` says what the
+event actually is.
+
+## Security
+
+Offline and credential-free by construction: it connects to no vCenter/NSX/Aria, has no destructive surface on
+VMware, and holds no secret to leak. The only writes are the local case ledger: evidence, gaps, hypotheses and
+grade history are append-only; `timeline.md` is regenerated from the evidence, and `case.json` holds the current
+grade and status. The same holds with several writers: every write to a case first takes that case's lock file
+(`.ledger.lock`, exclusive create), so two processes writing the same case in a shared `$OPS_HOME` are serialized
+instead of dropping each other's entries; every file is written under a temporary name and then moved into place,
+so a reader never sees a half-written file (on a file system without hard links, a new evidence file is instead
+created in place: still never overwritten, but it can be read half-written). A lock left behind by a crashed
+process is reported together with its holder and never deleted automatically; delete it by hand once you have
+confirmed no process is writing that case. Released versions 1.11.3 and earlier do not take this lock, so every
+machine sharing a case directory must upgrade. See [SECURITY.md](SECURITY.md).
+
 ## Offline / Air-Gapped Install (from source)
 
 This project uses the modern PEP 517 build system (hatchling), so there is **no

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/RELEASE_NOTES.md

@@ -1,3 +1,20 @@
+## v2.1.0 — offer only read tools, plus chosen write tools
+
+`vmware-debug mcp` can now offer a subset of this server's tools (HLD §17 D-16, via vmware-policy 1.20.0):
+
+```bash
+vmware-debug mcp --expose read --allow-write close_case
+```
+
+* `--expose read` (or `VMWARE_DEBUG_MCP_EXPOSE=read`) keeps only tools annotated `readOnlyHint: true`; `--allow-write a,b`
+  (or `VMWARE_DEBUG_MCP_ALLOW_WRITE`) keeps chosen write tools on top. The default is unchanged: every tool.
+* A bad value, or a name that is not a write tool of this server, stops the server before it serves (exit 2).
+  Flags and environment variables are not mixed; a blank flag counts as not given. Pre-2.0 names are accepted.
+* This limits what clients are offered; it is not authorization. See "Limiting which tools are offered" in
+  `references/setup-guide.md`, which also notes that an agent with a shell can bypass MCP, so the account itself
+  must be least-privilege.
+* Requires `vmware-policy>=1.20.0`.
+
 ## v2.0.0 — MCP tools renamed verb-first
 
 Every MCP tool in the VMware skill family now follows one naming convention: the verb comes first

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/openclaw.plugin.json

@@ -11,7 +11,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-debug==2.0.0",
+        "vmware-debug==2.1.0",
         "vmware-debug-mcp"
       ]
     }

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zw008/vmware-debug",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "VMware incident timeline, root-cause routing, local case ledger; no vSphere access. 14 MCP tools.",
   "private": true,
   "license": "MIT",

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-debug"
-version = "2.0.0"
+version = "2.1.0"
 description = "VMware diagnostic brain — offline incident triage, log/event correlation, and root-cause routing across the VMware skill family"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,7 @@ dependencies = [
     "typer>=0.12,<1.0",
     "rich>=13.0,<15.0",
     "mcp[cli]>=1.10,<2.0",
-    "vmware-policy>=1.18.1,<2.0",
+    "vmware-policy>=1.20.0,<2.0",
     # Imported directly by ops/cases/grading.py for the rules file. It has
     # always arrived transitively via vmware-policy; a package should
     # declare what it imports rather than rely on a dependency's dependency.

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/vmware-skills/VMware-Debug",
     "source": "github"
   },
-  "version": "2.0.0",
+  "version": "2.1.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-debug",
-      "version": "2.0.0",
+      "version": "2.1.0",
       "runtimeHint": "uvx",
       "packageArguments": [
         {

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/skills/vmware-debug/SKILL.md

@@ -51,7 +51,7 @@ write tools touch only the local case ledger.
 ## Quick Install
 
 ```bash
-uv tool install vmware-debug==2.0.0
+uv tool install vmware-debug==2.1.0
 vmware-debug categories          # see what it can diagnose
 ```
 

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/skills/vmware-debug/references/setup-guide.md

@@ -6,7 +6,7 @@ is a pure, offline correlation engine. There is no `config.yaml` and no `.env`.
 ## Install
 
 ```bash
-uv tool install vmware-debug==2.0.0
+uv tool install vmware-debug==2.1.0
 vmware-debug categories      # verify it runs
 ```
 
@@ -15,7 +15,7 @@ vmware-debug categories      # verify it runs
 ```json
 {
   "command": "uvx",
-  "args": ["--from", "vmware-debug==2.0.0", "vmware-debug-mcp"]
+  "args": ["--from", "vmware-debug==2.1.0", "vmware-debug-mcp"]
 }
 ```
 
@@ -26,6 +26,31 @@ For full cross-skill diagnosis, also install the data-source skills it correlate
 (vmware-monitor, vmware-log-insight, vmware-aria, vmware-nsx) and the executors it
 routes fixes to (vmware-aiops, vmware-pilot).
 
+## Limiting which tools are offered
+
+By default the MCP server offers every tool. To offer only read tools, start it with `--expose read`, or set
+`VMWARE_DEBUG_MCP_EXPOSE=read` in the MCP client's `env` block (useful when the client launches `vmware-debug mcp` itself). To offer
+chosen write tools as well, add `--allow-write` with a comma-separated list (or `VMWARE_DEBUG_MCP_ALLOW_WRITE`):
+
+```bash
+vmware-debug mcp --expose read --allow-write close_case
+```
+
+- A read tool is one annotated `readOnlyHint: true`; every other tool counts as a write.
+- An unknown setting, or a name that is not a write tool of this server, stops the server before it serves (exit
+  code 2), so it never offers more than you asked for. Pre-2.0 tool names are accepted.
+- With `--expose read`, the server prints one line to stderr saying what it exposes.
+- Flags and environment variables are not mixed: if either flag is given, both environment variables are
+  ignored, so a leftover `_ALLOW_WRITE` in the shell cannot widen `--expose read`. A blank flag value counts as
+  not given.
+- A tool that runs other steps (a plan, workflow or batch tool) carries every write it can execute, including
+  writes this setting hides. Expose such a tool only if you would expose those writes too.
+- A launcher that imports the server object can call
+  `vmware_policy.exposure.restrict_tools(mcp, skill="debug", expose="read", allow_write=[...])` before running it,
+  instead of editing the SDK's tool registry.
+- This limits what clients are offered. It is **not** authorization. This server's write tools change case records on this machine;
+  deny rules in `~/.vmware/rules.yaml` still apply to every exposed tool.
+
 ## Security
 
 > **Disclaimer**: Community-maintained open-source project, **not affiliated with,

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/tests/eval/capability/_family.py

@@ -104,9 +104,10 @@ FAMILY_TOOLS: dict[str, frozenset[str]] = {
         'update_dfw_policy', 'update_dfw_rule',
     }),
     'vmware-pilot': frozenset({
-        'approve', 'cancel_workflow', 'confirm_draft', 'create_workflow', 'design_workflow',
-        'get_skill_catalog', 'get_workflow_status', 'list_workflows', 'plan_workflow',
-        'review_workflow', 'rollback', 'run_workflow', 'update_draft',
+        'approve', 'cancel_workflow', 'confirm_draft', 'create_workflow',
+        'create_workflow_from_template', 'design_workflow', 'get_skill_catalog',
+        'get_workflow_status', 'list_workflows', 'review_workflow', 'rollback',
+        'run_workflow', 'update_draft',
     }),
     'vmware-storage': frozenset({
         'add_iscsi_target', 'browse_datastore', 'enable_iscsi', 'get_iscsi_status',
@@ -118,10 +119,11 @@ FAMILY_TOOLS: dict[str, frozenset[str]] = {
     'vmware-vks': frozenset({
         'check_vks_compatibility', 'create_namespace', 'create_tkc_cluster',
         'delete_namespace', 'delete_tkc_cluster', 'get_harbor_info', 'get_namespace',
-        'get_supervisor_kubeconfig', 'get_supervisor_status', 'get_tkc_available_versions',
-        'get_tkc_cluster', 'get_tkc_kubeconfig', 'list_namespace_storage_usage',
-        'list_namespaces', 'list_supervisor_storage_policies', 'list_tkc_clusters',
-        'list_vm_classes', 'list_vm_service_groups', 'list_vm_service_network_interfaces',
+        'get_supervisor_status', 'get_tkc_available_versions', 'get_tkc_cluster',
+        'issue_supervisor_kubeconfig', 'issue_tkc_kubeconfig',
+        'list_namespace_storage_usage', 'list_namespaces',
+        'list_supervisor_storage_policies', 'list_tkc_clusters', 'list_vm_classes',
+        'list_vm_service_groups', 'list_vm_service_network_interfaces',
         'list_vm_service_snapshots', 'scale_tkc_cluster', 'update_namespace',
         'upgrade_tkc_cluster',
     }),

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/uv.lock

@@ -1293,7 +1293,7 @@ wheels = [
 
 [[package]]
 name = "vmware-debug"
-version = "2.0.0"
+version = "2.1.0"
 source = { editable = "." }
 dependencies = [
     { name = "mcp", extra = ["cli"] },
@@ -1316,7 +1316,7 @@ requires-dist = [
     { name = "pyyaml", specifier = ">=6.0,<7.0" },
     { name = "rich", specifier = ">=13.0,<15.0" },
     { name = "typer", specifier = ">=0.12,<1.0" },
-    { name = "vmware-policy", specifier = ">=1.18.1,<2.0" },
+    { name = "vmware-policy", specifier = ">=1.20.0,<2.0" },
 ]
 
 [package.metadata.requires-dev]
@@ -1328,14 +1328,14 @@ dev = [
 
 [[package]]
 name = "vmware-policy"
-version = "1.18.2"
+version = "1.20.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "pyyaml" },
     { name = "rich" },
     { name = "typer" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/5d/ce/a4f31330f983f411051ab0f42dcbd3c7174670541fa5cdb7faaf22991b24/vmware_policy-1.18.2.tar.gz", hash = "sha256:8e52629bf4a0d355a6841f1d9d5fb4ac1e69bbc7ae22d3843dd7cf3426b30e4c", size = 208412, upload-time = "2026-10-14T06:08:54.124Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/66/f3/cae0e18d269bd4764d5f9b34a838174e9668f931e44d41effab620aeecf4/vmware_policy-1.20.0.tar.gz", hash = "sha256:eb9875d3e94435a18d1dd6cf2c71905c46e2e812808556db3fb741ef322bee99", size = 220048, upload-time = "2026-10-15T06:33:35.174Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/6b/cc/0ad37c57ee902819efc1c193b363df9a7c762794e7dff3318577c17743de/vmware_policy-1.18.2-py3-none-any.whl", hash = "sha256:6e7414f6cc7d783f486db858fd99dd7123ddefc0e823a8b319756e17ece03455", size = 80791, upload-time = "2026-10-14T06:08:52.267Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/cf/6c87f6b5439407c1c3b83b84a5ef53def7544b687efd6f16a6cb187acf78/vmware_policy-1.20.0-py3-none-any.whl", hash = "sha256:cea9451c70be96e3d7adc420a2ac001cf431c29b61350dd58c3771378058737a", size = 86684, upload-time = "2026-10-15T06:33:33.413Z" },
 ]

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/vmware_debug/__init__.py

@@ -6,4 +6,4 @@ remediation to vmware-aiops / vmware-pilot. Never writes to any VMware system
 and never executes fixes; its only writes go to the local case ledger.
 """
 
-__version__ = "2.0.0"
+__version__ = "2.1.0"

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/vmware_debug/cli.py

@@ -104,11 +104,23 @@ def triage(
 
 @app.command()
 @cli_local("starts the MCP server; its tools audit themselves")
-def mcp() -> None:
+def mcp(
+    expose: Optional[str] = typer.Option(
+        None,
+        "--expose",
+        help="Which tools to offer: all (default) or read. Limits what clients see; "
+        "not authorization: the account's permissions still decide.",
+    ),
+    allow_write: Optional[str] = typer.Option(
+        None,
+        "--allow-write",
+        help="With --expose read: comma-separated write tools to offer as well.",
+    ),
+) -> None:
     """Start the stdio MCP server (no network access; proxy-safe)."""
     from vmware_debug.mcp_server.server import main as _main
 
-    _main()
+    _main(expose=expose, allow_write=allow_write)
 
 
 if __name__ == "__main__":

{vmware_debug-2.0.0 → vmware_debug-2.1.0}/vmware_debug/mcp_server/server.py

@@ -862,7 +862,7 @@ def build_server() -> FastMCP:
 
 
     return server
-def main() -> None:
+def main(expose: Optional[str] = None, allow_write: Optional[str] = None) -> None:
     """Entry point for `vmware-debug-mcp` (stdio transport)."""
     # Floor is 3.10, matching `requires-python` and the other eleven skills.
     # This guard used to demand 3.11 on the grounds that FastMCP schema
@@ -878,7 +878,10 @@ def main() -> None:
             "Reinstall on a newer interpreter: "
             "uv tool install --python 3.12 --force vmware-debug"
         )
-    build_server().run()
+    from vmware_policy.exposure import apply_or_exit
+    server = build_server()
+    apply_or_exit(server, skill="debug", expose=expose, allow_write=allow_write)
+    server.run()
 
 
 if __name__ == "__main__":