@clubedge/create-clubedge-app 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.37.0
+
+- Add MCP server and agent skill (#110).
+- Still on Starter `v0.24.1`.
+
 ## 0.36.0
 
 - Bump vitest from 5.0.3 to 5.0.5 in the minor-and-patch group (#104).

package/README.md

@@ -27,6 +27,61 @@ Add, remove, or upgrade them later without losing your own changes.
 pnpm dlx @clubedge/create-clubedge-app my-app
 ```
 
+## MCP server
+
+Coding agents can connect to a local MCP server to inspect the capabilities of this CLI's pinned Starter release, validate stack and module choices, preview a complete scaffold plan, and generate a project in the server's working directory. The server exposes `get_starter_capabilities`, `validate_project_config`, `plan_project`, and `create_project`. Planning and validation do not write files. Project creation does not initialize Git or install dependencies unless those options are requested.
+
+After publishing a release that includes the MCP server, run it from the workspace where projects should be created:
+
+```sh
+npx -y --package @clubedge/create-clubedge-app create-clubedge-app-mcp
+```
+
+Configure an MCP client to launch `npx -y --package @clubedge/create-clubedge-app create-clubedge-app-mcp` with its working directory set to the workspace. In Codex, add this to `~/.codex/config.toml` and replace the example with the absolute path of the workspace where projects should be created:
+
+```toml
+[mcp_servers.clubedge-starter]
+command = "npx"
+args = ["--yes", "--package", "@clubedge/create-clubedge-app", "create-clubedge-app-mcp"]
+cwd = "D:/path/to/workspace"
+```
+
+The MCP server is included in the same package and uses the CLI's bundled Starter and compatibility rules. Its create tool only writes beneath the configured working directory and refuses a non-empty destination.
+
+### Agent skill
+
+The npm package includes the Agent Skill at [`skills/clubedge-starter/SKILL.md`](skills/clubedge-starter/SKILL.md). After the release is published, download and extract the package in PowerShell:
+
+```powershell
+$skillTarball = npm pack @clubedge/create-clubedge-app@latest
+tar -xzf $skillTarball
+```
+
+Then install it for the current user:
+
+```powershell
+# Codex
+New-Item -ItemType Directory -Force "$HOME/.agents/skills/clubedge-starter" | Out-Null
+Copy-Item .\package\skills\clubedge-starter\SKILL.md "$HOME/.agents/skills/clubedge-starter/SKILL.md"
+
+# Claude Code
+New-Item -ItemType Directory -Force "$HOME/.claude/skills/clubedge-starter" | Out-Null
+Copy-Item .\package\skills\clubedge-starter\SKILL.md "$HOME/.claude/skills/clubedge-starter/SKILL.md"
+```
+
+These commands create `package/` in the current directory. Remove that extracted folder and tarball when the copy is done. Before publication, the same copy commands work from the repository root by replacing `package/skills/...` with `skills/...`.
+
+For a repository-only install, use `.agents/skills/clubedge-starter/` for Codex or `.claude/skills/clubedge-starter/` for Claude Code instead of the `$HOME` paths. Restart the agent session after installing. In Codex, ask it to `Use the clubedge-starter skill to inspect the available stacks and modules. Do not create a project.` In Claude Code, invoke `/clubedge-starter` and give it the same request. The skill uses live MCP capabilities when available, so its choices follow the Starter release installed with the server.
+
+To connect the MCP server in Claude Code, run this from the workspace where projects should be created:
+
+```sh
+claude mcp add --scope local --transport stdio clubedge-starter -- npx -y --package @clubedge/create-clubedge-app create-clubedge-app-mcp
+claude mcp get clubedge-starter
+```
+
+Then open Claude Code in that workspace, invoke `/clubedge-starter`, and ask it to inspect the available stacks and modules without creating a project. In Codex, use the `cwd` in `~/.codex/config.toml` above, restart Codex, and ask the same prompt. To exercise project creation, ask the agent to create a named project in a new child folder with Git and dependency installation disabled; verify the folder and report before enabling those optional actions.
+
 ## Why create-clubedge-app
 
 Copying a starter is easy; living with it is not. You delete the services you don't use by hand, and once you've changed the code, every later improvement to the starter has to be copied over by hand too.
@@ -282,7 +337,7 @@ Projects created with `--infra neon` also have `.github/workflows/preview.yml`,
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.36.0
+create-clubedge-app v0.37.0
         |
         v
 Clubedge Starter v0.24.1
@@ -293,7 +348,7 @@ The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.36.0` | `clubedge-starter@v0.24.1` | The CLI's required, tested default |
+| `create-clubedge-app@0.37.0` | `clubedge-starter@v0.24.1` | The CLI's required, tested default |
 
 This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
 
@@ -404,6 +459,7 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.34.0 | v0.23.0 | Starter v0.23.0: a FastAPI API in Python (`--framework vite --api fastapi`), generated with no CLI change |
 | 0.35.0 | v0.24.0 | Deploy frontend and API stack packs; Default to Starter v0.24.0 |
 | 0.36.0 | v0.24.1 | Bump vitest from 5.0.3 to 5.0.5 in the minor-and-patch group; Bump giget from 2.0.0 to 3.3.1; Bump @types/node from 22.20.5 to 26.6.5; Default to Starter v0.24.1 |
+| 0.37.0 | v0.24.1 | Add MCP server and agent skill |
 | next | | Show the Starter's version of a conflicted file next to yours |
 
 ## Community

package/bin/mcp.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/mcp-server.js";

package/dist/mcp-server.js

@@ -0,0 +1,253 @@
+import { realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import process from "node:process";
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { z } from "zod/v4";
+import { executePlan } from "./core/execute.js";
+import { readTemplateManifest } from "./core/manifest.js";
+import { createPlan, describePlan } from "./core/plan.js";
+import { resolveTemplateSource } from "./core/source.js";
+import { cliVersion, cliUrl, siteUrl } from "./package-info.js";
+import { initializeGit } from "./steps/git.js";
+import { installDependencies, resolvePnpm } from "./steps/install.js";
+import { commandSucceeds, run } from "./utils/process.js";
+import { displayNameFromPackageName, packageNameFromDirectory } from "./utils/names.js";
+// Keep subprocess output off the MCP JSON-RPC stdout stream, and don't let children read MCP input.
+const mcpStdio = ["ignore", process.stderr, process.stderr];
+const selectionSchema = {
+    stacks: z.record(z.string(), z.string()).optional().describe("Stack id by slot, such as { framework: 'next', api: 'hono' }."),
+    modules: z.record(z.string(), z.string()).optional().describe("Module option by module id, such as { auth: 'supabase', storage: 's3' }."),
+};
+function isWithin(directory, candidate) {
+    const path = relative(directory, candidate);
+    return path === "" || (!isAbsolute(path) && path !== ".." && !path.startsWith(`..${sep}`));
+}
+async function workspaceDestination(directory) {
+    if (!directory.trim())
+        throw new Error("Choose a project directory inside the MCP server's working directory.");
+    if (isAbsolute(directory))
+        throw new Error("Use a relative project directory beneath the MCP server's working directory.");
+    const workspace = await realpath(process.cwd());
+    const target = resolve(workspace, directory);
+    if (!isWithin(workspace, target) || target === workspace) {
+        throw new Error("The project directory must be a child of the MCP server's working directory.");
+    }
+    // Resolve the nearest existing ancestor so a symlink inside the workspace cannot redirect
+    // project writes to an unrelated directory.
+    let ancestor = dirname(target);
+    let resolvedAncestor;
+    while (resolvedAncestor === undefined) {
+        try {
+            resolvedAncestor = await realpath(ancestor);
+        }
+        catch (error) {
+            if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT"))
+                throw error;
+            const parent = dirname(ancestor);
+            if (parent === ancestor)
+                throw error;
+            ancestor = parent;
+        }
+    }
+    if (resolvedAncestor === undefined || !isWithin(workspace, resolvedAncestor)) {
+        throw new Error("The project directory resolves outside the MCP server's working directory.");
+    }
+    try {
+        const resolvedTarget = await realpath(target);
+        if (!isWithin(workspace, resolvedTarget)) {
+            throw new Error("The project directory resolves outside the MCP server's working directory.");
+        }
+    }
+    catch (error) {
+        if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT"))
+            throw error;
+    }
+    return target;
+}
+async function withTemplate(fn) {
+    const source = await resolveTemplateSource({});
+    try {
+        return await fn(source);
+    }
+    finally {
+        await source.cleanup();
+    }
+}
+async function planProject(source, options, directory, sideEffects = {}) {
+    const manifest = await readTemplateManifest(source.root);
+    return createPlan({
+        targetDirectory: directory,
+        identity: {
+            packageName: packageNameFromDirectory(directory),
+            displayName: displayNameFromPackageName(packageNameFromDirectory(directory)),
+        },
+        source,
+        manifest,
+        stacks: options.stacks,
+        modules: options.modules,
+        cliVersion,
+        git: sideEffects.git ?? false,
+        install: sideEffects.install ?? false,
+    });
+}
+function capabilities(manifest, source) {
+    return {
+        cliVersion,
+        starter: {
+            repository: source.repository,
+            ref: source.ref,
+            commit: source.commit,
+            docs: cliUrl,
+            website: siteUrl,
+        },
+        slots: Object.entries(manifest.slots).map(([id, slot]) => ({
+            id,
+            name: slot.name,
+            default: slot.default ?? "none",
+            choices: Object.entries(manifest.stacks)
+                .filter(([, stack]) => stack.slot === id)
+                .map(([stackId, stack]) => ({ id: stackId, name: stack.name, role: stack.role, modules: stack.modules })),
+        })),
+        modules: Object.entries(manifest.modules).map(([id, module]) => ({
+            id,
+            name: module.name,
+            scope: module.scope,
+            default: module.default,
+            options: Object.entries(module.options).map(([optionId, option]) => ({
+                id: optionId,
+                name: option.name,
+                requires: option.requires,
+            })),
+        })),
+    };
+}
+function result(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+function createServer() {
+    const server = new McpServer({ name: "clubedge-starter", version: cliVersion });
+    server.registerTool("get_starter_capabilities", {
+        description: "Discover the frameworks, API stacks, modules, defaults, and compatibility choices supported by this CLI's pinned Clubedge Starter release.",
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+    }, async () => withTemplate(async (source) => result(capabilities(await readTemplateManifest(source.root), source))));
+    server.registerTool("validate_project_config", {
+        description: "Check requested stack and module choices against the pinned Starter. This does not write files.",
+        inputSchema: z.object(selectionSchema),
+        annotations: { readOnlyHint: true },
+    }, async (options) => withTemplate(async (source) => {
+        try {
+            const plan = await planProject(source, options, resolve(process.cwd(), ".clubedge-validation"));
+            return result({
+                valid: true,
+                stacks: plan.apps.map(({ slot, id, name }) => ({ slot, id, name })),
+                modules: plan.modules.map(({ id, option, optionName }) => ({ id, option, name: optionName })),
+            });
+        }
+        catch (error) {
+            return result({ valid: false, error: error instanceof Error ? error.message : String(error) });
+        }
+    }));
+    server.registerTool("plan_project", {
+        description: "Preview a complete scaffold plan using the pinned Starter. Validates stack and module compatibility and lists planned files and setup actions without writing to disk.",
+        inputSchema: z.object({
+            directory: z.string().min(1).describe("Destination path relative to the MCP server's working directory."),
+            ...selectionSchema,
+            initialize_git: z.boolean().default(false).describe("Include Git initialization in the plan."),
+            install_dependencies: z.boolean().default(false).describe("Include dependency installation in the plan."),
+        }),
+        annotations: { readOnlyHint: true },
+    }, async ({ directory, initialize_git, install_dependencies, ...options }) => withTemplate(async (source) => {
+        try {
+            const target = await workspaceDestination(directory);
+            const plan = await planProject(source, options, target, {
+                git: initialize_git,
+                install: install_dependencies,
+            });
+            return result({
+                valid: true,
+                directory: target,
+                destinationMustBeEmpty: true,
+                starterRef: plan.provenance.starterRef,
+                starterCommit: plan.provenance.starterCommit,
+                stacks: plan.apps.map(({ slot, id, name }) => ({ slot, id, name })),
+                modules: plan.modules.map(({ id, option, optionName }) => ({ id, option, name: optionName })),
+                fileCount: plan.files.length,
+                editCount: plan.edits.length,
+                environmentFiles: plan.envFiles.map(({ from, to }) => ({ source: from, destination: to })),
+                toolchains: plan.toolchains.map(({ directory: appDirectory, app, toolchain }) => ({
+                    directory: appDirectory,
+                    app,
+                    name: toolchain.name,
+                    install: toolchain.install,
+                })),
+                actions: describePlan(plan),
+            });
+        }
+        catch (error) {
+            return result({ valid: false, error: error instanceof Error ? error.message : String(error) });
+        }
+    }));
+    server.registerTool("create_project", {
+        description: "Generate a Clubedge Starter project under the MCP server's working directory. The destination must be empty or absent. Git initialization and dependency installation are opt-in.",
+        inputSchema: z.object({
+            directory: z.string().min(1).describe("Destination path relative to the MCP server's working directory."),
+            ...selectionSchema,
+            initialize_git: z.boolean().default(false).describe("Initialize a Git repository after generating files."),
+            install_dependencies: z.boolean().default(false).describe("Run pnpm install and declared secondary toolchain installs after generating files."),
+        }),
+    }, async ({ directory, initialize_git, install_dependencies, ...options }) => withTemplate(async (source) => {
+        const target = await workspaceDestination(directory);
+        const plan = await planProject(source, options, target, { git: initialize_git, install: install_dependencies });
+        await executePlan(plan, source);
+        const warnings = [];
+        if (initialize_git) {
+            try {
+                await initializeGit(target, mcpStdio);
+            }
+            catch (error) {
+                warnings.push(`Project created, but Git initialization failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (install_dependencies) {
+            const pnpm = await resolvePnpm();
+            if (!pnpm) {
+                warnings.push("Project created, but pnpm was not found. Install pnpm and run it in the project directory.");
+            }
+            else {
+                try {
+                    await installDependencies(target, pnpm, [], mcpStdio);
+                    for (const { directory: appDirectory, app, toolchain } of plan.toolchains) {
+                        const [check, ...checkArgs] = toolchain.check;
+                        if (!(await commandSucceeds(check, checkArgs))) {
+                            warnings.push(`${toolchain.name} is required to install ${app} dependencies: ${toolchain.url}`);
+                            continue;
+                        }
+                        const [command, ...args] = toolchain.install;
+                        try {
+                            await run(command, args, resolve(target, appDirectory), mcpStdio);
+                        }
+                        catch (error) {
+                            warnings.push(`${app} dependencies did not install: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                }
+                catch (error) {
+                    warnings.push(`Project created, but dependency installation did not complete: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+        return result({
+            created: true,
+            directory: target,
+            starterRef: plan.provenance.starterRef,
+            stacks: plan.apps.map(({ slot, id, name }) => ({ slot, id, name })),
+            modules: plan.modules.map(({ id, option, optionName }) => ({ id, option, name: optionName })),
+            actions: describePlan(plan),
+            warnings,
+        });
+    }));
+    return server;
+}
+serveStdio(createServer);

package/dist/steps/git.js

@@ -1,11 +1,11 @@
 import { run } from "../utils/process.js";
-export async function initializeGit(directory) {
+export async function initializeGit(directory, stdio) {
     try {
-        await run("git", ["init", "-b", "main"], directory);
+        await run("git", ["init", "-b", "main"], directory, stdio);
     }
     catch {
         // Git before 2.28 has no -b option.
-        await run("git", ["init"], directory);
-        await run("git", ["branch", "-M", "main"], directory);
+        await run("git", ["init"], directory, stdio);
+        await run("git", ["branch", "-M", "main"], directory, stdio);
     }
 }

package/dist/steps/install.js

@@ -13,7 +13,7 @@ export function detectLauncher(userAgent = process.env.npm_config_user_agent) {
     const name = userAgent?.split("/")[0];
     return name && ["npm", "pnpm", "yarn", "bun"].includes(name) ? name : null;
 }
-export async function installDependencies(directory, pnpm, args = []) {
+export async function installDependencies(directory, pnpm, args = [], stdio) {
     const [command, ...prefix] = pnpm;
-    await run(command, [...prefix, "install", ...args], directory);
+    await run(command, [...prefix, "install", ...args], directory, stdio);
 }

package/dist/utils/process.js

@@ -16,9 +16,9 @@ export function spawnCommand(command, args, options, shell = useShell) {
     return spawn([command, ...args].map(quoteForCmd).join(" "), { ...options, shell: true });
 }
 /** Runs a command with inherited output. Rejects on a non-zero exit. */
-export async function run(command, args, cwd) {
+export async function run(command, args, cwd, stdio = "inherit") {
     await new Promise((resolve, reject) => {
-        const child = spawnCommand(command, args, { cwd, stdio: "inherit" });
+        const child = spawnCommand(command, args, { cwd, stdio });
         child.once("error", reject);
         child.once("exit", (code, signal) => {
             if (code === 0)

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.36.0",
-  "description": "Create a React app with Next.js, TanStack Start, or Vite and a separate API from the Clubedge Starter.",
+  "version": "0.37.0",
+  "description": "Create React apps from Clubedge Starter with a CLI or local MCP server.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
   "bin": {
-    "create-clubedge-app": "./bin/create.mjs"
+    "create-clubedge-app": "./bin/create.mjs",
+    "create-clubedge-app-mcp": "./bin/mcp.mjs"
   },
   "files": [
     "bin/",
     "dist/",
     "template/",
     "template.lock.json",
+    "skills/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
@@ -40,7 +42,10 @@
     "nextjs",
     "tanstack-start",
     "starter",
-    "scaffolding"
+    "scaffolding",
+    "mcp",
+    "model-context-protocol",
+    "ai-agent"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -52,10 +57,12 @@
     "release": "node scripts/release.mjs"
   },
   "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
     "@clack/prompts": "^1.8.1",
     "giget": "^3.3.1",
     "node-diff3": "^3.2.1",
-    "ssh2": "^1.17.0"
+    "ssh2": "^1.17.0",
+    "zod": "^4.2.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.5",

package/skills/clubedge-starter/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: clubedge-starter
+description: Create and evolve applications based on Clubedge Starter with the create-clubedge-app CLI or MCP server. Use when asked to scaffold a Clubedge app, choose its framework or modules, validate a configuration, or change Starter modules in an existing generated project.
+compatibility: Requires Node.js 22.12+ and pnpm 10.9+ to create projects. The MCP workflow requires the Clubedge Starter MCP server to be configured.
+metadata:
+  author: Clubedge
+  repository: https://github.com/Clubedge/create-clubedge-app
+---
+
+# Clubedge Starter
+
+Create and manage Clubedge Starter projects through the supported CLI or MCP tools. Follow the user's requested stack and services; do not add unrequested modules.
+
+## Choose the interface
+
+- If the `clubedge-starter` MCP server is available, call `get_starter_capabilities` first. Treat its response as authoritative for framework/API choices, module options, defaults, and requirements.
+- Before scaffolding through MCP, call `plan_project` with the destination `directory` and requested `stacks` and `modules`. It validates compatibility and previews the files and setup actions without writing to disk. Resolve invalid combinations and any open choices before creating the project. Use `validate_project_config` when only a compatibility check is needed and no destination plan is useful.
+- Use `create_project` to scaffold through MCP. Give `directory` as a relative path beneath the MCP server's working directory. Set `initialize_git` and `install_dependencies` to `true` only when appropriate for the user's request; both default to `false`.
+- If MCP is unavailable, use the CLI. Prefer the installed project-local executable when present; otherwise use `pnpm dlx @clubedge/create-clubedge-app <directory> --yes` and provide the requested options as CLI flags.
+- Use the CLI's `add`, `remove`, or `upgrade` commands for changes to an existing generated project. Do not reproduce those changes by manually copying Starter files.
+
+## Scaffold a project
+
+For a new app:
+
+1. Identify the requested framework and API shape. Full-stack choices such as Next.js and TanStack Start do not use a separate API; Vite can be paired with Hono or FastAPI.
+2. Choose only the requested modules. Check the live capabilities or CLI `--help` rather than relying on a hard-coded list, since each CLI release is pinned to a specific Starter release.
+3. Validate that module requirements are met. For example, module compatibility can depend on the selected framework or another module.
+4. Preview with the CLI's `--dry-run` when the requested changes or destination are unclear. For MCP, describe the exact target directory and options before creating if the user has not made them clear.
+5. Create only in a new or empty directory. The MCP tool only accepts paths under its configured working directory. The CLI also refuses to overwrite an existing project.
+6. Report the target path, selected stacks and modules, and any actions that still need to be run, such as dependency installation or starting local infrastructure.
+
+CLI example:
+
+```sh
+pnpm dlx @clubedge/create-clubedge-app my-app --yes --framework next --auth better-auth --infra local
+```
+
+## Change an existing project
+
+Run the CLI from the generated project directory:
+
+```sh
+pnpm clubedge add payments stripe
+pnpm clubedge remove storage
+pnpm clubedge upgrade
+```
+
+Check the project's Git state first. These commands preserve user edits and can report merge conflicts that need review. After a change, follow the CLI's instructions and run relevant checks, migrations, or service setup for the modules involved.
+
+## Project guidance
+
+- Keep secrets in the project's environment file and never print or commit secret values.
+- Do not claim a project was created, installed, migrated, or deployed until the corresponding action succeeded.
+- If an install or provider setup fails, report the exact failed step and the next command needed to resume; do not silently present a partially configured project as ready.
+- Consult the generated `SETUP.md` and the official docs at https://starter.clubedge.live/docs for provider-specific configuration.