Skip to content

Add explain command and MCP explain_structure tool#145

Merged
httpdss merged 1 commit intomainfrom
codex/add-command-to-mcp-from-issue-136
May 9, 2026
Merged

Add explain command and MCP explain_structure tool#145
httpdss merged 1 commit intomainfrom
codex/add-command-to-mcp-from-issue-136

Conversation

@httpdss
Copy link
Copy Markdown
Owner

@httpdss httpdss commented May 9, 2026

Motivation

  • Provide a safe preview mode to inspect how a structure definition will resolve (files, folders, nested structures, remote references, variables and hooks) without creating files or running hooks.
  • Make that preview available to MCP clients so remote tooling can request explanations programmatically.
  • Improve developer UX by reporting conflict behaviour (skip, skip_if_exists, etc.) and resolved template variables prior to generation.

Description

  • Add a new CLI command explain implemented in structkit/commands/explain.py that computes a non-destructive explanation of a structure and can output text or JSON.
  • Integrate the command into the top-level parser via structkit/main.py and document it in docs/cli-reference.md.
  • Add MCP support by registering an explain_structure tool and exposing _explain_structure_logic and a compatibility handler in structkit/mcp_server.py, allowing MCP clients to request text or JSON explanations.
  • Add tests in tests/test_explain_command.py and update MCP advertising in structkit/commands/mcp.py; the explain implementation reports remote file refs, nested structures, hooks, resolved variables, and conflict actions.

Testing

  • Ran pytest -q tests/test_explain_command.py and the explain-specific tests passed.
  • Ran pytest -q tests/test_mcp_integration.py tests/test_commands.py tests/test_commands_more.py and those suites passed.
  • Ran the full test suite with pytest -q and all tests passed (no failures).

Codex Task

@httpdss httpdss merged commit d3fc004 into main May 9, 2026
3 checks passed
@httpdss httpdss deleted the codex/add-command-to-mcp-from-issue-136 branch May 9, 2026 19:40
@httpdss httpdss added the feature label May 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant