@cmpose/mcp 0.1.1 → 0.2.0

package/README.md

@@ -1,3 +1,105 @@
 # @cmpose/mcp
 
-A local stdio MCP server with two tools, `cmp_describe` and `cmp_generate`, that generates Compose Multiplatform projects on your own machine through `@cmpose/core`. Add it to Claude Code with `claude mcp add cmpose -- npx -y @cmpose/mcp`. See the README at the root of the cmpose repository for details.
+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 is the same generator that runs
+[cmpose.dev](https://cmpose.dev), 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."
+
+## Install
+
+Requires Node.js 20+ and git.
+
+**Claude Code**
+
+    claude mcp add cmpose -- npx -y @cmpose/mcp
+
+**Claude Desktop, Cursor, Windsurf and other MCP clients** (`mcpServers` config):
+
+```json
+{
+  "mcpServers": {
+    "cmpose": { "command": "npx", "args": ["-y", "@cmpose/mcp"] }
+  }
+}
+```
+
+**VS Code** (`.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "cmpose": { "type": "stdio", "command": "npx", "args": ["-y", "@cmpose/mcp"] }
+  }
+}
+```
+
+## What you get
+
+Every project has `androidApp`, `iosApp` (Xcode project), a `shared` module with Koin and
+Navigation, logging (Kermit), image loading (Coil), in-app review, update check, an About
+screen, a `build-logic` with convention plugins, and a README with a release checklist.
+
+- **Template:** `showcase` (home, onboarding and paywall demo screens) or `blank`
+  (a clean shell with a sample feature).
+- **Options for `blank`:** Ktor networking (with an optional in-app network inspector),
+  theming (light/dark/system), multi-language strings, DataStore, Room (KMP, bundled SQLite),
+  RevenueCat purchases with a custom Compose paywall, AdMob ads with UMP/ATT consent, detekt.
+- **Your own feature modules:** up to 3, each with contract/data/domain/presentation layers.
+- **CI:** an optional GitHub Actions workflow.
+- **Your names everywhere:** package, bundle id, app name, min SDK and iOS deployment target.
+
+## Games (Unity)
+
+> "Create a 2D Unity game called SkyHopper, package com.acme.skyhopper, in ~/Projects, blank,
+> with ads and leaderboards"
+
+Every game project is a Unity 6 project (editor 6000.3.25f1, URP) for Android and iOS, with
+VContainer + UniTask, a uGUI interface, a Boot → Menu → Game scene flow, a settings screen,
+saving, deep links, and in-app review and update check.
+
+- **Template:** `showcase` (a sample game with every flag on: a 2D runner, or a 3D track with
+  `render: "3d"`) or `blank` (an empty game with the flags you pick). `render` is `2d`
+  (default) or `3d`.
+- **Flags for `blank`:** `saveSystem`, `uiTheme`, `multiLang`, `network`, `networkInspector`
+  (needs `network`, added for you), `purchases` (RevenueCat), `ads` (AdMob) and
+  `leaderboards` (Google Play Games and Game Center).
+- **Your own feature modules (`blank`):** up to 3.
+- **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.
+- **CI:** an optional GitHub Actions workflow with GameCI.
+- **Your names everywhere:** package (application identifier), company name, app name, min SDK
+  (25+) and iOS deployment target (15.0+).
+
+## Tools
+
+- `cmp_describe`: the defaults, the options and the rules (name formats, limits, which option
+  needs which). Agents call it first.
+- `cmp_generate`: creates the project. Required: `projectName` (letters only), `appName`,
+  `packageName` (e.g. `com.acme.habits`) and an absolute `outputDir`. Optional:
+  `templateType`, `features`, `featuresConfig`, `minSdk`, `iosVersion`, `ci`, `templateRef`.
+  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.
+- `game_generate`: creates the game. Required: `projectName` (letters or digits, starting with
+  a letter), `appName`, `packageName` (e.g. `com.acme.skyhopper`) and an absolute `outputDir`.
+  Optional: `companyName`, `templateType`, `render`, `flags`, `features`, `minSdk`,
+  `iosVersion`, `ci`, `ids`, `templateRef`. It never overwrites a non-empty folder.
+
+## How it works
+
+Generation runs entirely on your machine. The first call downloads the pinned template
+([Keremturker/cmpose-template](https://github.com/Keremturker/cmpose-template)) into
+`~/.cache/cmpose` (override with `CMPOSE_CACHE_DIR`), and later calls reuse it. Games come the
+same way from the pinned game template
+([Keremturker/cmpose-game-template](https://github.com/Keremturker/cmpose-game-template)); Unity
+never runs during generation. Each release pins one tag of each template, so `@cmpose/mcp@x.y.z`
+always generates the same project.
+
+Source and issues: [github.com/Keremturker/cmpose](https://github.com/Keremturker/cmpose).
+MIT licensed. The projects you generate are yours.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@cmpose/mcp",
-  "version": "0.1.1",
-  "description": "Local MCP server that generates Compose Multiplatform projects (cmpose)",
+  "version": "0.2.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",
   "repository": {
     "type": "git",
@@ -19,7 +20,14 @@
     "kotlin-multiplatform",
     "kmp",
     "generator",
-    "scaffold"
+    "scaffold",
+    "android",
+    "ios",
+    "compose",
+    "unity",
+    "game",
+    "ai-agent",
+    "mcp-server"
   ],
   "bin": {
     "cmpose-mcp": "src/server.js"
@@ -35,7 +43,7 @@
     "test": "node --test test/*.test.js"
   },
   "dependencies": {
-    "@cmpose/core": "0.1.1",
+    "@cmpose/core": "0.2.0",
     "@modelcontextprotocol/sdk": "1.32.1",
     "fs-extra": "^11.3.2",
     "zod": "3.25.76"

package/src/gameGenerate.js

@@ -0,0 +1,77 @@
+'use strict';
+const path = require('path');
+const crypto = require('crypto');
+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_GAME = [
+    'Open the folder in Unity Hub with editor 6000.3.25f1 (Android and iOS Build Support modules).',
+    'Press Play in the Boot scene, or build with File > Build Profiles.',
+    'Read README.md for signing, IDs and the release checklist.'
+];
+
+// Validate → template cache → generate in a hidden sibling → rename into place.
+// Never overwrites anything and never leaves half a project behind.
+async function runGameGenerate(args, { cacheDir, remoteUrl, onProgress = () => { }, generatorVersion = null, now } = {}) {
+    const { outputDir, templateRef, ...rest } = args || {};
+    if (typeof outputDir !== 'string' || !path.isAbsolute(outputDir)) {
+        return fail('outputDir must be an absolute path (for example /path/to/projects).');
+    }
+    const checked = core.game.validateGame(rest);
+    if (!checked.ok) return fail(checked.error);
+    const value = checked.value;
+    const target = path.join(outputDir, value.projectName);
+    const problem = await targetProblem(target);
+    if (problem) return fail(problem);
+
+    const template = { repo: core.pins.game.repo, ref: templateRef || core.pins.game.ref, cacheDir };
+    let cache;
+    try {
+        const cached = await core.templateCache.isCached(template);
+        onProgress(cached ? 'Preparing the template' : 'Downloading the template (first run only)');
+        cache = await core.templateCache.ensure({ ...template, remoteUrl });
+    } catch (err) {
+        if (err instanceof core.TemplateFetchError || err instanceof TypeError) return fail(err.message);
+        throw err;
+    }
+
+    await fs.ensureDir(outputDir);
+    const work = path.join(outputDir, `.cmpose-${crypto.randomBytes(6).toString('hex')}`);
+    try {
+        onProgress('Generating the project');
+        await fs.copy(cache.dir, work);
+        const source = { repo: core.pins.game.repo, ref: cache.ref, commit: cache.commit };
+        const summary = await core.game.generateGame(value, {
+            projectDir: work, template: source, coreVersion: core.version, 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 result = {
+            projectDir: target,
+            template: source,
+            templateType: summary.templateType,
+            render: summary.render,
+            flags: summary.flags,
+            features: summary.features,
+            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.warnings.map((w) => `Warning: ${w}`),
+            'Next steps:', ...NEXT_STEPS_GAME.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 = { runGameGenerate, NEXT_STEPS_GAME };

package/src/generate.js

@@ -112,4 +112,4 @@ async function runGenerate(args, { cacheDir, remoteUrl, onProgress = () => { },
     }
 }
 
-module.exports = { runGenerate, removeEmptyDir, NEXT_STEPS };
+module.exports = { runGenerate, removeEmptyDir, targetProblem, NEXT_STEPS };

package/src/server.js

@@ -7,11 +7,31 @@ const core = require('@cmpose/core');
 const pkg = require('../package.json');
 const { describe } = require('./describe');
 const { runGenerate } = require('./generate');
+const { runGameGenerate } = require('./gameGenerate');
 
 const GENERATE_DESCRIPTION = 'Generate a Compose Multiplatform (Android + iOS) project on this machine. ' +
     'Call cmp_describe first for the options, defaults and validation rules. ' +
     'Writes <outputDir>/<projectName>; never overwrites an existing non-empty folder.';
 
+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. ' +
+    '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;
+    let step = 0;
+    return (message) => {
+        if (progressToken === undefined) return;
+        step += 1;
+        extra.sendNotification({
+            method: 'notifications/progress',
+            params: { progressToken, progress: step, total, message }
+        }).catch(() => { });
+    };
+}
+
 function createServer({ cacheDir, remoteUrl } = {}) {
     const server = new McpServer({ name: 'cmpose', version: pkg.version });
 
@@ -39,20 +59,44 @@ function createServer({ cacheDir, remoteUrl } = {}) {
             ci: z.boolean().optional(),
             templateRef: z.string().optional().describe('Override the pinned template tag')
         }
-    }, async (args, extra) => {
-        const progressToken = extra && extra._meta && extra._meta.progressToken;
-        let step = 0;
-        const onProgress = (message) => {
-            if (progressToken === undefined) return;
-            step += 1;
-            extra.sendNotification({
-                method: 'notifications/progress',
-                params: { progressToken, progress: step, total: 2, message }
-            }).catch(() => { });
-        };
-        return runGenerate(args, { cacheDir, remoteUrl, onProgress, generatorVersion: `mcp@${pkg.version}` });
+    }, async (args, extra) => runGenerate(args, {
+        cacheDir, remoteUrl, onProgress: progressReporter(extra, 2), generatorVersion: `mcp@${pkg.version}`
+    }));
+
+    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.',
+        inputSchema: {}
+    }, async () => {
+        const facts = core.game.describeGame();
+        return { content: [{ type: 'text', text: JSON.stringify(facts, null, 2) }], structuredContent: facts };
     });
 
+    server.registerTool('game_generate', {
+        description: GAME_GENERATE_DESCRIPTION,
+        inputSchema: {
+            projectName: z.string().describe('Letters or digits, starting with a letter, no spaces (e.g. SkyHopper)'),
+            appName: z.string().describe('Display name (e.g. Sky Hopper)'),
+            packageName: z.string().describe('Reverse-domain application identifier (e.g. com.example.skyhopper)'),
+            outputDir: z.string().describe('Absolute path of the folder to create the project in'),
+            companyName: z.string().optional().describe('Company name (defaults to the second packageName segment, capitalized)'),
+            templateType: z.enum(['showcase', 'blank']).optional()
+                .describe('showcase (default): the sample games with every flag on; blank: an empty game with the flags and features you pick'),
+            render: z.enum(['2d', '3d']).optional().describe('Render setup (default 2d)'),
+            flags: z.array(z.string()).optional()
+                .describe('blank only: flags from game_describe (required flags are added); showcase has every flag on'),
+            features: z.array(z.string()).optional().describe('blank only: extra feature modules (lower case names)'),
+            minSdk: z.union([z.string(), z.number()]).optional().describe('Android min SDK, e.g. "25" or 25'),
+            iosVersion: z.union([z.string(), z.number()]).optional().describe('iOS deployment target, e.g. "15.0"'),
+            ci: z.boolean().optional(),
+            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'),
+            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}`
+    }));
+
     return server;
 }