feat(mcp): a read-only server mode that hides and refuses writing tools

[mikhalchankasm]

What

The owner chose this on 2026-09-24, from the survey of other BIM/CAD MCP servers (dwg-mcp has the same switch). It gives a review or inspection session a boundary that an agent cannot talk its way past.

The MCP server can now run read-only: start it with --read-only, or set NAVISHELPER_MCP_READ_ONLY=1 (or true). In that mode:

• tools/list shows only the 36 tools whose ToolCapabilities effects are None (declared in feat(mcp): declare each tool's effects and requirements, with a generated table #68);
• a call to any other tool, including a remembered name or a dry-run, is refused with the new error code read_only_mode before any host is reached;
• mcp_health_check reports readOnlyMode.

The mode is strict: view-only tools (selection, camera, visibility) are hidden too, because they carry the View effect.

With the mode off, nothing changes: all 104 tool names, descriptions and input schemas are byte-identical to main's.

• Code: McpReadOnlyMode builds the name-to-effects map once at start-up by reflection. It registers a list-tools filter and a call-tool filter beside the existing validation and timing filters. Start-up fails if the attribute names ever drift from the registered tools.
• Refusal shape: the refusal takes the same form as the existing argument-validation refusal, IsError with a text block.
• Error contract: read_only_mode is added to ErrorCodes and to the contract that mcp_error_contract returns.
• Docs: a ## Read-only mode section in docs/MCP_TOOL_CONTRACTS.md, and a line in docs/MCP_CLIENT_GUIDE.md.

Provenance

• 52ecd89: Codex (gpt-6-sol, high effort) wrote it from a 1.3 KB brief and a context file (626 s, main checkout untouched).
• Head commit: the curator added the sentence saying the mode also hides view-only tools.

Verification

The acceptance script ended ALL PASS on the head, rerun by the curator. It checks:

• off: 104 tools, names and input schemas identical to main (3c7d5ffc…);
• on: exactly the 36 tools the generated table marks None, nothing else;
• refused: create_viewpoint is refused with read_only_mode;
• reported: readOnlyMode is true when on and false when off;
• contract: mcp_error_contract lists the new code;
• docs: both additions are present;
• tests: the full suite passes (1811; the new tests cover switch parsing, the filter decision over the real tool methods, and the refusal);
• guards: all pass, including the capability table check.

No plugin code changed.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-23T23:56:06.249673Z	7407932	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.