@theupsider/lsp-mcp 0.1.0

package/dist/lsp/lsp-client.js

@@ -0,0 +1,226 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LspClient = void 0;
+const node_events_1 = require("node:events");
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = __importDefault(require("node:path"));
+const uri_1 = require("../utils/uri");
+class LspClient extends node_events_1.EventEmitter {
+    serverDef;
+    projectRoot;
+    logLevel;
+    process = null;
+    nextRequestId = 1;
+    ready = false;
+    pendingRequests = new Map();
+    buffer = Buffer.alloc(0);
+    contentLength = null;
+    exitExpected = false;
+    initializeResult = null;
+    forcedKillTimer = null;
+    constructor(serverDef, projectRoot, logLevel) {
+        super();
+        this.serverDef = serverDef;
+        this.projectRoot = projectRoot;
+        this.logLevel = logLevel;
+    }
+    async start() {
+        if (this.process) {
+            return;
+        }
+        this.process = (0, node_child_process_1.spawn)(this.serverDef.cmd, this.serverDef.args, {
+            cwd: this.projectRoot,
+            env: { ...process.env },
+            stdio: 'pipe'
+        });
+        this.process.stdout.on('data', (chunk) => {
+            this.handleData(chunk);
+        });
+        this.process.on('error', (error) => {
+            this.log('error', 'lsp_process_error', { error: error.message });
+            this.emit('error', error);
+        });
+        this.process.on('exit', (code, signal) => {
+            this.handleExit(code, signal);
+        });
+        this.log('info', 'lsp_starting', { language: this.serverDef.cmd });
+        const initializeResult = await this.request('initialize', {
+            processId: process.pid,
+            clientInfo: { name: 'lsp-mcp', version: '0.1.0' },
+            rootUri: (0, uri_1.pathToUri)(this.projectRoot),
+            workspaceFolders: [
+                {
+                    uri: (0, uri_1.pathToUri)(this.projectRoot),
+                    name: node_path_1.default.basename(this.projectRoot)
+                }
+            ],
+            capabilities: {}
+        }, 30000);
+        this.initializeResult = initializeResult;
+        this.notify('initialized', {});
+        this.ready = true;
+        this.log('info', 'lsp_ready', { language: this.serverDef.cmd });
+    }
+    isReady() {
+        return this.ready;
+    }
+    async request(method, params, timeout) {
+        const id = this.nextRequestId;
+        this.nextRequestId += 1;
+        const message = {
+            jsonrpc: '2.0',
+            id,
+            method,
+            params
+        };
+        return await new Promise((resolve, reject) => {
+            const timeoutHandle = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new Error(`LSP request timed out: ${method}`));
+            }, timeout);
+            this.pendingRequests.set(id, {
+                resolve: (value) => resolve(value),
+                reject,
+                timeoutHandle
+            });
+            this.sendMessage(message);
+        });
+    }
+    notify(method, params) {
+        const message = {
+            jsonrpc: '2.0',
+            method,
+            params
+        };
+        this.sendMessage(message);
+    }
+    async shutdown() {
+        this.exitExpected = true;
+        if (!this.process) {
+            this.ready = false;
+            return;
+        }
+        await this.request('shutdown', {}, 5000);
+        this.notify('exit', {});
+        this.ready = false;
+        const currentProcess = this.process;
+        this.forcedKillTimer = setTimeout(() => {
+            currentProcess.kill('SIGKILL');
+        }, 5000);
+    }
+    getCapabilities() {
+        return this.initializeResult?.capabilities ?? null;
+    }
+    sendMessage(message) {
+        if (!this.process) {
+            throw new Error('LSP process is not running');
+        }
+        const body = JSON.stringify(message);
+        const content = `Content-Length: ${Buffer.byteLength(body, 'utf8')}\r\n\r\n${body}`;
+        this.process.stdin.write(content);
+    }
+    handleData(chunk) {
+        const incoming = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+        this.buffer = Buffer.concat([this.buffer, incoming]);
+        while (true) {
+            if (this.contentLength === null) {
+                const headerEnd = this.buffer.indexOf('\r\n\r\n');
+                if (headerEnd === -1) {
+                    return;
+                }
+                const header = this.buffer.subarray(0, headerEnd).toString('utf8');
+                this.buffer = this.buffer.subarray(headerEnd + 4);
+                const contentLengthLine = header
+                    .split('\r\n')
+                    .find((line) => line.toLowerCase().startsWith('content-length:'));
+                if (!contentLengthLine) {
+                    const error = new Error('Missing Content-Length header');
+                    this.emit('error', error);
+                    return;
+                }
+                const value = Number.parseInt(contentLengthLine.slice('Content-Length:'.length).trim(), 10);
+                this.contentLength = value;
+            }
+            if (this.buffer.byteLength < this.contentLength) {
+                return;
+            }
+            const messageBody = this.buffer.subarray(0, this.contentLength).toString('utf8');
+            this.buffer = this.buffer.subarray(this.contentLength);
+            this.contentLength = null;
+            this.handleMessage(JSON.parse(messageBody));
+        }
+    }
+    handleMessage(message) {
+        if (!message || typeof message !== 'object') {
+            return;
+        }
+        if ('method' in message) {
+            this.emit('notification', message.method, message.params);
+            return;
+        }
+        if ('id' in message && 'error' in message && message.id !== null) {
+            const pending = this.pendingRequests.get(message.id);
+            if (!pending) {
+                return;
+            }
+            clearTimeout(pending.timeoutHandle);
+            this.pendingRequests.delete(message.id);
+            pending.reject(new Error(message.error.message));
+            return;
+        }
+        if ('id' in message && 'result' in message) {
+            const pending = this.pendingRequests.get(message.id);
+            if (!pending) {
+                return;
+            }
+            clearTimeout(pending.timeoutHandle);
+            this.pendingRequests.delete(message.id);
+            pending.resolve(message.result);
+        }
+    }
+    handleExit(code, signal) {
+        if (this.forcedKillTimer) {
+            clearTimeout(this.forcedKillTimer);
+            this.forcedKillTimer = null;
+        }
+        this.rejectAllPending(new Error(`LSP server exited (code: ${code ?? 'null'}, signal: ${signal ?? 'null'})`));
+        this.ready = false;
+        this.process = null;
+        if (!this.exitExpected) {
+            const error = new Error(`LSP server exited unexpectedly (code: ${code ?? 'null'}, signal: ${signal ?? 'null'})`);
+            this.log('error', 'lsp_crash', { error: error.message, language: this.serverDef.cmd });
+            this.emit('crash', error);
+        }
+    }
+    rejectAllPending(error) {
+        for (const [id, pending] of this.pendingRequests.entries()) {
+            clearTimeout(pending.timeoutHandle);
+            pending.reject(error);
+            this.pendingRequests.delete(id);
+        }
+    }
+    log(level, event, extra) {
+        if (!shouldLog(this.logLevel, level)) {
+            return;
+        }
+        const payload = {
+            timestamp: new Date().toISOString(),
+            level,
+            event,
+            ...extra
+        };
+        process.stderr.write(`${JSON.stringify(payload)}\n`);
+    }
+}
+exports.LspClient = LspClient;
+function shouldLog(configuredLevel, messageLevel) {
+    const order = {
+        error: 0,
+        info: 1,
+        debug: 2
+    };
+    return order[messageLevel] <= order[configuredLevel];
+}

package/dist/mcp/__tests__/formatters.test.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const formatters_1 = require("../formatters");
+describe('mcp formatters', () => {
+    it('formats hover results as markdown summary plus code block', () => {
+        expect((0, formatters_1.formatHover)({
+            contents: {
+                kind: 'markdown',
+                value: '```ts\ntype Foo = string\n```\n\nFoo description'
+            }
+        })).toBe('**type Foo = string** — Foo description\n\n```ts\ntype Foo = string\n```');
+    });
+    it('formats definition locations with file coordinates', () => {
+        expect((0, formatters_1.formatDefinition)([
+            {
+                uri: 'file:///workspace/src/index.ts',
+                range: {
+                    start: { line: 41, character: 4 },
+                    end: { line: 41, character: 7 }
+                }
+            }
+        ])).toBe('Found 1 definition: `/workspace/src/index.ts:42:5`');
+    });
+    it('formats references as a bulleted list', () => {
+        expect((0, formatters_1.formatReferences)([
+            {
+                uri: 'file:///workspace/src/index.ts',
+                range: {
+                    start: { line: 0, character: 0 },
+                    end: { line: 0, character: 1 }
+                }
+            },
+            {
+                uri: 'file:///workspace/src/lib.ts',
+                range: {
+                    start: { line: 2, character: 3 },
+                    end: { line: 2, character: 4 }
+                }
+            }
+        ])).toBe('Found 2 references:\n- `/workspace/src/index.ts:1:1`\n- `/workspace/src/lib.ts:3:4`');
+    });
+    it('formats symbols with kind icons', () => {
+        expect((0, formatters_1.formatSymbols)([
+            {
+                name: 'UserService',
+                kind: 5,
+                location: {
+                    uri: 'file:///workspace/src/user-service.ts',
+                    range: {
+                        start: { line: 4, character: 0 },
+                        end: { line: 10, character: 0 }
+                    }
+                }
+            },
+            {
+                name: 'login',
+                kind: 12,
+                location: {
+                    uri: 'file:///workspace/src/user-service.ts',
+                    range: {
+                        start: { line: 6, character: 2 },
+                        end: { line: 8, character: 0 }
+                    }
+                }
+            }
+        ])).toContain('- 📦 `UserService` — /workspace/src/user-service.ts:5:1');
+    });
+    it('formats diagnostics grouped by severity with errors first', () => {
+        expect((0, formatters_1.formatDiagnostics)([
+            {
+                message: 'Cannot find name Foo',
+                severity: 1,
+                source: 'ts',
+                range: {
+                    start: { line: 1, character: 0 },
+                    end: { line: 1, character: 3 }
+                },
+                uri: 'file:///workspace/src/index.ts'
+            },
+            {
+                message: 'Unused variable',
+                severity: 2,
+                source: 'ts',
+                range: {
+                    start: { line: 3, character: 2 },
+                    end: { line: 3, character: 5 }
+                },
+                uri: 'file:///workspace/src/index.ts'
+            }
+        ], 'workspace')).toBe([
+            'Workspace diagnostics: 2 issue(s)',
+            '',
+            '### Errors',
+            '- `/workspace/src/index.ts:2:1` ts: Cannot find name Foo',
+            '',
+            '### Warnings',
+            '- `/workspace/src/index.ts:4:3` ts: Unused variable'
+        ].join('\n'));
+    });
+    it('formats completion items grouped by kind and limited to 50', () => {
+        const items = Array.from({ length: 55 }, (_, index) => ({
+            label: `item-${index}`,
+            kind: index < 30 ? 3 : 2,
+            detail: index === 0 ? 'string' : undefined
+        }));
+        const text = (0, formatters_1.formatCompletion)(items);
+        expect(text).toContain('Showing 50 of 55 completion item(s)');
+        expect(text).toContain('### Functions');
+        expect(text).toContain('- `item-0` — string');
+        expect(text).toContain('### Methods');
+        expect(text).not.toContain('item-54');
+    });
+    it('formats health rows as a markdown table', () => {
+        expect((0, formatters_1.formatHealth)([
+            { language: 'typescript', status: 'ready' },
+            { language: 'python', status: 'error', error: 'spawn failed' }
+        ])).toBe([
+            '| Language | Status | Error |',
+            '| --- | --- | --- |',
+            '| typescript | ready |  |',
+            '| python | error | spawn failed |'
+        ].join('\n'));
+    });
+    it('formats errors with raw payload passthrough', () => {
+        expect((0, formatters_1.formatError)(new Error('boom'))).toEqual({
+            error: true,
+            text: 'boom',
+            raw: expect.any(Error)
+        });
+    });
+    it('returns no result for empty formatter inputs', () => {
+        expect((0, formatters_1.formatHover)(null)).toBe('No result');
+        expect((0, formatters_1.formatDefinition)(null)).toBe('No result');
+        expect((0, formatters_1.formatReferences)([])).toBe('No result');
+        expect((0, formatters_1.formatSymbols)(null)).toBe('No result');
+        expect((0, formatters_1.formatDiagnostics)([], 'file')).toBe('No result');
+        expect((0, formatters_1.formatCompletion)(null)).toBe('No result');
+        expect((0, formatters_1.formatHealth)([])).toBe('No result');
+    });
+    it('formats multi-definition and string hover fallbacks', () => {
+        expect((0, formatters_1.formatHover)({ contents: 'Plain hover text' })).toBe('Plain hover text');
+        expect((0, formatters_1.formatDefinition)([
+            {
+                uri: 'file:///workspace/src/a.ts',
+                range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } }
+            },
+            {
+                uri: 'file:///workspace/src/b.ts',
+                range: { start: { line: 1, character: 1 }, end: { line: 1, character: 2 } }
+            }
+        ])).toContain('Found definitions:');
+    });
+});

package/dist/mcp/__tests__/read-tools.test.js

@@ -0,0 +1,281 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const promises_1 = require("node:fs/promises");
+const read_tools_1 = require("../tools/read-tools");
+const vscode_languageserver_protocol_1 = require("vscode-languageserver-protocol");
+jest.mock('node:fs/promises', () => ({
+    readFile: jest.fn(),
+    stat: jest.fn()
+}));
+class FakeRegistrar {
+    tools = new Map();
+    registerTool(name, config, handler) {
+        this.tools.set(name, { description: config.description, handler });
+    }
+}
+describe('registerReadTools', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+        promises_1.readFile.mockResolvedValue('const foo = 1;');
+        promises_1.stat.mockResolvedValue({ isDirectory: () => true });
+    });
+    it('initializes LSP with a valid root and reports health', async () => {
+        const registrar = new FakeRegistrar();
+        const initializeManager = jest.fn().mockResolvedValue({
+            root: '/workspace',
+            health: [
+                { language: 'typescript', status: 'ready' },
+                { language: 'python', status: 'error', error: 'missing pylsp' }
+            ]
+        });
+        (0, read_tools_1.registerReadTools)(registrar, createLifecycle({ fileClient: null }), { initializeManager });
+        await expect(getHandler(registrar, 'lsp_init')({ root: '/workspace' })).resolves.toEqual({
+            content: [{ type: 'text', text: 'Initialized LSP for /workspace. Detected languages: Typescript, Python. LSP servers: 1 started, 1 errors.' }],
+            text: 'Initialized LSP for /workspace. Detected languages: Typescript, Python. LSP servers: 1 started, 1 errors.',
+            raw: {
+                root: '/workspace',
+                languages: ['Typescript', 'Python'],
+                health: [
+                    { language: 'typescript', status: 'ready' },
+                    { language: 'python', status: 'error', error: 'missing pylsp' }
+                ]
+            }
+        });
+        expect(initializeManager).toHaveBeenCalledWith('/workspace', undefined);
+    });
+    it('rejects invalid lsp_init roots clearly', async () => {
+        const registrar = new FakeRegistrar();
+        const initializeManager = jest.fn();
+        promises_1.stat.mockRejectedValueOnce(new Error('ENOENT'));
+        (0, read_tools_1.registerReadTools)(registrar, createLifecycle({ fileClient: null }), { initializeManager });
+        await expect(getHandler(registrar, 'lsp_init')({ root: '/missing/project' })).resolves.toEqual({
+            content: [{ type: 'text', text: 'Project root does not exist: /missing/project' }],
+            error: true,
+            raw: null
+        });
+        expect(initializeManager).not.toHaveBeenCalled();
+    });
+    it('rejects missing, relative, and non-directory lsp_init roots', async () => {
+        const registrar = new FakeRegistrar();
+        const initializeManager = jest.fn();
+        (0, read_tools_1.registerReadTools)(registrar, createLifecycle({ fileClient: null }), { initializeManager });
+        await expect(getHandler(registrar, 'lsp_init')({})).resolves.toEqual({
+            content: [{ type: 'text', text: 'Project root is required. Provide lsp_init({ root: \'/absolute/path\' }).' }],
+            error: true,
+            raw: null
+        });
+        await expect(getHandler(registrar, 'lsp_init')({ root: 'relative/path' })).resolves.toEqual({
+            content: [{ type: 'text', text: 'Project root must be an absolute path: relative/path' }],
+            error: true,
+            raw: null
+        });
+        promises_1.stat.mockResolvedValueOnce({ isDirectory: () => false });
+        await expect(getHandler(registrar, 'lsp_init')({ root: '/workspace/file.ts' })).resolves.toEqual({
+            content: [{ type: 'text', text: 'Project root is not a directory: /workspace/file.ts' }],
+            error: true,
+            raw: null
+        });
+        expect(initializeManager).not.toHaveBeenCalled();
+    });
+    it('maps lsp_init startup failures into tool errors', async () => {
+        const registrar = new FakeRegistrar();
+        const initializeManager = jest.fn().mockRejectedValue(new Error('Lifecycle start timed out'));
+        (0, read_tools_1.registerReadTools)(registrar, createLifecycle({ fileClient: null }), { initializeManager });
+        await expect(getHandler(registrar, 'lsp_init')({ root: '/workspace' })).resolves.toEqual({
+            content: [{ type: 'text', text: 'Operation timed out after 30s — try a more specific query or check the LSP server health' }],
+            error: true,
+            raw: null
+        });
+    });
+    it('sends didOpen once and returns formatted hover results', async () => {
+        const registrar = new FakeRegistrar();
+        const client = createClient({ contents: 'hover docs' });
+        const lifecycle = createLifecycle({ fileClient: client });
+        (0, read_tools_1.registerReadTools)(registrar, lifecycle, { initializeManager: jest.fn() });
+        const hover = await getHandler(registrar, 'lsp_hover')({ file: '/workspace/src/index.ts', line: 2, character: 4 });
+        await getHandler(registrar, 'lsp_hover')({ file: '/workspace/src/index.ts', line: 2, character: 4 });
+        expect(promises_1.readFile).toHaveBeenCalledTimes(1);
+        expect(client.notify).toHaveBeenCalledWith('textDocument/didOpen', expect.objectContaining({
+            textDocument: expect.objectContaining({ uri: 'file:///workspace/src/index.ts', text: 'const foo = 1;' })
+        }));
+        expect(client.request).toHaveBeenCalledWith('textDocument/hover', {
+            textDocument: { uri: 'file:///workspace/src/index.ts' },
+            position: { line: 2, character: 4 }
+        }, 5000);
+        expect(hover).toEqual({
+            content: [{ type: 'text', text: 'hover docs' }],
+            raw: { contents: 'hover docs' }
+        });
+    });
+    it('formats definitions and converts URIs back to paths', async () => {
+        const registrar = new FakeRegistrar();
+        const lifecycle = createLifecycle({
+            fileClient: createClient([
+                {
+                    uri: 'file:///workspace/src/defs.ts',
+                    range: { start: { line: 3, character: 1 }, end: { line: 3, character: 2 } }
+                }
+            ])
+        });
+        (0, read_tools_1.registerReadTools)(registrar, lifecycle, { initializeManager: jest.fn() });
+        await expect(getHandler(registrar, 'lsp_definition')({ file: '/workspace/src/index.ts', line: 1, character: 1 })).resolves.toEqual({
+            content: [{ type: 'text', text: 'Found 1 definition: `/workspace/src/defs.ts:4:2`' }],
+            raw: [
+                {
+                    path: '/workspace/src/defs.ts',
+                    range: { start: { line: 3, character: 1 }, end: { line: 3, character: 2 } }
+                }
+            ]
+        });
+    });
+    it('uses the declaration flag when requesting references', async () => {
+        const registrar = new FakeRegistrar();
+        const client = createClient([]);
+        (0, read_tools_1.registerReadTools)(registrar, createLifecycle({ fileClient: client }), { initializeManager: jest.fn() });
+        await getHandler(registrar, 'lsp_references')({ file: '/workspace/src/index.ts', line: 0, character: 0, includeDeclaration: true });
+        expect(client.request).toHaveBeenCalledWith('textDocument/references', {
+            textDocument: { uri: 'file:///workspace/src/index.ts' },
+            position: { line: 0, character: 0 },
+            context: { includeDeclaration: true }
+        }, 15000);
+    });
+    it('merges workspace symbols across ready clients', async () => {
+        const registrar = new FakeRegistrar();
+        const firstClient = createClient([{ name: 'UserService', kind: 5, location: { uri: 'file:///workspace/src/user.ts', range: { start: { line: 0, character: 0 }, end: { line: 0, character: 4 } } } }]);
+        const secondClient = createClient([{ name: 'login', kind: 12, location: { uri: 'file:///workspace/src/auth.ts', range: { start: { line: 1, character: 0 }, end: { line: 1, character: 3 } } } }]);
+        (0, read_tools_1.registerReadTools)(registrar, createLifecycle({ workspaceClients: [firstClient, secondClient] }), { initializeManager: jest.fn() });
+        const result = await getHandler(registrar, 'lsp_workspace_symbols')({ query: 'log' });
+        expect(firstClient.request).toHaveBeenCalledWith('workspace/symbol', { query: 'log' }, 30000);
+        expect(secondClient.request).toHaveBeenCalledWith('workspace/symbol', { query: 'log' }, 30000);
+        expect(result).toEqual({
+            content: [{ type: 'text', text: expect.stringContaining('UserService') }],
+            raw: [
+                { name: 'UserService', kind: 5, path: '/workspace/src/user.ts', range: { start: { line: 0, character: 0 }, end: { line: 0, character: 4 } } },
+                { name: 'login', kind: 12, path: '/workspace/src/auth.ts', range: { start: { line: 1, character: 0 }, end: { line: 1, character: 3 } } }
+            ]
+        });
+    });
+    it('returns cached file diagnostics and aggregates workspace diagnostics', async () => {
+        const registrar = new FakeRegistrar();
+        const diagnostics = [{ uri: 'file:///workspace/src/index.ts', message: 'Boom', severity: vscode_languageserver_protocol_1.DiagnosticSeverity.Error, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }];
+        (0, read_tools_1.registerReadTools)(registrar, createLifecycle({ diagnostics, workspaceClients: [createClient([])] }), { initializeManager: jest.fn() });
+        await expect(getHandler(registrar, 'lsp_diagnostics')({ file: '/workspace/src/index.ts' })).resolves.toEqual({
+            content: [{ type: 'text', text: expect.stringContaining('File diagnostics: 1 issue(s)') }],
+            raw: diagnostics
+        });
+        await expect(getHandler(registrar, 'lsp_diagnostics')({ scope: 'workspace' })).resolves.toEqual({
+            content: [{ type: 'text', text: expect.stringContaining('Workspace diagnostics: 1 issue(s)') }],
+            raw: diagnostics
+        });
+    });
+    it('returns health instantly without LSP requests', async () => {
+        const registrar = new FakeRegistrar();
+        const lifecycle = createLifecycle({ health: [{ language: 'typescript', status: 'ready' }] });
+        (0, read_tools_1.registerReadTools)(registrar, lifecycle, { initializeManager: jest.fn() });
+        await expect(getHandler(registrar, 'lsp_health')({})).resolves.toEqual({
+            content: [{ type: 'text', text: '| Language | Status | Error |\n| --- | --- | --- |\n| typescript | ready |  |' }],
+            raw: [{ language: 'typescript', status: 'ready' }]
+        });
+    });
+    it('supports document symbols, completion lists, and signature help fallbacks', async () => {
+        const registrar = new FakeRegistrar();
+        const client = createClient({ items: [{ label: 'x', kind: 3 }] });
+        (0, read_tools_1.registerReadTools)(registrar, createLifecycle({ fileClient: client }), { initializeManager: jest.fn() });
+        await expect(getHandler(registrar, 'lsp_completion')({ file: '/workspace/src/index.ts', line: 0, character: 0 })).resolves.toEqual({
+            content: [{ type: 'text', text: 'Showing 1 of 1 completion item(s)\n\n### Functions\n- `x`' }],
+            raw: [{ label: 'x', kind: 3 }]
+        });
+        client.request.mockResolvedValueOnce([{ name: 'DocSymbol', kind: 5, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } }, selectionRange: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }]);
+        await expect(getHandler(registrar, 'lsp_document_symbols')({ file: '/workspace/src/index.ts' })).resolves.toEqual({
+            content: [{ type: 'text', text: '- 📦 `DocSymbol`' }],
+            raw: [{ name: 'DocSymbol', kind: 5, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } }, selectionRange: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }]
+        });
+        client.request.mockResolvedValueOnce(null);
+        await expect(getHandler(registrar, 'lsp_signature_help')({ file: '/workspace/src/index.ts', line: 0, character: 0 })).resolves.toEqual({
+            content: [{ type: 'text', text: 'No result' }],
+            raw: null
+        });
+    });
+    it('supports type and implementation lookups plus empty completion results', async () => {
+        const registrar = new FakeRegistrar();
+        const client = createClient({
+            uri: 'file:///workspace/src/types.ts',
+            range: { start: { line: 1, character: 2 }, end: { line: 1, character: 6 } }
+        });
+        (0, read_tools_1.registerReadTools)(registrar, createLifecycle({ fileClient: client }), { initializeManager: jest.fn() });
+        await expect(getHandler(registrar, 'lsp_type_definition')({ file: '/workspace/src/index.ts', line: 0, character: 0 })).resolves.toEqual({
+            content: [{ type: 'text', text: 'Found 1 definition: `/workspace/src/types.ts:2:3`' }],
+            raw: [{ path: '/workspace/src/types.ts', range: { start: { line: 1, character: 2 }, end: { line: 1, character: 6 } } }]
+        });
+        client.request.mockResolvedValueOnce(null);
+        await expect(getHandler(registrar, 'lsp_implementation')({ file: '/workspace/src/index.ts', line: 0, character: 0 })).resolves.toEqual({
+            content: [{ type: 'text', text: 'No result' }],
+            raw: null
+        });
+        client.request.mockResolvedValueOnce(null);
+        await expect(getHandler(registrar, 'lsp_completion')({ file: '/workspace/src/index.ts', line: 0, character: 0 })).resolves.toEqual({
+            content: [{ type: 'text', text: 'No result' }],
+            raw: null
+        });
+        client.request.mockResolvedValueOnce({ signatures: [{ label: 'fn(x: string)' }] });
+        await expect(getHandler(registrar, 'lsp_signature_help')({ file: '/workspace/src/index.ts', line: 0, character: 0 })).resolves.toEqual({
+            content: [{ type: 'text', text: JSON.stringify({ signatures: [{ label: 'fn(x: string)' }] }, null, 2) }],
+            raw: { signatures: [{ label: 'fn(x: string)' }] }
+        });
+    });
+    it('turns LSP timeouts into retry guidance', async () => {
+        const registrar = new FakeRegistrar();
+        const client = createClient(new Error('LSP request timed out: textDocument/hover'));
+        (0, read_tools_1.registerReadTools)(registrar, createLifecycle({ fileClient: client }), { initializeManager: jest.fn() });
+        await expect(getHandler(registrar, 'lsp_hover')({ file: '/workspace/src/index.ts', line: 0, character: 0 })).resolves.toEqual({
+            content: [{ type: 'text', text: 'Operation timed out after 5s — try a more specific query or check the LSP server health' }],
+            error: true,
+            raw: null
+        });
+    });
+    it('returns a no-server error when no language server matches the file', async () => {
+        const registrar = new FakeRegistrar();
+        (0, read_tools_1.registerReadTools)(registrar, createLifecycle({ fileClient: null }), { initializeManager: jest.fn() });
+        await expect(getHandler(registrar, 'lsp_hover')({ file: '/workspace/README.md', line: 0, character: 0 })).resolves.toEqual({
+            content: [{ type: 'text', text: 'No language server available for .md files. Run lsp_health for details.' }],
+            error: true,
+            raw: null
+        });
+    });
+    it('returns restart guidance when the LSP crashed', async () => {
+        const registrar = new FakeRegistrar();
+        const client = createClient(new Error('LSP server exited unexpectedly (code: 1, signal: null)'));
+        (0, read_tools_1.registerReadTools)(registrar, createLifecycle({ fileClient: client }), { initializeManager: jest.fn() });
+        await expect(getHandler(registrar, 'lsp_hover')({ file: '/workspace/src/index.ts', line: 0, character: 0 })).resolves.toEqual({
+            content: [{ type: 'text', text: 'Der Language Server ist neu gestartet, bitte versuche es erneut.' }],
+            error: true,
+            raw: null
+        });
+    });
+});
+function getHandler(registrar, name) {
+    const tool = registrar.tools.get(name);
+    if (!tool) {
+        throw new Error(`Missing tool ${name}`);
+    }
+    return tool.handler;
+}
+function createLifecycle(options) {
+    return {
+        getClientForFile: jest.fn((_) => options.fileClient ?? null),
+        getReadyClients: jest.fn((_) => options.workspaceClients ?? []),
+        getFileDiagnostics: jest.fn((_) => (options.diagnostics ?? []).filter((diagnostic) => diagnostic.uri === 'file:///workspace/src/index.ts')),
+        getWorkspaceDiagnostics: jest.fn((_) => options.diagnostics ?? []),
+        getHealth: jest.fn(() => options.health ?? []),
+        ensureLanguageForFile: jest.fn().mockResolvedValue(undefined)
+    };
+}
+function createClient(result) {
+    return {
+        request: result instanceof Error
+            ? jest.fn().mockRejectedValue(result)
+            : jest.fn().mockResolvedValue(result),
+        notify: jest.fn(),
+        getCapabilities: jest.fn(() => ({ renameProvider: true }))
+    };
+}