@soederpop/luca 0.0.2

package/src/commands/run.ts

@@ -0,0 +1,257 @@
+import { z } from 'zod'
+import { commands } from '../command.js'
+import { CommandOptionsSchema } from '../schemas/base.js'
+import type { ContainerContext } from '../container.js'
+
+declare module '../command.js' {
+	interface AvailableCommands {
+		run: ReturnType<typeof commands.registerHandler>
+	}
+}
+
+export const argsSchema = CommandOptionsSchema.extend({
+	safe: z.boolean().default(false).describe('Require approval before each code block (markdown mode)'),
+	console: z.boolean().default(false).describe('Start an interactive REPL after executing a markdown file, with all accumulated context'),
+	onlySections: z.string().optional().describe('Comma-separated list of section headings to run (case-insensitive, markdown only)'),
+})
+
+function resolveScript(ref: string, context: ContainerContext): string | null {
+	const container = context.container as any
+	const candidates = [
+		ref,
+		`${ref}.ts`,
+		`${ref}.js`,
+		`${ref}.md`,
+	]
+
+	for (const candidate of candidates) {
+		const resolved = container.paths.resolve(candidate)
+		if (container.fs.exists(resolved)) return resolved
+	}
+
+	return null
+}
+
+/**
+ * Find the ## Blocks section in the AST and return the indices to skip
+ * plus the tsx/jsx code block values to register.
+ */
+function extractBlocksSection(children: any[]): { skipIndices: Set<number>, blockSources: string[] } {
+	const skipIndices = new Set<number>()
+	const blockSources: string[] = []
+
+	let inBlocks = false
+	for (let i = 0; i < children.length; i++) {
+		const node = children[i]
+
+		if (node.type === 'heading' && node.depth === 2) {
+			const text = (node.children || []).map((c: any) => c.value || '').join('').trim()
+			if (text === 'Blocks') {
+				inBlocks = true
+				skipIndices.add(i)
+				continue
+			} else if (inBlocks) {
+				// hit the next ## heading — stop collecting
+				break
+			}
+		}
+
+		if (inBlocks) {
+			skipIndices.add(i)
+			if (node.type === 'code' && (node.lang === 'tsx' || node.lang === 'jsx')) {
+				blockSources.push(node.value)
+			}
+		}
+	}
+
+	return { skipIndices, blockSources }
+}
+
+async function runMarkdown(scriptPath: string, options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	console.clear()
+	const container = context.container as any
+	const requireApproval = options.safe
+	await container.docs.load()
+
+	const doc = await container.docs.parseMarkdownAtPath(scriptPath)
+
+	const esbuild = container.feature('esbuild')
+	const ink = container.feature('ink', { enable: true })
+	await ink.loadModules()
+
+	const vm = container.feature('vm')
+	const render = async (name: string, data?: any) => ink.renderBlock(name, data)
+	const renderAsync = async (name: string, data?: any, options?: { timeout?: number }) => ink.renderBlockAsync(name, data, options)
+	const shared = vm.createContext({
+		console, ink, render, renderAsync,
+		setTimeout, clearTimeout, setInterval, clearInterval,
+		fetch, URL, URLSearchParams,
+		...container.context,
+	})
+
+	// ─── Parse and register ## Blocks section ──────────────────────────
+	const { skipIndices, blockSources } = extractBlocksSection(doc.ast.children)
+
+	for (const source of blockSources) {
+		const keysBefore = new Set(Object.keys(shared))
+		const { code: transformed } = esbuild.transformSync(source, { loader: 'tsx', format: 'cjs' })
+
+		const hasTopLevelAwait = /\bawait\b/.test(transformed)
+		const wrapped = hasTopLevelAwait
+			? `(async function() { ${transformed} })()`
+			: transformed
+
+		await vm.run(wrapped, shared)
+
+		// auto-register any new functions as blocks
+		for (const key of Object.keys(shared)) {
+			if (!keysBefore.has(key) && typeof shared[key] === 'function') {
+				ink.registerBlock(key, shared[key])
+			}
+		}
+	}
+
+	// ─── Build section filter from --only-sections ───────────────────
+	let allowedIndices: Set<number> | null = null
+	if (options.onlySections) {
+		const requestedSections = options.onlySections.split(',').map(s => s.trim())
+		allowedIndices = new Set<number>()
+		for (const sectionName of requestedSections) {
+			try {
+				const sectionNodes = doc.extractSection(sectionName)
+				for (const node of sectionNodes) {
+					const idx = doc.ast.children.indexOf(node as any)
+					if (idx !== -1) allowedIndices.add(idx)
+				}
+			} catch {
+				// Section not found — skip silently
+			}
+		}
+	}
+
+	// ─── Execute document ──────────────────────────────────────────────
+	const children = doc.ast.children
+	for (let i = 0; i < children.length; i++) {
+		if (skipIndices.has(i)) continue
+		if (allowedIndices && !allowedIndices.has(i)) continue
+
+		const node = children[i]
+		if (node.type === 'code') {
+			const { value, lang, meta } = node
+
+			if (lang !== 'ts' && lang !== 'js' && lang !== 'tsx' && lang !== 'jsx') {
+				console.log(container.ui.markdown(['```' + (lang || ''), value, '```'].join('\n')))
+				continue
+			}
+
+			if (meta && typeof meta === 'string' && meta.toLowerCase().includes('skip')) continue
+
+			console.log(container.ui.markdown(['```' + lang, value, '```'].join('\n')))
+
+			if (requireApproval) {
+				const answer = await container.ui.askQuestion('Run this block? (y/n)')
+				if (answer.question.toLowerCase() !== 'y') continue
+			}
+
+			// Transform tsx/jsx through esbuild, and also ts for consistency
+			const needsTransform = lang === 'tsx' || lang === 'jsx'
+			let code = value
+
+			if (needsTransform) {
+				const { code: transformed } = esbuild.transformSync(value, {
+					loader: lang as 'tsx' | 'jsx',
+					format: 'cjs',
+				})
+				code = transformed
+			}
+
+			const hasTopLevelAwait = /\bawait\b/.test(code)
+			code = hasTopLevelAwait
+				? `(async function() { ${code} })()`
+				: code
+
+			await vm.run(code, shared)
+
+			// if we enabled any features, they will be in the context object
+			Object.assign(shared, container.context)
+		} else {
+			const md = doc.stringify({ type: 'root', children: [node] })
+			console.log(container.ui.markdown(md))
+		}
+	}
+
+	return shared
+}
+
+async function runScript(scriptPath: string, context: ContainerContext) {
+	const container = context.container as any
+
+	const { exitCode, stderr } = await container.proc.runScript(scriptPath)
+
+	if (exitCode === 0) return
+
+	console.error(`\nScript failed with exit code ${exitCode}.\n`)
+	if (stderr.length) {
+		console.error(stderr.join('\n'))
+	}
+}
+
+async function diagnoseError(_scriptPath: string, error: Error, _context: ContainerContext) {
+	console.error(`\n${error.stack || error.message}\n`)
+}
+
+export default async function run(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const fileRef = container.argv._[1] as string
+
+	if (!fileRef) {
+		console.error('Usage: luca run <file>')
+		process.exit(1)
+	}
+
+	const scriptPath = resolveScript(fileRef, context)
+
+	if (!scriptPath) {
+		console.error(`Could not find script: ${fileRef}`)
+		process.exit(1)
+	}
+
+	try {
+		if (scriptPath.endsWith('.md')) {
+			const shared = await runMarkdown(scriptPath, options, context)
+
+			if (options.console) {
+				const ui = container.feature('ui')
+				const prompt = ui.colors.cyan('luca') + ui.colors.dim(' > ')
+
+				console.log()
+				console.log(ui.colors.dim('  Entering REPL with markdown context. Type .exit to quit.'))
+				console.log()
+
+				const repl = container.feature('repl', { prompt })
+				await repl.start({
+					context: {
+						...shared,
+						console,
+						setTimeout,
+						setInterval,
+						clearTimeout,
+						clearInterval,
+						fetch,
+						Bun,
+					},
+				})
+			}
+		} else {
+			await runScript(scriptPath, context)
+		}
+	} catch (err: any) {
+		await diagnoseError(scriptPath, err instanceof Error ? err : new Error(String(err)), context)
+	}
+}
+
+commands.registerHandler('run', {
+	description: 'Run a script or markdown file (.ts, .js, .md)',
+	argsSchema,
+	handler: run,
+})

package/src/commands/sandbox-mcp.ts

@@ -0,0 +1,439 @@
+import { z } from 'zod'
+import { commands } from '../command.js'
+import { CommandOptionsSchema } from '../schemas/base.js'
+import type { ContainerContext } from '../container.js'
+import type { MCPServer } from '../servers/mcp.js'
+import { scaffolds, mcpReadme } from '../scaffolds/generated.js'
+import { generateScaffold } from '../scaffolds/template.js'
+
+declare module '../command.js' {
+	interface AvailableCommands {
+		'sandbox-mcp': ReturnType<typeof commands.registerHandler>
+	}
+}
+
+export const argsSchema = CommandOptionsSchema.extend({
+	transport: z.enum(['stdio', 'http']).default('stdio').describe('Transport type (stdio or http)'),
+	port: z.number().default(3002).describe('Port for HTTP transport'),
+	mcpCompat: z.enum(['standard', 'codex']).optional()
+		.describe('HTTP compatibility profile. Defaults to standard. Can also be set via MCP_HTTP_COMPAT.'),
+	stdioCompat: z.enum(['standard', 'codex', 'auto']).optional()
+		.describe('Stdio framing compatibility profile. Defaults to standard. Can also be set via MCP_STDIO_COMPAT.'),
+})
+
+export default async function mcpSandbox(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const envCompat = process.env.MCP_HTTP_COMPAT?.toLowerCase()
+	const resolvedCompat = options.mcpCompat || (envCompat === 'codex' ? 'codex' : 'standard')
+	const envStdioCompat = process.env.MCP_STDIO_COMPAT?.toLowerCase()
+	const resolvedStdioCompat = options.stdioCompat
+		|| (envStdioCompat === 'codex' || envStdioCompat === 'auto' ? envStdioCompat : 'standard')
+
+	const mcpServer = container.server('mcp', {
+		transport: options.transport,
+		port: options.port,
+		serverName: 'luca-sandbox',
+		serverVersion: container.manifest?.version || '1.0.0',
+		mcpCompat: options.mcpCompat,
+		stdioCompat: options.stdioCompat,
+	}) as MCPServer
+
+	// Persistent VM context shared across eval calls so variables survive between invocations
+	const vmFeature = container.feature('vm')
+	const sandboxContext = vmFeature.createContext({
+		container,
+		console: {
+			log: (...args: any[]) => args.map(a => typeof a === 'object' ? JSON.stringify(a, null, 2) : String(a)).join(' '),
+			error: (...args: any[]) => args.map(a => typeof a === 'object' ? JSON.stringify(a, null, 2) : String(a)).join(' '),
+			warn: (...args: any[]) => args.map(a => typeof a === 'object' ? JSON.stringify(a, null, 2) : String(a)).join(' '),
+		},
+		setTimeout,
+		setInterval,
+		clearTimeout,
+		clearInterval,
+		fetch,
+		Bun,
+	})
+
+	// Pre-populate sandbox with all enabled features
+	for (const name of container.features.available) {
+		try {
+			vmFeature.runSync(`var ${name} = container.feature('${name}')`, sandboxContext)
+		} catch {}
+	}
+
+	// --- Tool: read_me ---
+	mcpServer.tool('read_me', {
+		description: [
+			'Returns the Luca framework development guide. Call this BEFORE writing any code in a luca project.',
+			'Contains the import conventions, capability map, and workflow for discovering and using container features.',
+			'You should call this tool at the start of every session.',
+		].join('\n'),
+		schema: z.object({}),
+		handler: () => mcpReadme,
+	})
+
+	// --- Tool: find_capability ---
+	mcpServer.tool('find_capability', {
+		description: [
+			'Search for container capabilities by intent. Returns the full catalog of available features, clients,',
+			'and servers with their descriptions so you can find what you need before writing code.',
+			'Call this when you need to do something and aren\'t sure which helper provides it.',
+			'Prefer this over installing npm packages — the container likely already has what you need.',
+		].join('\n'),
+		schema: z.object({}),
+		handler: () => {
+			const sections: string[] = []
+
+			try {
+				sections.push(container.features.describeAll())
+			} catch {}
+
+			try {
+				sections.push(container.clients.describeAll())
+			} catch {}
+
+			try {
+				sections.push(container.servers.describeAll())
+			} catch {}
+
+			return sections.join('\n\n---\n\n')
+		},
+	})
+
+	// --- Tool: scaffold ---
+	mcpServer.tool('scaffold', {
+		description: [
+			'Generate correct boilerplate for a new luca helper (feature, client, server, command, or endpoint).',
+			'Returns the complete file content with your name and description filled in.',
+			'Write this to a file, then fill in your implementation.',
+			'The scaffold follows all luca conventions including schemas, jsdoc, module augmentation, and registration.',
+		].join('\n'),
+		schema: z.object({
+			type: z.enum(['feature', 'client', 'server', 'command', 'endpoint'])
+				.describe('What kind of helper to scaffold'),
+			name: z.string()
+				.describe('Name for the helper (e.g. "diskCache", "myApi", "healthCheck")'),
+			description: z.string().optional()
+				.describe('Brief description of what this helper does'),
+		}),
+		handler: (args) => {
+			const result = generateScaffold(args.type, args.name, args.description)
+			return result || `No scaffold template available for type: ${args.type}`
+		},
+	})
+
+	// --- Tool: eval ---
+	mcpServer.tool('eval', {
+		description: [
+			'Evaluate JavaScript/TypeScript code in a Luca container sandbox.',
+			'Use this to prototype and test container API calls before writing them into files.',
+			'The sandbox has all features available as top-level variables.',
+			'',
+			'The sandbox has a live `container` object and all enabled features as top-level variables',
+			'(e.g. `fs`, `git`, `ui`, `vm`, `proc`, `networking`, etc).',
+			'',
+			'Variables you define persist across calls, so you can build up state incrementally.',
+			'',
+			'The result of the last expression is returned. For async code, use `await`.',
+			'',
+			'Quick reference:',
+			'  container.features.available    — list available feature names',
+			'  container.clients.available     — list available client names',
+			'  container.servers.available     — list available server names',
+			'  container.commands.available    — list available command names',
+			'  container.features.describe(n)  — get docs for a feature by name',
+			'  container.clients.describe(n)   — get docs for a client by name',
+			'  container.inspectAsText()       — full container introspection',
+			'  fs.readFile(path)               — read a file',
+			'  fs.readdir(dir)                 — list directory contents',
+			'  proc.exec(cmd)                  — run a shell command',
+		].join('\n'),
+		schema: z.object({
+			code: z.string().describe('JavaScript code to evaluate in the Luca container sandbox'),
+		}),
+		handler: async (args) => {
+			try {
+				// Wrap code containing top-level await in an async IIFE so the VM can handle it.
+				// Try to return the last expression's value by prepending `return` to the last statement.
+				let code = args.code
+				if (/\bawait\b/.test(code) && !/^\s*\(?\s*async\b/.test(code)) {
+					const lines = code.split('\n')
+					const lastLine = lines[lines.length - 1]
+					// If the last line doesn't start with a keyword that can't be returned, add return
+					if (!/^\s*(var|let|const|if|for|while|switch|try|throw|class|function)\b/.test(lastLine)) {
+						lines[lines.length - 1] = `return ${lastLine}`
+					}
+					code = `(async () => { ${lines.join('\n')} })()`
+				}
+				const result = await vmFeature.run(code, sandboxContext)
+
+				let text: string
+				if (result === undefined) {
+					text = 'undefined'
+				} else if (result === null) {
+					text = 'null'
+				} else if (typeof result === 'string') {
+					text = result
+				} else if (typeof result === 'object') {
+					try {
+						text = JSON.stringify(result, null, 2)
+					} catch {
+						text = String(result)
+					}
+				} else {
+					text = String(result)
+				}
+
+				return { content: [{ type: 'text' as const, text }] }
+			} catch (error: any) {
+				return {
+					content: [{ type: 'text' as const, text: `Error: ${error.message}\n\n${error.stack || ''}` }],
+					isError: true,
+				}
+			}
+		},
+	})
+
+	// --- Tool: inspect_container ---
+	mcpServer.tool('inspect_container', {
+		description: [
+			'Inspect the Luca container — registries, state, methods, events, environment.',
+			'',
+			'Returns a markdown overview of the container. Optionally filter to a specific section.',
+			'',
+			'Sections: "methods", "getters", "events", "state", "options", "envVars"',
+			'Leave section empty for the full overview.',
+		].join('\n'),
+		schema: z.object({
+			section: z.enum(['methods', 'getters', 'events', 'state', 'options', 'envVars']).optional()
+				.describe('Optional section to filter to. Omit for full overview.'),
+		}),
+		handler: (args) => {
+			return container.inspectAsText(args.section)
+		},
+	})
+
+	// --- Tool: list_registry ---
+	mcpServer.tool('list_registry', {
+		description: [
+			'List available items in a container registry.',
+			'',
+			'Returns names and brief descriptions for all registered helpers in the chosen registry.',
+			'Use describe_helper to get full documentation for a specific item.',
+		].join('\n'),
+		schema: z.object({
+			registry: z.enum(['features', 'clients', 'servers', 'commands', 'endpoints'])
+				.describe('Which registry to list'),
+		}),
+		handler: (args) => {
+			const registry = (container as any)[args.registry]
+			if (!registry) return `Unknown registry: ${args.registry}`
+			const names: string[] = registry.available
+			if (names.length === 0) return `No ${args.registry} registered.`
+			const lines = [`# Available ${args.registry}\n`]
+			for (const name of names) {
+				try {
+					const Ctor = registry.lookup(name) as any
+					const desc = Ctor.description || ''
+					lines.push(`- **${name}**${desc ? `: ${desc}` : ''}`)
+				} catch {
+					lines.push(`- **${name}**`)
+				}
+			}
+			return lines.join('\n')
+		},
+	})
+
+	// --- Tool: describe_helper ---
+	mcpServer.tool('describe_helper', {
+		description: [
+			'Get full documentation for a specific helper (feature, client, server, command, endpoint).',
+			'This is the API documentation for any luca helper. There is no other documentation available —',
+			'call this before writing code that uses a feature, client, or server.',
+			'',
+			'Returns markdown with options, state schema, methods, getters, events, env vars, and descriptions.',
+			'Use list_registry or find_capability first to see what is available.',
+		].join('\n'),
+		schema: z.object({
+			registry: z.enum(['features', 'clients', 'servers', 'commands', 'endpoints'])
+				.describe('Which registry the helper belongs to'),
+			name: z.string().describe('Name of the helper (e.g. "fs", "rest", "express")'),
+			section: z.enum(['methods', 'getters', 'events', 'state', 'options', 'envVars']).optional()
+				.describe('Optional section to filter to. Omit for full documentation.'),
+		}),
+		handler: (args) => {
+			const registry = (container as any)[args.registry]
+			if (!registry) return `Unknown registry: ${args.registry}`
+			if (!registry.has(args.name)) {
+				return `"${args.name}" not found in ${args.registry}. Available: ${registry.available.join(', ')}`
+			}
+			try {
+				const Ctor = registry.lookup(args.name) as any
+				return Ctor.introspectAsText(args.section)
+			} catch (e: any) {
+				return `Error describing ${args.name}: ${e.message}`
+			}
+		},
+	})
+
+	// --- Tool: inspect_helper_instance ---
+	mcpServer.tool('inspect_helper_instance', {
+		description: [
+			'Inspect a live helper instance (enabled feature, active client/server).',
+			'Use this to inspect a live, running instance — see its current state,',
+			'check method signatures, and understand runtime behavior.',
+			'',
+			'Creates or retrieves the helper and returns introspectAsText() — the same',
+			'rich markdown documentation available on any Helper instance at runtime.',
+			'Optionally filter to a specific section.',
+		].join('\n'),
+		schema: z.object({
+			type: z.enum(['feature', 'client', 'server'])
+				.describe('What kind of helper to inspect'),
+			name: z.string().describe('Name of the helper (e.g. "fs", "rest", "express")'),
+			section: z.enum(['methods', 'getters', 'events', 'state', 'options', 'envVars']).optional()
+				.describe('Optional section to filter to. Omit for full introspection.'),
+		}),
+		handler: (args) => {
+			try {
+				let instance: any
+				if (args.type === 'feature') {
+					instance = container.feature(args.name as any)
+				} else if (args.type === 'client') {
+					instance = container.client(args.name as any)
+				} else if (args.type === 'server') {
+					instance = container.server(args.name as any)
+				}
+				return instance.introspectAsText(args.section)
+			} catch (e: any) {
+				return `Error inspecting ${args.type} "${args.name}": ${e.message}`
+			}
+		},
+	})
+
+	// --- Prompt: discover ---
+	mcpServer.prompt('discover', {
+		description: 'Learn how to explore the Luca container and discover available features, clients, servers, and commands.',
+		handler: () => [{
+			role: 'user' as const,
+			content: [
+				'# Luca Container Sandbox',
+				'',
+				'You have access to a live Luca container through the `eval` tool. The sandbox is a persistent JavaScript environment with a `container` global and all enabled features available as top-level variables.',
+				'',
+				'## Discovering what is available',
+				'',
+				'The container has registries for each helper type. Each registry has:',
+				'- `.available` — array of registered names',
+				'- `.describe(name)` — returns markdown docs for one helper',
+				'- `.describeAll()` — returns a condensed overview of all helpers (name + description)',
+				'',
+				'### Registries',
+				'```',
+				'container.features.available   // Features (fs, git, ui, vm, proc, ...)',
+				'container.clients.available    // Clients (rest, websocket, graphql, ...)',
+				'container.servers.available    // Servers (express, mcp, socket, ...)',
+				'container.commands.available   // Commands (run, console, serve, ...)',
+				'```',
+				'',
+				'### Getting documentation',
+				'```',
+				'container.features.describe("fs")      // Docs for the fs feature',
+				'container.features.describe("vm")      // Docs for the vm feature',
+				'container.clients.describe("rest")     // Docs for the rest client',
+				'container.inspectAsText()              // Full container introspection',
+				'container.inspectAsText("methods")     // Just the methods section',
+				'container.inspectAsText("state")       // Just the state section',
+				'```',
+				'',
+				'### Using features directly',
+				'All enabled features are available as top-level variables:',
+				'```',
+				'fs.readFile("package.json")            // Read a file',
+				'fs.readdir("src")                         // List directory',
+				'git.log({ max: 5 })                    // Recent git commits',
+				'proc.exec("ls -la")                    // Run a shell command',
+				'```',
+				'',
+				'### Persistent state',
+				'Variables you define in one eval call persist to the next:',
+				'```',
+				'// Call 1',
+				'const data = fs.readFile("package.json")',
+				'// Call 2',
+				'JSON.parse(data).name  // still has `data` from previous call',
+				'```',
+				'',
+				'## Recommended first steps',
+				'1. `container.features.available` — see what features exist',
+				'2. Pick an interesting feature and `container.features.describe("name")` it',
+				'3. Try using the feature directly',
+			].join('\n'),
+		}],
+	})
+
+	// --- Prompt: introspect ---
+	mcpServer.prompt('introspect', {
+		description: 'Get full introspection of the Luca container — all registries, state, methods, events, and environment info.',
+		handler: async () => {
+			const text = container.inspectAsText()
+			return [{
+				role: 'user' as const,
+				content: `Here is the full container introspection:\n\n${text}`,
+			}]
+		},
+	})
+
+	// --- Resource: container-info ---
+	mcpServer.resource('luca://container/info', {
+		name: 'Container Info',
+		description: 'Full introspection of the running Luca container',
+		mimeType: 'text/markdown',
+		handler: () => container.inspectAsText(),
+	})
+
+	// --- Resource: feature list ---
+	mcpServer.resource('luca://features', {
+		name: 'Available Features',
+		description: 'List of all registered features with descriptions',
+		mimeType: 'text/markdown',
+		handler: () => {
+			const lines = ['# Available Features\n']
+			for (const name of container.features.available) {
+				try {
+					const Ctor = container.features.lookup(name) as any
+					const desc = Ctor.description || ''
+					lines.push(`- **${name}**: ${desc}`)
+				} catch {
+					lines.push(`- **${name}**`)
+				}
+			}
+			return lines.join('\n')
+		},
+	})
+
+	// Start the server
+	await mcpServer.start({
+		transport: options.transport,
+		port: options.port,
+		mcpCompat: options.mcpCompat,
+		stdioCompat: options.stdioCompat,
+	})
+
+	if (options.transport === 'http') {
+		console.log(`\nLuca Sandbox MCP listening on http://localhost:${options.port}/mcp`)
+		console.log(`Compatibility: ${resolvedCompat}`)
+	} else {
+		console.error(`Luca Sandbox MCP started (stdio transport)`)
+		console.error(`Stdio Compatibility: ${resolvedStdioCompat}`)
+		console.error(`Tools: read_me, find_capability, scaffold, eval, inspect_container, list_registry, describe_helper, inspect_helper_instance`)
+		console.error(`Prompts: discover, introspect | Resources: luca://container/info, luca://features`)
+	}
+}
+
+commands.registerHandler('sandbox-mcp', {
+	description: 'Start an MCP server with a Luca container sandbox for AI agents to explore and test code',
+	argsSchema,
+	handler: mcpSandbox,
+})