@cmpose/mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cmpose contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @cmpose/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@cmpose/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Local MCP server that generates Compose Multiplatform projects (cmpose)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Keremturker/cmpose.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/Keremturker/cmpose/tree/main/packages/mcp#readme",
+  "bugs": {
+    "url": "https://github.com/Keremturker/cmpose/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "compose-multiplatform",
+    "kotlin-multiplatform",
+    "kmp",
+    "generator",
+    "scaffold"
+  ],
+  "bin": {
+    "cmpose-mcp": "src/server.js"
+  },
+  "main": "src/server.js",
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@cmpose/core": "0.1.1",
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "fs-extra": "^11.3.2",
+    "zod": "3.25.76"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/describe.js

@@ -0,0 +1,26 @@
+'use strict';
+const core = require('@cmpose/core');
+const pkg = require('../package.json');
+
+const DEFAULTS = Object.freeze({
+    templateType: 'showcase',
+    features: [],
+    minSdk: String(core.limits.minSdkMin),
+    iosVersion: core.limits.iosVersionMin,
+    ci: false
+});
+
+function describe() {
+    const contract = core.contractFacts();
+    return {
+        contractVersion: core.hashContract(contract),
+        coreVersion: core.version,
+        mcpVersion: pkg.version,
+        template: { ...core.pins.cmp },
+        // Outside `contract`: contractVersion hashes the contract only
+        defaults: { ...DEFAULTS, featuresConfig: { ...core.featuresConfig.DEFAULTS } },
+        contract
+    };
+}
+
+module.exports = { describe, DEFAULTS };

package/src/generate.js

@@ -0,0 +1,115 @@
+'use strict';
+const path = require('path');
+const crypto = require('crypto');
+const fs = require('fs-extra');
+const core = require('@cmpose/core');
+const { DEFAULTS } = require('./describe');
+
+const fail = (text) => ({ isError: true, content: [{ type: 'text', text }] });
+
+const NEXT_STEPS = [
+    'Open the project folder in Android Studio (it writes local.properties with your Android SDK path).',
+    'Run the Android app from Android Studio; for iOS open iosApp/iosApp.xcodeproj in Xcode.',
+    'Read README.md for the modules, requirements and release checklist.'
+];
+
+async function targetProblem(target) {
+    const stat = await fs.stat(target).catch(() => null);
+    if (!stat) return null;
+    if (!stat.isDirectory()) return `${target} already exists and is a file`;
+    if ((await fs.readdir(target)).length > 0) return `${target} already exists and is not empty`;
+    return null;
+}
+
+// Non-recursive: fails (ENOTEMPTY) if anything appeared at the target since it was checked.
+async function removeEmptyDir(dir) {
+    await fs.promises.rmdir(dir).catch((err) => { if (err.code !== 'ENOENT') throw err; });
+}
+
+// Validate → template cache → generate in a hidden sibling → rename into place.
+// Never overwrites anything and never leaves half a project behind.
+// A typo in a flag would otherwise just leave the feature out and still report success
+function unknownFeaturesConfigKeys(featuresConfig) {
+    if (!featuresConfig || typeof featuresConfig !== 'object' || Array.isArray(featuresConfig)) return [];
+    return Object.keys(featuresConfig).filter((k) => !core.SCHEMA.featuresConfigKeys.includes(k));
+}
+
+// Agents often send numbers; the core takes the hosted generator's strings
+function coerceVersions(options) {
+    const out = { ...options };
+    if (typeof out.minSdk === 'number') out.minSdk = String(out.minSdk);
+    if (typeof out.iosVersion === 'number') {
+        out.iosVersion = Number.isInteger(out.iosVersion) ? `${out.iosVersion}.0` : String(out.iosVersion);
+    }
+    return out;
+}
+
+async function runGenerate(args, { cacheDir, remoteUrl, onProgress = () => { }, generatorVersion = null } = {}) {
+    const { outputDir, templateRef, ...rest } = args || {};
+    const options = coerceVersions(rest);
+    if (typeof outputDir !== 'string' || !path.isAbsolute(outputDir)) {
+        return fail('outputDir must be an absolute path (for example /path/to/projects).');
+    }
+    const unknown = unknownFeaturesConfigKeys(options.featuresConfig);
+    if (unknown.length > 0) {
+        return fail(`Unknown featuresConfig key(s): ${unknown.join(', ')}. ` +
+            `Valid keys: ${core.SCHEMA.featuresConfigKeys.join(', ')}.`);
+    }
+    const checked = core.validate({ ...DEFAULTS, ...options });
+    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.cmp.repo, ref: templateRef || core.pins.cmp.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;
+    }
+    const versions = await core.readTemplateVersions(cache.dir);
+    const sdkError = core.minSdkAboveTarget(value.minSdk, versions.targetSdk);
+    if (sdkError) return fail(sdkError);
+
+    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 summary = await core.generateCmpProject(value, { projectDir: work, generatorVersion });
+        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 = [...summary.warnings];
+        if (value.templateType === 'showcase' && options.featuresConfig !== undefined) {
+            warnings.push('featuresConfig is ignored for showcase (it applies to blank only); the showcase template has its own fixed feature set');
+        }
+        const result = {
+            projectDir: target,
+            template: { repo: core.pins.cmp.repo, ref: cache.ref, commit: cache.commit },
+            templateType: summary.templateType,
+            features: summary.features,
+            featuresConfig: value.templateType === 'blank' ? value.featuresConfig : null,
+            warnings,
+            nextSteps: NEXT_STEPS
+        };
+        const text = [
+            `Generated ${value.projectName} at ${target}`,
+            `Template: ${result.template.repo}@${result.template.ref} (${String(cache.commit).slice(0, 7)})`,
+            ...warnings.map((w) => `Warning: ${w}`),
+            'Next steps:', ...NEXT_STEPS.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 = { runGenerate, removeEmptyDir, NEXT_STEPS };

package/src/server.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+'use strict';
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { z } = require('zod');
+const core = require('@cmpose/core');
+const pkg = require('../package.json');
+const { describe } = require('./describe');
+const { runGenerate } = require('./generate');
+
+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.';
+
+function createServer({ cacheDir, remoteUrl } = {}) {
+    const server = new McpServer({ name: 'cmpose', version: pkg.version });
+
+    server.registerTool('cmp_describe', {
+        description: 'Describe the cmpose generator: template types, featuresConfig flags and defaults, dependency rules, validation limits and the pinned template.',
+        inputSchema: {}
+    }, async () => {
+        const facts = describe();
+        return { content: [{ type: 'text', text: JSON.stringify(facts, null, 2) }], structuredContent: facts };
+    });
+
+    server.registerTool('cmp_generate', {
+        description: GENERATE_DESCRIPTION,
+        inputSchema: {
+            projectName: z.string().describe('Letters only, no spaces (e.g. MyApp)'),
+            appName: z.string().describe('Display name (e.g. My App)'),
+            packageName: z.string().describe('Reverse-domain package (e.g. com.example.myapp)'),
+            outputDir: z.string().describe('Absolute path of the folder to create the project in'),
+            templateType: z.enum(['showcase', 'blank']).optional(),
+            features: z.array(z.string()).optional().describe('Extra feature modules (lower case names)'),
+            featuresConfig: z.record(z.string(), z.any()).optional()
+                .describe('blank only: flags from cmp_describe (unknown keys are refused; ignored for showcase)'),
+            minSdk: z.union([z.string(), z.number()]).optional().describe('Android min SDK, e.g. "24" or 24'),
+            iosVersion: z.union([z.string(), z.number()]).optional().describe('iOS deployment target, e.g. "15.0"'),
+            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}` });
+    });
+
+    return server;
+}
+
+async function main() {
+    // stdout carries JSON-RPC: every log line goes to stderr
+    const toStderr = (...args) => console.error(...args);
+    core.setLogger({ info: toStderr, warn: toStderr, error: toStderr });
+    await createServer().connect(new StdioServerTransport());
+}
+
+if (require.main === module) {
+    main().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}
+
+module.exports = { createServer };