MCP (Model Context Protocol) Integration

June 28, 2026 ยท View on GitHub

The structkit tool now supports MCP (Model Context Protocol) integration, providing a programmable interface to interact with structure definitions. This enables automation and integration with other tools, particularly AI-assisted development workflows.

Available MCP Tools

1. list_structures

Lists all available structure definitions.

{
  "name": "list_structures",
  "arguments": {
    "structures_path": "/path/to/custom/structures"  // optional
  }
}

Parameters:

  • structures_path (optional): Custom path to structure definitions

2. get_structure_info

Get detailed information about a specific structure.

{
  "name": "get_structure_info",
  "arguments": {
    "structure_name": "project/python",
    "structures_path": "/path/to/custom/structures"  // optional
  }
}

Parameters:

  • structure_name (required): Name of the structure to get info about
  • structures_path (optional): Custom path to structure definitions

3. generate_structure

Generate a project structure using specified definition and options.

{
  "name": "generate_structure",
  "arguments": {
    "structure_definition": "project/python",
    "base_path": "/tmp/myproject",
    "output": "console",  // "console" or "files"
    "dry_run": false,
    "mappings": {
      "project_name": "MyProject",
      "author": "John Doe"
    },
    "structures_path": "/path/to/custom/structures",  // optional
    "source": "company"  // optional named source
  }
}

Parameters:

  • structure_definition (required): Name or path to the structure definition
  • base_path (required): Base path where the structure should be generated
  • output (optional): Output mode - "console" for stdout or "files" for actual generation (default: "files")
  • dry_run (optional): Perform a dry run without creating actual files (default: false)
  • mappings (optional): Variable mappings for template substitution
  • structures_path (optional): Custom path to structure definitions
  • source (optional): Named source configured with manage_sources. The structure definition can also use a <source>/<structure> prefix.

4. get_structure_vars

Inspect variables declared by a specific structure without generating files.

{
  "name": "get_structure_vars",
  "arguments": {
    "structure_name": "project/python",
    "structures_path": "/path/to/custom/structures",  // optional
    "output": "json"  // "text" or "json", optional
  }
}

Parameters:

  • structure_name (required): Name or local YAML path of the structure to inspect
  • structures_path (optional): Custom path to structure definitions
  • output (optional): Output format - "text" for aligned human-readable output or "json" for machine-readable output (default: "text")

5. validate_structure

Validate a structure configuration YAML file.

{
  "name": "validate_structure",
  "arguments": {
    "yaml_file": "/path/to/structure.yaml"
  }
}

Parameters:

  • yaml_file (required): Path to the YAML configuration file to validate

6. lint_structure

Lint one or more structure YAML files or structure names for quality and safety issues.

{
  "name": "lint_structure",
  "arguments": {
    "targets": ["project/python", "/path/to/.struct.yaml"],
    "structures_path": "/path/to/custom/structures",
    "lint_all": false,
    "output": "json"
  }
}

Parameters:

  • targets (optional): YAML file paths or structure names to lint. Required unless lint_all is true.
  • structures_path (optional): Custom path to structure definitions.
  • lint_all (optional): Lint all bundled contrib structures (default: false).
  • output (optional): Output format - "text" or "json" (default: "text").

7. graph_structure

Visualize structure dependencies from folders[].struct references as text, JSON, or Mermaid. The tool reports nested dependencies, missing references, and cycles.

{
  "name": "graph_structure",
  "arguments": {
    "structure_definition": "project/python",
    "structures_path": "/path/to/custom/structures",
    "graph_all": false,
    "output": "mermaid"
  }
}

Parameters:

  • structure_definition (optional): Structure name or local YAML file to graph. Required unless graph_all is true.
  • structures_path (optional): Custom path to structure definitions.
  • graph_all (optional): Graph all available structures (default: false).
  • output (optional): Output format - "text", "json", or "mermaid" (default: "text").

8. manage_sources

Manage named structure sources. Sources can point at local directories, GitHub repositories, or git URLs. Git-backed sources are cloned into the StructKit sources cache and refreshed when resolved or validated.

{
  "name": "manage_sources",
  "arguments": {
    "action": "add",
    "name": "platform",
    "path_or_url": "github://httpdss/platform-structures@v1/structures"
  }
}

Parameters:

  • action (required): One of list, add, remove, show, or validate.
  • name (required except for list): Source name.
  • path_or_url (required for add): Local directory, GitHub shorthand (owner/repo), github://owner/repo, or git URL.
  • config_path (optional): Override the sources config file for this request.

Usage

Starting the MCP Server (FastMCP stdio / http / sse)

The MCP server uses FastMCP (v2.0+) and can run over stdio, http, or sse transports.

  • stdio (default):
structkit mcp --server --transport stdio
  • HTTP (StreamableHTTP):
structkit mcp --server --transport http --host 127.0.0.1 --port 9000 --path /mcp
  • SSE:
structkit mcp --server --transport sse --host 0.0.0.0 --port 8080 --path /events

Command Line Integration

The existing list and info commands now support an optional --mcp flag:

# List structures with MCP support
structkit list --mcp

# Get structure info with MCP support
structkit info project/python --mcp

MCP Client Integration

Claude Desktop Integration

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "structkit": {
      "command": "structkit",
      "args": ["mcp", "--server"],
      "cwd": "/path/to/your/project"
    }
  }
}

Cline/Continue Integration

For Cline (VS Code extension), add to your .cline_mcp_settings.json:

{
  "mcpServers": {
    "structkit": {
      "command": "structkit",
      "args": ["mcp", "--server"]
    }
  }
}

Custom MCP Client Integration

For any MCP-compatible client, connect over stdio with your preferred SDK:

// Node.js example (MCP JS SDK)
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const transport = new StdioClientTransport({
  command: 'struct',
  args: ['mcp', '--server']
});

const client = new Client(
  {
    name: "struct-client",
    version: "1.0.0"
  },
  {
    capabilities: {}
  }
);

await client.connect(transport);

# Python example (MCP Python SDK)
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="structkit",
        args=["mcp", "--server"]
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            tools = await session.list_tools()
            print([t.name for t in tools.tools])

            result = await session.call_tool("list_structures", {})
            # FastMCP tools return plain text content
            print(result.content[0].text)

if __name__ == "__main__":
    asyncio.run(main())

AI-Assisted Development Workflows

The MCP integration is particularly powerful for AI-assisted development workflows:

Console Output Mode

Using output: "console" with generate_structure allows piping structure content to stdout for subsequent AI prompts:

# Generate structure content to console for AI review
structkit mcp --server | ai-tool "Review this project structure"

Chaining Operations

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
  5. Lint structures for stricter quality and safety checks

Integration Examples

Example 1: Generate and Review

// 1. Generate structure to console
{
  "name": "generate_structure",
  "arguments": {
    "structure_definition": "project/python",
    "base_path": "/tmp/review",
    "output": "console"
  }
}

// 2. Use output as context for AI code review

Example 2: Custom Structure Validation

// 1. Validate custom structure
{
  "name": "validate_structure",
  "arguments": {
    "yaml_file": "/path/to/custom-structure.yaml"
  }
}

// 2. If valid, generate using the custom structure
{
  "name": "generate_structure",
  "arguments": {
    "structure_definition": "file:///path/to/custom-structure.yaml",
    "base_path": "/tmp/project"
  }
}

End-to-end AI assistant workflow

Use this flow when you want an AI assistant to scaffold from an approved StructKit template instead of inventing a repository layout from scratch. The assistant should inspect available templates, choose one with you, preview the generated files, and only then write to disk.

1. Start the MCP server

For local MCP clients that launch tools over stdio, use:

structkit mcp --server --transport stdio

For a long-running local HTTP endpoint during development, use:

structkit mcp --server --transport http --host 127.0.0.1 --port 9000 --path /mcp

2. Give the assistant a scoped prompt

Use StructKit templates as the source of truth. List available structures,
inspect the Terraform module template, preview the generated output for a module
named "network-observability", and only write files after I approve the preview.

This prompt keeps the model on the approved-template path: discover, inspect, preview, then generate.

3. List templates and inspect the chosen one

First, the assistant can discover the bundled templates:

{
  "name": "list_structures",
  "arguments": {}
}

Then it can inspect the Terraform module scaffold:

{
  "name": "get_structure_info",
  "arguments": {
    "structure_name": "terraform/modules/generic"
  }
}

For required variables, ask for the variable schema before generating:

{
  "name": "get_structure_vars",
  "arguments": {
    "structure_name": "terraform/modules/generic",
    "output": "json"
  }
}

The bundled terraform/modules/generic structure declares module_name, so the assistant should provide that value instead of guessing during generation.

4. Preview generated output

Use output: "console" to render the structure into the chat or tool result without writing files:

{
  "name": "generate_structure",
  "arguments": {
    "structure_definition": "terraform/modules/generic",
    "base_path": "/tmp/structkit-preview/network-observability",
    "output": "console",
    "dry_run": true,
    "mappings": {
      "module_name": "network-observability"
    }
  }
}

Review the preview for the expected source-of-truth files:

  • main.tf
  • variables.tf
  • outputs.tf
  • versions.tf
  • README.md

If the preview is not right, adjust the selected structure or mappings rather than asking the assistant to hand-edit a bespoke layout.

5. Generate approved files

After approval, call the same structure with output: "files" and dry_run: false:

{
  "name": "generate_structure",
  "arguments": {
    "structure_definition": "terraform/modules/generic",
    "base_path": "./modules/network-observability",
    "output": "files",
    "dry_run": false,
    "mappings": {
      "module_name": "network-observability"
    }
  }
}

The generated project structure now comes from the checked-in StructKit template. Future changes to the scaffold should happen in the YAML definition, not as one-off AI-generated folder edits.

6. Validate custom templates

If your team stores its own templates, point the MCP tools at that directory:

{
  "name": "validate_structure",
  "arguments": {
    "yaml_file": "/path/to/company-structures/terraform/modules/service.yaml"
  }
}

Then generate from the same source of truth:

{
  "name": "generate_structure",
  "arguments": {
    "structure_definition": "terraform/modules/service",
    "structures_path": "/path/to/company-structures",
    "base_path": "./modules/service-a",
    "output": "files",
    "mappings": {
      "module_name": "service-a"
    }
  }
}

Configuration

Environment Variables

The MCP server respects the same environment variables as the regular structkit tool:

  • STRUCTKIT_STRUCTURES_PATH: Default path for structure definitions
  • Any mapping variables used in templates

Client Configuration Examples

1. Basic Configuration

{
  "command": "structkit",
  "args": ["mcp", "--server"]
}

2. With Custom Structures Path

{
  "command": "structkit",
  "args": ["mcp", "--server"],
  "env": {
    "STRUCTKIT_STRUCTURES_PATH": "/path/to/custom/structures"
  }
}

3. With Python Virtual Environment

{
  "command": "/path/to/venv/bin/python",
  "args": ["-m", "structkit.main", "mcp", "--server"],
  "cwd": "/path/to/structkit/project"
}

4. Using Shell Script Wrapper

Create a shell script struct-mcp.sh:

#!/bin/bash
cd /path/to/your/project
source .venv/bin/activate
structkit mcp --server

Then configure your MCP client:

{
  "command": "/path/to/struct-mcp.sh",
  "args": []
}

Quick Start Guide

Step 1: Install structkit with MCP support

pip install fastmcp>=2.0
# (your MCP client may also require installing the MCP SDK, e.g., `pip install mcp`)

Step 2: Test MCP server

# Test that MCP server starts correctly
structkit mcp --server
# Should show: Starting MCP server...
# Press Ctrl+C to stop

Step 3: Configure your MCP client

Add the configuration to your MCP client (see examples above).

Step 4: Start using MCP tools

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
  • get_structure_vars - Inspect declared structure variables
  • validate_structure - Validate YAML configuration files
  • lint_structure - Lint YAML files or structure names for quality and safety issues

Troubleshooting

Common Issues

  1. "Command not found: struct"

    • Solution: Ensure structkit is installed and in your PATH
    • Alternative: Use full path to Python executable

  2. MCP server won't start

    • Check if mcp package is installed: pip show mcp
    • Try running with verbose logging: structkit mcp --server --log DEBUG

  3. Client can't connect

    • Verify the command and args in your client configuration
    • Test MCP server manually first
    • Check working directory and environment variables

  4. Structures not found

    • Set STRUCTKIT_STRUCTURES_PATH environment variable
    • Use absolute paths in configuration
    • Verify structure files exist and are readable

Debug Mode

# Run with debug logging
STRUCTKIT_LOG_LEVEL=DEBUG structkit mcp --server

Benefits

  1. Automation: Programmatic access to all structkit tool functionality
  2. Integration: Easy integration with other development tools
  3. AI Workflows: Enhanced support for AI-assisted development processes
  4. Consistency: Same underlying logic as CLI commands
  5. Flexibility: Support for custom paths, mappings, and output modes

Backward Compatibility

All existing structkit tool functionality remains unchanged. The MCP integration is additive and does not affect existing workflows or commands.