create-basalt 1.2.2 → 1.3.0

package/README.md

@@ -46,6 +46,7 @@ Multi-tenancy? (Y/n) y
 Authentication? (Y/n) y
 Subscriptions / billing? (y/N) n
 Web UI (React + shadcn)? (y/N) n
+MCP server (routes as AI-agent tools)? (y/N) n
 'basalt' CLI (code generators)? (y/N) n
 Install dependencies now? (y/N) y
 Initialize a git repository? (y/N) y
@@ -89,6 +90,7 @@ Usage: npm create basalt <name> [options]
 | `--billing` | off | Includes subscriptions/plans (`@basaltkit/subscriptions`, example `free` and `pro` plans) |
 | `--ui` | off | Generates the `web/` frontend (React + shadcn via `@basaltkit/admin-shadcn` + `@basaltkit/sdk`). **Forces pnpm** — see note below |
 | `--cli` | off | Generates the `basalt` CLI (`bin/basalt.ts`, `pnpm basalt` script, `make:*` generators from `@basaltkit/generator`) |
+| `--mcp` | off | Exposes read-only routes as MCP tools (`@basaltkit/mcp`) over HTTP at `POST /mcp` — the overview and health endpoints are opted in via `meta.mcp` |
 | `--install` | off | Installs dependencies at the end (with the detected/chosen manager) |
 | `--git` | off | Runs `git init` + first commit ("Initial commit from create-basalt") |
 | `--pm=<manager>` | autodetect | Package manager: `pnpm` \| `npm` \| `yarn` \| `bun` |
@@ -202,6 +204,7 @@ Exported from `create-basalt` (in addition to the `create-basalt` executable):
 | `billing` | `boolean` | No | `false` | Include subscriptions |
 | `ui` | `boolean` | No | `false` | Generate the `web/` frontend |
 | `cli` | `boolean` | No | `false` | Generate the `basalt` CLI |
+| `mcp` | `boolean` | No | `false` | Expose read-only routes as MCP tools at `/mcp` |
 
 `CreateProjectResult`:
 

package/dist/cli.js

@@ -11,6 +11,7 @@ Options:
   --billing       Include subscriptions/billing
   --ui            Scaffold a web/ frontend (React + shadcn + SDK)
   --cli           Scaffold the 'basalt' CLI (code generators + commands)
+  --mcp           Expose read-only routes as MCP tools at /mcp
   --install       Install dependencies after scaffolding
   --git           Initialize a git repository with a first commit
   --pm=<manager>  Package manager: pnpm | npm | yarn | bun (default: auto-detect)
@@ -26,6 +27,7 @@ function parseArgs(argv) {
         billing: false,
         ui: false,
         cli: false,
+        mcp: false,
         install: false,
         git: false,
         yes: false,
@@ -41,6 +43,8 @@ function parseArgs(argv) {
             flags.ui = true;
         else if (token === '--cli')
             flags.cli = true;
+        else if (token === '--mcp')
+            flags.mcp = true;
         else if (token === '--install')
             flags.install = true;
         else if (token === '--git')
@@ -91,6 +95,7 @@ if (!flags.yes && flags.name === undefined && stdin.isTTY) {
         flags.billing = result.billing;
         flags.ui = result.ui;
         flags.cli = result.cli;
+        flags.mcp = result.mcp;
         flags.install = result.install;
         flags.git = result.git;
         flags.pm = result.pm;
@@ -121,6 +126,7 @@ try {
         billing: flags.billing,
         ui: flags.ui,
         cli: flags.cli,
+        mcp: flags.mcp,
     });
     console.log(`\nCreated ${result.options.name} in ${result.dir}\n`);
     for (const file of result.files)

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export interface CreateProjectInput {
     ui?: boolean;
     /** Scaffold the `basalt` CLI entrypoint (code generators + commands). Default: false. */
     cli?: boolean;
+    /** Expose opted-in routes as MCP tools over HTTP at `/mcp`. Default: false. */
+    mcp?: boolean;
 }
 export interface CreateProjectResult {
     dir: string;

package/dist/index.js

@@ -1,6 +1,6 @@
 import { mkdir, readdir, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
-import { appTest, appTs, envExample, envTs, gitignore, basaltBin, packageJson, pnpmWorkspaceYaml, readme, routesTs, serverTs, tsconfigJson, } from './templates.js';
+import { appTest, appTs, envExample, envTs, gitignore, mcpJson, basaltBin, packageJson, pnpmWorkspaceYaml, readme, routesTs, serverTs, tsconfigJson, } from './templates.js';
 import { uiFiles } from './templates-ui.js';
 export class TargetNotEmptyError extends Error {
     constructor(dir) {
@@ -27,6 +27,7 @@ export async function createProject(input) {
         billing: input.billing ?? false,
         ui: input.ui ?? false,
         cli: input.cli ?? false,
+        mcp: input.mcp ?? false,
     };
     const dir = resolve(input.dir ?? input.name);
     const existing = await readdir(dir).catch(() => null);
@@ -45,6 +46,7 @@ export async function createProject(input) {
         'src/server.ts': serverTs(),
         'tests/app.test.ts': appTest(options),
         ...(options.cli ? { 'bin/basalt.ts': basaltBin() } : {}),
+        ...(options.mcp ? { '.mcp.json': mcpJson(options) } : {}),
         ...(options.ui ? uiFiles(options) : {}),
     };
     for (const [path, content] of Object.entries(files)) {

package/dist/templates.d.ts

@@ -7,6 +7,8 @@ export interface ProjectOptions {
     ui: boolean;
     /** Scaffold the `basalt` CLI entrypoint (code generators + built-in commands). */
     cli: boolean;
+    /** Expose opted-in routes as MCP tools (@basaltkit/mcp) over HTTP at `/mcp`. */
+    mcp: boolean;
 }
 /** The dependency range for a @basalt package (override, else the base line). */
 export declare const versionOf: (pkg: string) => string;
@@ -20,6 +22,12 @@ export declare function serverTs(): string;
 export declare function basaltBin(): string;
 export declare function appTest(options: ProjectOptions): string;
 export declare function readme(options: ProjectOptions): string;
+/**
+ * A Claude Code / generic MCP client config that registers the dev-only
+ * `basalt-ai-mcp` bridge for this project. Claude Code reads `.mcp.json` at the
+ * project root automatically; Claude Desktop uses the same server entry.
+ */
+export declare function mcpJson(_options: ProjectOptions): string;
 export declare function gitignore(): string;
 /**
  * pnpm settings: esbuild's build script is required by tsx;

package/dist/templates.js

@@ -5,7 +5,10 @@ const BASALT_VERSION = '^1.0.0';
  * package that advances past the base line needs its own range or a fresh app
  * can't install it. Add an entry when a package crosses a minor.
  */
-const VERSIONS = {};
+const VERSIONS = {
+    // ai-mcp is on the 0.x line (published separately from the 1.x framework base).
+    '@basaltkit/ai-mcp': '^0.1.0',
+};
 /** The dependency range for a @basalt package (override, else the base line). */
 export const versionOf = (pkg) => VERSIONS[pkg] ?? BASALT_VERSION;
 export function packageJson(options) {
@@ -24,6 +27,8 @@ export function packageJson(options) {
         dependencies['@basaltkit/auth'] = BASALT_VERSION;
     if (options.billing)
         dependencies['@basaltkit/subscriptions'] = BASALT_VERSION;
+    if (options.mcp)
+        dependencies['@basaltkit/mcp'] = BASALT_VERSION;
     if (options.cli) {
         // Runtime deps: app.ts uses commandsPlugin (@basaltkit/cli); prisma powers
         // prismaPlugin + `basalt prisma:sync`. @basaltkit/generator is dev-only (below).
@@ -50,6 +55,12 @@ export function packageJson(options) {
         // never does, so the app runs completely without the codegen/AI layer.
         devDependencies['@basaltkit/generator'] = versionOf('@basaltkit/generator');
     }
+    if (options.mcp) {
+        // Dev-only AI bridge: exposes analyze/plan/make to MCP clients (Claude
+        // Code/Desktop) via the `basalt-ai-mcp` bin. NEVER a runtime dependency — the
+        // app ships and runs without it (see `.mcp.json` for the client config).
+        devDependencies['@basaltkit/ai-mcp'] = versionOf('@basaltkit/ai-mcp');
+    }
     return `${JSON.stringify({
         name: options.name,
         version: '0.1.0',
@@ -166,7 +177,19 @@ export function appTs(options) {
         imports.push(`import { commandsPlugin, type CommandDefinition } from '@basaltkit/cli'`);
         plugins.push(`...(options.commands && options.commands.length > 0 ? [commandsPlugin(options.commands)] : [])`);
     }
-    plugins.push(`fastifyPlugin({ routes: ${routesExpression} })`);
+    let adapterRoutesExpr = routesExpression;
+    if (options.mcp) {
+        imports.push(`import { mcpPlugin, mcpRoutes } from '@basaltkit/mcp'`);
+        // The MCP server scans the SAME app routes for `meta.mcp` (see routes.ts); the
+        // `/mcp` transport is added to the adapter so agents POST JSON-RPC to it. Tool
+        // calls run through the neutral pipeline, so tenancy/auth apply unchanged.
+        plugins.push(`mcpPlugin({ routes: ${routesExpression}, serverInfo: { name: '${options.name}', version: '0.1.0' } })`);
+        adapterRoutesExpr =
+            routesExpression === 'appRoutes'
+                ? '[...appRoutes, ...mcpRoutes()]'
+                : routesExpression.replace(/]$/, ', ...mcpRoutes()]');
+    }
+    plugins.push(`fastifyPlugin({ routes: ${adapterRoutesExpr} })`);
     const commandsField = options.cli
         ? `\n  /** Dev/CLI commands (make:*, ai:*, prisma:sync) — passed ONLY by bin/basalt.ts. */\n  commands?: CommandDefinition[]`
         : '';
@@ -201,6 +224,14 @@ export function routesTs(options) {
             ]
             : []),
     ];
+    // Opt these read-only routes in as MCP tools when MCP is enabled. Only safe,
+    // non-mutating endpoints are exposed — auth routes are deliberately left out.
+    const overviewMeta = options.mcp
+        ? `\n    meta: { mcp: { name: 'overview', description: 'List what this API exposes: name, status and available endpoints.' } },`
+        : '';
+    const healthMeta = options.mcp
+        ? `\n    meta: { mcp: { name: 'health', description: 'Liveness check — returns ok and the current request id.' } },`
+        : '';
     return `import { ctx } from '@basaltkit/core'
 import { route } from '@basaltkit/fastify'
 
@@ -208,7 +239,7 @@ export const appRoutes = [
   // Friendly index so \`GET /\` is never a bare 404 — lists what the API exposes.
   route({
     method: 'GET',
-    url: '/',
+    url: '/',${overviewMeta}
     async handler() {
       return {
         name: '${options.name}',
@@ -219,7 +250,7 @@ export const appRoutes = [
   }),
   route({
     method: 'GET',
-    url: '/health',
+    url: '/health',${healthMeta}
     async handler() {
       return { ok: true, requestId: ctx().requestId${options.tenancy ? ', tenant: ctx().tenant?.id ?? null' : ''} }
     },
@@ -313,6 +344,7 @@ export function readme(options) {
         ...(options.billing ? ['subscriptions with plans and feature limits'] : []),
         ...(options.ui ? ['web UI (React + shadcn/ui on @basaltkit/admin-shadcn + @basaltkit/sdk)'] : []),
         ...(options.cli ? ['`basalt` CLI with code generators (`make:*`) and built-in commands'] : []),
+        ...(options.mcp ? ['MCP server — read-only routes exposed as AI-agent tools at `/mcp`'] : []),
     ];
     return `# ${options.name}
 
@@ -352,9 +384,52 @@ pnpm --filter ${options.name}-web dev   # terminal 2 — UI on http://localhost:
 
 Open <http://localhost:5180>. The Vite dev server proxies \`/api\` to the API,
 so there is no CORS to configure${options.auth ? '. Register, then sign in' : ''}.
+`
+        : ''}${options.mcp
+        ? `
+## MCP server
+
+Read-only routes marked with \`meta.mcp\` in \`src/routes.ts\` (the overview and
+health endpoints) are exposed as [Model Context Protocol](https://modelcontextprotocol.io)
+tools over HTTP at \`POST /mcp\`. Point any MCP client at it:
+
+\`\`\`bash
+# list the tools
+curl -s localhost:3000/mcp -H 'content-type: application/json' \\
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+\`\`\`
+
+Tool calls run through the same neutral pipeline as HTTP, so validation, tenancy
+and auth apply unchanged. Add \`meta: { mcp: true }\` to any route to expose it —
+keep mutations and auth flows off unless an agent should really call them.
+
+### AI dev tools
+
+This project is also wired for AI-assisted development. \`.mcp.json\` registers the
+**dev-only** \`basalt-ai-mcp\` bridge (a \`devDependency\` — never shipped in your
+app's runtime) with MCP clients such as Claude Code and Claude Desktop. It exposes
+\`basalt_analyze\`, \`basalt_doctor\`, \`basalt_plan\`, \`basalt_review\` and
+\`basalt_make\` (preview by default, writes confined to this project) plus workflow
+prompts. Claude Code picks up \`.mcp.json\` automatically; for Claude Desktop add the
+same server to its config with \`--cwd=<absolute project path>\`.
 `
         : ''}`;
 }
+/**
+ * A Claude Code / generic MCP client config that registers the dev-only
+ * `basalt-ai-mcp` bridge for this project. Claude Code reads `.mcp.json` at the
+ * project root automatically; Claude Desktop uses the same server entry.
+ */
+export function mcpJson(_options) {
+    return `${JSON.stringify({
+        mcpServers: {
+            'basalt-ai': {
+                command: 'npx',
+                args: ['-y', '@basaltkit/ai-mcp', '--cwd=.'],
+            },
+        },
+    }, null, 2)}\n`;
+}
 export function gitignore() {
     return `node_modules/
 dist/

package/dist/wizard.d.ts

@@ -1,6 +1,6 @@
 import type { PackageManager } from './index.js';
 import { type Choice, type Prompter } from './prompt.js';
-export type FeatureKey = 'tenancy' | 'auth' | 'billing' | 'ui' | 'cli';
+export type FeatureKey = 'tenancy' | 'auth' | 'billing' | 'ui' | 'cli' | 'mcp';
 /** The feature toggles offered in the "custom" preset (and shown in the summary). */
 export declare const FEATURES: Choice<FeatureKey>[];
 interface Preset {
@@ -20,6 +20,7 @@ export interface WizardResult {
     billing: boolean;
     ui: boolean;
     cli: boolean;
+    mcp: boolean;
     pm: PackageManager;
     install: boolean;
     git: boolean;

package/dist/wizard.js

@@ -6,11 +6,12 @@ export const FEATURES = [
     { value: 'billing', label: 'Subscriptions / billing', hint: 'Stripe, Paddle, Lemon Squeezy' },
     { value: 'ui', label: 'Web UI', hint: 'React + shadcn + SDK (pnpm workspace)' },
     { value: 'cli', label: 'basalt CLI', hint: 'code generators + commands' },
+    { value: 'mcp', label: 'MCP server', hint: 'expose routes as AI-agent tools (/mcp)' },
 ];
 export const PRESETS = [
     { value: 'saas', label: 'SaaS starter', hint: 'tenancy + auth + billing + CLI', features: ['tenancy', 'auth', 'billing', 'cli'] },
-    { value: 'api', label: 'API only', hint: 'auth, no tenancy or UI', features: ['auth'] },
-    { value: 'full', label: 'Full stack', hint: 'everything + web UI', features: ['tenancy', 'auth', 'billing', 'ui', 'cli'] },
+    { value: 'api', label: 'API only', hint: 'auth + MCP, no tenancy or UI', features: ['auth', 'mcp'] },
+    { value: 'full', label: 'Full stack', hint: 'everything + web UI', features: ['tenancy', 'auth', 'billing', 'ui', 'cli', 'mcp'] },
     { value: 'minimal', label: 'Minimal', hint: 'no batteries, add them later', features: [] },
     { value: 'custom', label: 'Custom', hint: 'pick features yourself', features: null },
 ];
@@ -88,6 +89,7 @@ export async function runWizard(prompter, options = {}) {
         billing: featureSet.has('billing'),
         ui: featureSet.has('ui'),
         cli: featureSet.has('cli'),
+        mcp: featureSet.has('mcp'),
         pm,
         install,
         git,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-basalt",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Scaffold a production-shaped Basalt SaaS app: npm create basalt my-saas [--billing] [--ui] [--cli] [--install] [--git]",
   "license": "MIT",
   "type": "module",