@agiflowai/scaffold-mcp

MCP server for scaffolding applications with templates and feature generators

Use this server to generate projects and feature boilerplate from template-defined scaffolds.

Quick Start

1. Install Templates

# Downloads built-in templates to your workspace
npx @agiflowai/aicode-toolkit init

2. Configure Your AI Agent

Add to your MCP config (.mcp.json, .cursor/mcp.json, etc.):

{
  "mcpServers": {
    "scaffold-mcp": {
      "command": "npx",
      "args": ["-y", "@agiflowai/scaffold-mcp", "mcp-serve", "--admin-enable"]
    }
  }
}

Flags:

• --admin-enable: Enables tools for creating new templates (optional, useful during setup)

3. Start Using

Your agent can now call scaffold tools:

You: "Create a new Next.js app called dashboard"
Agent: [calls list-boilerplates, then use-boilerplate]

You: "Add a products page"
Agent: [calls list-scaffolding-methods, then use-scaffold-method]

Available Tools

Standard Tools

| Tool | Purpose | When to Use | |------|---------|-------------| | list-boilerplates | Show available project templates | Starting a new project | | use-boilerplate | Create project from template | After choosing a template | | list-scaffolding-methods | Show features for a project | Adding to existing project | | use-scaffold-method | Add feature to project | After choosing a feature | | write-to-file | Write content to file | Custom files not in templates |

Admin Tools (with --admin-enable)

| Tool | Purpose | When to Use | |------|---------|-------------| | generate-boilerplate | Create new project template | Building custom templates | | generate-feature-scaffold | Create new feature scaffold | Adding feature generators | | generate-boilerplate-file | Add files to templates | Populating template files |

How It Works

Your Project                          Templates Directory
─────────────                         ───────────────────
apps/
├── my-app/                           templates/
│   ├── project.json ──────────────►  └── nextjs-15/
│   │   └── sourceTemplate: "nextjs-15"    ├── scaffold.yaml    ← Defines what can be generated
│   └── src/                               ├── architect.yaml   ← Design patterns (optional)
│       └── app/                           ├── RULES.yaml       ← Coding rules (optional)
│           └── page.tsx                   └── src/             ← Template files (.liquid)

1. Templates define boilerplates and features in scaffold.yaml
2. Projects reference templates with sourceTemplate
3. Tools read the template and generate files

Built-in Templates

| Template | Stack | What You Can Generate | |----------|-------|----------------------| | nextjs-15-drizzle | Next.js 15 + App Router | Pages, layouts, components, API routes | | typescript-lib | TypeScript library | Library structure, tests | | typescript-mcp-package | MCP server | CLI commands, MCP tools |

CLI Commands

scaffold-mcp also works as a standalone CLI:

# List available boilerplates
npx @agiflowai/scaffold-mcp boilerplate list

# Get info about a boilerplate
npx @agiflowai/scaffold-mcp boilerplate info nextjs-15-drizzle

# Create project from boilerplate
npx @agiflowai/scaffold-mcp boilerplate create nextjs-15-drizzle \
  --vars '{"projectName":"my-app","packageName":"@myorg/my-app"}'

# List features for a project
npx @agiflowai/scaffold-mcp scaffold list ./apps/my-app

# Add feature to project
npx @agiflowai/scaffold-mcp scaffold add scaffold-nextjs-page \
  --project ./apps/my-app \
  --vars '{"pageTitle":"About","nextjsPagePath":"/about"}'

Server Options

# stdio transport (default) - for Claude Code, Cursor
npx @agiflowai/scaffold-mcp mcp-serve

# HTTP transport - for web applications
npx @agiflowai/scaffold-mcp mcp-serve --type http --port 3000

# SSE transport - for streaming clients
npx @agiflowai/scaffold-mcp mcp-serve --type sse --port 3000

# With admin tools enabled
npx @agiflowai/scaffold-mcp mcp-serve --admin-enable

# With Claude Code skill front matter on prompts
npx @agiflowai/scaffold-mcp mcp-serve --prompt-as-skill

# With a fallback LLM tool for scaffold operations
npx @agiflowai/scaffold-mcp mcp-serve --fallback-tool claude-code

# Fallback tool with a specific model config
npx @agiflowai/scaffold-mcp mcp-serve \
  --fallback-tool claude-code \
  --fallback-tool-config '{"model":"claude-sonnet-4-6"}'

For .toolkit/settings.yaml or .toolkit/settings.local.yaml, you can define multiple ordered fallbacks:

scaffold-mcp:
  mcp-serve:
    fallbacks:
      - tool: gemini-cli
        config:
          model: gemini-2.0-flash
      - tool: codex
        config:
          model: gpt-5.2-mini

The first valid entry is used when fallbackTool is not set.

| Option | Description | Default | |--------|-------------|---------| | -t, --type | Transport: stdio, http, sse | stdio | | -p, --port | Port for HTTP/SSE | 3000 | | --host | Host for HTTP/SSE | localhost | | --admin-enable | Enable template creation tools | false | | --prompt-as-skill | Render MCP prompts with Claude Code skill front matter, exposing them as /skill commands | false | | --fallback-tool | LLM tool for scaffold operations (claude-code, gemini-cli, codex) | disabled | | --fallback-tool-config | JSON config for the CLI fallback tool; settings files may also use ordered fallbacks entries | {} |

Creating Custom Templates

Option 1: Using Admin Tools

Ask your AI agent:

"Create a boilerplate template for our React + Vite setup"

The agent will use:

1. generate-boilerplate
2. generate-boilerplate-file

Option 2: Manually

Create the template structure:

templates/my-template/
├── scaffold.yaml           # Required: defines boilerplates and features
└── src/                    # Template files (use .liquid for variable replacement)
    ├── package.json.liquid
    └── src/
        └── index.ts.liquid

scaffold.yaml example:

boilerplate:
  name: my-template-app
  description: My custom application template
  targetFolder: apps
  variables_schema:
    type: object
    properties:
      projectName:
        type: string
        description: Project directory name
      packageName:
        type: string
        description: NPM package name
    required:
      - projectName
      - packageName
  includes:
    - package.json
    - src/index.ts

features:
  - name: scaffold-component
    description: Add a React component
    variables_schema:
      type: object
      properties:
        componentName:
          type: string
          description: Component name (PascalCase)
      required:
        - componentName
    includes:
      - src/components/{{ componentName }}/{{ componentName }}.tsx

Template file example (package.json.liquid):

{
  "name": "{{ packageName }}",
  "version": "0.1.0",
  "description": "{{ description | default: 'My application' }}"
}

Hooks Integration (Experimental)

Note: This feature is experimental and may change.

Hooks let scaffold-mcp proactively suggest templates when your AI agent creates files.

Claude Code setup (.claude/settings.json):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx @agiflowai/scaffold-mcp hook --type claude-code.preToolUse"
          }
        ]
      }
    ]
  }
}

When Claude tries to write a new file, the hook shows available scaffolding methods that match, so Claude can use templates instead of writing from scratch.

See Hooks Documentation for details.

Documentation

| Document | Description | |----------|-------------| | MCP Tools Reference | Detailed tool documentation | | CLI Commands | Complete CLI reference | | Template Conventions | How to create templates | | Advanced Generators | Custom TypeScript generators | | Hooks Integration | AI agent hooks setup |

License

AGPL-3.0