@agiflowai/scaffold-mcp 0.0.0

package/README.md

@@ -0,0 +1,264 @@
+# @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**.
+
+## Features
+
+- **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
+- **Template management**: Initialize templates folder and add templates from remote repositories
+- **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 Desktop and other MCP-compatible clients
+
+## Installation
+
+```bash
+pnpm install @agiflowai/scaffold-mcp
+```
+
+## Usage
+
+### 1. MCP Server
+
+Run scaffold-mcp as an MCP server to integrate with Claude Desktop or other MCP clients.
+
+#### Starting the Server
+
+```bash
+# stdio transport (default) - for Claude Desktop
+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
+```
+
+**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 Desktop Configuration
+
+Add to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "scaffold-mcp": {
+      "command": "npx",
+      "args": ["-y", "@agiflowai/scaffold-mcp", "mcp-serve"]
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "scaffold-mcp": {
+      "command": "scaffold-mcp",
+      "args": ["mcp-serve"]
+    }
+  }
+}
+```
+
+**To enable admin tools** (for template creation), add the `--admin-enable` flag:
+
+```json
+{
+  "mcpServers": {
+    "scaffold-mcp": {
+      "command": "npx",
+      "args": ["-y", "@agiflowai/scaffold-mcp", "mcp-serve", "--admin-enable"]
+    }
+  }
+}
+```
+
+#### Available MCP Tools
+
+**Standard Tools** (always available):
+
+1. **list-boilerplates**: List all available project boilerplates
+   - Returns: Array of boilerplate configurations with schemas
+
+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
+
+3. **list-scaffolding-methods**: List available features for a project
+   - Arguments:
+     - `projectPath` (string): Absolute path to project directory
+
+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
+
+5. **write-to-file**: Write content to a file
+   - Arguments:
+     - `file_path` (string): Path to the file
+     - `content` (string): Content to write
+
+**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
+
+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
+
+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
+
+Use scaffold-mcp as a standalone CLI tool for template management and scaffolding.
+
+#### Template Management
+
+```bash
+# Initialize templates folder
+scaffold-mcp init
+scaffold-mcp init --path /path/to/templates
+
+# Add templates from repositories
+scaffold-mcp add --name my-template --url https://github.com/user/template
+scaffold-mcp add --name my-scaffold --url https://github.com/user/scaffold --type scaffold
+```
+
+#### Boilerplate Commands
+
+```bash
+# List available boilerplates
+scaffold-mcp boilerplate list
+
+# Show boilerplate details
+scaffold-mcp boilerplate info <boilerplate-name>
+
+# 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
+```
+
+#### Scaffold Commands
+
+```bash
+# List scaffolding methods for a project
+scaffold-mcp scaffold list ./apps/my-app
+
+# Show scaffold method details
+scaffold-mcp scaffold info <feature-name> --project ./apps/my-app
+
+# 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
+```
+
+#### Environment Variables
+
+- `MCP_PORT`: Port number for HTTP/SSE servers (default: 3000)
+- `MCP_HOST`: Host for HTTP/SSE servers (default: localhost)
+
+## Quick Start
+
+### 1. Initialize Templates
+
+```bash
+# Initialize templates folder in your project
+scaffold-mcp init
+
+# Or specify a custom path
+scaffold-mcp init --path ./my-templates
+```
+
+### 2. Add Templates
+
+```bash
+# Add a boilerplate template from a repository
+scaffold-mcp add --name nextjs-15 --url https://github.com/yourorg/nextjs-15-template
+
+# Add a scaffold template
+scaffold-mcp add --name react-component --url https://github.com/yourorg/react-component-scaffold --type scaffold
+```
+
+### 3. Create a New Project
+
+```bash
+# List available boilerplates
+scaffold-mcp boilerplate list
+
+# Get info about a specific boilerplate
+scaffold-mcp boilerplate info nextjs-15-boilerplate
+
+# 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"}'
+```
+
+### 4. Add Features to Existing Projects
+
+```bash
+# List available features for your project
+scaffold-mcp scaffold list /path/to/your/project
+
+# Get info about a specific scaffold method
+scaffold-mcp scaffold info scaffold-nextjs-page --project /path/to/your/project
+
+# 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"}'
+```
+
+## 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
+
+## License
+
+AGPL-3.0

package/dist/ScaffoldConfigLoader-CI0T6zdG.js

@@ -0,0 +1,142 @@
+import path from "node:path";
+import yaml from "js-yaml";
+import { z } from "zod";
+
+//#region src/services/ScaffoldConfigLoader.ts
+const VariablesSchemaSchema = z.object({
+	type: z.literal("object"),
+	properties: z.record(z.any()),
+	required: z.array(z.string()),
+	additionalProperties: z.boolean()
+});
+const ScaffoldConfigEntrySchema = z.object({
+	name: z.string(),
+	description: z.string().optional(),
+	instruction: z.string().optional(),
+	targetFolder: z.string().optional(),
+	variables_schema: VariablesSchemaSchema,
+	includes: z.array(z.string()),
+	generator: z.string().optional(),
+	patterns: z.array(z.string()).optional()
+});
+const ScaffoldYamlSchema = z.object({
+	boilerplate: z.union([ScaffoldConfigEntrySchema, z.array(ScaffoldConfigEntrySchema)]).optional(),
+	features: z.union([ScaffoldConfigEntrySchema, z.array(ScaffoldConfigEntrySchema)]).optional()
+}).catchall(z.union([ScaffoldConfigEntrySchema, z.array(ScaffoldConfigEntrySchema)]));
+var ScaffoldConfigLoader = class {
+	constructor(fileSystem, templateService) {
+		this.fileSystem = fileSystem;
+		this.templateService = templateService;
+	}
+	async parseArchitectConfig(templatePath) {
+		const architectPath = path.join(templatePath, "scaffold.yaml");
+		if (!await this.fileSystem.pathExists(architectPath)) return null;
+		try {
+			const content = await this.fileSystem.readFile(architectPath, "utf8");
+			const rawConfig = yaml.load(content);
+			return ScaffoldYamlSchema.parse(rawConfig);
+		} catch (error) {
+			if (error instanceof z.ZodError) {
+				const errorMessages = error.errors.map((err) => `${err.path.join(".")}: ${err.message}`).join("; ");
+				throw new Error(`scaffold.yaml validation failed: ${errorMessages}`);
+			}
+			throw new Error(`Failed to parse scaffold.yaml: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	parseIncludeEntry(includeEntry, variables) {
+		const [pathPart, conditionsPart] = includeEntry.split("?");
+		const conditions = {};
+		if (conditionsPart) {
+			const conditionPairs = conditionsPart.split("&");
+			for (const pair of conditionPairs) {
+				const [key, value] = pair.split("=");
+				if (key && value) conditions[key.trim()] = value.trim();
+			}
+		}
+		if (pathPart.includes("->")) {
+			const [sourcePath, targetPath] = pathPart.split("->").map((p) => p.trim());
+			return {
+				sourcePath,
+				targetPath: this.replaceVariablesInPath(targetPath, variables),
+				conditions
+			};
+		}
+		const processedPath = this.replaceVariablesInPath(pathPart.trim(), variables);
+		return {
+			sourcePath: pathPart.trim(),
+			targetPath: processedPath,
+			conditions
+		};
+	}
+	replaceVariablesInPath(pathStr, variables) {
+		return this.templateService.renderString(pathStr, variables);
+	}
+	shouldIncludeFile(conditions, variables) {
+		if (!conditions || Object.keys(conditions).length === 0) return true;
+		for (const [conditionKey, conditionValue] of Object.entries(conditions)) {
+			const variableValue = variables[conditionKey];
+			if (conditionValue === "true" || conditionValue === "false") {
+				const expectedBoolean = conditionValue === "true";
+				if (Boolean(variableValue) !== expectedBoolean) return false;
+			} else if (String(variableValue) !== conditionValue) return false;
+		}
+		return true;
+	}
+	async validateTemplate(templatePath, scaffoldType) {
+		const errors = [];
+		const missingFiles = [];
+		if (!await this.fileSystem.pathExists(templatePath)) {
+			errors.push(`Template directory ${templatePath} does not exist`);
+			return {
+				isValid: false,
+				errors,
+				missingFiles
+			};
+		}
+		let architectConfig;
+		try {
+			architectConfig = await this.parseArchitectConfig(templatePath);
+		} catch (error) {
+			errors.push(`Failed to parse scaffold.yaml: ${error instanceof Error ? error.message : String(error)}`);
+			return {
+				isValid: false,
+				errors,
+				missingFiles
+			};
+		}
+		if (!architectConfig) {
+			errors.push("scaffold.yaml not found in template directory");
+			return {
+				isValid: false,
+				errors,
+				missingFiles
+			};
+		}
+		if (!architectConfig[scaffoldType]) {
+			const availableTypes = Object.keys(architectConfig).join(", ");
+			errors.push(`Scaffold type '${scaffoldType}' not found in scaffold.yaml. Available types: ${availableTypes}`);
+			return {
+				isValid: false,
+				errors,
+				missingFiles
+			};
+		}
+		const config = architectConfig[scaffoldType];
+		if (config.includes && Array.isArray(config.includes)) for (const includeFile of config.includes) {
+			const parsed = this.parseIncludeEntry(includeFile, {});
+			const sourcePath = path.join(templatePath, parsed.sourcePath);
+			const liquidSourcePath = `${sourcePath}.liquid`;
+			const sourceExists = await this.fileSystem.pathExists(sourcePath);
+			const liquidExists = await this.fileSystem.pathExists(liquidSourcePath);
+			if (!sourceExists && !liquidExists) missingFiles.push(includeFile);
+		}
+		return {
+			isValid: errors.length === 0 && missingFiles.length === 0,
+			errors,
+			missingFiles
+		};
+	}
+};
+
+//#endregion
+export { ScaffoldConfigLoader };

package/dist/ScaffoldConfigLoader-DhthV6xq.js

@@ -0,0 +1,3 @@
+import { ScaffoldConfigLoader } from "./ScaffoldConfigLoader-CI0T6zdG.js";
+
+export { ScaffoldConfigLoader };

package/dist/ScaffoldService-CDhYAUrp.js

@@ -0,0 +1,3 @@
+import { ScaffoldService } from "./ScaffoldService-CnJ1nj1v.js";
+
+export { ScaffoldService };