# MCP Standalone CLI Plan ## Goal Ship a bundled CLI tool (`bds-mcp`) alongside the Electron app that: - Runs as a self-contained MCP server over **stdio** (for Claude Desktop, VS Code, etc.) - Works entirely against the **SQLite database** — no Electron process required - Signals the running app of changes via a **`db_notifications`** table - Is installed into agent configs by the app's existing agent-config UI (with add **and remove**) --- ## Architecture ``` ┌─────────────────────────────────┐ ┌────────────────────────────────────┐ │ bds-mcp (bundled CLI binary) │ │ bDS Electron app │ │ │ │ │ │ StdioServerTransport ──────┐ │ │ HTTP MCPServer :4124 │ │ │ │ │ ├── same engines │ │ │ │ │ └── NotificationWatcher │ │ PostEngine ├───┼─────┼──► SQLite (WAL mode, shared) │ │ MediaEngine │ │ │ posts / media / scripts … │ │ ScriptEngine │ │ │ db_notifications ← new │ │ TemplateEngine │ │ └────────────────────────────────────┘ │ MCPServer (tools/res) │ │ ▲ │ ProposalStore (in-memory) │ │ chokidar(-wal) + 100 ms debounce └─────────────────────────────┘ │ invalidate engines + IPC to renderer │ agent (Claude Desktop, VS Code…) ─┘ (stdio) ``` ### Port mapping | Context | Port | Transport | |---|---|---| | bDS app running | :4124 | HTTP (existing, unchanged) | | `bds-mcp` CLI | — | stdio | --- ## Required Changes ### A — `db_notifications` table (new Drizzle migration) ```sql CREATE TABLE db_notifications ( id INTEGER PRIMARY KEY AUTOINCREMENT, entity TEXT NOT NULL, -- 'post' | 'media' | 'script' | 'template' entityId TEXT NOT NULL, action TEXT NOT NULL, -- 'created' | 'updated' | 'deleted' fromCli INTEGER NOT NULL DEFAULT 1, -- 1 = written by CLI; reserved for future app→CLI signalling seenAt INTEGER, -- NULL = unprocessed by app createdAt INTEGER NOT NULL ); ``` The CLI writes a row after every mutation. The app's `NotificationWatcher` queries for `seenAt IS NULL AND fromCli = 1`, invalidates the relevant engine cache, emits IPC events to the renderer, stamps `seenAt`, then **prunes rows whose `seenAt` is older than 1 hour** to prevent unbounded table growth. --- ### B — Draft mode for scripts and templates (new Drizzle migration) Scripts and templates currently write the file immediately on create. To allow CLI-created proposals to be durable (survive CLI restarts) without polluting the filesystem until accepted, add the same draft pattern that posts already use. ```sql -- scripts ALTER TABLE scripts ADD COLUMN status TEXT NOT NULL DEFAULT 'published' CHECK (status IN ('draft', 'published')); ALTER TABLE scripts ADD COLUMN content TEXT; -- draft body; NULL when on-disk -- templates ALTER TABLE templates ADD COLUMN status TEXT NOT NULL DEFAULT 'published' CHECK (status IN ('draft', 'published')); ALTER TABLE templates ADD COLUMN content TEXT; -- draft body; NULL when on-disk ``` Behaviour: - **`propose_script` / `propose_template`** → `INSERT` with `status: 'draft'`, body in `content`, `filePath: ''` — no file written yet; `ProposalStore` maps `proposalId → rowId` - **`accept_proposal`** → write file to disk, set `status: 'published'`, clear `content` - **`discard_proposal`** → `DELETE` the row (never touched the filesystem) --- ### C0 — Decouple `DatabaseConnection` from Electron `src/main/database/connection.ts` currently imports `{ app } from 'electron'` for three things: `app.getPath('userData')`, `app.isPackaged`, and `process.resourcesPath`. The CLI cannot load this file at all without Electron present. Refactor `DatabaseConnection` to accept explicit constructor arguments: ```typescript interface DatabaseConnectionConfig { dbPath: string; // absolute path to bds.db migrationsFolder: string; // absolute path to the drizzle/ migrations dir dataDirs?: string[]; // extra directories to mkdir at startup (posts/, media/, etc.) } ``` Four things must move out of `connection.ts` into `main.ts` (or equivalent callers): 1. `app.getPath('userData')` in the constructor — replaced by the explicit `dbPath` 2. `app.isPackaged` + `process.resourcesPath` in `runMigrations()` — replaced by the explicit `migrationsFolder` 3. The `posts/` and `media/` `mkdirSync` calls in the constructor — absorbed into the new `dataDirs` option (caller supplies the list) 4. **`getDataPaths()`** — this method also calls `app.getPath('userData')` directly and must be removed from `DatabaseConnection` entirely. Move callers to compute data paths themselves (they already have `userData` in scope in `main.ts`). The Electron `main.ts` constructs it as today, computing paths via `app.getPath` before passing them in. The CLI uses `platformConfigPath()` and `__dirname`-relative resolution. All Electron imports are removed from `connection.ts` itself. **WAL mode and synchronous pragma** — add to `initializeLocal()` immediately after creating the client, before running migrations: ```typescript await this.localClient.execute('PRAGMA journal_mode=WAL'); await this.localClient.execute('PRAGMA synchronous=NORMAL'); ``` This must be done for **both** the app and CLI connections. It ensures the `-wal` file exists (enabling chokidar to watch it) and gives consistent write performance. This is a prerequisite for every CLI section that follows. --- ### C — `platformConfigPath()` — userData without Electron (`src/cli/platform.ts`) Pure-Node helper to resolve the same path as Electron's `app.getPath('userData')`: | Platform | Path | |---|---| | macOS | `~/Library/Application Support/Blogging Desktop Server` | | Windows | `%APPDATA%\Blogging Desktop Server` | | Linux | `~/.config/Blogging Desktop Server` | Used by the CLI entrypoint to find the SQLite database without loading Electron. --- ### D — `CliNotifier` interface + injected DB writer ```typescript interface CliNotifier { notify(entity: string, id: string, action: 'created' | 'updated' | 'deleted'): Promise; } ``` - Electron app passes a no-op implementation (keeps engines clean, no code change needed in the app path) - CLI passes a DB writer implementation that inserts into `db_notifications` Injected as an optional constructor argument on `PostEngine`, `ScriptEngine`, `TemplateEngine`, `MediaEngine`. --- ### E — Engine `invalidate()` API No engine currently exposes a way to signal that its data is stale. Before `NotificationWatcher` can be implemented, each engine that holds any in-memory state needs an `invalidate(entityId?: string): void` method that clears the relevant cached entries (or the whole cache when `entityId` is omitted), forcing a fresh DB read on the next access. Engines that are already fully stateless (query DB on every call) get a no-op stub so `NotificationWatcher` can call a uniform API. Engines to update: `PostEngine`, `MediaEngine`, `ScriptEngine`, `TemplateEngine`. --- ### F — `NotificationWatcher` (new engine, app-side only) `src/main/engine/NotificationWatcher.ts` Uses **chokidar** (already in `dependencies`) to watch both `bds.db` and `bds.db-wal`. This gives sub-100 ms latency with zero boilerplate: chokidar handles missing files (the `-wal` file doesn't exist until the first write after WAL mode is enabled), platform differences (FSEvents on macOS, inotify on Linux, FSWatch on Windows), and `add` events for when the WAL file is created for the first time. ```typescript import chokidar, { FSWatcher } from 'chokidar'; export class NotificationWatcher { private watcher: FSWatcher | null = null; private debounceTimer: ReturnType | null = null; constructor( private readonly dbPath: string, // absolute path to bds.db private readonly db: DrizzleDB, private readonly engines: WatchableEngines, private readonly mainWindow: BrowserWindow, private readonly debounceMs = 100, ) {} start(): void { // Watch both the main db file (catches checkpoints) and the WAL file // (catches every write before checkpoint). chokidar handles the case // where bds.db-wal does not yet exist — it fires 'add' when it appears. this.watcher = chokidar.watch( [this.dbPath, `${this.dbPath}-wal`], { persistent: false, ignoreInitial: true, // don't fire on startup for pre-existing files usePolling: false, // rely on native FSEvents/inotify/kqueue awaitWriteFinish: false, }, ); this.watcher.on('change', () => this.schedule()); this.watcher.on('add', () => this.schedule()); // WAL created for first time } private schedule(): void { if (this.debounceTimer) clearTimeout(this.debounceTimer); this.debounceTimer = setTimeout(() => this.process(), this.debounceMs); } private async process(): Promise { const rows = await this.db .select() .from(dbNotifications) .where(and( isNull(dbNotifications.seenAt), eq(dbNotifications.fromCli, 1), )); for (const row of rows) { this.engines[row.entity]?.invalidate(row.entityId); this.mainWindow.webContents.send( 'entity:changed', { entity: row.entity, entityId: row.entityId, action: row.action }, ); await this.db .update(dbNotifications) .set({ seenAt: Date.now() }) .where(eq(dbNotifications.id, row.id)); } // Prune rows processed more than 1 hour ago to prevent unbounded growth. await this.db .delete(dbNotifications) .where(lt(dbNotifications.seenAt, Date.now() - 3_600_000)); } stop(): void { if (this.debounceTimer) clearTimeout(this.debounceTimer); this.watcher?.close().catch(() => {}); } } ``` `WatchableEngines` is a plain record keyed by entity name (`post`, `media`, `script`, `template`) mapping to objects that expose `invalidate()`. Started in `main.ts` alongside `PreviewServer` and `MCPServer`; stopped in the `app.on('before-quit')` handler. --- ### G — `MCPServer.startCli()` (extend existing `MCPServer.ts`) The App View's `app.callServerTool()` routes through the MCP host (Claude Desktop, VS Code, etc.) over the **same** connection the server is on — it does not make a direct HTTP call to a secondary endpoint. The CLI therefore needs exactly one server and one transport: ```typescript async startCli(): Promise { const server = this.createMcpServer(); const transport = new StdioServerTransport(); await server.connect(transport); // Block until the MCP host closes stdin (normal session end). // Signal-based shutdown is the caller's responsibility: do NOT register // signal handlers here or they will race with the bds-mcp.ts handlers. await new Promise((resolve) => { process.stdin.on('close', resolve); }); await server.close(); } ``` No secondary HTTP port. No `bds-mcp-base-url` meta tag. The `ProposalStore` is owned by the single `MCPServer` instance as before. --- ### H — `src/cli/bds-mcp.ts` — CLI entrypoint (no Electron imports) ``` 1. platformConfigPath() → userData dir 2. dbPath = path.join(userData, 'bds.db') 3. migrationsFolder = path.join(__dirname, 'drizzle') // Contents/Resources/drizzle/ 4. new DatabaseConnection({ dbPath, migrationsFolder, dataDirs: [postsDir, mediaDir] }) 5. await db.initializeLocal() // runs WAL + synchronous pragmas, then migrations 6. SELECT active project (isActive = 1); exit with message if none 7. instantiate engines with CliNotifier DB writer 8. new MCPServer({ postEngine, mediaEngine, … }, { proposalTtlMs: 8 * 60 * 60 * 1000 }) 9. await mcpServer.startCli() // blocks until stdin closes 10. await shutdown() // graceful post-stdin exit ``` `MCPServer` should accept an optional `proposalTtlMs` to override the default 30-minute TTL. CLI sessions can last hours (overnight agent runs), so **8 hours** is the appropriate default. Pass `proposalTtlMs` through to the `ProposalStore` constructor. No `electron` imports. Fully standalone Node process. **Graceful shutdown** — two paths, no racing: ```typescript // Called both by signal handlers (forced) and after normal stdin-close (graceful). // process.exit() makes it non-reentrant even without the once guards. async function shutdown(): Promise { mcpServer.proposalStore.destroy(); await db.close(); // flushes any in-flight @libsql writes process.exit(0); } // Signal handlers own interruption; registered before startCli() so they are // active during the entire session. Do NOT register signals inside startCli(). process.once('SIGTERM', shutdown); process.once('SIGINT', shutdown); // Normal path: stdin closes → startCli() resolves → server.close() runs → shutdown() await mcpServer.startCli(); await shutdown(); ``` When SIGTERM fires, `shutdown()` runs and calls `process.exit(0)` — `startCli()` never resumes, `server.close()` is skipped (safe: the process is exiting anyway). When stdin closes cleanly, `startCli()` resumes, `server.close()` runs first, then `shutdown()` exits. The `once` guards and `process.exit` together make the function non-reentrant. **Native module resolution** — When launched as `ELECTRON_RUN_AS_NODE=1`, Electron's ASAR patching is still active, so `require('@libsql/client')` resolves into `app.asar/node_modules`. This is a documented side-effect of `ELECTRON_RUN_AS_NODE` that has been stable since Electron 20. Add an integration test that verifies the module resolves and the DB opens successfully from the bundled path; if a future Electron major breaks this, the test will catch it early. --- ### I — esbuild/Vite build target for CLI bundle New build target in `vite.config.ts` (or `package.json` scripts): ``` src/cli/bds-mcp.ts → dist/cli/bds-mcp.cjs target: node, format: cjs, bundle: true ``` The project uses `@libsql/client` with platform-specific native binaries (e.g. `@libsql/darwin-arm64`). These **cannot** be bundled by esbuild. Externalize all `@libsql/*` and `chokidar`-related native packages, and ensure they resolve at runtime from the app bundle (see the ASAR resolution note in section H): ``` externals: ['@libsql/client', '@libsql/darwin-arm64', '@libsql/linux-x64-gnu', 'chokidar', 'fsevents', …] ``` The `drizzle/` migrations folder does **not** need to be re-bundled alongside the `.cjs` file — it is already included in `extraResources` (see J). The path resolution `path.join(__dirname, 'drizzle')` resolves correctly when `bds-mcp.cjs` sits at `Contents/Resources/bds-mcp.cjs` and `drizzle/` is at `Contents/Resources/drizzle/`. Runs as part of `npm run build` before the Electron build. --- ### J — electron-builder `extraResources` The `{ "from": "drizzle", "to": "drizzle" }` entry **already exists** in `package.json`. Only the CLI bundle itself needs to be added: ```json "build": { "extraResources": [ { "from": "dist/cli/bds-mcp.cjs", "to": "bds-mcp.cjs" } // { "from": "drizzle", "to": "drizzle" } ← already present, do not duplicate ] } ``` `bds-mcp.cjs` lands at `Contents/Resources/bds-mcp.cjs`; `drizzle/` is already at `Contents/Resources/drizzle/`. The CLI migration resolver `path.join(__dirname, 'drizzle')` resolves `Contents/Resources/drizzle/` correctly from that location. --- ### K — `MCPAgentConfigEngine` — add Claude Desktop + stdio support + remove #### New agent type ```typescript export type MCPAgentId = | 'claude-code' | 'claude-desktop' // ← NEW (stdio) | 'github-copilot' | 'gemini-cli' | 'opencode'; ``` #### Extended options ```typescript export interface MCPAgentConfigOptions { homeDir: string; platform: NodeJS.Platform; mcpUrl: string; // stdio agents (set from app at runtime) execPath: string; // process.execPath (packaged) or 'node' (dev) scriptPath: string; // path to bds-mcp.cjs } ``` #### Claude Desktop entry ```typescript case 'claude-desktop': return { command: this.execPath, args: [this.scriptPath], env: { ELECTRON_RUN_AS_NODE: '1' }, }; ``` Config file path: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` - Linux: `~/.config/Claude/claude_desktop_config.json` > **Note:** Verify the current OpenCode config schema before implementing the `opencode` > entry — the format has changed between releases. Check the live spec at > https://opencode.ai/docs before writing the `buildEntry` case. #### Remove from config (new method) ```typescript removeFromConfig(agentId: MCPAgentId): AgentConfigResult ``` - Reads the config file - Deletes `config[serversKey][SERVER_NAME]` - If `serversKey` object is now empty, removes the key entirely - Writes back; returns `{ success, configPath }` - No-ops gracefully if file or entry does not exist This powers **Remove** buttons in the agent-config UI alongside the existing **Add** buttons, so users never have to hunt down config files manually. --- ### L — `ScriptEngine` / `TemplateEngine` — draft lifecycle methods New methods on each engine: ```typescript // ScriptEngine createDraftScript(data: CreateScriptInput): Promise // status: 'draft', no file publishScript(id: string): Promise // write file, status: 'published' deleteDraftScript(id: string): Promise // only if status: 'draft' // TemplateEngine createDraftTemplate(data: CreateTemplateInput): Promise publishTemplate(id: string): Promise deleteDraftTemplate(id: string): Promise ``` --- ### M — `ProposalStore` — map proposals to DB row IDs For `draftPost` proposals the store already maps `proposalId → postId` (the DB row). Extend this consistently: - `proposeScript` → maps `proposalId → scriptId` (DB row, `status: 'draft'`) - `proposeTemplate` → maps `proposalId → templateId` (DB row, `status: 'draft'`) - `proposeMediaMetadata` → stays in-memory (no draft DB row needed, metadata diff only) - `proposePostMetadata` → stays in-memory (same reason) `accept_proposal` dispatches to `publishScript` / `publishTemplate` / `publishPost` etc. `discard_proposal` dispatches to `deleteDraftScript` / `deleteDraftTemplate` / `deletePost`. **Known failure mode for in-memory metadata proposals:** if the CLI process is killed after a `propose_media_metadata` or `propose_post_metadata` call but before accept/discard, the `proposalId` no longer exists in any `ProposalStore`. The App View buttons will call `accept_proposal` and receive `{ success: false, message: "Proposal … not found" }` — this is already user-visible in the review UI. No silent corruption occurs; the post or media item is simply unchanged. This is accepted as the trade-off for keeping metadata proposals lightweight (no DB rows, no filesystem side effects). --- ### N — Renderer: subscribe to `entity:changed` IPC events The app's UI must reflect changes the CLI makes while the app is open. `NotificationWatcher` fires `entity:changed` IPC events (section F), but nothing currently handles them in the renderer. **`preload.ts`** — expose the channel alongside existing IPC listeners: ```typescript onEntityChanged: (cb: (payload: EntityChangedPayload) => void) => ipcRenderer.on('entity:changed', (_, payload) => cb(payload)), ``` **Renderer subscription** — in the top-level app component (or a dedicated `IpcListener` component that mounts once), subscribe on mount and unsubscribe on unmount: ```typescript useEffect(() => { const unsub = window.api.onEntityChanged(({ entity, entityId, action }) => { // Dispatch store invalidation so the next render fetches fresh data if (entity === 'post') postsStore.getState().invalidate(entityId); if (entity === 'media') mediaStore.getState().invalidate(entityId); if (entity === 'script') scriptsStore.getState().invalidate(entityId); if (entity === 'template') templatesStore.getState().invalidate(entityId); }); return () => unsub(); }, []); ``` Store `invalidate()` methods should clear the cached entry and, if the entity is currently displayed, trigger an immediate refetch — consistent with how other IPC-driven refreshes work in the app. --- ## Design Decisions | Question | Decision | |---|---| | Active project in CLI | Use `isActive = 1` from DB; fail fast if none | | Proposal durability | Scripts/templates use DB draft rows; metadata proposals stay in-memory (failure mode documented in M) | | Proposal TTL | 30 min default in app; **8 hours** in CLI (overnight agent sessions) | | App View tool calls in CLI mode | `app.callServerTool()` routes through the MCP host, not a direct HTTP call — no secondary port needed | | Claude Desktop support | stdio via bundled `bds-mcp.cjs` + `ELECTRON_RUN_AS_NODE=1` (entitlements already set) | | Remove from config | New `removeFromConfig()` method + Remove buttons in UI | | DB change detection | **chokidar** on both `bds.db` and `bds.db-wal`; 100 ms debounce; handles missing WAL via `add` events | | WAL mode | Explicit `PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL` in `initializeLocal()` for both app and CLI | | `db_notifications` growth | Rows pruned after `seenAt` is 1 hour old, inside each `process()` call | | DB coupling to Electron | `DatabaseConnection` accepts explicit paths; `getDataPaths()` removed; Electron path resolution stays in `main.ts` | | Native module resolution | `ELECTRON_RUN_AS_NODE` inherits Electron ASAR require-hooking; integration test guards against regression | | Signal handling | Signal handlers in `bds-mcp.ts` only; `startCli()` only listens to stdin-close — no competing handlers | | Renderer live updates | Section N: `entity:changed` IPC → store `invalidate()` → refetch | --- ## Implementation Order (TDD per AGENTS.md) 1. **Migrations** (A + B) — schema changes first, all other work builds on them 2. **Decouple `DatabaseConnection` from Electron** (C0) — remove `app` import, move `getDataPaths()` to callers, add WAL pragmas; update existing DB tests to pass explicit paths 3. **`platformConfigPath()`** (C) — pure function, easy to test 4. **`CliNotifier` + DB writer** (D) — unit tests with mock DB 5. **Engine `invalidate()` API** (E) — add and test on each engine before NotificationWatcher 6. **`ScriptEngine`/`TemplateEngine` draft lifecycle** (L) — tests first 7. **`ProposalStore` TTL option + DB mapping** (M) — extend existing tests; add `proposalTtlMs` constructor arg 8. **`NotificationWatcher`** (F) — test with mock DB rows + mock chokidar emitter (emit `'change'` / `'add'` events on a fake `FSWatcher`) 9. **`MCPAgentConfigEngine` — `claude-desktop` + `removeFromConfig`** (K) — extend existing tests; verify opencode format before writing its case 10. **`MCPServer.startCli()`** (G) — test with in-process `StdioServerTransport` 11. **`src/cli/bds-mcp.ts`** (H) — integration test: spawn process, send `initialize`, assert response, assert clean shutdown on SIGTERM and on stdin-close 12. **Build target + `extraResources`** (I + J) — verify `npm run build` produces `dist/cli/bds-mcp.cjs`; `drizzle/` entry already in `extraResources`, only add `bds-mcp.cjs` 13. **UI: Remove buttons** — renderer component changes, follows K 14. **`NotificationWatcher` wired in `main.ts`** (F, app side) + stopped in `before-quit` 15. **Renderer `entity:changed` subscription** (N) — `preload.ts` exposure + store `invalidate()` hookup + component subscription Each step: write failing test → implement → green → next.