@vscode/component-explorer-cli 0.1.1-6 → 0.1.1-8

package/dist/mcp/McpServer.js

@@ -1,6 +1,14 @@
 import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import '../external/vscode-observables/observables/dist/observableInternal/index.js';
+import { Disposable } from '../external/vscode-observables/observables/dist/disposables.js';
+import '../external/vscode-observables/observables/dist/observableInternal/debugLocation.js';
+import { autorun } from '../external/vscode-observables/observables/dist/observableInternal/reactions/autorun.js';
+import '../external/vscode-observables/observables/dist/observableInternal/observables/derived.js';
+import '../external/vscode-observables/observables/dist/observableInternal/utils/utils.js';
+import '../external/vscode-observables/observables/dist/observableInternal/observables/observableFromEvent.js';
+import { buildExplorerUrl } from '../utils.js';
 
 // ---------------------------------------------------------------------------
 // Client-local state
@@ -40,43 +48,141 @@ class WatchList {
         };
     }
 }
+function noDaemonError(hint) {
+    let text = 'Error: No daemon is currently running.';
+    if (hint) {
+        text += ` ${hint}`;
+    }
+    else {
+        text += ' Please start the Component Explorer daemon first by running:\n\n' +
+            '  component-explorer serve --project <config.json>\n\n' +
+            'Or start it in the background:\n\n' +
+            '  component-explorer serve --project <config.json> --background\n\n' +
+            'The daemon manages dev servers and enables fixture screenshots.';
+    }
+    return {
+        content: [{ type: 'text', text }],
+        isError: true,
+    };
+}
+// ---------------------------------------------------------------------------
+// DaemonConnection - wrapper to avoid Proxy issues with observables
+// ---------------------------------------------------------------------------
+class DaemonConnection {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+}
 // ---------------------------------------------------------------------------
 // ComponentExplorerMcpServer
 // ---------------------------------------------------------------------------
-class ComponentExplorerMcpServer {
-    _daemon;
+class ComponentExplorerMcpServer extends Disposable {
+    _daemonConnection;
+    static async create(daemon, options) {
+        const server = new ComponentExplorerMcpServer(daemon, options ?? {});
+        const transport = new StdioServerTransport();
+        await server._mcp.connect(transport);
+        return server;
+    }
     _mcp;
     _watchList = new WatchList();
+    _pollFn;
+    _noAutostartHint;
+    _multiSessionTools = [];
     _sessions = [];
-    constructor(_daemon) {
-        this._daemon = _daemon;
+    _eventStreamAbortController;
+    constructor(_daemonConnection, options) {
+        super();
+        this._daemonConnection = _daemonConnection;
+        this._pollFn = options.pollFn;
+        this._noAutostartHint = options.noAutostartHint;
         this._mcp = new McpServer({
             name: 'component-explorer',
             version: '0.1.0',
         });
         this._registerTools();
+        this._store.add(autorun(async (reader) => {
+            const conn = this._daemonConnection.read(reader);
+            await this._onDaemonChanged(conn?.client);
+        }));
     }
-    async connect() {
-        this._sessions = await this._daemon.methods.sessions();
-        this._startEventListener();
-        const transport = new StdioServerTransport();
-        await this._mcp.connect(transport);
+    async _onDaemonChanged(daemon) {
+        // Cancel any existing event stream
+        this._eventStreamAbortController?.abort();
+        this._eventStreamAbortController = undefined;
+        if (!daemon) {
+            this._sessions = [];
+            this._log('info', { type: 'daemon-disconnected' });
+            return;
+        }
+        // Fetch sessions and start event listener
+        try {
+            this._sessions = await daemon.methods.sessions();
+            this._log('info', { type: 'daemon-connected', sessions: this._sessions.length });
+            this._updateMultiSessionToolVisibility();
+            this._startEventListener(daemon);
+        }
+        catch (e) {
+            this._log('info', { type: 'daemon-error', error: String(e) });
+            this._sessions = [];
+        }
+    }
+    _getDaemon() {
+        return this._daemonConnection.get()?.client;
+    }
+    /**
+     * If no daemon is connected and we have a pollFn, poll immediately and wait
+     * up to 3 seconds for the daemon to become available.
+     */
+    async _waitForDaemon() {
+        let daemon = this._getDaemon();
+        if (daemon || !this._pollFn) {
+            return daemon;
+        }
+        // Poll immediately and wait up to 3 seconds
+        const startTime = Date.now();
+        const timeout = 3000;
+        while (Date.now() - startTime < timeout) {
+            await this._pollFn();
+            daemon = this._getDaemon();
+            if (daemon) {
+                return daemon;
+            }
+            // Wait 200ms before next poll
+            await new Promise(resolve => setTimeout(resolve, 200));
+        }
+        return undefined;
+    }
+    _noDaemonError() {
+        return noDaemonError(this._noAutostartHint);
     }
     _log(level, data) {
         this._mcp.sendLoggingMessage({ level, logger: 'daemon', data }).catch(() => { });
     }
-    async _startEventListener() {
-        const stream = await this._daemon.methods.events();
+    _startEventListener(daemon) {
+        const controller = new AbortController();
+        this._eventStreamAbortController = controller;
         (async () => {
-            for await (const raw of stream) {
-                const event = raw;
-                if (event.type === 'source-change' && event.sessionName && event.sourceTreeId) {
-                    this._updateSessionSourceTreeId(event.sessionName, event.sourceTreeId);
+            try {
+                const stream = await daemon.methods.events();
+                for await (const raw of stream) {
+                    if (controller.signal.aborted)
+                        break;
+                    const event = raw;
+                    if (event.type === 'source-change' && event.sessionName && event.sourceTreeId) {
+                        this._updateSessionSourceTreeId(event.sessionName, event.sourceTreeId);
+                    }
+                    if (event.type === 'ref-change') {
+                        await this._refreshSessions();
+                    }
+                    this._log(event.type === 'log' && event.level === 'debug' ? 'debug' : 'info', event);
                 }
-                if (event.type === 'ref-change') {
-                    await this._refreshSessions();
+            }
+            catch (e) {
+                if (!controller.signal.aborted) {
+                    this._log('info', { type: 'event-stream-error', error: String(e) });
                 }
-                this._log(event.type === 'log' && event.level === 'debug' ? 'debug' : 'info', event);
             }
         })();
     }
@@ -94,7 +200,7 @@ class ComponentExplorerMcpServer {
     }
     _sourceTreeId(sessionName) {
         const s = this._sessions.find(s => s.name === sessionName);
-        return s?.sourceTreeId ?? '';
+        return s && !s.isLoading ? s.sourceTreeId : '';
     }
     _updateSessionSourceTreeId(sessionName, sourceTreeId) {
         const s = this._sessions.find(s => s.name === sessionName);
@@ -103,7 +209,25 @@ class ComponentExplorerMcpServer {
         }
     }
     async _refreshSessions() {
-        this._sessions = await this._daemon.methods.sessions();
+        const daemon = this._getDaemon();
+        if (daemon) {
+            const prevCount = this._sessions.length;
+            this._sessions = await daemon.methods.sessions();
+            if (this._sessions.length !== prevCount) {
+                this._updateMultiSessionToolVisibility();
+            }
+        }
+    }
+    _updateMultiSessionToolVisibility() {
+        const isMultiSession = this._sessions.length > 1;
+        for (const tool of this._multiSessionTools) {
+            if (isMultiSession) {
+                tool.enable();
+            }
+            else {
+                tool.disable();
+            }
+        }
     }
     async _withSourceTreeRetry(fn) {
         try {
@@ -124,12 +248,15 @@ class ComponentExplorerMcpServer {
         this._registerScreenshot();
         this._registerCompareScreenshot();
         this._registerApproveDiff();
+        this._registerEvaluateJs();
+        this._registerDebugReloadPage();
         this._registerWatchAdd();
         this._registerWatchRemove();
         this._registerWatchSet();
         this._registerWatchCompare();
         this._registerWaitForUpdate();
         this._registerSessions();
+        this._registerGetUrl();
     }
     _registerListFixtures() {
         this._mcp.registerTool('list_fixtures', {
@@ -138,11 +265,16 @@ class ComponentExplorerMcpServer {
                 sessionName: z.string().optional().describe('Session name (defaults to first session)'),
                 sourceTreeId: z.string().optional().describe('Source tree ID (defaults to latest known)'),
             },
+            annotations: { readOnlyHint: true },
         }, async (args) => {
+            const daemon = await this._waitForDaemon();
+            if (!daemon) {
+                return this._noDaemonError();
+            }
             const sessionName = args.sessionName ?? this._defaultSessionName();
             return this._withSourceTreeRetry(async () => {
                 const sourceTreeId = args.sourceTreeId ?? this._sourceTreeId(sessionName);
-                const fixtures = await this._daemon.methods.fixtures.list({ sessionName, sourceTreeId });
+                const fixtures = await daemon.methods.fixtures.list({ sessionName, sourceTreeId });
                 return {
                     content: [{ type: 'text', text: JSON.stringify(fixtures, null, 2) }],
                 };
@@ -151,21 +283,29 @@ class ComponentExplorerMcpServer {
     }
     _registerScreenshot() {
         this._mcp.registerTool('screenshot', {
-            description: 'Take a screenshot of a single fixture',
+            description: 'Take a screenshot of a single fixture. ' +
+                'When stabilityCheck is true, the fixture is unmounted and re-mounted, then three screenshots are taken. ',
             inputSchema: {
                 fixtureId: z.string().describe('The fixture ID'),
                 sessionName: z.string().optional().describe('Session name (defaults to first session)'),
                 sourceTreeId: z.string().optional().describe('Source tree ID (defaults to latest known)'),
+                stabilityCheck: z.boolean().optional().describe('If true, takes three screenshots (at render time, ~500ms, ~3000ms) to check visual stability. Expensive (~3s extra) — only use it when you need to verify rendering stability..'),
             },
+            annotations: { readOnlyHint: true },
         }, async (args) => {
+            const daemon = await this._waitForDaemon();
+            if (!daemon) {
+                return this._noDaemonError();
+            }
             const sessionName = args.sessionName ?? this._defaultSessionName();
             return this._withSourceTreeRetry(async () => {
                 const sourceTreeId = args.sourceTreeId ?? this._sourceTreeId(sessionName);
-                const result = await this._daemon.methods.screenshots.take({
+                const result = await daemon.methods.screenshots.take({
                     fixtureId: args.fixtureId,
                     sessionName,
                     sourceTreeId,
                     includeImage: true,
+                    stabilityCheck: args.stabilityCheck,
                 });
                 const r = result;
                 this._updateSessionSourceTreeId(sessionName, r.sourceTreeId);
@@ -176,18 +316,34 @@ class ComponentExplorerMcpServer {
                 if (r.errors && r.errors.length > 0) {
                     info.errors = r.errors;
                 }
-                const content = [
-                    { type: 'text', text: JSON.stringify(info, null, 2) },
-                ];
-                if (r.image) {
+                if (r.isStable !== undefined) {
+                    info.isStable = r.isStable;
+                }
+                const content = [];
+                if (r.isStable === false && r.stabilityScreenshots) {
+                    // Not stable: return all distinct screenshots
+                    const seenHashes = new Set();
+                    const screenshotDetails = [];
+                    for (const s of r.stabilityScreenshots) {
+                        screenshotDetails.push({ hash: s.hash, delayMs: s.delayMs });
+                        if (!seenHashes.has(s.hash) && s.image) {
+                            seenHashes.add(s.hash);
+                            content.push({ type: 'image', data: s.image, mimeType: 'image/png' });
+                        }
+                    }
+                    info.stabilityScreenshots = screenshotDetails;
+                }
+                else if (r.image) {
+                    // Stable or no stability check: return single image
                     content.push({ type: 'image', data: r.image, mimeType: 'image/png' });
                 }
+                content.unshift({ type: 'text', text: JSON.stringify(info, null, 2) });
                 return { content };
             });
         });
     }
     _registerCompareScreenshot() {
-        this._mcp.registerTool('compare_screenshot', {
+        const tool = this._mcp.registerTool('compare_screenshot', {
             description: 'Compare a fixture\'s screenshot across two sessions (e.g. baseline vs current)',
             inputSchema: {
                 fixtureId: z.string().describe('The fixture ID'),
@@ -196,13 +352,18 @@ class ComponentExplorerMcpServer {
                 baselineSourceTreeId: z.string().optional().describe('Baseline source tree ID (defaults to latest known)'),
                 currentSourceTreeId: z.string().optional().describe('Current source tree ID (defaults to latest known)'),
             },
+            annotations: { readOnlyHint: true },
         }, async (args) => {
+            const daemon = await this._waitForDaemon();
+            if (!daemon) {
+                return this._noDaemonError();
+            }
             const baselineSessionName = args.baselineSessionName ?? this._defaultBaselineSessionName();
             const currentSessionName = args.currentSessionName ?? this._defaultCurrentSessionName();
             return this._withSourceTreeRetry(async () => {
                 const baselineSourceTreeId = args.baselineSourceTreeId ?? this._sourceTreeId(baselineSessionName);
                 const currentSourceTreeId = args.currentSourceTreeId ?? this._sourceTreeId(currentSessionName);
-                const result = await this._daemon.methods.screenshots.compare({
+                const result = await daemon.methods.screenshots.compare({
                     fixtureId: args.fixtureId,
                     baselineSessionName,
                     baselineSourceTreeId,
@@ -237,9 +398,11 @@ class ComponentExplorerMcpServer {
                 return { content };
             });
         });
+        tool.disable();
+        this._multiSessionTools.push(tool);
     }
     _registerApproveDiff() {
-        this._mcp.registerTool('approve_diff', {
+        const tool = this._mcp.registerTool('approve_diff', {
             description: 'Approve a visual diff so it won\'t require re-inspection next time',
             inputSchema: {
                 fixtureId: z.string(),
@@ -248,7 +411,11 @@ class ComponentExplorerMcpServer {
                 comment: z.string().describe('Reason for approving this diff'),
             },
         }, async (args) => {
-            await this._daemon.methods.approvals.approve(args);
+            const daemon = await this._waitForDaemon();
+            if (!daemon) {
+                return this._noDaemonError();
+            }
+            await daemon.methods.approvals.approve(args);
             return {
                 content: [{
                         type: 'text',
@@ -256,6 +423,74 @@ class ComponentExplorerMcpServer {
                     }],
             };
         });
+        tool.disable();
+        this._multiSessionTools.push(tool);
+    }
+    _registerEvaluateJs() {
+        this._mcp.registerTool('evaluate_js', {
+            description: 'Evaluate a JavaScript expression in the browser page where fixtures are rendered, for debugging purposes. ' +
+                'Returns the expression result as JSON. The expression can return a Promise (it will be awaited). ' +
+                'Use this to inspect DOM state, computed styles, element dimensions, or component output. ' +
+                'Do NOT use this to modify the DOM — this tool is for read-only inspection and debugging only.',
+            inputSchema: {
+                expression: z.string().describe('JavaScript expression to evaluate. Can return a Promise. The result must be JSON-serializable.'),
+                fixtureId: z.string().optional().describe('If provided, renders this fixture before evaluating the expression'),
+                sessionName: z.string().optional().describe('Session name (defaults to first session)'),
+                sourceTreeId: z.string().optional().describe('Source tree ID (defaults to latest known)'),
+            },
+        }, async (args) => {
+            const daemon = await this._waitForDaemon();
+            if (!daemon) {
+                return this._noDaemonError();
+            }
+            const sessionName = args.sessionName ?? this._defaultSessionName();
+            return this._withSourceTreeRetry(async () => {
+                const sourceTreeId = args.sourceTreeId ?? this._sourceTreeId(sessionName);
+                const result = await daemon.methods.evaluate({
+                    sessionName,
+                    sourceTreeId,
+                    expression: args.expression,
+                    fixtureId: args.fixtureId,
+                });
+                const r = result;
+                let text;
+                try {
+                    text = JSON.stringify(r.result, null, 2) ?? 'undefined';
+                }
+                catch {
+                    text = String(r.result);
+                }
+                return {
+                    content: [{ type: 'text', text }],
+                };
+            });
+        });
+    }
+    _registerDebugReloadPage() {
+        this._mcp.registerTool('debug_reload_page', {
+            description: 'Force-reload the browser page used for rendering fixtures. ' +
+                'Only use this as a last resort if screenshots or evaluate_js return stale/broken results ' +
+                'that persist after source changes. Normal HMR updates should handle most cases automatically.',
+            inputSchema: {
+                sessionName: z.string().optional().describe('Session name (defaults to first session)'),
+            },
+            annotations: { destructiveHint: true },
+        }, async (args) => {
+            const daemon = await this._waitForDaemon();
+            if (!daemon) {
+                return this._noDaemonError();
+            }
+            const sessionName = args.sessionName ?? this._defaultSessionName();
+            const sourceTreeId = this._sourceTreeId(sessionName);
+            await daemon.methods.evaluate({
+                sessionName,
+                sourceTreeId,
+                expression: 'location.reload()',
+            });
+            return {
+                content: [{ type: 'text', text: `Reloaded page for session '${sessionName}'.` }],
+            };
+        });
     }
     _registerWatchAdd() {
         this._mcp.registerTool('watch_add', {
@@ -306,7 +541,7 @@ class ComponentExplorerMcpServer {
         });
     }
     _registerWatchCompare() {
-        this._mcp.registerTool('watch_compare', {
+        const tool = this._mcp.registerTool('watch_compare', {
             description: 'Compare all watched fixtures across two sessions. Takes fresh screenshots from both sessions and reports which fixtures differ.',
             inputSchema: {
                 baselineSessionName: z.string().optional().describe('Baseline session name (defaults to worktree session)'),
@@ -314,7 +549,12 @@ class ComponentExplorerMcpServer {
                 baselineSourceTreeId: z.string().optional().describe('Baseline source tree ID (defaults to latest known)'),
                 currentSourceTreeId: z.string().optional().describe('Current source tree ID (defaults to latest known)'),
             },
+            annotations: { readOnlyHint: true },
         }, async (args) => {
+            const daemon = await this._waitForDaemon();
+            if (!daemon) {
+                return this._noDaemonError();
+            }
             const ids = [...this._watchList.fixtureIds];
             if (ids.length === 0) {
                 return { content: [{ type: 'text', text: 'Watch list is empty. Use watch_add or watch_set first.' }] };
@@ -325,12 +565,12 @@ class ComponentExplorerMcpServer {
                 const baselineSourceTreeId = args.baselineSourceTreeId ?? this._sourceTreeId(baselineSessionName);
                 const currentSourceTreeId = args.currentSourceTreeId ?? this._sourceTreeId(currentSessionName);
                 const [baselineResult, currentResult] = await Promise.all([
-                    this._daemon.methods.screenshots.takeBatch({
+                    daemon.methods.screenshots.takeBatch({
                         fixtureIds: ids,
                         sessionName: baselineSessionName,
                         sourceTreeId: baselineSourceTreeId,
                     }),
-                    this._daemon.methods.screenshots.takeBatch({
+                    daemon.methods.screenshots.takeBatch({
                         fixtureIds: ids,
                         sessionName: currentSessionName,
                         sourceTreeId: currentSourceTreeId,
@@ -355,7 +595,7 @@ class ComponentExplorerMcpServer {
                 for (const entry of entries) {
                     let approval = undefined;
                     if (!entry.match && entry.baselineHash && entry.currentHash) {
-                        approval = await this._daemon.methods.approvals.lookup({
+                        approval = await daemon.methods.approvals.lookup({
                             fixtureId: entry.fixtureId,
                             originalHash: entry.baselineHash,
                             modifiedHash: entry.currentHash,
@@ -368,72 +608,187 @@ class ComponentExplorerMcpServer {
                 };
             });
         });
+        tool.disable();
+        this._multiSessionTools.push(tool);
     }
     _registerWaitForUpdate() {
         this._mcp.registerTool('wait_for_update', {
-            description: 'Block until the next source change or ref change event. If fixtures are on the watch list, automatically re-screenshots them and reports which changed.',
-        }, async () => {
-            const events = await this._daemon.methods.events();
-            const iterator = events[Symbol.asyncIterator]();
-            const { value: event, done } = await iterator.next();
-            // Close the stream after consuming one event
-            await iterator.return?.();
-            if (done || !event) {
-                return { content: [{ type: 'text', text: 'Event stream ended.' }] };
-            }
-            const ev = event;
-            // Update cached session info
-            if (ev.type === 'source-change' && ev.sourceTreeId) {
-                this._updateSessionSourceTreeId(ev.sessionName, ev.sourceTreeId);
+            description: 'Block until the source tree changes from the given sourceTreeId. ' +
+                'Pass the sourceTreeId you already observed — resolves immediately if it already differs, ' +
+                'otherwise waits for a source-change or ref-change event. ' +
+                'If fixtures are on the watch list, automatically re-screenshots them and reports which changed.',
+            inputSchema: {
+                sourceTreeId: z.string().describe('The sourceTreeId the client currently knows about. The call resolves once the source tree differs from this value.'),
+                sessionName: z.string().optional().describe('Session name (defaults to first session)'),
+            },
+            annotations: { readOnlyHint: true },
+        }, async (args) => {
+            const daemon = await this._waitForDaemon();
+            if (!daemon) {
+                return this._noDaemonError();
             }
-            if (ev.type === 'ref-change') {
-                await this._refreshSessions();
+            const sessionName = args.sessionName ?? this._defaultSessionName();
+            const knownSourceTreeId = args.sourceTreeId;
+            // Check if already changed
+            const currentSourceTreeId = this._sourceTreeId(sessionName);
+            if (currentSourceTreeId && currentSourceTreeId !== knownSourceTreeId) {
+                return this._waitForUpdateResult(daemon, sessionName, currentSourceTreeId);
             }
-            // If there are watched fixtures and this is a source-change, re-screenshot them
-            const watchedIds = [...this._watchList.fixtureIds];
-            if (ev.type === 'source-change' && watchedIds.length > 0 && ev.sourceTreeId) {
-                const batchResult = await this._daemon.methods.screenshots.takeBatch({
-                    fixtureIds: watchedIds,
-                    sessionName: ev.sessionName,
-                    sourceTreeId: ev.sourceTreeId,
-                });
-                const br = batchResult;
-                const changes = [];
-                for (const s of br.screenshots) {
-                    const prevHash = this._watchList.getHash(s.fixtureId);
-                    const changed = prevHash !== undefined && prevHash !== s.hash;
-                    this._watchList.setHash(s.fixtureId, s.hash);
-                    if (changed) {
-                        changes.push({ fixtureId: s.fixtureId, previousHash: prevHash, hash: s.hash });
+            // Wait for an event that changes the source tree (max 5s)
+            const events = await daemon.methods.events();
+            const iterator = events[Symbol.asyncIterator]();
+            try {
+                const timeout = new Promise(resolve => setTimeout(() => resolve('timeout'), 5000));
+                while (true) {
+                    const next = iterator.next();
+                    const result = await Promise.race([next, timeout]);
+                    if (result === 'timeout') {
+                        return { content: [{ type: 'text', text: JSON.stringify({ timeout: true, sessionName, sourceTreeId: knownSourceTreeId }, null, 2) }] };
+                    }
+                    const { value: event, done } = result;
+                    if (done || !event) {
+                        return { content: [{ type: 'text', text: 'Event stream ended.' }] };
+                    }
+                    const ev = event;
+                    if (ev.type === 'source-change' && ev.sourceTreeId) {
+                        this._updateSessionSourceTreeId(ev.sessionName, ev.sourceTreeId);
+                    }
+                    if (ev.type === 'ref-change') {
+                        await this._refreshSessions();
+                    }
+                    const newSourceTreeId = this._sourceTreeId(sessionName);
+                    if (newSourceTreeId && newSourceTreeId !== knownSourceTreeId) {
+                        return this._waitForUpdateResult(daemon, sessionName, newSourceTreeId);
                     }
                 }
-                return {
-                    content: [{
-                            type: 'text',
-                            text: JSON.stringify({
-                                event: ev,
-                                watchedFixtures: br.screenshots.length,
-                                changed: changes,
-                            }, null, 2),
-                        }],
-                };
+            }
+            finally {
+                await iterator.return?.();
+            }
+        });
+    }
+    async _waitForUpdateResult(daemon, sessionName, sourceTreeId) {
+        const watchedIds = [...this._watchList.fixtureIds];
+        if (watchedIds.length > 0) {
+            const batchResult = await daemon.methods.screenshots.takeBatch({
+                fixtureIds: watchedIds,
+                sessionName,
+                sourceTreeId,
+            });
+            const br = batchResult;
+            const changes = [];
+            for (const s of br.screenshots) {
+                const prevHash = this._watchList.getHash(s.fixtureId);
+                const changed = prevHash !== undefined && prevHash !== s.hash;
+                this._watchList.setHash(s.fixtureId, s.hash);
+                if (changed) {
+                    changes.push({ fixtureId: s.fixtureId, previousHash: prevHash, hash: s.hash });
+                }
             }
             return {
-                content: [{ type: 'text', text: JSON.stringify(ev, null, 2) }],
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            sourceTreeId,
+                            sessionName,
+                            watchedFixtures: br.screenshots.length,
+                            changed: changes,
+                        }, null, 2),
+                    }],
             };
-        });
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ sourceTreeId, sessionName }, null, 2),
+                }],
+        };
     }
     _registerSessions() {
         this._mcp.registerTool('sessions', {
             description: 'List active sessions with their names, URLs, and current sourceTreeIds',
+            annotations: { readOnlyHint: true },
         }, async () => {
+            const daemon = await this._waitForDaemon();
+            if (!daemon) {
+                return this._noDaemonError();
+            }
             await this._refreshSessions();
             return {
                 content: [{ type: 'text', text: JSON.stringify(this._sessions, null, 2) }],
             };
         });
     }
+    _registerGetUrl() {
+        this._mcp.registerTool('get_url', {
+            description: 'Get URL(s) for viewing fixtures. Returns the Component Explorer UI URL by default, ' +
+                'or the raw render URL for embedding/screenshots when useRawDirectRenderingWithoutExplorerUi is true.',
+            inputSchema: {
+                sessionName: z.string().optional().describe('Session name (defaults to first session)'),
+                fixtureId: z.string().optional().describe('Specific fixture ID. If omitted, returns URL for the explorer root or all fixtures.'),
+                useRawDirectRenderingWithoutExplorerUi: z.boolean().optional().describe('If true, returns the raw rendering URL (for embedding or screenshots) instead of the Explorer UI URL. ' +
+                    'The raw URL renders only the fixture without the explorer chrome. Default: false.'),
+            },
+            annotations: { readOnlyHint: true },
+        }, async (args) => {
+            const sessionName = args.sessionName ?? this._defaultSessionName();
+            const session = this._sessions.find(s => s.name === sessionName);
+            if (!session) {
+                // Try to refresh sessions if we don't have the requested session
+                const daemon = await this._waitForDaemon();
+                if (daemon) {
+                    await this._refreshSessions();
+                }
+                const refreshedSession = this._sessions.find(s => s.name === sessionName);
+                if (!refreshedSession) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `Error: Session '${sessionName}' not found. Available sessions: ${this._sessions.map(s => s.name).join(', ') || '(none)'}`,
+                            }],
+                        isError: true,
+                    };
+                }
+            }
+            const resolved = session ?? this._sessions.find(s => s.name === sessionName);
+            const baseUrl = resolved && !resolved.isLoading ? resolved.serverUrl : undefined;
+            if (!baseUrl) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Error: Session '${sessionName}' is still loading.`,
+                        }],
+                    isError: true,
+                };
+            }
+            const useRaw = args.useRawDirectRenderingWithoutExplorerUi ?? false;
+            const url = buildExplorerUrl({
+                baseUrl,
+                rawRender: useRaw,
+                fixtureId: args.fixtureId,
+            });
+            const result = {
+                url,
+                sessionName,
+            };
+            if (args.fixtureId) {
+                result.fixtureId = args.fixtureId;
+            }
+            if (useRaw) {
+                result.mode = 'raw-render';
+            }
+            else {
+                result.mode = 'explorer';
+                if (args.fixtureId) {
+                    result.note = 'Fixture selection in the Explorer UI is not URL-based. Navigate to the fixture manually in the tree view.';
+                }
+            }
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        });
+    }
 }
 
-export { ComponentExplorerMcpServer };
+export { ComponentExplorerMcpServer, DaemonConnection };
 //# sourceMappingURL=McpServer.js.map