Add explain structure MCP tool

Author: httpdss

docs/mcp-integration.md

@@ -69,7 +69,38 @@ Generate a project structure using specified definition and options.
 - `mappings` (optional): Variable mappings for template substitution
 - `structures_path` (optional): Custom path to structure definitions
 
-### 4. validate_structure
+### 4. explain_structure
+Explain how a structure resolves without creating files, fetching remote content, generating prompt-based content, or executing hooks. This is useful when an AI assistant needs to inspect the structure graph before deciding whether to generate it.
+
+```json
+{
+  "name": "explain_structure",
+  "arguments": {
+    "structure_definition": "project/python",
+    "base_path": "/tmp/myproject",
+    "output": "json",
+    "variables": {
+      "project_name": "MyProject"
+    },
+    "mappings": {
+      "team": "platform"
+    },
+    "file_strategy": "overwrite",
+    "structures_path": "/path/to/custom/structures"
+  }
+}
+```
+
+**Parameters:**
+- `structure_definition` (required): Name or path to the structure definition
+- `base_path` (optional): Base path used to resolve generated paths (default: `.`)
+- `output` (optional): Output mode - `"text"` or `"json"` (default: `"text"`)
+- `variables` (optional): Template variables to resolve structure names, paths, hooks, and nested `with` values
+- `mappings` (optional): Additional mappings exposed to templates as `mappings`
+- `file_strategy` (optional): Conflict strategy to explain: `overwrite`, `skip`, `append`, `rename`, or `backup` (default: `overwrite`)
+- `structures_path` (optional): Custom path to structure definitions
+
+### 5. validate_structure
 Validate a structure configuration YAML file.
 
 ```json
@@ -204,6 +235,12 @@ async def main():
             # FastMCP tools return plain text content
             print(result.content[0].text)
 
+            explanation = await session.call_tool("explain_structure", {
+                "structure_definition": "project/python",
+                "output": "json"
+            })
+            print(explanation.content[0].text)
+
 if __name__ == "__main__":
     asyncio.run(main())
 ```
@@ -225,8 +262,9 @@ The MCP tools can be chained together for complex workflows:
 
 1. List available structures
 2. Get detailed info about a specific structure
-3. Generate the structure with custom mappings
-4. Validate any custom configurations
+3. Explain the structure to preview files, folders, variables, hooks, and remote references
+4. Generate the structure with custom mappings
+5. Validate any custom configurations
 
 ### Integration Examples
 
@@ -265,6 +303,32 @@ The MCP tools can be chained together for complex workflows:
 }
 ```
 
+
+**Example 3: Explain Before Generate**
+```json
+// 1. Explain structure resolution without side effects
+{
+  "name": "explain_structure",
+  "arguments": {
+    "structure_definition": "project/python",
+    "base_path": "/tmp/review",
+    "output": "json",
+    "variables": {
+      "project_name": "ReviewProject"
+    }
+  }
+}
+
+// 2. If the explanation looks correct, generate the structure
+{
+  "name": "generate_structure",
+  "arguments": {
+    "structure_definition": "project/python",
+    "base_path": "/tmp/review"
+  }
+}
+```
+
 ## Configuration
 
 ### Environment Variables
@@ -353,6 +417,7 @@ Once connected, you can use these tools:
 - `list_structures` - Get all available structures
 - `get_structure_info` - Get details about a specific structure
 - `generate_structure` - Generate project structures
+- `explain_structure` - Explain structure resolution without side effects
 - `validate_structure` - Validate YAML configuration files
 
 ## Troubleshooting

structkit/commands/mcp.py

@@ -49,6 +49,7 @@ def execute(self, args):
             print("  - list_structures: List all available structure definitions")
             print("  - get_structure_info: Get detailed information about a structure")
             print("  - generate_structure: Generate structures with various options")
+            print("  - explain_structure: Explain structure resolution without side effects")
             print("  - validate_structure: Validate structure configuration files")
             print("\nExamples:")
             print("  structkit mcp --server --transport stdio --debug")

structkit/mcp_server.py

@@ -6,6 +6,7 @@
 2. Getting detailed information about structures
 3. Generating structures with various options
 4. Validating structure configurations
+5. Explaining structure resolution without side effects
 """
 import asyncio
 import logging
@@ -17,6 +18,7 @@
 from fastmcp import FastMCP
 
 from structkit.commands.generate import GenerateCommand
+from structkit.commands.explain import ExplainCommand
 from structkit.commands.validate import ValidateCommand
 from structkit import __version__
 
@@ -193,6 +195,56 @@ class Args:
         finally:
             sys.stdout = old
 
+    def _explain_structure_logic(
+        self,
+        structure_definition: str,
+        base_path: str = ".",
+        output: str = "text",
+        variables: Optional[Dict[str, str]] = None,
+        mappings: Optional[Dict[str, Any]] = None,
+        structures_path: Optional[str] = None,
+        file_strategy: str = "overwrite",
+    ) -> str:
+        if not structure_definition:
+            return "Error: structure_definition is required"
+
+        valid_outputs = {"text", "json"}
+        if output not in valid_outputs:
+            return f"Error: output must be one of {sorted(valid_outputs)}, got: {output}"
+
+        valid_file_strategies = {"overwrite", "skip", "append", "rename", "backup"}
+        if file_strategy not in valid_file_strategies:
+            return f"Error: file_strategy must be one of {sorted(valid_file_strategies)}, got: {file_strategy}"
+
+        class Args:
+            pass
+        args = Args()
+        args.structure_definition = structure_definition
+        args.base_path = base_path or "."
+        args.output = output
+        args.json_output = output == "json"
+        args.structures_path = structures_path
+        args.vars = None
+        args.mappings_file = None
+        args.file_strategy = file_strategy
+        args.log = "INFO"
+        args.config_file = None
+        args.log_file = None
+
+        if variables:
+            args.vars = ",".join([f"{k}={v}" for k, v in variables.items()])
+
+        import argparse
+        dummy_parser = argparse.ArgumentParser()
+        command = ExplainCommand(dummy_parser)
+        explanation = command.explain(args, mappings=mappings or {})
+        if explanation is None:
+            return f"Unable to explain structure '{structure_definition}'"
+        if output == "json":
+            import json
+            return json.dumps(explanation, indent=2, sort_keys=True)
+        return command._format_text(explanation)
+
     # =====================
     # FastMCP tool registration (maps to logic above)
     # =====================
@@ -255,6 +307,41 @@ async def validate_structure(yaml_file: str) -> str:
             self.logger.debug(f"MCP response: validate_structure len={len(result)} preview=\n{preview}")
             return result
 
+        @self.app.tool(name="explain_structure", description="Explain structure resolution without creating files, fetching remote content, or running hooks")
+        async def explain_structure(
+            structure_definition: str,
+            base_path: str = ".",
+            output: str = "text",
+            variables: Optional[Dict[str, str]] = None,
+            mappings: Optional[Dict[str, Any]] = None,
+            structures_path: Optional[str] = None,
+            file_strategy: str = "overwrite",
+        ) -> str:
+            self.logger.debug(
+                "MCP request: explain_structure args=%s",
+                {
+                    "structure_definition": structure_definition,
+                    "base_path": base_path,
+                    "output": output,
+                    "variables": variables,
+                    "mappings": mappings,
+                    "structures_path": structures_path,
+                    "file_strategy": file_strategy,
+                },
+            )
+            result = self._explain_structure_logic(
+                structure_definition,
+                base_path,
+                output,
+                variables,
+                mappings,
+                structures_path,
+                file_strategy,
+            )
+            preview = result if len(result) <= 1000 else result[:1000] + f"... [truncated {len(result)-1000} chars]"
+            self.logger.debug(f"MCP response: explain_structure len={len(result)} preview=\n{preview}")
+            return result
+
     async def run(
         self,
         transport: str = "stdio",

tests/test_mcp_integration.py

@@ -43,6 +43,49 @@ def test_generate_structure_logic(self):
             )
             self.assertIsInstance(text, str)
 
+
+    def test_explain_structure_logic(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            structure_path = os.path.join(temp_dir, 'example.yaml')
+            with open(structure_path, 'w') as f:
+                yaml.dump({
+                    'variables': [
+                        {'project_name': {'type': 'string', 'default': 'Demo'}}
+                    ],
+                    'pre_hooks': ['echo {{@ project_name @}}'],
+                    'files': [
+                        {'README.md': {'content': '# {{@ project_name @}}'}},
+                        {'remote.txt': {'file': 'https://example.com/template.txt'}}
+                    ],
+                }, f)
+
+            text = self.server._explain_structure_logic(
+                structure_definition=structure_path,
+                base_path=temp_dir,
+                variables={'project_name': 'MCP Demo'},
+            )
+
+            self.assertIn('Structure explanation', text)
+            self.assertIn('MCP Demo', text)
+            self.assertIn('remote.txt', text)
+            self.assertIn('https://example.com/template.txt', text)
+            self.assertIn('Hooks (not executed)', text)
+
+            json_text = self.server._explain_structure_logic(
+                structure_definition=structure_path,
+                base_path=temp_dir,
+                output='json',
+                variables={'project_name': 'MCP Demo'},
+                file_strategy='skip',
+            )
+            self.assertIn('"file_strategy": "skip"', json_text)
+            self.assertIn('"remote_files"', json_text)
+
+    def test_explain_structure_logic_validates_inputs(self):
+        self.assertIn('structure_definition is required', self.server._explain_structure_logic(''))
+        self.assertIn('output must be one of', self.server._explain_structure_logic('project/python', output='xml'))
+        self.assertIn('file_strategy must be one of', self.server._explain_structure_logic('project/python', file_strategy='replace'))
+
     def test_validate_structure_logic(self):
         # Missing yaml_file
         text = self.server._validate_structure_logic(None)