@vzn/vx 0.0.0 → 0.0.12

package/src/cli/index.ts

@@ -0,0 +1,85 @@
+// Module contract for `cli`: the top-level dispatcher plus re-exports
+// for the test suite, which asserts on the pure parsers and formatters
+// directly. Each subcommand handler lives in a sibling `<name>.ts`.
+
+import { VERSION } from '../version.js'
+import { runCmd } from './run.js'
+import { watchCmd } from './watch.js'
+import { cacheCmd } from './cache.js'
+import { lockCmd } from './lock.js'
+import { migrateCmd } from './migrate.js'
+import { upgradeCmd } from './upgrade.js'
+import { showCmd } from './show.js'
+import { infoCmd } from './info.js'
+import { mcpCmd } from './mcp.js'
+import { printHelp } from './help.js'
+
+export async function run(argv: readonly string[]): Promise<number> {
+  const [command, ...rest] = argv
+
+  switch (command) {
+    case undefined:
+    case '--help':
+    case '-h':
+    case 'help':
+      printHelp()
+      return 0
+    case '--version':
+    case 'version':
+      process.stdout.write(`vx ${VERSION}\n`)
+      return 0
+    case 'run':
+      return await runCmd(rest)
+    case 'watch':
+      return await watchCmd(rest)
+    case 'cache':
+      return await cacheCmd(rest)
+    case 'lock':
+      return await lockCmd(rest)
+    case 'migrate':
+      return await migrateCmd(rest)
+    case 'upgrade':
+      return await upgradeCmd(rest)
+    case 'show':
+      return await showCmd(rest)
+    case 'info':
+    case 'stats': // deprecated alias — `vx info` absorbed `vx stats`
+      return await infoCmd(rest)
+    case 'mcp':
+      return await mcpCmd(rest)
+    case 'serve':
+    case 'dev':
+      // vx core is only a task runner — it has no service layer of its own.
+      // A dashboard, remote cache, distributed execution, etc. are provided
+      // by PLUGINS (declared in vx.workspace.ts), never by core. We keep this
+      // neutral hint for the common muscle-memory verbs, but core names no
+      // specific plugin package: any package can provide these.
+      process.stderr.write(
+        `vx: '${command}' is not a vx core command.\n` +
+          `  vx core runs tasks in-process. A dashboard, remote cache, and\n` +
+          `  distributed execution come from plugins — not core. See the plugin\n` +
+          `  guide: https://vznjs.github.io/vx/guides/plugins/\n`,
+      )
+      return 1
+    default:
+      process.stderr.write(`vx: unknown command: ${command}\n`)
+      printHelp()
+      return 1
+  }
+}
+
+// Re-exports for tests + programmatic embedders.
+export { detectFlow, parseRunArgs, type RunArgs } from './run.js'
+export { parsePruneArgs, parseDuration, parseSize } from './cache.js'
+export { parseLockArgs, type LockArgs } from './lock.js'
+export { parseMigrateArgs, type MigrateArgs } from './migrate.js'
+export { parseShowArgs, type ShowArgs } from './show.js'
+export { parseMcpArgs, type McpArgs } from './mcp.js'
+export {
+  handleMcpRequest,
+  listMcpTools,
+  setMcpContext,
+  type McpContext,
+  type McpToolDef,
+} from './mcp-rpc.js'
+export { formatBytes } from './format.js'

package/src/cli/info.ts

@@ -0,0 +1,83 @@
+// `vx info` — workspace doctor printout. One screen of environment +
+// workspace + cache facts for bug reports and quick sanity checks.
+// `vx stats` is a deprecated alias (info absorbed it).
+
+import { Cache } from '../cache/index.js'
+import { VERSION } from '../version.js'
+import {
+  findWorkspaceRoot,
+  listProjects,
+  loadProjectConfig,
+  loadWorkspace,
+  loadWorkspaceConfig,
+  lockfilePath,
+  resolveCacheDir,
+} from '../workspace/index.js'
+import { formatBytes } from './format.js'
+
+export async function infoCmd(args: readonly string[]): Promise<number> {
+  if (args.length > 0) {
+    process.stderr.write(`vx info: unknown argument: ${args[0]}\n`)
+    return 1
+  }
+  const root = await findWorkspaceRoot(process.cwd())
+  const metas = await listProjects(await loadWorkspace(root))
+
+  let taskCount = 0
+  await Promise.all(
+    metas.map(async (meta) => {
+      if (meta.configPath === null) return
+      // A broken config must not take the doctor down with it — it
+      // just contributes zero tasks to the count.
+      try {
+        const config = await loadProjectConfig(meta.configPath)
+        taskCount += Object.keys(config.tasks ?? {}).length
+      } catch {
+        // counted as zero
+      }
+    }),
+  )
+
+  const cacheDir = resolveCacheDir(root, await loadWorkspaceConfig(root))
+  const cache = new Cache(cacheDir)
+  let stats
+  try {
+    stats = cache.stats()
+  } finally {
+    cache.close()
+  }
+
+  const lockPresent = await Bun.file(lockfilePath(root)).exists()
+  const remoteConfigured =
+    Boolean(process.env.VX_REMOTE_CACHE_URL) && Boolean(process.env.VX_REMOTE_CACHE_TOKEN)
+
+  const rows: [string, string][] = [
+    ['vx', VERSION],
+    ['bun', Bun.version],
+    ['git', gitVersion()],
+    ['workspace root', root],
+    ['projects', `${metas.length} (${taskCount} task${taskCount === 1 ? '' : 's'})`],
+    ['cache dir', cacheDir],
+    ['cache entries', `${stats.entryCount} (${formatBytes(stats.totalBytes)})`],
+    ['runs (24h)', `${stats.runCountLast24h} (${stats.hitCountLast24h} cache hits)`],
+    ['vx-lock.json', lockPresent ? 'yes' : 'no'],
+    ['remote cache', remoteConfigured ? 'yes' : 'no'],
+  ]
+  const labelW = Math.max(...rows.map(([label]) => label.length))
+  const lines = rows.map(([label, value]) => `${`${label}:`.padEnd(labelW + 1)} ${value}`)
+  process.stdout.write(`${lines.join('\n')}\n`)
+  return 0
+}
+
+function gitVersion(): string {
+  try {
+    const p = Bun.spawnSync({ cmd: ['git', '--version'], stdout: 'pipe', stderr: 'pipe' })
+    if (p.exitCode !== 0) return '(not found)'
+    return new TextDecoder()
+      .decode(p.stdout)
+      .trim()
+      .replace(/^git version /, '')
+  } catch {
+    return '(not found)'
+  }
+}

package/src/cli/lock.ts

@@ -0,0 +1,135 @@
+// `vx lock` — freeze every resolved vx.config.* into vx-lock.json.
+// `vx lock --check` — audit the lock against a fresh evaluation in the
+// current environment. Design: docs/design/config-lock-2026-06.md.
+
+import type { ProjectConfig } from '../config.js'
+import { relPosix, xxh3hex } from '../util/index.js'
+import {
+  findWorkspaceRoot,
+  listProjects,
+  loadProjectConfig,
+  loadWorkspace,
+  LOCKFILE_NAME,
+  LOCKFILE_VERSION,
+  readLockfile,
+  writeLockfile,
+  type Lockfile,
+  type LockfileEntry,
+  type ProjectMeta,
+} from '../workspace/index.js'
+
+export interface LockArgs {
+  check: boolean
+  error?: string
+}
+
+export function parseLockArgs(args: readonly string[]): LockArgs {
+  const out: LockArgs = { check: false }
+  for (const a of args) {
+    if (a === '--check') out.check = true
+    else return { check: false, error: `unknown argument: ${a}` }
+  }
+  return out
+}
+
+type ConfiguredMeta = ProjectMeta & { configPath: string }
+
+export async function lockCmd(args: readonly string[]): Promise<number> {
+  const parsed = parseLockArgs(args)
+  if (parsed.error) {
+    process.stderr.write(`vx lock: ${parsed.error}\n`)
+    return 1
+  }
+  const root = await findWorkspaceRoot(process.cwd())
+  const workspace = await loadWorkspace(root)
+  const metas = (await listProjects(workspace)).filter(
+    (m): m is ConfiguredMeta => m.configPath !== null,
+  )
+  if (parsed.check) return await checkLock(root, metas)
+  return await writeLock(root, metas)
+}
+
+/** Evaluate one config in the current env, returning its lock entry. */
+async function evaluateEntry(root: string, meta: ConfiguredMeta): Promise<LockfileEntry> {
+  const bytes = await Bun.file(meta.configPath).bytes()
+  // `fresh: true` — locking must observe the current environment, not
+  // a module-cache replay from earlier in this process.
+  const config = await loadProjectConfig(meta.configPath, { fresh: true })
+  return {
+    configPath: relPosix(root, meta.configPath),
+    configHash: xxh3hex(bytes),
+    // JSON round-trip drops `undefined` fields so the stored object is
+    // byte-identical to what a later read of the lock will produce —
+    // the exact form `--check` compares against.
+    config: JSON.parse(JSON.stringify(config)) as ProjectConfig,
+  }
+}
+
+async function writeLock(root: string, metas: ConfiguredMeta[]): Promise<number> {
+  const entries = await Promise.all(metas.map((m) => evaluateEntry(root, m)))
+  const projects: Record<string, LockfileEntry> = {}
+  // `listProjects` sorts by name — stable lockfile diffs for free.
+  for (let i = 0; i < metas.length; i++) projects[metas[i]!.name] = entries[i]!
+  const lock: Lockfile = { version: LOCKFILE_VERSION, projects }
+  await writeLockfile(root, lock)
+  const n = metas.length
+  process.stdout.write(`vx: locked ${n} project config${n === 1 ? '' : 's'} → ${LOCKFILE_NAME}\n`)
+  return 0
+}
+
+/**
+ * Audit the lock. Two layers, strictly stronger than what runs do:
+ *   1. The same hash check runs perform (file bytes vs lock hash).
+ *   2. A full re-evaluation of every config in the CURRENT environment,
+ *      deep-compared against the lock's stored resolved object. This
+ *      catches eval-time env-var drift that file hashes cannot see —
+ *      file bytes unchanged, resolved value changed.
+ */
+async function checkLock(root: string, metas: ConfiguredMeta[]): Promise<number> {
+  const lock = await readLockfile(root)
+  if (!lock) {
+    process.stderr.write(
+      `vx lock --check: no ${LOCKFILE_NAME} at ${root} — run \`vx lock\` first\n`,
+    )
+    return 1
+  }
+  const results = await Promise.all(
+    metas.map(async (m): Promise<string | null> => {
+      const rel = relPosix(root, m.configPath)
+      const entry = lock.projects[m.name]
+      if (!entry || entry.configPath !== rel) {
+        return `"${m.name}" (${rel}) is not in the lock — run 'vx lock'`
+      }
+      const hash = xxh3hex(await Bun.file(m.configPath).bytes())
+      if (hash !== entry.configHash) {
+        return `config file changed since lock (${m.name}: ${rel}) — run 'vx lock'`
+      }
+      const fresh = JSON.parse(
+        JSON.stringify(await loadProjectConfig(m.configPath, { fresh: true })),
+      ) as ProjectConfig
+      if (!Bun.deepEquals(fresh, entry.config, true)) {
+        return (
+          `lock differs from fresh evaluation in this environment (${m.name}) — ` +
+          `env-dependent config? run 'vx lock' here or remove env reads from config`
+        )
+      }
+      return null
+    }),
+  )
+  const failures = results.filter((r): r is string => r !== null)
+  const inWorkspace = new Set(metas.map((m) => m.name))
+  for (const name of Object.keys(lock.projects)) {
+    if (!inWorkspace.has(name)) {
+      failures.push(
+        `locked project "${name}" no longer has a config in the workspace — run 'vx lock'`,
+      )
+    }
+  }
+  if (failures.length > 0) {
+    for (const f of failures) process.stderr.write(`vx lock --check: ${f}\n`)
+    return 1
+  }
+  const n = metas.length
+  process.stdout.write(`vx: lock is up to date (${n} project${n === 1 ? '' : 's'})\n`)
+  return 0
+}

package/src/cli/mcp-rpc.ts

@@ -0,0 +1,292 @@
+// MCP RPC dispatcher — pure handlers that the MCP server (and a future
+// WS-side inspector) both delegate to. Each tool here corresponds to one
+// of the inspector RPCs from docs/design/wire-protocol-2026-06.md §3.
+// Schemas are JSON Schema for the MCP listing; the handlers stay
+// untyped at the boundary and validate per-tool.
+//
+// Handlers open the local cache.db on demand. The MCP server is a
+// short-lived adapter — long-lived embedders should keep the Cache
+// open across calls via `setMcpContext`.
+
+import { Cache } from '../cache/index.js'
+import { LocalHistoryProvider } from '../orchestrator/index.js'
+import { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from '../workspace/index.js'
+import { UserError } from '../util/index.js'
+
+export interface McpToolDef {
+  name: string
+  description: string
+  inputSchema: Record<string, unknown>
+}
+
+/**
+ * Where the handlers reach for state. Overridable so an embedder
+ * (a future inspector WS server) can inject a long-lived Cache + a
+ * specific workspace root instead of opening one per RPC.
+ */
+export interface McpContext {
+  /** Workspace root. Defaults to discovery from process.cwd(). */
+  workspaceRoot?: string
+}
+
+let mcpContext: McpContext = {}
+
+export function setMcpContext(ctx: McpContext): void {
+  mcpContext = ctx
+}
+
+const TOOLS: readonly McpToolDef[] = [
+  {
+    name: 'getCacheStats',
+    description: 'Aggregate cache statistics (entries, total size, hits in last 24h).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        scope: {
+          oneOf: [
+            { type: 'string', enum: ['all'] },
+            { type: 'object', properties: { project: { type: 'string' } }, required: ['project'] },
+          ],
+        },
+      },
+    },
+  },
+  {
+    name: 'getRunHistory',
+    description: 'Recent runs filtered by project / task, with per-task summary stats.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string' },
+        task: { type: 'string' },
+        limit: { type: 'integer', minimum: 1, maximum: 500, default: 50 },
+      },
+    },
+  },
+  {
+    name: 'explainCacheKey',
+    description:
+      'Break down the inputs that contribute to a task cache key (files / env / runtime / upstream).',
+    inputSchema: {
+      type: 'object',
+      properties: { taskId: { type: 'string', description: 'project#task' } },
+      required: ['taskId'],
+    },
+  },
+  {
+    name: 'whyDidThisRerun',
+    description:
+      'Compare two recent run cache keys for a task and identify the inputs that changed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        runId: { type: 'string' },
+        taskId: { type: 'string' },
+      },
+      required: ['runId', 'taskId'],
+    },
+  },
+]
+
+export function listMcpTools(): readonly McpToolDef[] {
+  return TOOLS
+}
+
+/**
+ * Dispatch a tool call by name. Returns a JSON-serializable result.
+ */
+export async function handleMcpRequest(
+  name: string,
+  argsRaw: unknown,
+): Promise<Record<string, unknown>> {
+  const args = (argsRaw ?? {}) as Record<string, unknown>
+  switch (name) {
+    case 'getCacheStats':
+      return getCacheStats(args)
+    case 'getRunHistory':
+      return getRunHistory(args)
+    case 'explainCacheKey':
+      return explainCacheKey(args)
+    case 'whyDidThisRerun':
+      return whyDidThisRerun(args)
+    default:
+      throw new UserError(`vx mcp: unknown tool: ${name}`)
+  }
+}
+
+/** Discover + open a Cache against the current workspace. Caller closes. */
+async function openCache(): Promise<{ cache: Cache; workspaceRoot: string }> {
+  const workspaceRoot = mcpContext.workspaceRoot ?? (await findWorkspaceRoot(process.cwd()))
+  const config = await loadWorkspaceConfig(workspaceRoot)
+  const cacheDir = resolveCacheDir(workspaceRoot, config)
+  return { cache: new Cache(cacheDir), workspaceRoot }
+}
+
+async function getCacheStats(args: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const { cache } = await openCache()
+  try {
+    const stats = cache.stats()
+    const hitRate24h = stats.runCountLast24h > 0 ? stats.hitCountLast24h / stats.runCountLast24h : 0
+    return {
+      scope: args.scope ?? 'all',
+      entryCount: stats.entryCount,
+      totalBytes: stats.totalBytes,
+      runCountLast24h: stats.runCountLast24h,
+      hitCountLast24h: stats.hitCountLast24h,
+      hitRate24h,
+    }
+  } finally {
+    cache.close()
+  }
+}
+
+async function getRunHistory(args: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const limit = typeof args.limit === 'number' ? Math.min(500, Math.max(1, args.limit)) : 50
+  const projectFilter = typeof args.project === 'string' ? args.project : undefined
+  const taskFilter = typeof args.task === 'string' ? args.task : undefined
+
+  const { cache } = await openCache()
+  try {
+    const db = cache.dbHandle()
+    // Distinct (project, task) pairs from the most recent runs.
+    const where: string[] = []
+    const params: (string | number)[] = []
+    if (projectFilter) {
+      where.push('project = ?')
+      params.push(projectFilter)
+    }
+    if (taskFilter) {
+      where.push('task = ?')
+      params.push(taskFilter)
+    }
+    const clause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''
+    const pairs = db
+      .query(`SELECT DISTINCT project, task FROM runs ${clause} ORDER BY started_at DESC LIMIT ?`)
+      .all(...params, limit) as { project: string; task: string }[]
+    if (pairs.length === 0) {
+      return { runs: [], history: [] }
+    }
+    const ids = pairs.map((p) => `${p.project}#${p.task}`)
+    const provider = new LocalHistoryProvider(db)
+    const table = await provider.loadFor(ids)
+    const history = ids
+      .map((id) => {
+        const h = table.get(id)
+        return h ? { id, ...h } : null
+      })
+      .filter((x) => x !== null)
+    // Most-recent N rows for the timeline view.
+    const recent = db
+      .query(
+        `SELECT run_id AS runId, project, task, status, duration_ms AS durationMs,
+                started_at AS startedAt, ended_at AS endedAt, cache_hit AS cacheHit
+         FROM runs ${clause} ORDER BY started_at DESC LIMIT ?`,
+      )
+      .all(...params, limit) as Array<{
+      runId: string | null
+      project: string
+      task: string
+      status: string
+      durationMs: number
+      startedAt: number
+      endedAt: number
+      cacheHit: number | null
+    }>
+    return { runs: recent, history }
+  } finally {
+    cache.close()
+  }
+}
+
+async function explainCacheKey(args: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const taskId = args.taskId
+  if (typeof taskId !== 'string' || !taskId.includes('#')) {
+    throw new UserError('explainCacheKey: taskId must be a "project#task" string')
+  }
+  const [project, task] = taskId.split('#', 2) as [string, string]
+  const { cache } = await openCache()
+  try {
+    const db = cache.dbHandle()
+    // The cache stores the resolved task hash on the latest entry; we
+    // surface what we know from the entries + runs tables. The deeper
+    // input-component breakdown (env / runtime / upstream) requires
+    // re-deriving the key from a live config; that's the next layer
+    // (a "prepareRun-lite" tool). For now we return what's persisted.
+    const entry = db
+      .query(
+        `SELECT hash, command, exit_code AS exitCode, duration_ms AS durationMs,
+                size_bytes AS sizeBytes, created_at AS createdAt
+         FROM entries WHERE project = ? AND task = ? ORDER BY created_at DESC LIMIT 1`,
+      )
+      .get(project, task) as
+      | {
+          hash: string
+          command: string
+          exitCode: number
+          durationMs: number
+          sizeBytes: number
+          createdAt: number
+        }
+      | undefined
+    return {
+      taskId,
+      project,
+      task,
+      latestEntry: entry ?? null,
+      note: 'cache key components (files / env / runtime / upstream hashes) require live config evaluation; this surface returns the persisted entry metadata',
+    }
+  } finally {
+    cache.close()
+  }
+}
+
+async function whyDidThisRerun(args: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const runId = args.runId
+  const taskId = args.taskId
+  if (typeof runId !== 'string' || typeof taskId !== 'string') {
+    throw new UserError('whyDidThisRerun: runId and taskId must be strings')
+  }
+  if (!taskId.includes('#')) {
+    throw new UserError('whyDidThisRerun: taskId must be a "project#task" string')
+  }
+  const [project, task] = taskId.split('#', 2) as [string, string]
+  const { cache } = await openCache()
+  try {
+    const db = cache.dbHandle()
+    const this_ = db
+      .query(
+        `SELECT hash, status, cache_hit AS cacheHit, started_at AS startedAt
+         FROM runs WHERE run_id = ? AND project = ? AND task = ?`,
+      )
+      .get(runId, project, task) as
+      | { hash: string; status: string; cacheHit: number | null; startedAt: number }
+      | undefined
+    if (!this_) {
+      return { runId, taskId, found: false, note: 'no row matching that runId + taskId' }
+    }
+    const prev = db
+      .query(
+        `SELECT hash, status, cache_hit AS cacheHit, started_at AS startedAt
+         FROM runs WHERE project = ? AND task = ? AND started_at < ?
+         ORDER BY started_at DESC LIMIT 1`,
+      )
+      .get(project, task, this_.startedAt) as
+      | { hash: string; status: string; cacheHit: number | null; startedAt: number }
+      | undefined
+    return {
+      runId,
+      taskId,
+      thisRun: this_,
+      previousRun: prev ?? null,
+      hashChanged: prev ? prev.hash !== this_.hash : null,
+      note:
+        prev && prev.hash !== this_.hash
+          ? 'cache key changed between the previous run and this one (inputs differ)'
+          : prev
+            ? 'cache key unchanged — re-run with the same key (likely --no-cache or unrelated)'
+            : 'no prior run for this (project, task)',
+    }
+  } finally {
+    cache.close()
+  }
+}

package/src/cli/mcp.ts

@@ -0,0 +1,92 @@
+// `vx mcp` — Model Context Protocol server adapter.
+//
+// Exposes vx as a typed tool surface to AI agents (Claude Code, Cursor,
+// Continue.dev, etc.). The MCP envelope is JSON-RPC 2.0 — the same
+// envelope wire-protocol-2026-06.md commits to — so this adapter is a
+// thin mapping layer: MCP tool calls dispatch to internal RPC methods.
+//
+// stdio transport in v1: every relevant agent client runs servers over
+// stdio. Streamable HTTP is a follow-up; the SDK supports both, dispatch
+// is identical, only the transport object changes.
+//
+// Tools exposed:
+//   runTasks(tasks: string[], cwd?: string)
+//   getCacheStats(scope?: 'all' | { project: string })
+//   getRunHistory({ project?, task?, limit? })
+//   explainCacheKey(taskId)
+//   whyDidThisRerun({ runId, taskId })
+//
+// The implementations live in `src/cli/mcp-rpc.ts` so a future WS-side
+// inspector can reuse them without duplicating logic.
+
+import { UserError } from '../util/index.js'
+import { VERSION } from '../version.js'
+import { handleMcpRequest, listMcpTools, type McpToolDef } from './mcp-rpc.js'
+
+export interface McpArgs {
+  /** stdio (default) | http (deferred to a follow-up) */
+  transport: 'stdio'
+}
+
+export function parseMcpArgs(args: readonly string[]): McpArgs {
+  for (const a of args) {
+    if (a === '--http') {
+      throw new UserError('vx mcp --http is not yet implemented; use stdio (default)')
+    }
+    if (a !== '--stdio') {
+      throw new UserError(`vx mcp: unknown flag ${a}`)
+    }
+  }
+  return { transport: 'stdio' }
+}
+
+export async function mcpCmd(args: readonly string[]): Promise<number> {
+  parseMcpArgs(args) // validate flags; defaults to stdio
+  let StdioServerTransport: any
+  let McpServer: any
+  try {
+    const sdkServer = await import('@modelcontextprotocol/sdk/server/index.js')
+    const sdkStdio = await import('@modelcontextprotocol/sdk/server/stdio.js')
+    McpServer = (sdkServer as { Server: any }).Server
+    StdioServerTransport = (sdkStdio as { StdioServerTransport: any }).StdioServerTransport
+  } catch {
+    throw new UserError(
+      `vx mcp requires @modelcontextprotocol/sdk to be installed. ` +
+        `Add it to your package.json or install with: bun add @modelcontextprotocol/sdk`,
+    )
+  }
+
+  const server = new McpServer(
+    { name: 'vx', version: VERSION },
+    { capabilities: { tools: {}, resources: {} } },
+  )
+
+  // Tool listing
+  const sdkTypes = await import('@modelcontextprotocol/sdk/types.js')
+  server.setRequestHandler(
+    (sdkTypes as { ListToolsRequestSchema: any }).ListToolsRequestSchema,
+    async () => ({
+      tools: listMcpTools().map((t: McpToolDef) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+      })),
+    }),
+  )
+
+  // Tool call dispatch
+  server.setRequestHandler(
+    (sdkTypes as { CallToolRequestSchema: any }).CallToolRequestSchema,
+    async (req: { params: { name: string; arguments?: unknown } }) => {
+      const result = await handleMcpRequest(req.params.name, req.params.arguments)
+      return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+      }
+    },
+  )
+
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+  await new Promise(() => undefined) // run until stdin closes
+  return 0
+}