@livestore/cli 0.4.0-dev.9 → 0.5.0-dev.0

package/src/commands/mcp-coach.ts

@@ -1,68 +1,70 @@
+import { AiError, LanguageModel, Prompt, Tool } from 'effect/unstable/ai'
 import { OpenAiClient, OpenAiLanguageModel } from '@effect/ai-openai'
-import {
-  AiError,
-  Config,
-  Effect,
-  FetchHttpClient,
-  LanguageModel,
-  Layer,
-  Prompt,
-  Schema,
-  Tool,
-} from '@livestore/utils/effect'
+
+import { Config, Effect, FetchHttpClient, Layer, Schema } from '@livestore/utils/effect'
 
 // Define the coach tool that analyzes LiveStore usage
 export const coachTool = Tool.make('livestore_coach', {
   description:
     'Analyze LiveStore code (schemas, queries, mutations, etc.) and provide AI-powered feedback on best practices, performance, and improvements.',
-  parameters: {
-    code: Schema.String.annotations({
+  parameters: Schema.Struct({
+    code: Schema.String.annotate({
       description: 'The LiveStore code to analyze (TypeScript/JavaScript)',
     }),
     codeType: Schema.optional(
-      Schema.String.annotations({
+      Schema.String.annotate({
         description: "Type of code being analyzed: 'schema', 'query', 'mutation', 'component', or 'general'",
       }),
     ),
-  },
+  }),
   success: Schema.Struct({
-    feedback: Schema.String.annotations({
+    feedback: Schema.String.annotate({
       description: 'AI-generated feedback and recommendations for the code',
     }),
     score: Schema.optional(
-      Schema.Number.annotations({
+      Schema.Number.annotate({
         description: 'Code quality score from 1-10 (optional)',
       }),
     ),
     suggestions: Schema.Array(
-      Schema.String.annotations({
+      Schema.String.annotate({
         description: 'Specific actionable suggestions for improvement',
       }),
-    ).annotations({
+    ).annotate({
       description: 'List of specific improvement suggestions',
     }),
   }),
   failure: AiError.AiError,
 })
 
-const OpenAiClientLayer = OpenAiClient.layerConfig({
-  apiKey: Config.redacted('OPENAI_API_KEY'),
-})
+/** Composed layer: HttpClient → OpenAiClient → LanguageModel */
+const LanguageModelLayer = OpenAiLanguageModel.layer({ model: 'gpt-4o-mini' }).pipe(
+  Layer.provide(OpenAiClient.layerConfig({ apiKey: Config.redacted('OPENAI_API_KEY') })),
+  Layer.provide(FetchHttpClient.layer),
+)
 
-const OpenAiModel = OpenAiLanguageModel.layer({
-  model: 'gpt-5-nano',
-})
+type CoachToolHandlerInput = {
+  readonly code: string
+  readonly codeType?: string | undefined
+}
+
+type CoachToolResult = {
+  readonly feedback: string
+  readonly score: number | undefined
+  readonly suggestions: string[]
+}
 
-// Coach tool handler that uses OpenAI for analysis
-export const coachToolHandler = Effect.fnUntraced(
-  function* ({ code, codeType }) {
-    // Build the analysis prompt
-    const codeTypeContext = codeType ? `This is ${codeType} code using LiveStore. ` : 'This is LiveStore code. '
+/** Coach tool handler that uses OpenAI for analysis */
+export const coachToolHandler: (input: CoachToolHandlerInput) => Effect.Effect<CoachToolResult, AiError.AiError> =
+  Effect.fn('mcp-coach-handler')(({ code, codeType }) => {
+    const effect = Effect.gen(function* () {
+      const codeTypeContext =
+        codeType !== undefined ? `This is ${codeType} code using LiveStore. ` : 'This is LiveStore code. '
 
-    const prompt = Prompt.makeMessage('user', {
-      content: [
-        Prompt.makePart('text', {
-          text: `${codeTypeContext}Please review the following code and provide helpful feedback focusing on:
+      const prompt = Prompt.makeMessage('user', {
+        content: [
+          Prompt.makePart('text', {
+            text: `${codeTypeContext}Please review the following code and provide helpful feedback focusing on:
 
 1. LiveStore best practices and conventions
 2. Schema design and relationships (if applicable)
@@ -84,47 +86,46 @@ Please provide:
 4. Any potential issues or concerns
 
 Format your response as constructive feedback that helps developers improve their LiveStore usage.`,
-        }),
-      ],
-    })
+          }),
+        ],
+      })
 
-    const systemPrompt = Prompt.makeMessage('system', {
-      content: `You are an expert LiveStore developer and code reviewer. Provide constructive, specific, and actionable feedback on LiveStore code. Focus on best practices, performance, and maintainability.`,
+      const systemPrompt = Prompt.makeMessage('system', {
+        content: `You are an expert LiveStore developer and code reviewer. Provide constructive, specific, and actionable feedback on LiveStore code. Focus on best practices, performance, and maintainability.`,
+      })
+
+      const llm = yield* LanguageModel.LanguageModel
+      const completion = yield* llm.generateText({ prompt: Prompt.fromMessages([systemPrompt, prompt]) })
+
+      const feedback = completion.text ?? 'Unable to generate feedback'
+
+      const suggestions = feedback
+        .split('\n')
+        .filter(
+          (line: string) =>
+            line.trim().startsWith('-') ||
+            line.trim().startsWith('*') ||
+            line.trim().startsWith('•') ||
+            line.toLowerCase().includes('recommend') ||
+            line.toLowerCase().includes('consider') ||
+            line.toLowerCase().includes('improve'),
+        )
+        .map((line: string) => line.replace(/^[-*•]\s*/, '').trim())
+        .filter((suggestion: string) => suggestion.length > 10)
+        .slice(0, 5)
+
+      const scoreMatch = feedback.match(/(?:score|rating|quality).*?(\d+(?:\.\d+)?)/i)
+      const score = scoreMatch !== null ? Number.parseFloat(scoreMatch[1] ?? '0') : undefined
+
+      return {
+        feedback,
+        score: score !== undefined && score >= 1 && score <= 10 ? score : undefined,
+        suggestions,
+      }
     })
 
-    // Get OpenAI client and call the API
-    const llm = yield* LanguageModel.LanguageModel
-    const completion = yield* llm.generateText({ prompt: Prompt.fromMessages([systemPrompt, prompt]) })
-
-    const feedback = completion.text ?? 'Unable to generate feedback'
-
-    // Extract suggestions from the feedback (simple approach)
-    const suggestions: string[] = feedback
-      .split('\n')
-      .filter(
-        (line: string) =>
-          line.trim().startsWith('-') ||
-          line.trim().startsWith('*') ||
-          line.trim().startsWith('•') ||
-          line.toLowerCase().includes('recommend') ||
-          line.toLowerCase().includes('consider') ||
-          line.toLowerCase().includes('improve'),
-      )
-      .map((line: string) => line.replace(/^[-*•]\s*/, '').trim())
-      .filter((suggestion: string) => suggestion.length > 10)
-      .slice(0, 5) // Limit to 5 suggestions
-
-    // Try to extract a score (simple regex approach)
-    const scoreMatch = feedback.match(/(?:score|rating|quality).*?(\d+(?:\.\d+)?)/i)
-    const score = scoreMatch ? Number.parseFloat(scoreMatch[1] ?? '0') : undefined
-
-    return {
-      feedback,
-      score: score && score >= 1 && score <= 10 ? score : undefined,
-      suggestions,
-    }
-  },
-  Effect.provide(Layer.provideMerge(OpenAiModel, OpenAiClientLayer)),
-  Effect.provide(FetchHttpClient.layer),
-  Effect.catchTag('ConfigError', (e) => Effect.die(e)),
-)
+    return effect.pipe(
+      Effect.provide(LanguageModelLayer),
+      Effect.catchTag('ConfigError', (e) => Effect.die(e)),
+    )
+  })

package/src/commands/mcp-protocols.test.ts

@@ -0,0 +1,76 @@
+import { spawn } from 'node:child_process'
+
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+
+import { supportedMcpProtocols } from './mcp-protocols.ts'
+
+const protocolVersions = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'] as const
+
+Vitest.describe('supportedMcpProtocols', () => {
+  Vitest.it('keeps the fallback protocol newest-first', () => {
+    Vitest.expect(supportedMcpProtocols.map((protocol) => protocol.protocolVersion)).toEqual(protocolVersions)
+  })
+
+  Vitest.it.each(protocolVersions)('negotiates an exact %s stdio initialize offer', async (protocolVersion) => {
+    const response = await initialize(protocolVersion)
+
+    Vitest.expect(response.result?.protocolVersion).toBe(protocolVersion)
+  })
+})
+
+const initialize = (protocolVersion: (typeof protocolVersions)[number]) =>
+  new Promise<InitializeResponse>((resolve, reject) => {
+    const child = spawn('bun', [new URL('./__fixtures__/mcp-protocol-server.ts', import.meta.url).pathname], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    let stdout = ''
+    let stderr = ''
+
+    const timeout = setTimeout(() => {
+      child.kill('SIGTERM')
+      reject(new Error(`MCP initialize timed out. stdout=${stdout} stderr=${stderr}`))
+    }, 5_000)
+
+    child.stdout.setEncoding('utf8')
+    child.stderr.setEncoding('utf8')
+    child.stdout.on('data', (chunk: string) => {
+      stdout += chunk
+      if (stdout.endsWith('\n') === false) return
+
+      try {
+        const response = JSON.parse(stdout.trim()) as InitializeResponse
+        clearTimeout(timeout)
+        child.kill('SIGTERM')
+        resolve(response)
+      } catch (error) {
+        clearTimeout(timeout)
+        child.kill('SIGTERM')
+        reject(error)
+      }
+    })
+    child.stderr.on('data', (chunk: string) => {
+      stderr += chunk
+    })
+    child.on('error', (error) => {
+      clearTimeout(timeout)
+      reject(error)
+    })
+    child.stdin.write(
+      `${JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion,
+          capabilities: {},
+          clientInfo: { name: 'livestore-mcp-protocol-test', version: '0.0.0' },
+        },
+      })}\n`,
+    )
+  })
+
+interface InitializeResponse {
+  readonly result?: {
+    readonly protocolVersion?: string
+  }
+}

package/src/commands/mcp-protocols.ts

@@ -0,0 +1,12 @@
+import { McpProtocol } from 'effect/unstable/ai'
+
+/**
+ * MCP stdio selects an exact offered version when available and otherwise
+ * falls back to the first adapter, so keep every supported adapter newest-first.
+ */
+export const supportedMcpProtocols = [
+  McpProtocol.v2025_11_25,
+  McpProtocol.v2025_06_18,
+  McpProtocol.v2025_03_26,
+  McpProtocol.v2024_11_05,
+] as const

package/src/commands/mcp-stdio.test.ts

@@ -0,0 +1,93 @@
+import { spawn } from 'node:child_process'
+
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+
+Vitest.describe('mcp server stdio', () => {
+  Vitest.it('reserves stdout for JSON-RPC messages', async () => {
+    const response = await initialize()
+
+    Vitest.expect(response.result?.protocolVersion).toBe('2025-06-18')
+  })
+})
+
+/** Exercises the real CLI entrypoint so root-level warnings and logs cannot corrupt MCP framing. */
+const initialize = () =>
+  new Promise<InitializeResponse>((resolve, reject) => {
+    const child = spawn('bun', [new URL('../bin.ts', import.meta.url).pathname, 'mcp', 'server'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    let stdoutBuffer = ''
+    let stderr = ''
+    let settled = false
+
+    const finish = (result: { readonly response: InitializeResponse } | { readonly error: unknown }) => {
+      if (settled === true) return
+      settled = true
+      clearTimeout(timeout)
+      child.kill('SIGTERM')
+      if ('error' in result) reject(result.error)
+      else resolve(result.response)
+    }
+
+    const timeout = setTimeout(() => {
+      finish({ error: new Error(`MCP initialize timed out. stdout=${stdoutBuffer} stderr=${stderr}`) })
+    }, 5_000)
+
+    child.stdout.setEncoding('utf8')
+    child.stderr.setEncoding('utf8')
+    child.stdout.on('data', (chunk: string) => {
+      stdoutBuffer += chunk
+      const lines = stdoutBuffer.split('\n')
+      stdoutBuffer = lines.pop() ?? ''
+
+      for (const line of lines) {
+        if (line.length === 0) continue
+
+        try {
+          const message = JSON.parse(line) as InitializeResponse
+          if (message.jsonrpc !== '2.0') {
+            finish({ error: new Error(`MCP stdout contained a non-JSON-RPC message: ${line}`) })
+            return
+          }
+          if (message.id === 1) {
+            finish({ response: message })
+            return
+          }
+        } catch (error) {
+          finish({ error: new Error(`MCP stdout contained invalid JSON: ${line}`, { cause: error }) })
+          return
+        }
+      }
+    })
+    child.stderr.on('data', (chunk: string) => {
+      stderr += chunk
+    })
+    child.on('error', (error) => {
+      finish({ error })
+    })
+    child.on('exit', (code) => {
+      if (settled === false) {
+        finish({ error: new Error(`MCP server exited before initialize completed (code ${code}). stderr=${stderr}`) })
+      }
+    })
+    child.stdin.write(
+      `${JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2025-06-18',
+          capabilities: {},
+          clientInfo: { name: 'livestore-mcp-stdio-test', version: '0.0.0' },
+        },
+      })}\n`,
+    )
+  })
+
+interface InitializeResponse {
+  readonly jsonrpc?: unknown
+  readonly id?: unknown
+  readonly result?: {
+    readonly protocolVersion?: string
+  }
+}

package/src/commands/{mcp-tools.ts → mcp-tool-handlers.ts}

@@ -1,61 +1,23 @@
-import { Effect, Schema, Tool, Toolkit } from '@livestore/utils/effect'
+import { type Toolkit } from 'effect/unstable/ai'
+
+import { Effect, FetchHttpClient, Layer } from '@livestore/utils/effect'
+import { PlatformNode } from '@livestore/utils/node'
+
 import { blogSchemaContent } from '../mcp-content/schemas/blog.ts'
 import { ecommerceSchemaContent } from '../mcp-content/schemas/ecommerce.ts'
 import { socialSchemaContent } from '../mcp-content/schemas/social.ts'
 import { todoSchemaContent } from '../mcp-content/schemas/todo.ts'
-import { coachTool, coachToolHandler } from './mcp-coach.ts'
-
-// Create toolkit with tools and handlers following Tim Smart's pattern
-export const livestoreToolkit = Toolkit.make(
-  coachTool,
-
-  Tool.make('livestore_generate_schema', {
-    description:
-      'Generate a LiveStore schema for a specific use case. Choose from predefined types (todo, blog, social, ecommerce) or request a custom schema by providing a description.',
-    parameters: {
-      schemaType: Schema.String.annotations({
-        description: "Schema type: 'todo', 'blog', 'social', 'ecommerce', or 'custom'",
-      }),
-      customDescription: Schema.optional(
-        Schema.String.annotations({
-          description:
-            "For custom schemas: describe your data model needs (e.g., 'user management system with roles and permissions')",
-        }),
-      ),
-    },
-    success: Schema.Struct({
-      schemaCode: Schema.String.annotations({
-        description: 'The generated LiveStore schema TypeScript code',
-      }),
-      explanation: Schema.String.annotations({
-        description: 'Brief explanation of the schema structure',
-      }),
-    }),
-  }),
+import * as Runtime from '../mcp-runtime/runtime.ts'
+import * as SyncOps from '../sync-operations.ts'
+import { coachToolHandler } from './mcp-coach.ts'
+import { livestoreToolkit } from './mcp-tools-defs.ts'
 
-  Tool.make('livestore_get_example_schema', {
-    description:
-      'Get a complete example LiveStore schema with TypeScript code. Returns ready-to-use schema definitions for common application types.',
-    parameters: {
-      type: Schema.String.annotations({
-        description: "Example type: 'todo', 'blog', 'social', or 'ecommerce'",
-      }),
-    },
-    success: Schema.Struct({
-      schemaCode: Schema.String.annotations({
-        description: 'The complete LiveStore schema code',
-      }),
-      description: Schema.String.annotations({
-        description: 'Description of what this schema models',
-      }),
-    }),
-  })
-    .annotate(Tool.Readonly, true)
-    .annotate(Tool.Destructive, false),
-)
-
-// Tool handlers using Tim Smart's pattern
-export const toolHandlers = livestoreToolkit.of({
+/** Layer providing FileSystem and HttpClient for sync operations */
+const SyncOpsLayer = Layer.mergeAll(PlatformNode.NodeFileSystem.layer, FetchHttpClient.layer)
+
+type LivestoreToolHandlers = Toolkit.HandlersFrom<Toolkit.Tools<typeof livestoreToolkit>>
+
+export const toolHandlers: LivestoreToolHandlers = livestoreToolkit.of({
   livestore_coach: coachToolHandler,
 
   livestore_generate_schema: Effect.fnUntraced(function* ({ schemaType, customDescription }) {
@@ -80,7 +42,7 @@ export const toolHandlers = livestoreToolkit.of({
         explanation = 'E-commerce schema with products, categories, orders, and inventory'
         break
       case 'custom': {
-        if (!customDescription) {
+        if (customDescription == null) {
           schemaCode = `// Custom schema requested but no description provided
 import { Schema } from '@livestore/livestore'
 
@@ -99,13 +61,14 @@ export const schema = Schema.create({
         }
 
         // Generate a basic custom schema based on description
-        const tableName = customDescription.toLowerCase().includes('user')
-          ? 'users'
-          : customDescription.toLowerCase().includes('product')
-            ? 'products'
-            : customDescription.toLowerCase().includes('post')
-              ? 'posts'
-              : 'items'
+        const tableName =
+          customDescription.toLowerCase().includes('user') === true
+            ? 'users'
+            : customDescription.toLowerCase().includes('product') === true
+              ? 'products'
+              : customDescription.toLowerCase().includes('post') === true
+                ? 'posts'
+                : 'items'
 
         schemaCode = `// Custom schema based on: ${customDescription}
 import { Schema } from '@livestore/livestore'
@@ -166,4 +129,80 @@ export const schema = Schema.create({
 
     return { schemaCode, description }
   }),
+
+  // Connect the single in-process LiveStore instance from user module
+  livestore_instance_connect: Effect.fnUntraced(function* ({ configPath, storeId, clientId, sessionId }) {
+    const store = yield* Runtime.init({
+      configPath,
+      storeId,
+      ...(clientId !== undefined ? { clientId } : {}),
+      ...(sessionId !== undefined ? { sessionId } : {}),
+    }).pipe(Effect.orDie)
+    const eventNames = Array.from(store.schema.eventsDefsMap.keys())
+    const tableNames = Array.from(store.schema.state.sqlite.tables.keys())
+
+    return {
+      storeId: store.storeId,
+      clientId: store.clientId,
+      sessionId: store.sessionId,
+      schemaInfo: {
+        tableNames,
+        eventNames,
+      },
+    }
+  }),
+
+  // Execute a raw SQL query against the local client DB
+  livestore_instance_query: Effect.fnUntraced(function* ({ sql, bindValues }) {
+    return yield* Runtime.query({ sql, bindValues })
+  }),
+
+  // Validate and commit events
+  livestore_instance_commit_events: Effect.fnUntraced(function* ({ events }) {
+    return yield* Runtime.commit({ events })
+  }),
+
+  // Status
+  livestore_instance_status: Effect.fnUntraced(function* () {
+    return yield* Runtime.status
+  }),
+
+  // Disconnect
+  livestore_instance_disconnect: Effect.fnUntraced(function* () {
+    return yield* Runtime.disconnect
+  }),
+
+  // Sync export - pull all events from sync backend
+  livestore_sync_export: Effect.fnUntraced(function* ({ configPath, storeId, clientId }) {
+    const result = yield* SyncOps.pullEventsFromSyncBackend({
+      configPath,
+      storeId,
+      clientId: clientId ?? 'mcp-export',
+    }).pipe(Effect.scoped, Effect.provide(SyncOpsLayer), Effect.orDie)
+
+    return {
+      storeId: result.storeId,
+      eventCount: result.eventCount,
+      exportedAt: result.exportedAt,
+      data: result.data,
+    }
+  }),
+
+  // Sync import - push events to sync backend
+  livestore_sync_import: Effect.fnUntraced(function* ({ configPath, storeId, clientId, data, force, dryRun }) {
+    const result = yield* SyncOps.pushEventsToSyncBackend({
+      configPath,
+      storeId,
+      clientId: clientId ?? 'mcp-import',
+      data,
+      force: force ?? false,
+      dryRun: dryRun ?? false,
+    }).pipe(Effect.scoped, Effect.provide(SyncOpsLayer), Effect.orDie)
+
+    return {
+      storeId: result.storeId,
+      eventCount: result.eventCount,
+      dryRun: result.dryRun,
+    }
+  }),
 })

package/src/commands/mcp-tools-defs.test.ts

@@ -0,0 +1,13 @@
+import { Tool } from 'effect/unstable/ai'
+
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+
+import { livestoreToolkit } from './mcp-tools-defs.ts'
+
+Vitest.describe('livestoreToolkit', () => {
+  Vitest.it('exposes MCP-compatible object parameter schemas', () => {
+    for (const tool of Object.values(livestoreToolkit.tools)) {
+      Vitest.expect(Tool.getJsonSchema(tool), tool.name).toMatchObject({ type: 'object' })
+    }
+  })
+})