insta 0.0.20 → 0.0.21

package/dist/commands/mcp.js

@@ -0,0 +1,136 @@
+// `insta mcp install` — write the insta-cloud remote MCP server into each coding agent's own
+// config format. Claude Code is NOT handled here — it has a real registry CLI (`claude mcp add`,
+// see setup.ts registerMcp); these are the config-file agents. All entries are OAuth (no
+// credential written): each client discovers the platform AS via RFC 9728 and runs the browser
+// flow on first use.
+import { promises as fs } from 'node:fs';
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { info } from '../util.js';
+import { DEFAULT_MCP_URL, MCP_SERVER_NAME, registerMcp } from './setup.js';
+export const MCP_AGENT_TARGETS = ['cursor', 'codex', 'opencode', 'copilot', 'factory-droid'];
+export function configPath(slug, home) {
+    switch (slug) {
+        case 'cursor': return path.join(home, '.cursor', 'mcp.json');
+        case 'codex': return path.join(home, '.codex', 'config.toml');
+        case 'opencode': return path.join(home, '.config', 'opencode', 'opencode.json');
+        case 'copilot': return path.join(home, '.copilot', 'mcp-config.json');
+        case 'factory-droid': return path.join(home, '.factory', 'mcp.json');
+    }
+}
+// An agent counts as "on this machine" when its config dir already exists — we configure what's
+// installed, never scaffold a tool the user doesn't have.
+export function detectAgents(home) {
+    return MCP_AGENT_TARGETS.filter((slug) => existsSync(path.dirname(configPath(slug, home))));
+}
+// Merge our entry into existing JSON config. Returns null (skip, leave file alone) when the
+// existing content isn't valid JSON — never clobber a config we can't parse.
+export function renderJsonConfig(slug, existing, url) {
+    let root = {};
+    if (existing && existing.trim()) {
+        try {
+            root = JSON.parse(existing);
+        }
+        catch {
+            return null;
+        }
+        if (typeof root !== 'object' || root === null || Array.isArray(root))
+            return null;
+    }
+    if (slug === 'opencode') {
+        // OpenCode: `mcp` key, `type: "remote"` schema (docs.opencode.ai).
+        root.mcp = { ...(root.mcp ?? {}), [MCP_SERVER_NAME]: { type: 'remote', url, enabled: true } };
+        root.$schema ??= 'https://opencode.ai/config.json';
+    }
+    else {
+        const entry = slug === 'cursor' ? { url } // Cursor auto-detects HTTP from `url`
+            : slug === 'copilot' ? { type: 'http', url, tools: ['*'] }
+                : { type: 'http', url, disabled: false }; // factory-droid
+        root.mcpServers = { ...(root.mcpServers ?? {}), [MCP_SERVER_NAME]: entry };
+    }
+    return JSON.stringify(root, null, 2) + '\n';
+}
+// Codex config is TOML. Appending a complete `[mcp_servers.<name>]` table is always valid at
+// EOF, so we avoid a TOML parser: string-detect for idempotency, append for install.
+export function renderCodexConfig(existing, url) {
+    const base = existing ?? '';
+    if (base.includes(`[mcp_servers.${MCP_SERVER_NAME}]`))
+        return null; // already configured
+    const sep = base.length && !base.endsWith('\n') ? '\n' : '';
+    return `${base}${sep}\n[mcp_servers.${MCP_SERVER_NAME}]\nurl = "${url}"\n`;
+}
+// Install for one agent. Returns 'installed' | 'already' | 'skipped' (unparseable config).
+export async function installFor(slug, home, url) {
+    const file = configPath(slug, home);
+    let existing = null;
+    try {
+        existing = await fs.readFile(file, 'utf8');
+    }
+    catch {
+        existing = null;
+    }
+    if (slug === 'codex') {
+        const next = renderCodexConfig(existing, url);
+        if (next === null)
+            return 'already';
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        await fs.writeFile(file, next);
+        return 'installed';
+    }
+    if (existing) {
+        try {
+            const root = JSON.parse(existing);
+            const entry = slug === 'opencode' ? root?.mcp?.[MCP_SERVER_NAME] : root?.mcpServers?.[MCP_SERVER_NAME];
+            if (entry)
+                return 'already';
+        }
+        catch { /* fall through to renderJsonConfig, which refuses to clobber */ }
+    }
+    const next = renderJsonConfig(slug, existing, url);
+    if (next === null)
+        return 'skipped';
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, next);
+    return 'installed';
+}
+const AGENT_LABELS = {
+    cursor: 'Cursor', codex: 'OpenAI Codex', opencode: 'OpenCode', copilot: 'GitHub Copilot', 'factory-droid': 'Factory Droid',
+};
+// Configure every detected config-file agent (or one forced via `agent`). Returns the labels of
+// agents now configured (installed or already present) for the caller's summary line.
+export async function installAgentConfigs(agent, home = os.homedir()) {
+    const url = process.env.INSTA_MCP_URL || DEFAULT_MCP_URL;
+    const targets = agent
+        ? MCP_AGENT_TARGETS.includes(agent) ? [agent] : []
+        : detectAgents(home);
+    if (agent && targets.length === 0) {
+        info(`unknown --agent "${agent}" — supported: claude-code, ${MCP_AGENT_TARGETS.join(', ')}`);
+        return [];
+    }
+    const done = [];
+    for (const slug of targets) {
+        const result = await installFor(slug, home, url);
+        if (result === 'skipped')
+            info(`  ${AGENT_LABELS[slug]}: existing config at ${configPath(slug, home)} isn't valid JSON — add ${MCP_SERVER_NAME} manually`);
+        else
+            done.push(AGENT_LABELS[slug]);
+    }
+    return done;
+}
+// `insta mcp install [--agent <slug>] [--mcp-token]` — claude-code goes through its registry CLI
+// (registerMcp); everything else is a config-file write. No --agent = claude-code + all detected.
+export async function mcpInstall(opts) {
+    if (!opts.agent || opts.agent === 'claude-code') {
+        await registerMcp(undefined, undefined, !!opts.mcpToken);
+        if (opts.agent)
+            return;
+    }
+    const done = await installAgentConfigs(opts.agent);
+    if (done.length)
+        info(`✓ MCP — configured for ${done.join(', ')} (restart those tools to pick it up)`);
+    else if (opts.agent) { /* messages already printed */ }
+    else
+        info('  no other MCP-capable agents detected (supported: cursor, codex, opencode, copilot, factory-droid)');
+}
+//# sourceMappingURL=mcp.js.map

package/dist/commands/setup.js

@@ -6,7 +6,10 @@
 // Stack skills (neon/tigris/better-auth) intentionally stay per-project: their presence in a
 // project doubles as its stack manifest — that install happens on `project create|link`.
 import { spawn } from 'node:child_process';
+import os from 'node:os';
+import { ApiClient } from '../api.js';
 import { info } from '../util.js';
+import { installAgentConfigs } from './mcp.js';
 // The `skills` tool we shell out to prints a clack UI: a frame-by-frame clone spinner, an
 // "Installing to all N agents" banner, a full N-line install-path box, and a third-party
 // "Security Risk Assessment" that flags our OWN first-party skill as "Critical Risk". Streamed
@@ -89,7 +92,56 @@ const defaultRunner = (cmd, args) => new Promise((resolve) => {
 // -g = user-level (machine-global); -a '*' = every agent dir the skills tool supports
 // (Claude Code, Codex, Cursor, OpenCode, Copilot, …); --copy = real files, not cache symlinks.
 export const SETUP_ARGS = ['skills', 'add', 'InsForge/insta-skills', '-s', 'insta', '-a', '*', '-g', '-y', '--copy'];
-export async function setupAgent(opts, run = defaultRunner) {
+// ---- remote MCP registration ----
+export const MCP_SERVER_NAME = 'insta-cloud';
+export const DEFAULT_MCP_URL = 'https://mcp.instacloud.com/mcp';
+const defaultMinter = async () => {
+    try {
+        const api = await ApiClient.load();
+        if (!api.config.accessToken)
+            return null;
+        const { token } = await api.request('POST', '/tokens', { name: `mcp-${os.hostname()}` });
+        return token ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+// Register the insta-cloud remote MCP server with Claude Code (user scope, so it follows the
+// machine like the skill install above). Default is OAuth: register with NO credential — the
+// platform's Better Auth MCP authorization server is discovered via RFC 9728 and Claude runs
+// the browser flow on first `/mcp` use, so no static token ever lands on disk. `--mcp-token`
+// is the headless fallback (CI, no browser): mint a durable token into the header instead.
+// Idempotent — an existing registration is left alone. Best-effort: the skill install is the
+// primary outcome; agents without an MCP registry are covered by the skill alone.
+export async function registerMcp(run = defaultRunner, mint = defaultMinter, useToken = false) {
+    const url = process.env.INSTA_MCP_URL || DEFAULT_MCP_URL;
+    if (!(await run('claude', ['--version'])).ok)
+        return; // no Claude Code on this machine
+    if ((await run('claude', ['mcp', 'get', MCP_SERVER_NAME])).ok) {
+        info(`✓ MCP — ${MCP_SERVER_NAME} already registered with Claude Code`);
+        return;
+    }
+    const args = ['mcp', 'add', '--transport', 'http', '--scope', 'user', MCP_SERVER_NAME, url];
+    if (useToken) {
+        const token = await mint();
+        if (!token) {
+            info('  MCP not registered (--mcp-token needs a login) — run `insta login`, then `insta setup agent --mcp-token` again');
+            return;
+        }
+        args.push('--header', `Authorization: Bearer ${token}`);
+    }
+    const res = await run('claude', args);
+    if (res.ok) {
+        info(`✓ MCP — ${MCP_SERVER_NAME} registered with Claude Code (\`claude mcp list\` to verify)`);
+        if (!useToken)
+            info('  first use: run `/mcp` in Claude Code and authorize in the browser (headless machines: `insta setup agent --mcp-token`)');
+    }
+    else {
+        info(`  MCP registration failed — add manually:\n    claude mcp add --transport http ${MCP_SERVER_NAME} ${url}`);
+    }
+}
+export async function setupAgent(opts, run = defaultRunner, mint, installConfigs = installAgentConfigs) {
     if (!opts.yes && !process.stdout.isTTY) {
         info('non-interactive shell — assuming -y');
     }
@@ -111,5 +163,9 @@ export async function setupAgent(opts, run = defaultRunner) {
     }
     info(summarizeInstall(res.output ?? ''));
     info('  every coding agent on this machine now knows InstaCloud (review skills before use — they run with full permissions).');
+    await registerMcp(run, mint, !!opts.mcpToken);
+    const others = await installConfigs();
+    if (others.length)
+        info(`✓ MCP — also configured for ${others.join(', ')} (restart those tools to pick it up)`);
 }
 //# sourceMappingURL=setup.js.map

package/dist/index.js

@@ -5,6 +5,7 @@ import { ApiError } from './api.js';
 import { die } from './util.js';
 import * as auth from './commands/auth.js';
 import * as setup from './commands/setup.js';
+import * as mcp from './commands/mcp.js';
 import * as runCmd from './commands/run.js';
 import * as org from './commands/org.js';
 import * as project from './commands/project.js';
@@ -66,7 +67,14 @@ program.command('run <cmd> [args...]').description('Run a command with the branc
 const setupCmd = program.command('setup').description('Set up this machine for InstaCloud agent workflows');
 setupCmd.command('agent').description('Install the insta skill user-globally for all coding agents')
     .option('-y, --yes', 'non-interactive')
+    .option('--mcp-token', 'register the MCP server with a minted insta_ API token instead of OAuth (headless machines / CI)')
     .action(guard((o) => setup.setupAgent(o)));
+// ---- MCP server integration ----
+const mcpCmd = program.command('mcp').description('insta-cloud remote MCP server integration');
+mcpCmd.command('install').description('Register the remote MCP server with coding agents (default: Claude Code + all detected)')
+    .option('--agent <slug>', 'one agent: claude-code, cursor, codex, opencode, copilot, factory-droid')
+    .option('--mcp-token', 'claude-code only: minted insta_ API token instead of OAuth (headless machines / CI)')
+    .action(guard((o) => mcp.mcpInstall(o)));
 // ---- org ----
 const orgCmd = program.command('org').description('Manage organizations');
 orgCmd.command('list').option('--json').action(guard((o) => org.orgList(o)));

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "insta",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "type": "module",
-  "description": "InstaCloud CLI — a thin client of the platform control-plane API.",
+  "description": "InstaCloud CLI \u2014 a thin client of the platform control-plane API.",
   "keywords": [
     "insta",
     "insforge",