@agiflowai/scaffold-mcp

MCP server for scaffolding applications with templates and feature generators

Use the local CLI to generate projects and feature boilerplate from template-defined scaffolds without loading MCP tools into your agent's context. MCP serving remains available.

Local CLI: progressive discovery

After installing templates (below), discover only what you need:

npx @agiflowai/scaffold-mcp --help
npx @agiflowai/scaffold-mcp boilerplate --help
npx @agiflowai/scaffold-mcp boilerplate list --json
npx @agiflowai/scaffold-mcp boilerplate info typescript-lib --json
npx @agiflowai/scaffold-mcp boilerplate create --help
npx @agiflowai/scaffold-mcp scaffold --help
npx @agiflowai/scaffold-mcp scaffold list ./apps/my-app --json
npx @agiflowai/scaffold-mcp scaffold info scaffold-service --project ./apps/my-app --json
npx @agiflowai/scaffold-mcp scaffold add --help

Use --help at each level for arguments, prerequisites, and examples. Use --json on local commands for one structured success document on stdout; failures emit JSON on stderr and exit nonzero. boilerplate generate, scaffold generate, and template file create author reusable templates, while boilerplate create and scaffold add generate project files.

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

# Create template authoring entries (CLI equivalents for admin MCP tools)
npx @agiflowai/scaffold-mcp boilerplate generate scaffold-vite-app \
  --template vite-react \
  --description "React Vite starter" \
  --target-folder apps \
  --variables '[{"name":"appName","description":"Application name","type":"string","required":true}]'

npx @agiflowai/scaffold-mcp scaffold generate scaffold-service \
  --template typescript-lib \
  --description "Generate a service class and unit test" \
  --variables '[{"name":"serviceName","description":"Service name","type":"string","required":true}]'

npx @agiflowai/scaffold-mcp template file create src/index.ts \
  --template typescript-lib \
  --content 'export const {{ name | camelCase }} = "{{ name }}";'

npx @agiflowai/scaffold-mcp file write .env.local \
  --content 'NEXT_PUBLIC_API_URL=https://api.example.com'

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.

Hooks are also available for Gemini CLI and OpenAI Codex CLI (--type codex.preToolUse, configured in .codex/config.toml); see the hooks docs for setup.

Relaxing enforcement: to let some files (docs, content, generated code) be written directly, add exclude globs — workspace-wide via scaffold-mcp.hook.excludeGlobs in .toolkit/settings.yaml, or per-template via a top-level exclude in scaffold.yaml:

# .toolkit/settings.yaml
scaffold-mcp:
  hook:
    excludeGlobs:
      - '**/*.md'
      - '**/*.mdx'
      - '**/src/content/**'

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