BetterDB MCP

Instructions

Implementation Reference

• packages/mcp/src/autostart.ts:52-80 (handler)

  The actual implementation logic for startMonitor.

  export async function startMonitor(opts: {
    persist: boolean;
    port: number;
    storage: 'sqlite' | 'memory';
  }): Promise<{ url: string; alreadyRunning: boolean }> {
    const url = `http://localhost:${opts.port}`;
  
    // Pre-check: existing PID file
    if (fs.existsSync(PID_FILE)) {
      const raw = fs.readFileSync(PID_FILE, 'utf-8').trim();
      const [, portStr] = raw.split(':');
      const pid = readValidPid(PID_FILE);
      const existingPort = portStr ? Number(portStr) : opts.port;
  
      if (pid === null) {
        fs.unlinkSync(PID_FILE);
      } else {
        let processAlive = false;
        try {
          process.kill(pid, 0);
          processAlive = true;
        } catch {
          // Process not running
        }
  
        if (processAlive) {
          if (await checkHealth(existingPort)) {
            return { url: `http://localhost:${existingPort}`, alreadyRunning: true };
          }

• packages/mcp/src/index.ts:674-690 (registration)

  Registration of the 'start_monitor' tool using the server.tool method.

  server.tool(
    'start_monitor',
    'Start the BetterDB monitor as a persistent background process. If already running, returns the existing URL. The monitor persists across MCP sessions and must be stopped explicitly with stop_monitor.',
    {
      port: z.number().int().min(1).max(65535).default(3001).describe('Port for the monitor API (default 3001)'),
      storage: z.enum(['sqlite', 'memory']).default('sqlite').describe('Storage backend (default sqlite)'),
    },
    async ({ port, storage }) => {
      try {
        const { startMonitor } = await import('./autostart.js');
        const result = await startMonitor({ persist: true, port, storage });
        BETTERDB_URL = result.url;
        process.env.BETTERDB_URL = result.url;
        detectedPrefix = null;
        const status = result.alreadyRunning ? 'Monitor already running' : 'Monitor started';
        return {
          content: [{ type: 'text' as const, text: `${status} at ${result.url}` }],