@agiflowai/scaffold-mcp 1.0.6 → 1.0.8

package/README.md

@@ -1,246 +1,284 @@
 # @agiflowai/scaffold-mcp
 
-A Model Context Protocol (MCP) server for scaffolding applications with boilerplate templates and feature generators. Supports multiple transport modes: **stdio**, **HTTP**, **SSE**, and **CLI**.
+> MCP server for scaffolding applications with templates and feature generators
 
-## Features
+Generate consistent, convention-following code for your AI coding agents. scaffold-mcp provides templates for common patterns (routes, components, services) so agents don't write boilerplate from scratch.
 
-- **Boilerplate scaffolding**: Generate complete application structures from templates
-- **Feature scaffolding**: Add features to existing projects with custom generators
-- **Custom generators**: Template-specific TypeScript generators for advanced scaffolding logic
-- **Liquid templating**: Use powerful templating engine for dynamic file generation
-- **Variable replacement**: Customize generated code with context-aware variable substitution
-- **Dynamic template discovery**: Automatically finds templates in your workspace
-- **Multiple frameworks**: Support for Next.js, Vite React, and custom boilerplates
-- **Multiple modes**: MCP server mode (stdio/HTTP/SSE) and standalone CLI mode
-- **MCP integration**: Seamlessly works with Claude Code and other MCP-compatible clients
+## Why Use This?
 
-## Installation
+When you ask an AI agent to "add a new page," it generates working code—but not necessarily code that follows your team's patterns. scaffold-mcp solves this by:
 
-```bash
-pnpm install @agiflowai/scaffold-mcp
-```
+1. **Providing templates** for common patterns your team has standardized
+2. **Enforcing structure** so every route, component, or service looks the same
+3. **Reducing boilerplate** by generating the repetitive parts automatically
 
-## Usage
+Think of it as "Rails generators" or "Angular schematics" for any stack.
 
-### 1. MCP Server
+---
 
-Run scaffold-mcp as an MCP server to integrate with Claude Code or other MCP clients.
+## Quick Start
 
-#### Starting the Server
+### 1. Install Templates
 
 ```bash
-# stdio transport (default) - for Claude Code
-npx @agiflowai/scaffold-mcp mcp-serve
-
-# HTTP transport - for web applications
-npx @agiflowai/scaffold-mcp mcp-serve --type http --port 3000
-
-# SSE transport - for legacy clients
-npx @agiflowai/scaffold-mcp mcp-serve --type sse --port 3000
-
-# Enable admin mode (template generation tools)
-npx @agiflowai/scaffold-mcp mcp-serve --admin-enable
+# Downloads built-in templates to your workspace
+npx @agiflowai/aicode-toolkit init
 ```
 
-**Server Options:**
-- `-t, --type <type>`: Transport type: `stdio`, `http`, or `sse` (default: `stdio`)
-- `-p, --port <port>`: Port for HTTP/SSE servers (default: `3000`)
-- `--host <host>`: Host to bind to for HTTP/SSE (default: `localhost`)
-- `--admin-enable`: Enable admin tools for template generation
-
-#### Claude Code Configuration
+### 2. Configure Your AI Agent
 
-Add to your Claude Code config:
+Add to your MCP config (`.mcp.json`, `.cursor/mcp.json`, etc.):
 
 ```json
 {
   "mcpServers": {
     "scaffold-mcp": {
       "command": "npx",
-      "args": ["-y", "@agiflowai/scaffold-mcp", "mcp-serve"]
+      "args": ["-y", "@agiflowai/scaffold-mcp", "mcp-serve", "--admin-enable"]
     }
   }
 }
 ```
 
-Or if installed globally:
+**Flags:**
+- `--admin-enable`: Enables tools for creating new templates (optional, useful during setup)
 
-```json
-{
-  "mcpServers": {
-    "scaffold-mcp": {
-      "command": "scaffold-mcp",
-      "args": ["mcp-serve"]
-    }
-  }
-}
-```
+### 3. Start Using
 
-**To enable admin tools** (for template creation), add the `--admin-enable` flag:
+Your AI agent now has access to scaffolding tools:
 
-```json
-{
-  "mcpServers": {
-    "scaffold-mcp": {
-      "command": "npx",
-      "args": ["-y", "@agiflowai/scaffold-mcp", "mcp-serve", "--admin-enable"]
-    }
-  }
-}
 ```
+You: "Create a new Next.js app called dashboard"
+Agent: [calls list-boilerplates, then use-boilerplate]
 
-#### Available MCP Tools
+You: "Add a products page"
+Agent: [calls list-scaffolding-methods, then use-scaffold-method]
+```
 
-**Standard Tools** (always available):
+---
 
-1. **list-boilerplates**: List all available project boilerplates
-   - Returns: Array of boilerplate configurations with schemas
+## Available Tools
 
-2. **use-boilerplate**: Create a new project from a boilerplate template
-   - Arguments:
-     - `boilerplateName` (string): Name of the boilerplate
-     - `variables` (object): Variables matching the boilerplate's schema
+### Standard Tools
 
-3. **list-scaffolding-methods**: List available features for a project
-   - Arguments:
-     - `projectPath` (string): Absolute path to project directory
+| 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 |
 
-4. **use-scaffold-method**: Add a feature to an existing project
-   - Arguments:
-     - `projectPath` (string): Absolute path to project directory
-     - `scaffold_feature_name` (string): Name of the feature to add
-     - `variables` (object): Variables for the feature
+### Admin Tools (with `--admin-enable`)
 
-5. **write-to-file**: Write content to a file
-   - Arguments:
-     - `file_path` (string): Path to the file
-     - `content` (string): Content to write
+| 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 |
 
-**Admin Tools** (enabled with `--admin-enable` flag):
+---
 
-6. **generate-boilerplate**: Create a new boilerplate configuration in a template's scaffold.yaml
-   - Arguments:
-     - `templateName` (string): Name of the template folder
-     - `boilerplateName` (string): Name of the boilerplate (kebab-case)
-     - `description` (string): Detailed description
-     - `targetFolder` (string): Target folder for projects
-     - `variables` (array): Variable definitions with schema
-     - `includes` (array): Template files to include
-     - `instruction` (string, optional): Usage instructions
+## How It Works
 
-7. **generate-feature-scaffold**: Create a new feature configuration in a template's scaffold.yaml
-   - Arguments:
-     - `templateName` (string): Name of the template folder
-     - `featureName` (string): Name of the feature (kebab-case)
-     - `description` (string): Feature description
-     - `variables` (array): Variable definitions with schema
-     - `includes` (array, optional): Template files to include
-     - `patterns` (array, optional): File patterns this feature works with
-     - `instruction` (string, optional): Usage instructions
+```
+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 patterns**: Each template has a `scaffold.yaml` that defines boilerplates and features
+2. **Projects reference templates**: Your `project.json` has a `sourceTemplate` field pointing to the template
+3. **Tools generate code**: MCP tools read the template and generate files in your project
 
-8. **generate-boilerplate-file**: Create template files for boilerplates or features
-   - Arguments:
-     - `templateName` (string): Name of the template folder
-     - `filePath` (string): Path of the file within the template
-     - `content` (string): File content with Liquid variables
-     - `header` (string, optional): Header comment for AI hints
-     - `sourceFile` (string, optional): Copy from existing source file
+---
 
-### 2. CLI Commands
+## Built-in Templates
 
-Use scaffold-mcp as a standalone CLI tool for scaffolding projects and adding features.
+| 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 |
 
-**Note:** Template management (init, add) is now handled by the `@agiflowai/aicode-toolkit` CLI. See [aicode-toolkit documentation](../../apps/aicode-toolkit/README.md) for details.
+---
 
-#### Boilerplate Commands
+## CLI Commands
+
+scaffold-mcp also works as a standalone CLI:
 
 ```bash
 # List available boilerplates
-scaffold-mcp boilerplate list
+npx @agiflowai/scaffold-mcp boilerplate list
 
-# Show boilerplate details
-scaffold-mcp boilerplate info <boilerplate-name>
+# Get info about a boilerplate
+npx @agiflowai/scaffold-mcp boilerplate info nextjs-15-drizzle
 
 # Create project from boilerplate
-scaffold-mcp boilerplate create <name> --vars '{"appName":"my-app"}'
-scaffold-mcp boilerplate create nextjs-15-boilerplate \
-  --vars '{"projectName":"my-app","packageName":"@myorg/my-app"}' \
-  --verbose
+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"}'
 ```
 
-#### Scaffold Commands
+---
+
+## Server Options
 
 ```bash
-# List scaffolding methods for a project
-scaffold-mcp scaffold list ./apps/my-app
+# stdio transport (default) - for Claude Code, Cursor
+npx @agiflowai/scaffold-mcp mcp-serve
 
-# Show scaffold method details
-scaffold-mcp scaffold info <feature-name> --project ./apps/my-app
+# HTTP transport - for web applications
+npx @agiflowai/scaffold-mcp mcp-serve --type http --port 3000
 
-# Add feature to project
-scaffold-mcp scaffold add <feature> --project ./apps/my-app --vars '{"name":"MyFeature"}'
-scaffold-mcp scaffold add scaffold-nextjs-page \
-  --project ./apps/my-app \
-  --vars '{"pageTitle":"About Us","nextjsPagePath":"/about"}' \
-  --verbose
+# 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
 ```
 
-#### Environment Variables
+| 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` |
 
-- `MCP_PORT`: Port number for HTTP/SSE servers (default: 3000)
-- `MCP_HOST`: Host for HTTP/SSE servers (default: localhost)
+---
 
-## Quick Start
+## Creating Custom Templates
 
-### 1. Setup Templates
+### Option 1: Using Admin Tools (Recommended)
 
-For template management (downloading and managing templates), use the `@agiflowai/aicode-toolkit` CLI:
+Ask your AI agent:
+```
+"Create a boilerplate template for our React + Vite setup"
+```
 
-```bash
-# Initialize workspace and download templates
-npx @agiflowai/aicode-toolkit init
+The agent will use:
+1. `generate-boilerplate` - Creates scaffold.yaml entry
+2. `generate-boilerplate-file` - Adds template files
 
-# Add custom templates
-npx @agiflowai/aicode-toolkit add --name my-template --url https://github.com/user/template
-```
+### Option 2: Manually
 
-See the [aicode-toolkit documentation](../../apps/aicode-toolkit/README.md) for complete setup instructions.
+Create the template structure:
 
-### 2. Create a New Project
+```
+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
+```
 
-```bash
-# List available boilerplates
-scaffold-mcp boilerplate list
+**scaffold.yaml example:**
+
+```yaml
+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
+```
 
-# Get info about a specific boilerplate
-scaffold-mcp boilerplate info nextjs-15-boilerplate
+**Template file example (package.json.liquid):**
 
-# Create a new Next.js 15 project
-scaffold-mcp boilerplate create nextjs-15-boilerplate \
-  --vars '{"projectName":"my-app","packageName":"@myorg/my-app","appName":"My App"}'
+```json
+{
+  "name": "{{ packageName }}",
+  "version": "0.1.0",
+  "description": "{{ description | default: 'My application' }}"
+}
 ```
 
-### 3. Add Features to Existing Projects
+---
 
-```bash
-# List available features for your project
-scaffold-mcp scaffold list /path/to/your/project
+## Hooks Integration (Experimental)
+
+> **Note:** This feature is experimental and may change.
 
-# Get info about a specific scaffold method
-scaffold-mcp scaffold info scaffold-nextjs-page --project /path/to/your/project
+Hooks let scaffold-mcp proactively suggest templates when your AI agent creates files.
 
-# Add a new Next.js page
-scaffold-mcp scaffold add scaffold-nextjs-page \
-  --project /path/to/your/project \
-  --vars '{"pageTitle":"About Us","pageDescription":"Learn more","nextjsPagePath":"/about"}'
+**Claude Code setup** (`.claude/settings.json`):
+
+```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](./docs/hooks.md) for details.
+
+---
+
 ## Documentation
 
-- [CLI Commands](./docs/cli-commands.md) - Complete CLI reference
-- [MCP Tools](./docs/mcp-tools.md) - MCP server tools reference
-- [Template Conventions](./docs/template-conventions.md) - Guide for creating templates with Liquid syntax
-- [Advanced Generators](./docs/advanced-generators.md) - Guide for creating custom TypeScript generators
+| Document | Description |
+|----------|-------------|
+| [MCP Tools Reference](./docs/mcp-tools.md) | Detailed tool documentation |
+| [CLI Commands](./docs/cli-commands.md) | Complete CLI reference |
+| [Template Conventions](./docs/template-conventions.md) | How to create templates |
+| [Advanced Generators](./docs/advanced-generators.md) | Custom TypeScript generators |
+| [Hooks Integration](./docs/hooks.md) | AI agent hooks setup |
+
+---
 
 ## License