@cmpose/mcp 0.3.0 → 0.5.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):
 
@@ -75,9 +76,24 @@ saving, deep links, and in-app review and update check.
 - **IDs:** `ids` takes your real AdMob (`admob`), RevenueCat (`revenueCat`) and Play Games +
   Game Center (`gameServices`) IDs, each group with its flag; `game_describe` lists the fields.
   A group you leave out keeps the test IDs / placeholders and is reported as a warning.
+- **Look (`theme`):** one of the template's style families (`bright`, `neon`, `pastel`, `bold`,
+  `nature`, `clean`; palette, shapes, motion and a font pair), listed by `game_describe` under
+  `themes` with what each suits. `theme: { family, primary, accent, fontPair }`, every field
+  optional: `primary` and `accent` (`#RRGGBB`) recolour the family with their lightness shifted
+  until text and buttons keep their contrast; a colour that still cannot pass keeps the
+  family's and is reported as a warning. Without `theme` the project gets `clean`, exactly as
+  the template ships it.
 - **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
@@ -89,14 +105,27 @@ saving, deep links, and in-app review and update check.
   It returns the project path, the template version it used, warnings (e.g. test ad IDs to
   replace) and next steps.
 - `game_describe`: the Unity game generator's engine and editor version, template types,
-  renders, flags and their dependencies, ID groups, defaults and limits. Agents call it first.
+  renders, flags and their dependencies, ID groups, defaults, limits and the pinned template's
+  theme families (`themes`: `default` and each family's `id`, `title`, `suits` and `fontPairs`;
+  the first call downloads the template). Agents call it first.
 - `game_generate`: creates the game. Required: `projectName` (1 to 30 letters or digits,
   starting with a letter), `appName` (up to 30 characters), `packageName` (e.g.
   `com.acme.skyhopper`, at least 3 segments, up to 50 characters) and an absolute `outputDir`.
   Optional: `companyName` (like `projectName`; by default the package's second segment,
   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.
+  written as `major.minor`), `ids`, `theme`, `templateRef`. It never overwrites a non-empty
+  folder. The result names the applied theme (`theme`) and lists colour fallbacks among the
+  warnings.
+- `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 +134,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.5.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.5.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/gameGenerate.js

@@ -59,12 +59,14 @@ async function runGameGenerate(args, { cacheDir, remoteUrl, onProgress = () => {
             render: summary.render,
             flags: summary.flags,
             features: summary.features,
+            theme: summary.theme,
             warnings: summary.warnings,
             nextSteps: NEXT_STEPS_GAME
         };
         const text = [
             `Generated ${value.projectName} at ${target}`,
             `Template: ${source.repo}@${source.ref} (${String(source.commit).slice(0, 7)})`,
+            ...(result.theme ? [`Theme: ${result.theme.family} (${result.theme.fontPair})`] : []),
             ...result.warnings.map((w) => `Warning: ${w}`),
             'Next steps:', ...NEXT_STEPS_GAME.map((s) => `- ${s}`)
         ].join('\n');
@@ -75,4 +77,21 @@ async function runGameGenerate(args, { cacheDir, remoteUrl, onProgress = () => {
     }
 }
 
-module.exports = { runGameGenerate, NEXT_STEPS_GAME };
+// game_describe with the pinned template's theme families (fetched into the cache on first use).
+// A template that cannot be fetched or read still describes the generator: no families, and why.
+async function runGameDescribe({ cacheDir, remoteUrl } = {}) {
+    let themes = null;
+    let unavailable = null;
+    try {
+        const cache = await core.templateCache.ensure({ ...core.pins.game, cacheDir, remoteUrl });
+        themes = await core.game.readThemes(cache.dir);
+    } catch (err) {
+        if (!(err instanceof core.TemplateFetchError || err instanceof TypeError || err instanceof core.game.ThemesFileError)) throw err;
+        unavailable = `Theme families unavailable: ${err.message}`;
+    }
+    const facts = core.game.describeGame({ themes });
+    if (unavailable) facts.themes.unavailable = unavailable;
+    return { content: [{ type: 'text', text: JSON.stringify(facts, null, 2) }], structuredContent: facts };
+}
+
+module.exports = { runGameGenerate, runGameDescribe, NEXT_STEPS_GAME };

package/src/server.js

@@ -7,7 +7,8 @@ const core = require('@cmpose/core');
 const pkg = require('../package.json');
 const { describe } = require('./describe');
 const { runGenerate } = require('./generate');
-const { runGameGenerate } = require('./gameGenerate');
+const { runGameGenerate, runGameDescribe } = 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. ' +
@@ -16,6 +17,15 @@ const GENERATE_DESCRIPTION = 'Generate a Compose Multiplatform (Android + iOS) p
 const GAME_GENERATE_DESCRIPTION = 'Generate a Unity 6 (Android + iOS) mobile game project on this machine. ' +
     'Call game_describe first for the flags, defaults and validation rules. ' +
     'showcase has every flag on; flags and features apply to blank only. ' +
+    'theme picks one of the style families game_describe lists under themes (palette, shapes, motion, fonts; ' +
+    'match the family whose suits fits the game) and optionally a fontPair of that family. primary and accent ' +
+    '(#RRGGBB) recolour the family: their lightness is shifted until text and buttons keep their contrast, and a ' +
+    'colour that still cannot pass falls back to the family default with a warning. Without theme the template ' +
+    'default family (clean) is used. ' +
+    '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
@@ -32,7 +42,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', {
@@ -64,12 +75,9 @@ function createServer({ cacheDir, remoteUrl } = {}) {
     }));
 
     server.registerTool('game_describe', {
-        description: 'Describe the Unity game generator: engine and editor version, template types, renders, flags and their dependencies, ID groups, defaults, validation limits and the pinned game template.',
+        description: 'Describe the Unity game generator: engine and editor version, template types, renders, flags and their dependencies, ID groups, defaults, validation limits, the pinned game template and its theme families (themes: default, and each family\'s id, title, suits and fontPairs).',
         inputSchema: {}
-    }, async () => {
-        const facts = core.game.describeGame();
-        return { content: [{ type: 'text', text: JSON.stringify(facts, null, 2) }], structuredContent: facts };
-    });
+    }, async () => runGameDescribe({ cacheDir, remoteUrl }));
 
     server.registerTool('game_generate', {
         description: GAME_GENERATE_DESCRIPTION,
@@ -90,12 +98,43 @@ function createServer({ cacheDir, remoteUrl } = {}) {
             ids: z.record(z.string(), z.record(z.string(), z.string())).optional()
                 .describe('Real IDs by group (admob, revenueCat, gameServices; fields in game_describe), each needing its flag. ' +
                     'A group left out keeps the test IDs / placeholders, reported as a warning'),
+            // passthrough: unknown fields reach validateGame, which refuses them by name
+            theme: z.object({
+                family: z.string().optional().describe('A family id from game_describe themes.families (default: themes.default)'),
+                primary: z.string().optional().describe('#RRGGBB primary colour; lightness is adjusted to keep contrast'),
+                accent: z.string().optional().describe('#RRGGBB accent colour; lightness is adjusted to keep contrast'),
+                fontPair: z.string().optional().describe("One of the family's fontPairs (default: its first)")
+            }).passthrough().optional()
+                .describe('Style family and optional colour shifts; without it the template default family is used'),
             templateRef: z.string().optional().describe('Override the pinned game template tag')
         }
     }, async (args, extra) => runGameGenerate(args, {
         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;
 }