hugo/bDS

Fork 0

Files

hugo 82d2751d20 docs: add MCP standalone CLI plan

2026-02-28 15:51:51 +01:00

11 KiB

Raw Blame History

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.)
Spins up HTTP :4125 alongside stdio for App View callbacks (same shared state)
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              │
│  StreamableHTTP :4125 ──────┤   │     │  ├── same engines                  │
│                             │   │     │  └── NotificationWatcher           │
│  PostEngine                 ├───┼─────┼──► SQLite (WAL mode, shared)       │
│  MediaEngine                │   │     │      posts / media / scripts …     │
│  ScriptEngine               │   │     │      db_notifications  ← new       │
│  TemplateEngine             │   │     └────────────────────────────────────┘
│  MCPServer (tools/res)      │   │                    ▲
│  ProposalStore (in-memory)  │   │           setInterval polls
└─────────────────────────────┘   │           refresh caches + IPC to renderer
                                  │
agent (Claude Desktop, VS Code…) ─┘
(stdio)

Port mapping

Context	Port	Transport
bDS app running	:4124	HTTP (existing, unchanged)
CLI stdio mode — agent	—	stdio
CLI stdio mode — App View callbacks	:4125	HTTP

Required Changes

A — `db_notifications` table (new Drizzle migration)

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'
  origin    TEXT NOT NULL,    -- 'cli' | 'app'
  seenAt    INTEGER,          -- NULL = unprocessed by app
  createdAt INTEGER NOT NULL
);

The CLI writes a row after every mutation. The app's NotificationWatcher polls for seenAt IS NULL AND origin = 'cli', refreshes the relevant engine cache, emits IPC events to the renderer, then stamps seenAt.

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.

-- 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)

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

interface CliNotifier {
  notify(entity: string, id: string, action: 'created' | 'updated' | 'deleted'): Promise<void>;
}

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 — `NotificationWatcher` (new engine, app-side only)

src/main/engine/NotificationWatcher.ts

setInterval polling every 2 s
Reads db_notifications WHERE seenAt IS NULL AND origin = 'cli'
For each row: invalidates the relevant engine's cache, calls mainWindow.webContents.send('entity:changed', { entity, entityId, action })
Stamps seenAt = Date.now() on processed rows
Started in main.ts alongside PreviewServer and MCPServer

F — `MCPServer.startCli()` (extend existing `MCPServer.ts`)

async startCli(appViewsPort = 4125): Promise<void> {
  // 1. Stdio transport — primary agent connection
  const stdioTransport = new StdioServerTransport();
  const stdioMcp = this.createServer({ mode: 'cli', appViewsPort });
  await stdioMcp.connect(stdioTransport);

  // 2. HTTP :4125 — App View callbacks, same ProposalStore
  await this.startHttp(appViewsPort, { mode: 'cli' });
}

Both McpServer instances are created via the same createServer() factory sharing the same ProposalStore instance. App View HTML receives the :4125 base URL injected as a <meta name="bds-mcp-base-url"> tag at render time so callServerTool() points to the right endpoint regardless of mode.

G — `src/cli/bds-mcp.ts` — CLI entrypoint (no Electron imports)

1. platformConfigPath() → userData dir
2. getDatabase(path.join(userData, 'bds.db'))
3. SELECT active project (isActive = 1); exit with message if none
4. instantiate engines with CliNotifier DB writer
5. new MCPServer({ postEngine, mediaEngine, … })
6. mcpServer.startCli()

No electron imports. Fully standalone Node process.

H — 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
externals: native modules only (better-sqlite3)

Runs as part of npm run build before the Electron build.

I — electron-builder `extraResources`

"build": {
  "extraResources": [
    { "from": "dist/cli/bds-mcp.cjs", "to": "bds-mcp.cjs" }
  ]
}

Placed at Contents/Resources/bds-mcp.cjs in the macOS app bundle.

J — `MCPAgentConfigEngine` — add Claude Desktop + stdio support + remove

New agent type

export type MCPAgentId =
  | 'claude-code'
  | 'claude-desktop'       // ← NEW (stdio)
  | 'github-copilot'
  | 'gemini-cli'
  | 'opencode';

Extended options

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

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

Remove from config (new method)

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.

K — `ScriptEngine` / `TemplateEngine` — draft lifecycle methods

New methods on each engine:

// ScriptEngine
createDraftScript(data: CreateScriptInput): Promise<ScriptData>   // status: 'draft', no file
publishScript(id: string): Promise<ScriptData | null>              // write file, status: 'published'
deleteDraftScript(id: string): Promise<boolean>                    // only if status: 'draft'

// TemplateEngine
createDraftTemplate(data: CreateTemplateInput): Promise<TemplateData>
publishTemplate(id: string): Promise<TemplateData | null>
deleteDraftTemplate(id: string): Promise<boolean>

L — `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.

Unresolved Questions

None — all design decisions resolved:

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
App View URL in CLI mode	Injected as `<meta name="bds-mcp-base-url">` at render time
Claude Desktop support	stdio via bundled `bds-mcp.cjs` + `ELECTRON_RUN_AS_NODE=1`
Remove from config	New `removeFromConfig()` method + Remove buttons in UI

Implementation Order (TDD per AGENTS.md)

Migrations (A + B) — schema changes first, all other work builds on them
platformConfigPath() (C) — pure function, easy to test
CliNotifier + DB writer (D) — unit tests with mock DB
ScriptEngine/TemplateEngine draft lifecycle (K) — tests first
ProposalStore DB mapping (L) — extend existing tests
NotificationWatcher (E) — test with mock DB rows
MCPAgentConfigEngine — claude-desktop + removeFromConfig (J) — extend existing tests
MCPServer.startCli() (F) — test with in-process transports
src/cli/bds-mcp.ts (G) — integration test: spawn, send initialize, assert response
Build target + extraResources (H + I) — verify npm run build produces bundle
UI: Remove buttons — renderer component changes, follows J
NotificationWatcher wired in main.ts (E, app side)

Each step: write failing test → implement → green → next.

11 KiB Raw Blame History