@cmpose/mcp 0.3.0 → 0.4.0

package/README.md

@@ -2,9 +2,10 @@
 
 Ask your AI agent for a **Compose Multiplatform** app and get a real, buildable Android + iOS
 project on disk, generated locally from a tested template. It also generates **Unity** mobile
-games (Android + iOS). This is a local stdio MCP server with four tools: `cmp_describe`,
-`cmp_generate`, `game_describe` and `game_generate`. It runs on your machine, with no account,
-no API key and no upload.
+games (Android + iOS) and standalone **Kotlin/Ktor backends**. This is a local stdio MCP
+server with six tools: `cmp_describe`, `cmp_generate`, `game_describe`, `game_generate`,
+`backend_describe` and `backend_generate`. It runs on your machine, with no account, no API key
+and no upload.
 
 > "Create a blank Compose Multiplatform app called Habits, package com.acme.habits, in
 > ~/Projects, with Room, light/dark theming and AdMob ads."
@@ -17,7 +18,7 @@ Requires Node.js 20+ and git.
 
 **Claude Code**
 
-    claude mcp add cmpose -- npx -y @cmpose/mcp
+    claude mcp add -s user cmpose -- npx -y @cmpose/mcp
 
 **Claude Desktop, Cursor, Windsurf and other MCP clients** (`mcpServers` config):
 
@@ -78,6 +79,14 @@ saving, deep links, and in-app review and update check.
 - **Your names everywhere:** package (application identifier), company name, app name, min SDK
   (25 to 36) and iOS deployment target (15.0 to 26.2).
 
+> "Create a backend called NotesBackend, service name notes-api, package com.acme.notes, in
+> ~/Projects, with sharing"
+
+Every backend is a Kotlin (JVM 21) Ktor server with PostgreSQL (Exposed, Flyway), Firebase ID
+tokens verified on the server (no Admin SDK), file uploads, account deletion, one sample feature
+to copy, a security checklist, a local runner (`./gradlew runLocal`) and the parts to deploy it
+as one Docker container behind nginx. `sharing` adds spaces, roles and invitations.
+
 ## Tools
 
 - `cmp_describe`: the defaults, the options and the rules (name formats, limits, which option
@@ -97,6 +106,15 @@ saving, deep links, and in-app review and update check.
   capitalized), `templateType`, `render`, `flags`, `features` (module names: 1 to 20 lowercase
   letters or digits, starting with a letter), `minSdk` (25 to 36), `iosVersion` (15.0 to 26.2,
   written as `major.minor`), `ids`, `templateRef`. It never overwrites a non-empty folder.
+- `backend_describe`: the backend generator's options, `appName` rules, the project anatomy and
+  the conventions to follow when adding code (protected routes, the 404 rule, where features
+  go, the security checklist, the local runner and the deploy parts). Agents call it first.
+- `backend_generate`: creates the backend. Required: `projectName` (letters only, up to 30),
+  `appName` (the service name: 2 to 31 lowercase letters, digits or `-`, starting with a letter;
+  not `api`, `health`, `admin` or `static`), `packageName` (e.g. `com.acme.notes`) and an
+  absolute `outputDir`. Optional: `sharing` (default `false`), `templateRef`. It never
+  overwrites a non-empty folder. `CMPOSE_BACKEND_TEMPLATE_DIR` (the absolute path of a backend
+  template checkout) generates from that checkout instead of the pinned tag.
 
 ## How it works
 
@@ -105,7 +123,8 @@ Generation runs entirely on your machine. The first call downloads the pinned te
 `~/.cache/cmpose` (override with `CMPOSE_CACHE_DIR`), and later calls reuse it. Games come the
 same way from the pinned game template
 ([whinstudio/cmpose-game-template](https://github.com/whinstudio/cmpose-game-template)); Unity
-never runs during generation. Each release pins one tag of each template, so `@cmpose/mcp@x.y.z`
+never runs during generation. Backends come from the pinned backend template
+(`whinstudio/cmpose-backend-template`). Each release pins one tag of each template, so `@cmpose/mcp@x.y.z`
 always generates the same project.
 
 Source and issues: [github.com/whinstudio/cmpose](https://github.com/whinstudio/cmpose).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmpose/mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "mcpName": "io.github.Keremturker/cmpose",
   "description": "MCP server that generates buildable Compose Multiplatform (Android + iOS) projects and Unity game projects locally from any AI agent",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "test": "node --test test/*.test.js"
   },
   "dependencies": {
-    "@cmpose/core": "0.3.0",
+    "@cmpose/core": "0.4.0",
     "@modelcontextprotocol/sdk": "1.32.1",
     "fs-extra": "^11.3.2",
     "zod": "3.25.76"

package/src/backendGenerate.js

@@ -0,0 +1,137 @@
+'use strict';
+const path = require('path');
+const crypto = require('crypto');
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+const fs = require('fs-extra');
+const core = require('@cmpose/core');
+const { removeEmptyDir, targetProblem } = require('./generate');
+
+const fail = (text) => ({ isError: true, content: [{ type: 'text', text }] });
+
+const NEXT_STEPS_BACKEND = [
+    'Create .local-server/config.properties with firebaseProjectId=<your Firebase project id>, then run ./gradlew runLocal (port 18001).',
+    'Add features under feature/<name>/ by copying feature/sample, and go through SECURITY-CHECKLIST.md.',
+    'Read deploy/README.md for the server contract, the first deployment and updates.'
+];
+
+// A local checkout's working files that a released template never holds
+const LOCAL_SKIP = new Set(['.git', '.claude', '.idea', '.gradle', '.kotlin', '.local-server', 'build', '.DS_Store']);
+const isPending = (ref) => /-PENDING$/.test(ref);
+// Secret files a checkout outside git may hold, skipped at every level (deploy/.env.example is the template's own)
+const isSecretName = (name) => name !== '.env.example' && (name === '.env' || name.endsWith('.env') || name.startsWith('.env.')
+    || /\.(p8|pem|key)$/.test(name) || /^service-account.*\.json$/.test(name)
+    || name === 'google-services.json' || name === 'GoogleService-Info.plist');
+const LOCAL_DIRTY_WARNING = 'The local template checkout has uncommitted changes; the project holds them.';
+
+const git = (dir, args) => promisify(execFile)('git', ['-C', dir, ...args], { maxBuffer: 64 * 1024 * 1024, encoding: 'utf8' });
+
+// A git checkout's tracked files (relative paths), or null when dir is not in a git work tree
+async function trackedFiles(dir) {
+    try {
+        await git(dir, ['rev-parse', '--is-inside-work-tree']);
+    } catch (err) {
+        if (err.code === 'ENOENT' && (await fs.pathExists(path.join(dir, '.git')))) {
+            throw new TypeError('git is needed to copy the local template checkout (CMPOSE_BACKEND_TEMPLATE_DIR).');
+        }
+        return null;
+    }
+    const { stdout } = await git(dir, ['ls-files', '-z']);
+    return stdout.split('\0').filter(Boolean);
+}
+
+// Copies a local checkout into work: only git's tracked files, or (outside git) all but the working and secret files.
+// Returns the warnings the result carries.
+async function copyLocalTemplate(dir, work) {
+    const tracked = await trackedFiles(dir);
+    if (!tracked) {
+        const filter = (src) => !isSecretName(path.basename(src)) && (path.dirname(src) !== dir || !LOCAL_SKIP.has(path.basename(src)));
+        await fs.copy(dir, work, { filter });
+        return [];
+    }
+    let copied = 0;
+    for (const rel of tracked) {
+        if (LOCAL_SKIP.has(rel.split('/')[0])) continue;
+        const src = path.join(dir, rel);
+        const stat = await fs.lstat(src).catch(() => null);
+        // a tracked file deleted in the work tree, or a submodule, is not copied
+        if (!stat || stat.isDirectory()) continue;
+        await fs.copy(src, path.join(work, rel)); // keeps the mode, so the executable bits too
+        copied += 1;
+    }
+    if (!copied) throw new TypeError('The local template checkout (CMPOSE_BACKEND_TEMPLATE_DIR) has no tracked files.');
+    const { stdout } = await git(dir, ['status', '--porcelain', '--untracked-files=no']);
+    return stdout.trim() ? [LOCAL_DIRTY_WARNING] : [];
+}
+
+// The template source: a local checkout (templateDir / CMPOSE_BACKEND_TEMPLATE_DIR) or the template cache
+async function resolveTemplate({ templateRef, templateDir, cacheDir, remoteUrl, cacheEnsure, onProgress }) {
+    if (templateDir) {
+        const stat = path.isAbsolute(templateDir) ? await fs.stat(templateDir).catch(() => null) : null;
+        if (!stat || !stat.isDirectory()) throw new TypeError('CMPOSE_BACKEND_TEMPLATE_DIR must be the absolute path of a backend template checkout.');
+        onProgress('Preparing the local template');
+        return { dir: templateDir, ref: templateRef || 'local', commit: null, local: true };
+    }
+    const template = { repo: core.pins.backend.repo, ref: templateRef || core.pins.backend.ref, cacheDir };
+    if (isPending(template.ref)) {
+        throw new TypeError('The backend template is not released yet; pass templateRef or set CMPOSE_BACKEND_TEMPLATE_DIR.');
+    }
+    const cached = await core.templateCache.isCached(template);
+    onProgress(cached ? 'Preparing the template' : 'Downloading the template (first run only)');
+    return cacheEnsure({ ...template, remoteUrl });
+}
+
+// Validate → template cache → generate in a hidden sibling → rename into place (the runGameGenerate flow).
+// Never overwrites anything and never leaves half a project behind.
+async function runBackendGenerate(args, {
+    cacheDir, remoteUrl, templateDir = null, cacheEnsure = core.templateCache.ensure,
+    onProgress = () => { }, generatorVersion = null, now
+} = {}) {
+    const checked = core.backend.validateBackend(args);
+    if (!checked.ok) return fail(['Invalid input:', ...checked.errors.map((e) => `- ${e.field}: ${e.message}`)].join('\n'));
+    const value = checked.value;
+    const target = path.join(value.outputDir, value.projectName);
+    const problem = await targetProblem(target);
+    if (problem) return fail(problem);
+
+    let cache;
+    try {
+        cache = await resolveTemplate({ templateRef: value.templateRef, templateDir, cacheDir, remoteUrl, cacheEnsure, onProgress });
+    } catch (err) {
+        if (err instanceof core.TemplateFetchError || err instanceof TypeError) return fail(err.message);
+        throw err;
+    }
+
+    await fs.ensureDir(value.outputDir);
+    const work = path.join(value.outputDir, `.cmpose-${crypto.randomBytes(6).toString('hex')}`);
+    try {
+        onProgress('Generating the project');
+        let localWarnings = [];
+        if (cache.local) localWarnings = await copyLocalTemplate(cache.dir, work);
+        else await fs.copy(cache.dir, work);
+        // Called through core.backend at call time (never destructured): the tests replace it to fail mid-generation
+        const { record } = await core.backend.generateBackend(value, {
+            projectDir: work, templateRef: cache.ref, templateCommit: cache.commit, generatorVersion, ...(now ? { now } : {})
+        });
+        const late = await targetProblem(target);
+        if (late) throw new Error(late);
+        await removeEmptyDir(target); // never recursive: a concurrent run's project stays intact
+        await fs.rename(work, target);
+        const warnings = cache.local
+            ? ['Generated from a local template checkout (CMPOSE_BACKEND_TEMPLATE_DIR), not a released tag.', ...localWarnings] : [];
+        const result = { projectDir: target, sharing: value.sharing, template: record.template, record, warnings, nextSteps: NEXT_STEPS_BACKEND };
+        const text = [
+            `Generated ${value.projectName} at ${target}`,
+            `Template: ${record.template.repo}@${record.template.ref}${record.template.commit ? ` (${String(record.template.commit).slice(0, 7)})` : ''}`,
+            `Sharing: ${value.sharing ? 'on' : 'off'}`,
+            ...warnings.map((w) => `Warning: ${w}`),
+            'Next steps:', ...NEXT_STEPS_BACKEND.map((s) => `- ${s}`)
+        ].join('\n');
+        return { content: [{ type: 'text', text }], structuredContent: result };
+    } catch (err) {
+        await fs.remove(work).catch(() => { });
+        return fail(`Generation failed: ${err.message}`);
+    }
+}
+
+module.exports = { runBackendGenerate, NEXT_STEPS_BACKEND };

package/src/server.js

@@ -8,6 +8,7 @@ const pkg = require('../package.json');
 const { describe } = require('./describe');
 const { runGenerate } = require('./generate');
 const { runGameGenerate } = require('./gameGenerate');
+const { runBackendGenerate } = require('./backendGenerate');
 
 const GENERATE_DESCRIPTION = 'Generate a Compose Multiplatform (Android + iOS) project on this machine. ' +
     'Call cmp_describe first for the options, defaults and validation rules. ' +
@@ -18,6 +19,10 @@ const GAME_GENERATE_DESCRIPTION = 'Generate a Unity 6 (Android + iOS) mobile gam
     'showcase has every flag on; flags and features apply to blank only. ' +
     'Writes <outputDir>/<projectName>; never overwrites an existing non-empty folder.';
 
+const BACKEND_GENERATE_DESCRIPTION = 'Generate a standalone Kotlin/Ktor backend (Docker-ready) on this machine. ' +
+    'Call backend_describe first. ' +
+    'Writes <outputDir>/<projectName>; never overwrites an existing non-empty folder.';
+
 // MCP progress notifications for a tool call that sent a progress token
 function progressReporter(extra, total) {
     const progressToken = extra && extra._meta && extra._meta.progressToken;
@@ -32,7 +37,8 @@ function progressReporter(extra, total) {
     };
 }
 
-function createServer({ cacheDir, remoteUrl } = {}) {
+// backendTemplateDir: a local backend template checkout used instead of the template cache (CMPOSE_BACKEND_TEMPLATE_DIR)
+function createServer({ cacheDir, remoteUrl, backendTemplateDir = process.env.CMPOSE_BACKEND_TEMPLATE_DIR || null } = {}) {
     const server = new McpServer({ name: 'cmpose', version: pkg.version });
 
     server.registerTool('cmp_describe', {
@@ -96,6 +102,29 @@ function createServer({ cacheDir, remoteUrl } = {}) {
         cacheDir, remoteUrl, onProgress: progressReporter(extra, 2), generatorVersion: `mcp@${pkg.version}`
     }));
 
+    server.registerTool('backend_describe', {
+        description: 'Describe the Kotlin/Ktor backend generator: options, appName rules, the project anatomy, the pinned backend template ' +
+            'and the conventions to follow when writing code in a generated backend.',
+        inputSchema: {}
+    }, async () => {
+        const facts = core.backend.describeBackend();
+        return { content: [{ type: 'text', text: JSON.stringify(facts, null, 2) }], structuredContent: facts };
+    });
+
+    server.registerTool('backend_generate', {
+        description: BACKEND_GENERATE_DESCRIPTION,
+        inputSchema: {
+            projectName: z.string().describe('Letters only, no spaces (e.g. NotesBackend)'),
+            appName: z.string().describe('Service name: 2-31 lowercase letters, digits or -, starting with a letter (e.g. notes-api)'),
+            packageName: z.string().describe('Reverse-domain Kotlin package (e.g. com.example.notes)'),
+            outputDir: z.string().describe('Absolute path of the folder to create the project in'),
+            sharing: z.boolean().optional().describe('Spaces shared between users with roles and invitations (default false)'),
+            templateRef: z.string().optional().describe('Override the pinned backend template tag')
+        }
+    }, async (args, extra) => runBackendGenerate(args, {
+        cacheDir, remoteUrl, templateDir: backendTemplateDir, onProgress: progressReporter(extra, 2), generatorVersion: `mcp@${pkg.version}`
+    }));
+
     return server;
 }