Skip to content
This repository was archived by the owner on Oct 11, 2026. It is now read-only.

docs: correct the result contract and document the _for_cli Blender lookup - #1

Merged
teknium1 merged 1 commit into
NousResearch:mainfrom
MaxFreedomPollard:docs/skill-result-and-for-cli
Oct 5, 2026
Merged

teknium1 merged 1 commit into
NousResearch:mainfrom
MaxFreedomPollard:docs/skill-result-and-for-cli

Conversation

@MaxFreedomPollard

Copy link
Copy Markdown
Contributor

Two parts of the skill don't match what the pinned server (v1.0.3, 2cea8d5) actually does.

Bug

  1. SKILL.md says to assign JSON-serializable output to result, and the server's own instructions (prompts.yml) suggest returning "dicts, lists". The add-on only accepts a dict: result = [1.5, 2.5, 3.5] or result = 4 comes back as The `result` variable must be a dict, not list. That error arrives after the code has already run, so an agent that retries can apply the same edit twice.
  2. The six *_for_cli tools (execute_blender_code_for_cli and the five get_blendfile_summary_*_for_cli tools) fail when Blender comes from the blender.org macOS app or Windows installer, since neither puts a blender command on PATH: Blender executable not found at 'blender'. Set the BLENDER_PATH environment variable to the correct path. Setting BLENDER_PATH in a shell or .env, as that message says, doesn't reach the server under Hermes, and the docs don't mention any of this.

Cause

  1. mcp_to_blender_server.py in the add-on runs the code, then rejects any result that isn't a dict. execute_blender_code sends strict_json=False, so Blender objects inside the dict are converted with repr rather than failing.
  2. Those tools run blender --background from BLENDER_PATH, else from PATH (blmcp/tools_helpers/blender_cli.py). Hermes starts MCP servers with a filtered environment (_build_safe_env in tools/mcp_tool_config.py) that keeps PATH but drops shell and .env variables such as BLENDER_PATH, and portable mcp.json values aren't ${VAR}-interpolated, so this package can't forward it either.

Fix

Docs only; mcp.json and plugin.json are unchanged. SKILL.md states the dict contract with an example, says a rejected result has still run, and tells the agent that _for_cli tools take an absolute path and need blender on the server's PATH, so it points the user to setup instead of retrying. setup.md gets a Failures entry with the cause and the fix, and the README lists the optional prerequisite.

Verification

  • Ran the add-on's own _execute_code from 2cea8d5 outside Blender, with only bpy.ops stubbed: list and int results return the dict error, {"location": [1.5, 2.5, 3.5]} returns ok, {"obj": object()} returns ok with a repr string, and a snippet that sets a global and then assigns a list returns the error with the global still set.
  • Installed the plugin from main (d1929b5, same mcp.json as this branch) into a temporary HERMES_HOME with current Hermes main (71a2fe3) using the README commands, then started the server the way _run_stdio does and called get_blendfile_summary_path_info_for_cli:
    • BLENDER_PATH exported in the shell, pointing at an existing executable: missing from the server's environment, and the tool fails with Blender executable not found at 'blender'.
    • BLENDER_PATH in HERMES_HOME/.env: same result.
    • A blender executable on PATH: the server runs it with --background <file>.
  • The server lists 26 tools; the 6 that take blend_file all end in _for_cli.
  • hermes plugins validate --json on this branch: ok, no warnings. The skill still loads, and the translated MCP launch config is identical to main.
  • Blender isn't installed on the machine I tested on, so I haven't run a _for_cli tool against a real Blender.

@teknium1
teknium1 merged commit be90637 into NousResearch:main Oct 5, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants