MCP / AI Agent Workflow

    StructKit is YAML scaffolding your AI assistant can actually run: over the Model Context Protocol an assistant discovers approved templates, inspects them, previews output, then generates.

    Hook Safety

    generate_structure defaults to no_hooks: true, so an assistant never executes generation hooks by accident. Running hooks requires explicitly passing no_hooks: false, which is not recommended. See hook safety controls.

    Available MCP Tools

    list_structures

    Lists all available structure definitions.

    get_structure_info

    Get detailed information about a specific structure.

    get_structure_vars

    Get the declared variables/mappings schema for a structure before generating.

    generate_structure

    Generate a project structure with specified definition and options.

    validate_structure

    Validate a structure configuration YAML file.

    manage_sources — named structure sources tool

    Keywords: manage_sources, sources, STRUCTKIT_SOURCES_CONFIG, STRUCTKIT_SOURCES_CACHE, named sources, git-backed sources.

    Manage named structure sources from the assistant. Sources can point at local directories, GitHub repositories, or git URLs. Git-backed sources are cloned into the StructKit sources cache (STRUCTKIT_SOURCES_CACHE) and refreshed when resolved or validated. The user-level sources config is controlled by STRUCTKIT_SOURCES_CONFIG. Actions: list, add, remove, show, validate.

    Starting the MCP Server

    Terminalbash
    # 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

    Claude Desktop Integration

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

    Cline / Continue Integration

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

    Custom Client Examples

    Python

    Python MCP clientpython
    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])

asyncio.run(main())

    Node.js

    Node.js MCP clientjavascript
    import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

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

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

await client.connect(transport);

    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:

    Terminalbash
    structkit mcp --server --transport stdio

    For a long-running local HTTP endpoint during development:

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

    2. Give the assistant a scoped prompt

    Prompttext
    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, discover the bundled templates:

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

    Then inspect the Terraform module scaffold:

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

    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"
    }
  }
}

    Managing Named Sources from the Assistant

    Use the manage_sources tool so the assistant configures named sources instead of hardcoding structures_path values. Sources support local directories, GitHub shorthand (owner/repo), github://owner/repo@ref/subdir, and git URLs.

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

    Then reference the source by name when generating — either via the source argument or with a <source>/<structure> prefix:

    {
  "name": "generate_structure",
  "arguments": {
    "structure_definition": "project/python",
    "source": "platform",
    "base_path": "./app",
    "output": "files",
    "dry_run": false
  }
}

    For branches that contain slashes, use the query-style ref form. This is a complete, copy-pastemanage_sources + generate_structure workflow:

    Slash-ref source workflowjson
    {
  "name": "manage_sources",
  "arguments": {
    "action": "add",
    "name": "release_branch",
    "path_or_url": "github://httpdss/platform-structures/structures?ref=release/1.x"
  }
}

{
  "name": "generate_structure",
  "arguments": {
    "structure_definition": "release_branch/github/actions-ci",
    "base_path": "./.github/workflows",
    "output": "files",
    "dry_run": true
  }
}

    Git-backed sources are cloned into $XDG_CACHE_HOME/structkit/sources (or ~/.cache/structkit/sources) and refreshed with git fetch on each resolution or validation. Branch refs check out from origin/<branch>; tags and commit SHAs check out detached. Override the cache directory with STRUCTKIT_SOURCES_CACHE.

    Generating from File-Local Sources

    When a project's .structkit.yaml declares its own sources: block, the assistant can point generate_structure at that file directly. File-local sources override user-level sources with the same name, and nested structs inherit the parent's source context.

    .structkit.yamlyaml
    # .structkit.yaml committed to the repo
sources:
  platform:
    url: github://httpdss/platform-structures@v1.2.0/structures

folders:
  - ./:
      struct:
        - platform/python/service
        - platform/github/actions-ci   # inherits the "platform" source
      with:
        service_name: demo-api
    {
  "name": "generate_structure",
  "arguments": {
    "structure_definition": ".structkit.yaml",
    "base_path": "./app",
    "output": "files",
    "dry_run": true
  }
}

    Configuration with Custom Structures

    Env vars: STRUCTKIT_STRUCTURES_PATH, STRUCTKIT_SOURCES_CONFIG (named-sources config file), STRUCTKIT_SOURCES_CACHE (git-backed sources cache).

    {
  "command": "structkit",
  "args": ["mcp", "--server"],
  "env": {
    "STRUCTKIT_STRUCTURES_PATH": "/path/to/custom/structures",
    "STRUCTKIT_SOURCES_CONFIG": "/path/to/sources.yaml",
    "STRUCTKIT_SOURCES_CACHE": "/path/to/sources-cache"
  }
}

    Related

    Previous

    Environment Variables

    Next

    GitHub Integration