@actuate-media/cli 0.10.0 → 0.11.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @actuate-media/cli@0.10.0 build /home/runner/work/actuatecms/actuatecms/packages/cli
+> @actuate-media/cli@0.11.0 build /home/runner/work/actuatecms/actuatecms/packages/cli
 > tsc
 

package/.turbo/turbo-test.log

@@ -1,38 +1,38 @@
 
-> @actuate-media/cli@0.10.0 test /home/runner/work/actuatecms/actuatecms/packages/cli
+> @actuate-media/cli@0.11.0 test /home/runner/work/actuatecms/actuatecms/packages/cli
 > vitest run
 
 
  RUN  v4.1.8 /home/runner/work/actuatecms/actuatecms/packages/cli
 
- ✓ dist/__tests__/db-sync.test.js (10 tests) 324ms
- ✓ dist/__tests__/seed.test.js (10 tests) 241ms
- ✓ src/__tests__/db-sync.test.ts (10 tests) 300ms
- ✓ src/__tests__/seed.test.ts (10 tests) 141ms
- ✓ dist/__tests__/deployment-diagnostics.test.js (8 tests) 68ms
- ✓ src/__tests__/deployment-diagnostics.test.ts (8 tests) 58ms
+ ✓ dist/__tests__/db-sync.test.js (10 tests) 462ms
+ ✓ dist/__tests__/seed.test.js (10 tests) 201ms
+ ✓ src/__tests__/db-sync.test.ts (10 tests) 468ms
+ ✓ src/__tests__/seed.test.ts (10 tests) 194ms
+ ✓ dist/__tests__/deployment-diagnostics.test.js (8 tests) 52ms
+ ✓ src/__tests__/deployment-diagnostics.test.ts (8 tests) 59ms
 - Reading canonical Actuate schema...
+✔ Actuate CMS models added to schema.
+- Running prisma generate...
 stdout | dist/__tests__/db-init.test.js > db:init (WS-D D5 — canonical schema, no stale fragment) > command > injects canonical models with @@map and no duplicate datasource/generator
 ✔ Prisma client generated.
 ℹ Run `npx prisma migrate dev --name actuate-cms` to create the migration.
 
-✔ Actuate CMS models added to schema.
-- Running prisma generate...
+- Reading canonical Actuate schema...
+✖ Could not locate @actuate-media/cms-core.
 stdout | dist/__tests__/db-init.test.js > db:init (WS-D D5 — canonical schema, no stale fragment) > command > fails clearly when cms-core cannot be located
 ℹ Install it first: `npm install @actuate-media/cms-core`.
-- Reading canonical Actuate schema...
 
-✖ Could not locate @actuate-media/cms-core.
 - Reading canonical Actuate schema...
+✔ Actuate CMS models added to schema.
+- Running prisma generate...
 stdout | dist/__tests__/db-init.test.js > db:init (WS-D D5 — canonical schema, no stale fragment) > command > is idempotent without --force
 ✔ Prisma client generated.
 ℹ Run `npx prisma migrate dev --name actuate-cms` to create the migration.
 
-✔ Actuate CMS models added to schema.
-- Running prisma generate...
 - Reading canonical Actuate schema...
 ℹ Actuate CMS models already present in schema. Use --force to overwrite.
- ✓ dist/__tests__/db-init.test.js (4 tests) 285ms
+ ✓ dist/__tests__/db-init.test.js (4 tests) 365ms
 - Reading canonical Actuate schema...
 ✔ Actuate CMS models added to schema.
 - Running prisma generate...
@@ -41,8 +41,8 @@
 ℹ Run `npx prisma migrate dev --name actuate-cms` to create the migration.
 
 stdout | src/__tests__/db-init.test.ts > db:init (WS-D D5 — canonical schema, no stale fragment) > command > fails clearly when cms-core cannot be located
-- Reading canonical Actuate schema...
 ℹ Install it first: `npm install @actuate-media/cms-core`.
+- Reading canonical Actuate schema...
 
 ✖ Could not locate @actuate-media/cms-core.
 - Reading canonical Actuate schema...
@@ -54,32 +54,290 @@
 
 - Reading canonical Actuate schema...
 ℹ Actuate CMS models already present in schema. Use --force to overwrite.
- ✓ src/__tests__/db-init.test.ts (4 tests) 289ms
- ✓ dist/__tests__/form-seed.test.js (10 tests) 57ms
- ✓ src/__tests__/form-seed.test.ts (10 tests) 59ms
- ✓ dist/__tests__/vercel-env-matrix.test.js (5 tests) 34ms
- ✓ src/__tests__/vercel-env-matrix.test.ts (5 tests) 43ms
+ ✓ src/__tests__/db-init.test.ts (4 tests) 391ms
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > creates both editor configs with placeholder key and git-ignores them
+✔ Created .cursor/mcp.json
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > creates both editor configs with placeholder key and git-ignores them
+✔ Created .vscode/mcp.json
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > creates both editor configs with placeholder key and git-ignores them
+✔ Added to .gitignore: .cursor/mcp.json, .vscode/mcp.json
+
+Next steps
+  1. Mint an API key in Admin → Settings → API Keys (act_sk_...)
+  2. Replace act_sk_REPLACE_WITH_YOUR_KEY in both config files with the real key
+  3. Restart Cursor / VS Code so the MCP server is picked up
+  Tip: pass --url https://your-site.com to target a deployed CMS instead.
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > applies --url and --key to both configs
+✔ Created .cursor/mcp.json
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > applies --url and --key to both configs
+✔ Created .vscode/mcp.json
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > applies --url and --key to both configs
+✔ Added to .gitignore: .cursor/mcp.json, .vscode/mcp.json
+
+Next steps
+  1. Restart Cursor / VS Code so the MCP server is picked up
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > merges into an existing config without clobbering other servers
+✔ Updated .cursor/mcp.json
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > merges into an existing config without clobbering other servers
+✔ Created .vscode/mcp.json
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > merges into an existing config without clobbering other servers
+✔ Added to .gitignore: .cursor/mcp.json, .vscode/mcp.json
+
+Next steps
+  1. Mint an API key in Admin → Settings → API Keys (act_sk_...)
+  2. Replace act_sk_REPLACE_WITH_YOUR_KEY in both config files with the real key
+  3. Restart Cursor / VS Code so the MCP server is picked up
+  Tip: pass --url https://your-site.com to target a deployed CMS instead.
+
+stderr | dist/__tests__/mcp-init.test.js > mcp:init > leaves an existing actuate entry alone unless --force is passed
+⚠ .cursor/mcp.json already has an "actuate" server — use --force to replace it.
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > leaves an existing actuate entry alone unless --force is passed
+✔ Created .vscode/mcp.json
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > leaves an existing actuate entry alone unless --force is passed
+✔ Added to .gitignore: .cursor/mcp.json, .vscode/mcp.json
+
+Next steps
+  1. Mint an API key in Admin → Settings → API Keys (act_sk_...)
+  2. Replace act_sk_REPLACE_WITH_YOUR_KEY in both config files with the real key
+  3. Restart Cursor / VS Code so the MCP server is picked up
+  Tip: pass --url https://your-site.com to target a deployed CMS instead.
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > leaves an existing actuate entry alone unless --force is passed
+✔ Updated .cursor/mcp.json
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > leaves an existing actuate entry alone unless --force is passed
+✔ Updated .vscode/mcp.json
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > leaves an existing actuate entry alone unless --force is passed
+
+Next steps
+  1. Mint an API key in Admin → Settings → API Keys (act_sk_...)
+  2. Replace act_sk_REPLACE_WITH_YOUR_KEY in both config files with the real key
+  3. Restart Cursor / VS Code so the MCP server is picked up
+
+stderr | dist/__tests__/mcp-init.test.js > mcp:init > fails on invalid JSON without --force, overwrites with --force
+✖ .cursor/mcp.json contains invalid JSON — fix it or re-run with --force.
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > fails on invalid JSON without --force, overwrites with --force
+✔ Created .vscode/mcp.json
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > fails on invalid JSON without --force, overwrites with --force
+✔ Added to .gitignore: .cursor/mcp.json, .vscode/mcp.json
+
+Next steps
+  1. Mint an API key in Admin → Settings → API Keys (act_sk_...)
+  2. Replace act_sk_REPLACE_WITH_YOUR_KEY in both config files with the real key
+  3. Restart Cursor / VS Code so the MCP server is picked up
+  Tip: pass --url https://your-site.com to target a deployed CMS instead.
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > fails on invalid JSON without --force, overwrites with --force
+✔ Updated .cursor/mcp.json
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > fails on invalid JSON without --force, overwrites with --force
+✔ Updated .vscode/mcp.json
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > fails on invalid JSON without --force, overwrites with --force
+
+Next steps
+  1. Mint an API key in Admin → Settings → API Keys (act_sk_...)
+  2. Replace act_sk_REPLACE_WITH_YOUR_KEY in both config files with the real key
+  3. Restart Cursor / VS Code so the MCP server is picked up
+  Tip: pass --url https://your-site.com to target a deployed CMS instead.
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > does not duplicate gitignore entries on re-runs
+✔ Created .cursor/mcp.json
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > does not duplicate gitignore entries on re-runs
+✔ Created .vscode/mcp.json
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > does not duplicate gitignore entries on re-runs
+✔ Added to .gitignore: .cursor/mcp.json, .vscode/mcp.json
+
+Next steps
+  1. Mint an API key in Admin → Settings → API Keys (act_sk_...)
+  2. Replace act_sk_REPLACE_WITH_YOUR_KEY in both config files with the real key
+  3. Restart Cursor / VS Code so the MCP server is picked up
+  Tip: pass --url https://your-site.com to target a deployed CMS instead.
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > does not duplicate gitignore entries on re-runs
+✔ Updated .cursor/mcp.json
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > does not duplicate gitignore entries on re-runs
+✔ Updated .vscode/mcp.json
+
+stdout | dist/__tests__/mcp-init.test.js > mcp:init > does not duplicate gitignore entries on re-runs
+
+Next steps
+  1. Mint an API key in Admin → Settings → API Keys (act_sk_...)
+  2. Replace act_sk_REPLACE_WITH_YOUR_KEY in both config files with the real key
+  3. Restart Cursor / VS Code so the MCP server is picked up
+  Tip: pass --url https://your-site.com to target a deployed CMS instead.
+
+ ✓ dist/__tests__/mcp-init.test.js (6 tests) 514ms
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > creates both editor configs with placeholder key and git-ignores them
+✔ Created .cursor/mcp.json
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > creates both editor configs with placeholder key and git-ignores them
+✔ Created .vscode/mcp.json
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > creates both editor configs with placeholder key and git-ignores them
+✔ Added to .gitignore: .cursor/mcp.json, .vscode/mcp.json
+
+Next steps
+  1. Mint an API key in Admin → Settings → API Keys (act_sk_...)
+  2. Replace act_sk_REPLACE_WITH_YOUR_KEY in both config files with the real key
+  3. Restart Cursor / VS Code so the MCP server is picked up
+  Tip: pass --url https://your-site.com to target a deployed CMS instead.
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > applies --url and --key to both configs
+✔ Created .cursor/mcp.json
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > applies --url and --key to both configs
+✔ Created .vscode/mcp.json
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > applies --url and --key to both configs
+✔ Added to .gitignore: .cursor/mcp.json, .vscode/mcp.json
+
+Next steps
+  1. Restart Cursor / VS Code so the MCP server is picked up
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > merges into an existing config without clobbering other servers
+✔ Updated .cursor/mcp.json
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > merges into an existing config without clobbering other servers
+✔ Created .vscode/mcp.json
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > merges into an existing config without clobbering other servers
+✔ Added to .gitignore: .cursor/mcp.json, .vscode/mcp.json
+
+Next steps
+  1. Mint an API key in Admin → Settings → API Keys (act_sk_...)
+  2. Replace act_sk_REPLACE_WITH_YOUR_KEY in both config files with the real key
+  3. Restart Cursor / VS Code so the MCP server is picked up
+  Tip: pass --url https://your-site.com to target a deployed CMS instead.
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > leaves an existing actuate entry alone unless --force is passed
+✔ Created .vscode/mcp.json
+
+stderr | src/__tests__/mcp-init.test.ts > mcp:init > leaves an existing actuate entry alone unless --force is passed
+⚠ .cursor/mcp.json already has an "actuate" server — use --force to replace it.
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > leaves an existing actuate entry alone unless --force is passed
+✔ Added to .gitignore: .cursor/mcp.json, .vscode/mcp.json
+
+Next steps
+  1. Mint an API key in Admin → Settings → API Keys (act_sk_...)
+  2. Replace act_sk_REPLACE_WITH_YOUR_KEY in both config files with the real key
+  3. Restart Cursor / VS Code so the MCP server is picked up
+  Tip: pass --url https://your-site.com to target a deployed CMS instead.
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > leaves an existing actuate entry alone unless --force is passed
+✔ Updated .cursor/mcp.json
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > leaves an existing actuate entry alone unless --force is passed
+✔ Updated .vscode/mcp.json
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > leaves an existing actuate entry alone unless --force is passed
+
+Next steps
+  1. Mint an API key in Admin → Settings → API Keys (act_sk_...)
+  2. Replace act_sk_REPLACE_WITH_YOUR_KEY in both config files with the real key
+  3. Restart Cursor / VS Code so the MCP server is picked up
+
+stderr | src/__tests__/mcp-init.test.ts > mcp:init > fails on invalid JSON without --force, overwrites with --force
+✖ .cursor/mcp.json contains invalid JSON — fix it or re-run with --force.
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > fails on invalid JSON without --force, overwrites with --force
+✔ Created .vscode/mcp.json
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > fails on invalid JSON without --force, overwrites with --force
+✔ Added to .gitignore: .cursor/mcp.json, .vscode/mcp.json
+
+Next steps
+  1. Mint an API key in Admin → Settings → API Keys (act_sk_...)
+  2. Replace act_sk_REPLACE_WITH_YOUR_KEY in both config files with the real key
+  3. Restart Cursor / VS Code so the MCP server is picked up
+  Tip: pass --url https://your-site.com to target a deployed CMS instead.
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > fails on invalid JSON without --force, overwrites with --force
+✔ Updated .cursor/mcp.json
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > fails on invalid JSON without --force, overwrites with --force
+✔ Updated .vscode/mcp.json
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > fails on invalid JSON without --force, overwrites with --force
+
+Next steps
+  1. Mint an API key in Admin → Settings → API Keys (act_sk_...)
+  2. Replace act_sk_REPLACE_WITH_YOUR_KEY in both config files with the real key
+  3. Restart Cursor / VS Code so the MCP server is picked up
+  Tip: pass --url https://your-site.com to target a deployed CMS instead.
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > does not duplicate gitignore entries on re-runs
+✔ Created .cursor/mcp.json
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > does not duplicate gitignore entries on re-runs
+✔ Created .vscode/mcp.json
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > does not duplicate gitignore entries on re-runs
+✔ Added to .gitignore: .cursor/mcp.json, .vscode/mcp.json
+
+Next steps
+  1. Mint an API key in Admin → Settings → API Keys (act_sk_...)
+  2. Replace act_sk_REPLACE_WITH_YOUR_KEY in both config files with the real key
+  3. Restart Cursor / VS Code so the MCP server is picked up
+  Tip: pass --url https://your-site.com to target a deployed CMS instead.
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > does not duplicate gitignore entries on re-runs
+✔ Updated .cursor/mcp.json
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > does not duplicate gitignore entries on re-runs
+✔ Updated .vscode/mcp.json
+
+stdout | src/__tests__/mcp-init.test.ts > mcp:init > does not duplicate gitignore entries on re-runs
+
+Next steps
+  1. Mint an API key in Admin → Settings → API Keys (act_sk_...)
+  2. Replace act_sk_REPLACE_WITH_YOUR_KEY in both config files with the real key
+  3. Restart Cursor / VS Code so the MCP server is picked up
+  Tip: pass --url https://your-site.com to target a deployed CMS instead.
+
+ ✓ src/__tests__/mcp-init.test.ts (6 tests) 366ms
+ ✓ dist/__tests__/form-seed.test.js (10 tests) 67ms
+ ✓ src/__tests__/form-seed.test.ts (10 tests) 61ms
+ ✓ dist/__tests__/vercel-env-matrix.test.js (5 tests) 49ms
+ ✓ src/__tests__/vercel-env-matrix.test.ts (5 tests) 69ms
 - Reading canonical Actuate schema...
 ✔ Actuate CMS models added to schema.
-- Running prisma generate...
 stdout | dist/__tests__/schema-fragment.test.js > db:init schema fragment > injects all deploy-critical Actuate models
 ✔ Prisma client generated.
 ℹ Run `npx prisma migrate dev --name actuate-cms` to create the migration.
 
- ✓ dist/__tests__/schema-fragment.test.js (1 test) 96ms
+- Running prisma generate...
+ ✓ dist/__tests__/schema-fragment.test.js (1 test) 193ms
 - Reading canonical Actuate schema...
-stdout | src/__tests__/schema-fragment.test.ts > db:init schema fragment > injects all deploy-critical Actuate models
 ✔ Actuate CMS models added to schema.
+- Running prisma generate...
+stdout | src/__tests__/schema-fragment.test.ts > db:init schema fragment > injects all deploy-critical Actuate models
 ✔ Prisma client generated.
 ℹ Run `npx prisma migrate dev --name actuate-cms` to create the migration.
 
-- Running prisma generate...
- ✓ src/__tests__/schema-fragment.test.ts (1 test) 116ms
- ✓ dist/__tests__/init.test.js (2 tests) 54ms
- ✓ src/__tests__/init.test.ts (2 tests) 32ms
-
- Test Files  16 passed (16)
-      Tests  100 passed (100)
-   Start at  15:53:52
-   Duration  23.79s (transform 2.27s, setup 0ms, import 6.86s, tests 2.20s, environment 2ms)
+ ✓ src/__tests__/schema-fragment.test.ts (1 test) 172ms
+ ✓ dist/__tests__/init.test.js (2 tests) 45ms
+ ✓ src/__tests__/init.test.ts (2 tests) 42ms
+
+ Test Files  18 passed (18)
+      Tests  112 passed (112)
+   Start at  03:11:38
+   Duration  30.42s (transform 2.66s, setup 0ms, import 7.77s, tests 3.77s, environment 12ms)
 

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @actuate-media/cli
 
+## 0.11.0
+
+### Minor Changes
+
+- eb998e5: New `actuate mcp:init` command — retrofit the Actuate MCP server onto existing projects.
+
+  Writes `.cursor/mcp.json` (Cursor / Claude Desktop shape) and `.vscode/mcp.json` (VS Code shape) wiring `@actuate-media/mcp-server`, with `--url` / `--key` options. Merges into existing configs without clobbering other MCP servers; an existing `actuate` entry is only replaced with `--force`. Both paths are appended to `.gitignore` so a real `act_sk_...` key is never committed. New scaffolds already get these files from `create-actuate-cms` — this closes the gap for projects created before that.
+
 ## 0.10.0
 
 ### Minor Changes

package/dist/__tests__/mcp-init.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mcp-init.test.d.ts.map

package/dist/__tests__/mcp-init.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-init.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/mcp-init.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/mcp-init.test.js

@@ -0,0 +1,100 @@
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { Command } from 'commander';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { registerMcpCommand } from '../commands/mcp.js';
+/**
+ * `actuate mcp:init` retrofits MCP editor configs onto existing projects.
+ * Pins the merge contract: other configured servers are never clobbered, an
+ * existing `actuate` entry needs `--force`, and both config paths end up
+ * git-ignored (they hold a real API key once configured).
+ */
+let projectDir;
+let originalCwd;
+async function run(args = []) {
+    const program = new Command();
+    program.exitOverride();
+    registerMcpCommand(program);
+    await program.parseAsync(['mcp:init', ...args], { from: 'user' });
+}
+async function readJson(relPath) {
+    return JSON.parse(await readFile(path.join(projectDir, relPath), 'utf8'));
+}
+beforeEach(async () => {
+    originalCwd = process.cwd();
+    projectDir = await mkdtemp(path.join(tmpdir(), 'actuate-mcp-init-'));
+    process.chdir(projectDir);
+});
+afterEach(async () => {
+    process.chdir(originalCwd);
+    process.exitCode = 0;
+    await rm(projectDir, { recursive: true, force: true });
+});
+describe('mcp:init', () => {
+    it('creates both editor configs with placeholder key and git-ignores them', async () => {
+        await writeFile(path.join(projectDir, '.gitignore'), 'node_modules\n', 'utf8');
+        await run();
+        const cursor = await readJson('.cursor/mcp.json');
+        expect(cursor.mcpServers.actuate.command).toBe('npx');
+        expect(cursor.mcpServers.actuate.args).toEqual(['-y', '@actuate-media/mcp-server']);
+        expect(cursor.mcpServers.actuate.env.ACTUATE_BASE_URL).toBe('http://localhost:3000');
+        expect(cursor.mcpServers.actuate.env.ACTUATE_API_KEY).toBe('act_sk_REPLACE_WITH_YOUR_KEY');
+        const vscode = await readJson('.vscode/mcp.json');
+        expect(vscode.servers.actuate.type).toBe('stdio');
+        const gitignore = await readFile(path.join(projectDir, '.gitignore'), 'utf8');
+        expect(gitignore).toContain('node_modules');
+        expect(gitignore).toContain('.cursor/mcp.json');
+        expect(gitignore).toContain('.vscode/mcp.json');
+    });
+    it('applies --url and --key to both configs', async () => {
+        await run(['--url', 'https://example.com', '--key', 'act_sk_real123']);
+        const cursor = await readJson('.cursor/mcp.json');
+        expect(cursor.mcpServers.actuate.env).toEqual({
+            ACTUATE_BASE_URL: 'https://example.com',
+            ACTUATE_API_KEY: 'act_sk_real123',
+        });
+        const vscode = await readJson('.vscode/mcp.json');
+        expect(vscode.servers.actuate.env.ACTUATE_BASE_URL).toBe('https://example.com');
+    });
+    it('merges into an existing config without clobbering other servers', async () => {
+        await mkdir(path.join(projectDir, '.cursor'), { recursive: true });
+        await writeFile(path.join(projectDir, '.cursor', 'mcp.json'), JSON.stringify({ mcpServers: { sentry: { command: 'sentry-mcp' } } }), 'utf8');
+        await run();
+        const cursor = await readJson('.cursor/mcp.json');
+        expect(cursor.mcpServers.sentry).toEqual({ command: 'sentry-mcp' });
+        expect(cursor.mcpServers.actuate).toBeDefined();
+    });
+    it('leaves an existing actuate entry alone unless --force is passed', async () => {
+        await mkdir(path.join(projectDir, '.cursor'), { recursive: true });
+        const existing = {
+            mcpServers: { actuate: { command: 'custom', env: { ACTUATE_BASE_URL: 'https://keep.me' } } },
+        };
+        await writeFile(path.join(projectDir, '.cursor', 'mcp.json'), JSON.stringify(existing), 'utf8');
+        await run();
+        let cursor = await readJson('.cursor/mcp.json');
+        expect(cursor.mcpServers.actuate.command).toBe('custom');
+        await run(['--force', '--url', 'https://new.example.com']);
+        cursor = await readJson('.cursor/mcp.json');
+        expect(cursor.mcpServers.actuate.command).toBe('npx');
+        expect(cursor.mcpServers.actuate.env.ACTUATE_BASE_URL).toBe('https://new.example.com');
+    });
+    it('fails on invalid JSON without --force, overwrites with --force', async () => {
+        await mkdir(path.join(projectDir, '.cursor'), { recursive: true });
+        await writeFile(path.join(projectDir, '.cursor', 'mcp.json'), '{ not json', 'utf8');
+        await run();
+        expect(process.exitCode).toBe(1);
+        process.exitCode = 0;
+        await run(['--force']);
+        const cursor = await readJson('.cursor/mcp.json');
+        expect(cursor.mcpServers.actuate).toBeDefined();
+    });
+    it('does not duplicate gitignore entries on re-runs', async () => {
+        await run();
+        await run(['--force']);
+        const gitignore = await readFile(path.join(projectDir, '.gitignore'), 'utf8');
+        const count = gitignore.split('\n').filter((l) => l.trim() === '.cursor/mcp.json').length;
+        expect(count).toBe(1);
+    });
+});
+//# sourceMappingURL=mcp-init.test.js.map

package/dist/__tests__/mcp-init.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-init.test.js","sourceRoot":"","sources":["../../src/__tests__/mcp-init.test.ts"],"names":[],"mappings":"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"}

package/dist/commands/mcp.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerMcpCommand(program: Command): void;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/commands/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAuHnC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0DzD"}

package/dist/commands/mcp.js

@@ -0,0 +1,126 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import chalk from 'chalk';
+import { logger } from '../utils/logger.js';
+const PLACEHOLDER_KEY = 'act_sk_REPLACE_WITH_YOUR_KEY';
+/** Cursor / Claude Desktop shape: top-level `mcpServers`. */
+function cursorEntry(opts) {
+    return {
+        command: 'npx',
+        args: ['-y', '@actuate-media/mcp-server'],
+        env: { ACTUATE_BASE_URL: opts.url, ACTUATE_API_KEY: opts.key },
+    };
+}
+/** VS Code shape: top-level `servers`, each entry declares `type: "stdio"`. */
+function vscodeEntry(opts) {
+    return { type: 'stdio', ...cursorEntry(opts) };
+}
+/**
+ * Create or merge one editor config. Existing files keep every other server
+ * entry; an existing `actuate` entry is only replaced with `--force`.
+ */
+async function mergeConfigFile(root, target, force) {
+    const filePath = path.join(root, target.relPath);
+    let config = {};
+    let existed = false;
+    if (existsSync(filePath)) {
+        existed = true;
+        const raw = await readFile(filePath, 'utf8');
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                config = parsed;
+            }
+            else if (!force) {
+                logger.error(`${target.relPath} is not a JSON object — fix it or re-run with --force.`);
+                return 'error';
+            }
+        }
+        catch {
+            if (!force) {
+                logger.error(`${target.relPath} contains invalid JSON — fix it or re-run with --force.`);
+                return 'error';
+            }
+            config = {};
+        }
+    }
+    const serversRaw = config[target.rootKey];
+    const servers = serversRaw && typeof serversRaw === 'object' && !Array.isArray(serversRaw)
+        ? serversRaw
+        : {};
+    if (servers.actuate && !force) {
+        logger.warn(`${target.relPath} already has an "actuate" server — use --force to replace it.`);
+        return 'skipped';
+    }
+    config[target.rootKey] = { ...servers, actuate: target.entry };
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    return existed ? 'updated' : 'created';
+}
+/**
+ * Make sure both MCP config paths are git-ignored. Appends only the missing
+ * entries; creates `.gitignore` if the project somehow has none.
+ */
+async function ensureGitignored(root, relPaths) {
+    const gitignorePath = path.join(root, '.gitignore');
+    const existing = existsSync(gitignorePath) ? await readFile(gitignorePath, 'utf8') : '';
+    const lines = new Set(existing.split(/\r?\n/).map((l) => l.trim()));
+    const missing = relPaths.filter((p) => !lines.has(p));
+    if (missing.length === 0)
+        return [];
+    const block = (existing && !existing.endsWith('\n') ? '\n' : '') +
+        '\n# MCP configs hold a real API key once configured — never commit them\n' +
+        missing.join('\n') +
+        '\n';
+    await writeFile(gitignorePath, existing + block, 'utf8');
+    return missing;
+}
+export function registerMcpCommand(program) {
+    program
+        .command('mcp:init')
+        .description('Write .cursor/mcp.json + .vscode/mcp.json wiring the Actuate MCP server')
+        .option('--url <baseUrl>', 'Base URL of the running CMS', 'http://localhost:3000')
+        .option('--key <apiKey>', 'Actuate API key (act_sk_...)', PLACEHOLDER_KEY)
+        .option('--force', 'Replace an existing "actuate" server entry (or unparseable config)')
+        .action(async (opts) => {
+        const root = process.cwd();
+        if (opts.key !== PLACEHOLDER_KEY && !opts.key.startsWith('act_sk_')) {
+            logger.warn('The provided --key does not look like an Actuate API key (expected act_sk_ prefix).');
+        }
+        const targets = [
+            { relPath: '.cursor/mcp.json', rootKey: 'mcpServers', entry: cursorEntry(opts) },
+            { relPath: '.vscode/mcp.json', rootKey: 'servers', entry: vscodeEntry(opts) },
+        ];
+        let failed = false;
+        for (const target of targets) {
+            const result = await mergeConfigFile(root, target, Boolean(opts.force));
+            if (result === 'created')
+                logger.success(`Created ${target.relPath}`);
+            else if (result === 'updated')
+                logger.success(`Updated ${target.relPath}`);
+            else if (result === 'error')
+                failed = true;
+        }
+        const ignored = await ensureGitignored(root, targets.map((t) => t.relPath));
+        if (ignored.length > 0) {
+            logger.success(`Added to .gitignore: ${ignored.join(', ')}`);
+        }
+        console.log();
+        console.log(chalk.bold('Next steps'));
+        if (opts.key === PLACEHOLDER_KEY) {
+            console.log(`  1. Mint an API key in ${chalk.cyan('Admin → Settings → API Keys')} (act_sk_...)`);
+            console.log(`  2. Replace ${chalk.cyan(PLACEHOLDER_KEY)} in both config files with the real key`);
+            console.log('  3. Restart Cursor / VS Code so the MCP server is picked up');
+        }
+        else {
+            console.log('  1. Restart Cursor / VS Code so the MCP server is picked up');
+        }
+        if (opts.url === 'http://localhost:3000') {
+            console.log(chalk.dim('  Tip: pass --url https://your-site.com to target a deployed CMS instead.'));
+        }
+        if (failed)
+            process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=mcp.js.map

package/dist/commands/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -14,6 +14,7 @@ import { registerDbStatusCommand } from './commands/db-status.js';
 import { registerInitCommand } from './commands/init.js';
 import { registerDeployCheckCommand, registerDoctorCommand, registerVerifyCommand, } from './commands/doctor.js';
 import { registerVercelBlobLinkCommand } from './commands/vercel-blob-link.js';
+import { registerMcpCommand } from './commands/mcp.js';
 const program = new Command();
 program
     .name('actuate')
@@ -35,5 +36,6 @@ registerDoctorCommand(program);
 registerDeployCheckCommand(program);
 registerVerifyCommand(program);
 registerVercelBlobLinkCommand(program);
+registerMcpCommand(program);
 program.parse();
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAA;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAC7D,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAA;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAA;AAE9E,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAA;AAE7B,OAAO;KACJ,IAAI,CAAC,SAAS,CAAC;KACf,WAAW,CAAC,6DAA6D,CAAC;KAC1E,OAAO,CAAC,OAAO,CAAC,CAAA;AAEnB,sBAAsB,CAAC,OAAO,CAAC,CAAA;AAC/B,8BAA8B,CAAC,OAAO,CAAC,CAAA;AACvC,uBAAuB,CAAC,OAAO,CAAC,CAAA;AAChC,mBAAmB,CAAC,OAAO,CAAC,CAAA;AAC5B,qBAAqB,CAAC,OAAO,CAAC,CAAA;AAC9B,qBAAqB,CAAC,OAAO,CAAC,CAAA;AAC9B,sBAAsB,CAAC,OAAO,CAAC,CAAA;AAC/B,0BAA0B,CAAC,OAAO,CAAC,CAAA;AACnC,qBAAqB,CAAC,OAAO,CAAC,CAAA;AAC9B,qBAAqB,CAAC,OAAO,CAAC,CAAA;AAC9B,uBAAuB,CAAC,OAAO,CAAC,CAAA;AAChC,mBAAmB,CAAC,OAAO,CAAC,CAAA;AAC5B,qBAAqB,CAAC,OAAO,CAAC,CAAA;AAC9B,0BAA0B,CAAC,OAAO,CAAC,CAAA;AACnC,qBAAqB,CAAC,OAAO,CAAC,CAAA;AAC9B,6BAA6B,CAAC,OAAO,CAAC,CAAA;AAEtC,OAAO,CAAC,KAAK,EAAE,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAA;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAC7D,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAA;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAA;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAEtD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAA;AAE7B,OAAO;KACJ,IAAI,CAAC,SAAS,CAAC;KACf,WAAW,CAAC,6DAA6D,CAAC;KAC1E,OAAO,CAAC,OAAO,CAAC,CAAA;AAEnB,sBAAsB,CAAC,OAAO,CAAC,CAAA;AAC/B,8BAA8B,CAAC,OAAO,CAAC,CAAA;AACvC,uBAAuB,CAAC,OAAO,CAAC,CAAA;AAChC,mBAAmB,CAAC,OAAO,CAAC,CAAA;AAC5B,qBAAqB,CAAC,OAAO,CAAC,CAAA;AAC9B,qBAAqB,CAAC,OAAO,CAAC,CAAA;AAC9B,sBAAsB,CAAC,OAAO,CAAC,CAAA;AAC/B,0BAA0B,CAAC,OAAO,CAAC,CAAA;AACnC,qBAAqB,CAAC,OAAO,CAAC,CAAA;AAC9B,qBAAqB,CAAC,OAAO,CAAC,CAAA;AAC9B,uBAAuB,CAAC,OAAO,CAAC,CAAA;AAChC,mBAAmB,CAAC,OAAO,CAAC,CAAA;AAC5B,qBAAqB,CAAC,OAAO,CAAC,CAAA;AAC9B,0BAA0B,CAAC,OAAO,CAAC,CAAA;AACnC,qBAAqB,CAAC,OAAO,CAAC,CAAA;AAC9B,6BAA6B,CAAC,OAAO,CAAC,CAAA;AACtC,kBAAkB,CAAC,OAAO,CAAC,CAAA;AAE3B,OAAO,CAAC,KAAK,EAAE,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actuate-media/cli",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "CLI for Actuate CMS — migrations, codegen, imports, exports, and upgrades",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
   "devDependencies": {
     "typescript": "^5.7.0",
     "vitest": "^4.1.0",
-    "@actuate-media/cms-core": "0.61.0"
+    "@actuate-media/cms-core": "0.63.0"
   },
   "scripts": {
     "build": "tsc",

package/src/__tests__/mcp-init.test.ts

@@ -0,0 +1,125 @@
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { Command } from 'commander'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { registerMcpCommand } from '../commands/mcp.js'
+
+/**
+ * `actuate mcp:init` retrofits MCP editor configs onto existing projects.
+ * Pins the merge contract: other configured servers are never clobbered, an
+ * existing `actuate` entry needs `--force`, and both config paths end up
+ * git-ignored (they hold a real API key once configured).
+ */
+
+let projectDir: string
+let originalCwd: string
+
+async function run(args: string[] = []): Promise<void> {
+  const program = new Command()
+  program.exitOverride()
+  registerMcpCommand(program)
+  await program.parseAsync(['mcp:init', ...args], { from: 'user' })
+}
+
+async function readJson(relPath: string): Promise<any> {
+  return JSON.parse(await readFile(path.join(projectDir, relPath), 'utf8'))
+}
+
+beforeEach(async () => {
+  originalCwd = process.cwd()
+  projectDir = await mkdtemp(path.join(tmpdir(), 'actuate-mcp-init-'))
+  process.chdir(projectDir)
+})
+
+afterEach(async () => {
+  process.chdir(originalCwd)
+  process.exitCode = 0
+  await rm(projectDir, { recursive: true, force: true })
+})
+
+describe('mcp:init', () => {
+  it('creates both editor configs with placeholder key and git-ignores them', async () => {
+    await writeFile(path.join(projectDir, '.gitignore'), 'node_modules\n', 'utf8')
+    await run()
+
+    const cursor = await readJson('.cursor/mcp.json')
+    expect(cursor.mcpServers.actuate.command).toBe('npx')
+    expect(cursor.mcpServers.actuate.args).toEqual(['-y', '@actuate-media/mcp-server'])
+    expect(cursor.mcpServers.actuate.env.ACTUATE_BASE_URL).toBe('http://localhost:3000')
+    expect(cursor.mcpServers.actuate.env.ACTUATE_API_KEY).toBe('act_sk_REPLACE_WITH_YOUR_KEY')
+
+    const vscode = await readJson('.vscode/mcp.json')
+    expect(vscode.servers.actuate.type).toBe('stdio')
+
+    const gitignore = await readFile(path.join(projectDir, '.gitignore'), 'utf8')
+    expect(gitignore).toContain('node_modules')
+    expect(gitignore).toContain('.cursor/mcp.json')
+    expect(gitignore).toContain('.vscode/mcp.json')
+  })
+
+  it('applies --url and --key to both configs', async () => {
+    await run(['--url', 'https://example.com', '--key', 'act_sk_real123'])
+
+    const cursor = await readJson('.cursor/mcp.json')
+    expect(cursor.mcpServers.actuate.env).toEqual({
+      ACTUATE_BASE_URL: 'https://example.com',
+      ACTUATE_API_KEY: 'act_sk_real123',
+    })
+    const vscode = await readJson('.vscode/mcp.json')
+    expect(vscode.servers.actuate.env.ACTUATE_BASE_URL).toBe('https://example.com')
+  })
+
+  it('merges into an existing config without clobbering other servers', async () => {
+    await mkdir(path.join(projectDir, '.cursor'), { recursive: true })
+    await writeFile(
+      path.join(projectDir, '.cursor', 'mcp.json'),
+      JSON.stringify({ mcpServers: { sentry: { command: 'sentry-mcp' } } }),
+      'utf8',
+    )
+    await run()
+
+    const cursor = await readJson('.cursor/mcp.json')
+    expect(cursor.mcpServers.sentry).toEqual({ command: 'sentry-mcp' })
+    expect(cursor.mcpServers.actuate).toBeDefined()
+  })
+
+  it('leaves an existing actuate entry alone unless --force is passed', async () => {
+    await mkdir(path.join(projectDir, '.cursor'), { recursive: true })
+    const existing = {
+      mcpServers: { actuate: { command: 'custom', env: { ACTUATE_BASE_URL: 'https://keep.me' } } },
+    }
+    await writeFile(path.join(projectDir, '.cursor', 'mcp.json'), JSON.stringify(existing), 'utf8')
+
+    await run()
+    let cursor = await readJson('.cursor/mcp.json')
+    expect(cursor.mcpServers.actuate.command).toBe('custom')
+
+    await run(['--force', '--url', 'https://new.example.com'])
+    cursor = await readJson('.cursor/mcp.json')
+    expect(cursor.mcpServers.actuate.command).toBe('npx')
+    expect(cursor.mcpServers.actuate.env.ACTUATE_BASE_URL).toBe('https://new.example.com')
+  })
+
+  it('fails on invalid JSON without --force, overwrites with --force', async () => {
+    await mkdir(path.join(projectDir, '.cursor'), { recursive: true })
+    await writeFile(path.join(projectDir, '.cursor', 'mcp.json'), '{ not json', 'utf8')
+
+    await run()
+    expect(process.exitCode).toBe(1)
+    process.exitCode = 0
+
+    await run(['--force'])
+    const cursor = await readJson('.cursor/mcp.json')
+    expect(cursor.mcpServers.actuate).toBeDefined()
+  })
+
+  it('does not duplicate gitignore entries on re-runs', async () => {
+    await run()
+    await run(['--force'])
+    const gitignore = await readFile(path.join(projectDir, '.gitignore'), 'utf8')
+    const count = gitignore.split('\n').filter((l) => l.trim() === '.cursor/mcp.json').length
+    expect(count).toBe(1)
+  })
+})

package/src/commands/mcp.ts

@@ -0,0 +1,181 @@
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { Command } from 'commander'
+import chalk from 'chalk'
+import { logger } from '../utils/logger.js'
+
+/**
+ * `actuate mcp:init` — retrofit the Actuate MCP server config onto an
+ * existing project.
+ *
+ * New scaffolds (`npm create actuate-cms`) emit `.cursor/mcp.json` and
+ * `.vscode/mcp.json` automatically; projects created before that feature (or
+ * set up by hand) have no easy path. This command writes both editor configs,
+ * merging into existing files so other MCP servers are preserved, and ensures
+ * both paths are git-ignored (a real `act_sk_...` key pasted into them must
+ * never be committed).
+ */
+
+interface McpInitOptions {
+  url: string
+  key: string
+  force?: boolean
+}
+
+const PLACEHOLDER_KEY = 'act_sk_REPLACE_WITH_YOUR_KEY'
+
+/** Cursor / Claude Desktop shape: top-level `mcpServers`. */
+function cursorEntry(opts: McpInitOptions): Record<string, unknown> {
+  return {
+    command: 'npx',
+    args: ['-y', '@actuate-media/mcp-server'],
+    env: { ACTUATE_BASE_URL: opts.url, ACTUATE_API_KEY: opts.key },
+  }
+}
+
+/** VS Code shape: top-level `servers`, each entry declares `type: "stdio"`. */
+function vscodeEntry(opts: McpInitOptions): Record<string, unknown> {
+  return { type: 'stdio', ...cursorEntry(opts) }
+}
+
+interface MergeTarget {
+  /** Path relative to the project root, also used in log lines. */
+  relPath: string
+  /** Top-level key the editor expects (`mcpServers` vs `servers`). */
+  rootKey: 'mcpServers' | 'servers'
+  entry: Record<string, unknown>
+}
+
+type MergeResult = 'created' | 'updated' | 'skipped' | 'error'
+
+/**
+ * Create or merge one editor config. Existing files keep every other server
+ * entry; an existing `actuate` entry is only replaced with `--force`.
+ */
+async function mergeConfigFile(
+  root: string,
+  target: MergeTarget,
+  force: boolean,
+): Promise<MergeResult> {
+  const filePath = path.join(root, target.relPath)
+
+  let config: Record<string, unknown> = {}
+  let existed = false
+  if (existsSync(filePath)) {
+    existed = true
+    const raw = await readFile(filePath, 'utf8')
+    try {
+      const parsed = JSON.parse(raw) as unknown
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        config = parsed as Record<string, unknown>
+      } else if (!force) {
+        logger.error(`${target.relPath} is not a JSON object — fix it or re-run with --force.`)
+        return 'error'
+      }
+    } catch {
+      if (!force) {
+        logger.error(`${target.relPath} contains invalid JSON — fix it or re-run with --force.`)
+        return 'error'
+      }
+      config = {}
+    }
+  }
+
+  const serversRaw = config[target.rootKey]
+  const servers =
+    serversRaw && typeof serversRaw === 'object' && !Array.isArray(serversRaw)
+      ? (serversRaw as Record<string, unknown>)
+      : {}
+
+  if (servers.actuate && !force) {
+    logger.warn(`${target.relPath} already has an "actuate" server — use --force to replace it.`)
+    return 'skipped'
+  }
+
+  config[target.rootKey] = { ...servers, actuate: target.entry }
+
+  await mkdir(path.dirname(filePath), { recursive: true })
+  await writeFile(filePath, JSON.stringify(config, null, 2) + '\n', 'utf8')
+  return existed ? 'updated' : 'created'
+}
+
+/**
+ * Make sure both MCP config paths are git-ignored. Appends only the missing
+ * entries; creates `.gitignore` if the project somehow has none.
+ */
+async function ensureGitignored(root: string, relPaths: string[]): Promise<string[]> {
+  const gitignorePath = path.join(root, '.gitignore')
+  const existing = existsSync(gitignorePath) ? await readFile(gitignorePath, 'utf8') : ''
+  const lines = new Set(existing.split(/\r?\n/).map((l) => l.trim()))
+  const missing = relPaths.filter((p) => !lines.has(p))
+  if (missing.length === 0) return []
+
+  const block =
+    (existing && !existing.endsWith('\n') ? '\n' : '') +
+    '\n# MCP configs hold a real API key once configured — never commit them\n' +
+    missing.join('\n') +
+    '\n'
+  await writeFile(gitignorePath, existing + block, 'utf8')
+  return missing
+}
+
+export function registerMcpCommand(program: Command): void {
+  program
+    .command('mcp:init')
+    .description('Write .cursor/mcp.json + .vscode/mcp.json wiring the Actuate MCP server')
+    .option('--url <baseUrl>', 'Base URL of the running CMS', 'http://localhost:3000')
+    .option('--key <apiKey>', 'Actuate API key (act_sk_...)', PLACEHOLDER_KEY)
+    .option('--force', 'Replace an existing "actuate" server entry (or unparseable config)')
+    .action(async (opts: McpInitOptions) => {
+      const root = process.cwd()
+
+      if (opts.key !== PLACEHOLDER_KEY && !opts.key.startsWith('act_sk_')) {
+        logger.warn(
+          'The provided --key does not look like an Actuate API key (expected act_sk_ prefix).',
+        )
+      }
+
+      const targets: MergeTarget[] = [
+        { relPath: '.cursor/mcp.json', rootKey: 'mcpServers', entry: cursorEntry(opts) },
+        { relPath: '.vscode/mcp.json', rootKey: 'servers', entry: vscodeEntry(opts) },
+      ]
+
+      let failed = false
+      for (const target of targets) {
+        const result = await mergeConfigFile(root, target, Boolean(opts.force))
+        if (result === 'created') logger.success(`Created ${target.relPath}`)
+        else if (result === 'updated') logger.success(`Updated ${target.relPath}`)
+        else if (result === 'error') failed = true
+      }
+
+      const ignored = await ensureGitignored(
+        root,
+        targets.map((t) => t.relPath),
+      )
+      if (ignored.length > 0) {
+        logger.success(`Added to .gitignore: ${ignored.join(', ')}`)
+      }
+
+      console.log()
+      console.log(chalk.bold('Next steps'))
+      if (opts.key === PLACEHOLDER_KEY) {
+        console.log(
+          `  1. Mint an API key in ${chalk.cyan('Admin → Settings → API Keys')} (act_sk_...)`,
+        )
+        console.log(
+          `  2. Replace ${chalk.cyan(PLACEHOLDER_KEY)} in both config files with the real key`,
+        )
+        console.log('  3. Restart Cursor / VS Code so the MCP server is picked up')
+      } else {
+        console.log('  1. Restart Cursor / VS Code so the MCP server is picked up')
+      }
+      if (opts.url === 'http://localhost:3000') {
+        console.log(
+          chalk.dim('  Tip: pass --url https://your-site.com to target a deployed CMS instead.'),
+        )
+      }
+
+      if (failed) process.exitCode = 1
+    })
+}

package/src/index.ts

@@ -18,6 +18,7 @@ import {
   registerVerifyCommand,
 } from './commands/doctor.js'
 import { registerVercelBlobLinkCommand } from './commands/vercel-blob-link.js'
+import { registerMcpCommand } from './commands/mcp.js'
 
 const program = new Command()
 
@@ -42,5 +43,6 @@ registerDoctorCommand(program)
 registerDeployCheckCommand(program)
 registerVerifyCommand(program)
 registerVercelBlobLinkCommand(program)
+registerMcpCommand(program)
 
 program.parse()