Add graph tool to MCP server

Author: httpdss

docs/mcp-integration.md

@@ -69,7 +69,28 @@ 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. graph_structure
+Visualize dependency graphs from `folders[].struct` references.
+
+```json
+{
+  "name": "graph_structure",
+  "arguments": {
+    "structure_definition": "project/python",
+    "structures_path": "/path/to/custom/structures",
+    "include_all": false,
+    "output_format": "mermaid"
+  }
+}
+```
+
+**Parameters:**
+- `structure_definition` (optional): Name or local YAML path to graph. Required unless `include_all` is `true`
+- `structures_path` (optional): Custom path to structure definitions
+- `include_all` (optional): Include all available structures instead of a single root (default: `false`)
+- `output_format` (optional): Output format - `text`, `json`, or `mermaid` (default: `text`)
+
+### 5. validate_structure
 Validate a structure configuration YAML file.
 
 ```json

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("  - graph_structure: Visualize structure dependency graphs")
             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. Visualizing structure dependency graphs
 """
 import asyncio
 import logging
@@ -17,6 +18,7 @@
 from fastmcp import FastMCP
 
 from structkit.commands.generate import GenerateCommand
+from structkit.commands.graph import GraphCommand
 from structkit.commands.validate import ValidateCommand
 from structkit import __version__
 
@@ -167,6 +169,30 @@ class Args:
                 return f"Dry run completed for structure '{structure_definition}' at '{base_path}'"
             return f"Structure '{structure_definition}' generated successfully at '{base_path}'"
 
+    def _graph_structure_logic(
+        self,
+        structure_definition: Optional[str] = None,
+        structures_path: Optional[str] = None,
+        include_all: bool = False,
+        output_format: str = "text",
+    ) -> str:
+        if not include_all and not structure_definition:
+            return "Error: structure_definition is required unless include_all is true"
+
+        if output_format not in {"text", "json", "mermaid"}:
+            return "Error: output_format must be one of: text, json, mermaid"
+
+        import argparse
+        dummy_parser = argparse.ArgumentParser()
+        command = GraphCommand(dummy_parser)
+        graph = command.build_graph(structure_definition, structures_path, include_all)
+
+        if output_format == "json":
+            return command.format_json(graph)
+        if output_format == "mermaid":
+            return command.format_mermaid(graph)
+        return command.format_text(graph)
+
     def _validate_structure_logic(self, yaml_file: Optional[str]) -> str:
         if not yaml_file:
             return "Error: yaml_file is required"
@@ -247,6 +273,32 @@ async def generate_structure(
             self.logger.debug(f"MCP response: generate_structure len={len(result)} preview=\n{preview}")
             return result
 
+        @self.app.tool(name="graph_structure", description="Visualize structure dependency graphs from folders[].struct references")
+        async def graph_structure(
+            structure_definition: Optional[str] = None,
+            structures_path: Optional[str] = None,
+            include_all: bool = False,
+            output_format: str = "text",
+        ) -> str:
+            self.logger.debug(
+                "MCP request: graph_structure args=%s",
+                {
+                    "structure_definition": structure_definition,
+                    "structures_path": structures_path,
+                    "include_all": include_all,
+                    "output_format": output_format,
+                },
+            )
+            result = self._graph_structure_logic(
+                structure_definition,
+                structures_path,
+                include_all,
+                output_format,
+            )
+            preview = result if len(result) <= 1000 else result[:1000] + f"... [truncated {len(result)-1000} chars]"
+            self.logger.debug(f"MCP response: graph_structure len={len(result)} preview=\n{preview}")
+            return result
+
         @self.app.tool(name="validate_structure", description="Validate a structure configuration YAML file")
         async def validate_structure(yaml_file: str) -> str:
             self.logger.debug(f"MCP request: validate_structure args={{'yaml_file': {yaml_file!r}}}")

tests/test_commands_more.py

@@ -167,6 +167,17 @@ async def fake_start(args):
         mock_start.assert_called_once()
 
 
+def test_mcp_command_lists_graph_tool(parser):
+    command = MCPCommand(parser)
+    args = parser.parse_args([])
+
+    with patch('builtins.print') as mock_print:
+        command.execute(args)
+
+    printed = "\n".join(call.args[0] for call in mock_print.call_args_list)
+    assert 'graph_structure' in printed
+
+
 # ValidateCommand error-path tests on helpers
 
 def test_validate_structure_config_errors(parser):

tests/test_mcp_integration.py

@@ -1,6 +1,7 @@
 """
 Tests for MCP (Model Context Protocol) integration with FastMCP stdio transport.
 """
+import json
 import os
 import tempfile
 import unittest
@@ -43,6 +44,41 @@ def test_generate_structure_logic(self):
             )
             self.assertIsInstance(text, str)
 
+    def test_graph_structure_logic(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            app_path = os.path.join(temp_dir, "app.yaml")
+            library_path = os.path.join(temp_dir, "library.yaml")
+            with open(app_path, "w") as f:
+                yaml.dump({
+                    "files": [],
+                    "folders": [
+                        {"src": {"struct": "library"}}
+                    ],
+                }, f)
+            with open(library_path, "w") as f:
+                yaml.dump({"files": []}, f)
+
+            text = self.server._graph_structure_logic("app", temp_dir)
+            self.assertIn("app", text)
+            self.assertIn("library", text)
+
+            payload = json.loads(
+                self.server._graph_structure_logic("app", temp_dir, output_format="json")
+            )
+            self.assertEqual(payload["edges"], [{"from": "app", "to": "library"}])
+
+            mermaid = self.server._graph_structure_logic(
+                "app", temp_dir, output_format="mermaid"
+            )
+            self.assertIn('n_app["app"] --> n_library["library"]', mermaid)
+
+    def test_graph_structure_logic_validates_arguments(self):
+        text = self.server._graph_structure_logic()
+        self.assertIn("structure_definition is required", text)
+
+        text = self.server._graph_structure_logic("app", output_format="dot")
+        self.assertIn("output_format must be one of", text)
+
     def test_validate_structure_logic(self):
         # Missing yaml_file
         text = self.server._validate_structure_logic(None)