mcp-lsp-driver 0.0.1

package/dist/formatting.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Formatting utilities for converting LSP results to markdown.
+ * @internal
+ */
+import type { Diagnostic, DocumentSymbol } from './types.js';
+export declare const makeToolResult: <T extends {
+    [x: string]: unknown;
+}>(result: T) => {
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    structuredContent: {
+        [x: string]: unknown;
+    };
+};
+/**
+ * Normalizes a URI to handle Windows/Unix path separator differences.
+ */
+export declare function normalizeUri(uri: string): string;
+/**
+ * Generates a unique ID for pending edit operations.
+ */
+export declare function generateEditId(): string;
+/**
+ * Formats diagnostics as markdown for resource content.
+ */
+export declare function formatDiagnosticsAsMarkdown(diagnostics: Diagnostic[]): string;
+/**
+ * Formats document symbols as markdown for resource content.
+ */
+export declare function formatSymbolsAsMarkdown(symbols: DocumentSymbol[], indent?: number): string;
+//# sourceMappingURL=formatting.d.ts.map

package/dist/formatting.js

@@ -0,0 +1,67 @@
+/**
+ * Formatting utilities for converting LSP results to markdown.
+ * @internal
+ */
+export const makeToolResult = (result) => ({
+    content: [{ type: 'text', text: JSON.stringify(result ?? '') }],
+    structuredContent: result,
+});
+/**
+ * Normalizes a URI to handle Windows/Unix path separator differences.
+ */
+export function normalizeUri(uri) {
+    // If it's already a file:// URI, leave it alone
+    if (uri.startsWith('file://')) {
+        return uri;
+    }
+    // Normalize backslashes to forward slashes for consistency
+    return uri.replace(/\\/g, '/');
+}
+/**
+ * Generates a unique ID for pending edit operations.
+ */
+export function generateEditId() {
+    return `edit-${Date.now()}`;
+}
+/**
+ * Formats diagnostics as markdown for resource content.
+ */
+export function formatDiagnosticsAsMarkdown(diagnostics) {
+    if (diagnostics.length === 0) {
+        return 'No diagnostics found.';
+    }
+    return diagnostics
+        .map((d) => {
+        const line = d.range.start.line + 1;
+        const severity = d.severity.toUpperCase();
+        const source = d.source ? ` [${d.source}]` : '';
+        const code = d.code !== undefined ? ` (${d.code})` : '';
+        return `- **${severity}**${source}${code} at line ${line}: ${d.message}`;
+    })
+        .join('\n');
+}
+/**
+ * Formats document symbols as markdown for resource content.
+ */
+export function formatSymbolsAsMarkdown(symbols, indent = 0) {
+    if (symbols.length === 0 && indent === 0) {
+        return 'No symbols found.';
+    }
+    const prefix = '  '.repeat(indent);
+    return symbols
+        .map((s) => {
+        const startLine = s.range.start.line + 1;
+        const endLine = s.range.end.line + 1;
+        const range = startLine === endLine
+            ? `line ${startLine}`
+            : `lines ${startLine}-${endLine}`;
+        const detail = s.detail ? ` - ${s.detail}` : '';
+        const line = `${prefix}- **${s.kind}** \`${s.name}\`${detail} (${range})`;
+        if (s.children && s.children.length > 0) {
+            return `${line}\n${formatSymbolsAsMarkdown(s.children, indent + 1)}`;
+        }
+        return line;
+    })
+        .join('\n');
+}
+//# sourceMappingURL=formatting.js.map

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * MCP LSP Driver SDK
+ *
+ * A TypeScript SDK for building IDE plugins that expose LSP features
+ * through the Model Context Protocol (MCP).
+ *
+ * @packageDocumentation
+ */
+export type { DefinitionProvider, DiagnosticsProvider, FilesystemProvider, GlobalFindMatch, GlobalFindOptions, GlobalFindProvider, HierarchyProvider, IdeCapabilities, OnDiagnosticsChangedCallback, OutlineProvider, ReferencesProvider, } from './capabilities.js';
+export type { FileAccessProvider, UserInteractionProvider, } from './interfaces.js';
+export type { ResolverConfig } from './resolver.js';
+export { SymbolResolutionError, SymbolResolver } from './resolver.js';
+export type { McpLspDriverConfig } from './server.js';
+export { installMcpLspDriver } from './server.js';
+export type { CodeSnippet, Diagnostic, DiagnosticSeverity, DiskRange, DocumentSymbol, EditFailureReason, EditResult, ExactPosition, FuzzyPosition, PendingEditOperation, SymbolKind, TextEdit, UnifiedUri, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * MCP LSP Driver SDK
+ *
+ * A TypeScript SDK for building IDE plugins that expose LSP features
+ * through the Model Context Protocol (MCP).
+ *
+ * @packageDocumentation
+ */
+// Symbol Resolver
+export { SymbolResolutionError, SymbolResolver } from './resolver.js';
+// Driver
+export { installMcpLspDriver } from './server.js';
+//# sourceMappingURL=index.js.map

package/dist/interfaces.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Infrastructure Interfaces for MCP LSP Driver SDK
+ *
+ * The SDK consumer (Plugin Developer) must implement these interfaces
+ * to bridge the SDK to the specific IDE.
+ */
+import type { PendingEditOperation, UnifiedUri } from './types.js';
+/**
+ * Provides access to the file system for reading files.
+ * Since the SDK is responsible for resolving FuzzyPosition to ExactPosition,
+ * it needs direct access to read files from the disk.
+ */
+export interface FileAccessProvider {
+    /**
+     * Reads the content of a file from the disk (ignoring unsaved IDE buffers).
+     * Used for symbol resolution and context retrieval.
+     *
+     * @param uri - The URI of the file to read
+     * @returns The content of the file as a string
+     * @throws Error if the file cannot be read
+     */
+    readFile(uri: UnifiedUri): Promise<string>;
+}
+/**
+ * Provides user interaction capabilities for edit operations.
+ * The SDK uses this to present diffs and get user approval before applying changes.
+ */
+export interface UserInteractionProvider {
+    /**
+     * Displays a diff view or a confirmation dialog in the IDE.
+     * The user decides whether to apply the edits or discard them.
+     *
+     * @param operation - The pending edit operation to preview
+     * @returns true if applied, false if rejected/cancelled
+     */
+    previewAndApplyEdits(operation: PendingEditOperation): Promise<boolean>;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/interfaces.js

@@ -0,0 +1,8 @@
+/**
+ * Infrastructure Interfaces for MCP LSP Driver SDK
+ *
+ * The SDK consumer (Plugin Developer) must implement these interfaces
+ * to bridge the SDK to the specific IDE.
+ */
+export {};
+//# sourceMappingURL=interfaces.js.map

package/dist/resolver.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Smart Resolver Logic for MCP LSP Driver SDK
+ *
+ * This is the internal engine of the SDK. It translates the LLM's imprecise
+ * instructions into precise coordinates.
+ */
+import type { FileAccessProvider } from './interfaces.js';
+import type { DiskRange, ExactPosition, FuzzyPosition, UnifiedUri } from './types.js';
+/**
+ * Configuration options for the SymbolResolver.
+ */
+export interface ResolverConfig {
+    /**
+     * Number of lines to scan above and below the lineHint if the symbol
+     * is not found at the exact line. Defaults to 2.
+     */
+    lineSearchRadius?: number;
+}
+/**
+ * Error thrown when a symbol cannot be resolved.
+ */
+export declare class SymbolResolutionError extends Error {
+    readonly symbolName: string;
+    readonly lineHint: number;
+    readonly reason: string;
+    constructor(symbolName: string, lineHint: number, reason: string);
+}
+/**
+ * The SymbolResolver translates fuzzy positions (as provided by an LLM)
+ * into exact positions that can be used by the IDE.
+ *
+ * Algorithm:
+ * 1. Read file content via FileAccessProvider.
+ * 2. Split content into lines.
+ * 3. Target the lineHint (converting 1-based to 0-based).
+ * 4. Search for symbolName in that line.
+ *    - If orderHint is 0, find first occurrence.
+ *    - If orderHint is N, find Nth occurrence.
+ * 5. Robustness Fallback:
+ *    - If the line is empty or symbol not found at lineHint,
+ *      scan +/- lineSearchRadius lines to handle minor line shifts.
+ * 6. Return ExactPosition (line, character start index).
+ */
+export declare class SymbolResolver {
+    private readonly fs;
+    private readonly lineSearchRadius;
+    constructor(fs: FileAccessProvider, config?: ResolverConfig);
+    /**
+     * Resolves a fuzzy position to an exact position.
+     *
+     * @param uri - The URI of the file
+     * @param fuzzy - The fuzzy position provided by the LLM
+     * @returns The exact position in the file
+     * @throws SymbolResolutionError if the symbol cannot be found
+     */
+    resolvePosition(uri: UnifiedUri, fuzzy: FuzzyPosition): Promise<ExactPosition>;
+    /**
+     * Finds the Nth occurrence of a symbol in a line.
+     *
+     * @param line - The line to search in (may be undefined if out of bounds)
+     * @param symbolName - The symbol to find
+     * @param orderHint - Which occurrence to find (0-based)
+     * @returns The character offset of the symbol, or null if not found
+     */
+    private findSymbolInLine;
+    /**
+     * Finds exact text in a file and returns its range.
+     * Used for search-and-replace operations.
+     *
+     * @param uri - The URI of the file
+     * @param searchText - The exact text to find
+     * @returns The range of the found text
+     * @throws Error if the text is not found or appears multiple times
+     */
+    findExactText(uri: UnifiedUri, searchText: string): Promise<DiskRange>;
+    /**
+     * Converts a character offset to a line/character position.
+     */
+    private offsetToPosition;
+}
+//# sourceMappingURL=resolver.d.ts.map

package/dist/resolver.js

@@ -0,0 +1,171 @@
+/**
+ * Smart Resolver Logic for MCP LSP Driver SDK
+ *
+ * This is the internal engine of the SDK. It translates the LLM's imprecise
+ * instructions into precise coordinates.
+ */
+/**
+ * Error thrown when a symbol cannot be resolved.
+ */
+export class SymbolResolutionError extends Error {
+    symbolName;
+    lineHint;
+    reason;
+    constructor(symbolName, lineHint, reason) {
+        super(`Could not find symbol '${symbolName}' at or near line ${lineHint}. ${reason}`);
+        this.symbolName = symbolName;
+        this.lineHint = lineHint;
+        this.reason = reason;
+        this.name = 'SymbolResolutionError';
+    }
+}
+/**
+ * The SymbolResolver translates fuzzy positions (as provided by an LLM)
+ * into exact positions that can be used by the IDE.
+ *
+ * Algorithm:
+ * 1. Read file content via FileAccessProvider.
+ * 2. Split content into lines.
+ * 3. Target the lineHint (converting 1-based to 0-based).
+ * 4. Search for symbolName in that line.
+ *    - If orderHint is 0, find first occurrence.
+ *    - If orderHint is N, find Nth occurrence.
+ * 5. Robustness Fallback:
+ *    - If the line is empty or symbol not found at lineHint,
+ *      scan +/- lineSearchRadius lines to handle minor line shifts.
+ * 6. Return ExactPosition (line, character start index).
+ */
+export class SymbolResolver {
+    fs;
+    lineSearchRadius;
+    constructor(fs, config) {
+        this.fs = fs;
+        this.lineSearchRadius = config?.lineSearchRadius ?? 2;
+    }
+    /**
+     * Resolves a fuzzy position to an exact position.
+     *
+     * @param uri - The URI of the file
+     * @param fuzzy - The fuzzy position provided by the LLM
+     * @returns The exact position in the file
+     * @throws SymbolResolutionError if the symbol cannot be found
+     */
+    async resolvePosition(uri, fuzzy) {
+        const content = await this.fs.readFile(uri);
+        const lines = content.split(/\r?\n/);
+        // Convert 1-based lineHint to 0-based index
+        const targetLine = fuzzy.lineHint - 1;
+        const orderHint = fuzzy.orderHint ?? 0;
+        // First, try to find the symbol at the exact line
+        const exactResult = this.findSymbolInLine(lines[targetLine], fuzzy.symbolName, orderHint);
+        if (exactResult !== null) {
+            return { line: targetLine, character: exactResult };
+        }
+        // Fallback: scan nearby lines
+        for (let offset = 1; offset <= this.lineSearchRadius; offset++) {
+            // Check line above
+            const lineAbove = targetLine - offset;
+            if (lineAbove >= 0) {
+                const resultAbove = this.findSymbolInLine(lines[lineAbove], fuzzy.symbolName, orderHint);
+                if (resultAbove !== null) {
+                    return { line: lineAbove, character: resultAbove };
+                }
+            }
+            // Check line below
+            const lineBelow = targetLine + offset;
+            if (lineBelow < lines.length) {
+                const resultBelow = this.findSymbolInLine(lines[lineBelow], fuzzy.symbolName, orderHint);
+                if (resultBelow !== null) {
+                    return { line: lineBelow, character: resultBelow };
+                }
+            }
+        }
+        // Symbol not found anywhere in the search range
+        throw new SymbolResolutionError(fuzzy.symbolName, fuzzy.lineHint, `Please verify the file content and try again. Searched lines ${Math.max(1, fuzzy.lineHint - this.lineSearchRadius)} to ${Math.min(lines.length, fuzzy.lineHint + this.lineSearchRadius)}.`);
+    }
+    /**
+     * Finds the Nth occurrence of a symbol in a line.
+     *
+     * @param line - The line to search in (may be undefined if out of bounds)
+     * @param symbolName - The symbol to find
+     * @param orderHint - Which occurrence to find (0-based)
+     * @returns The character offset of the symbol, or null if not found
+     */
+    findSymbolInLine(line, symbolName, orderHint) {
+        if (line === undefined || line.length === 0) {
+            return null;
+        }
+        let currentIndex = 0;
+        let occurrenceCount = 0;
+        while (currentIndex < line.length) {
+            const foundIndex = line.indexOf(symbolName, currentIndex);
+            if (foundIndex === -1) {
+                break;
+            }
+            if (occurrenceCount === orderHint) {
+                return foundIndex;
+            }
+            occurrenceCount++;
+            currentIndex = foundIndex + 1;
+        }
+        return null;
+    }
+    /**
+     * Finds exact text in a file and returns its range.
+     * Used for search-and-replace operations.
+     *
+     * @param uri - The URI of the file
+     * @param searchText - The exact text to find
+     * @returns The range of the found text
+     * @throws Error if the text is not found or appears multiple times
+     */
+    async findExactText(uri, searchText) {
+        const content = await this.fs.readFile(uri);
+        // Find all occurrences
+        const occurrences = [];
+        let searchIndex = 0;
+        while (searchIndex < content.length) {
+            const foundIndex = content.indexOf(searchText, searchIndex);
+            if (foundIndex === -1) {
+                break;
+            }
+            occurrences.push(foundIndex);
+            searchIndex = foundIndex + 1;
+        }
+        if (occurrences.length === 0) {
+            throw new Error(`Text not found in file: "${searchText.slice(0, 50)}${searchText.length > 50 ? '...' : ''}"`);
+        }
+        if (occurrences.length > 1) {
+            throw new Error(`Text appears ${occurrences.length} times in file. Please provide more context to uniquely identify the location.`);
+        }
+        // Convert character offset to line/character position
+        const startOffset = occurrences[0];
+        const endOffset = startOffset + searchText.length;
+        const start = this.offsetToPosition(content, startOffset);
+        const end = this.offsetToPosition(content, endOffset);
+        return { start, end };
+    }
+    /**
+     * Converts a character offset to a line/character position.
+     */
+    offsetToPosition(content, offset) {
+        let line = 0;
+        let character = 0;
+        let currentOffset = 0;
+        for (const char of content) {
+            if (currentOffset === offset) {
+                break;
+            }
+            if (char === '\n') {
+                line++;
+                character = 0;
+            }
+            else {
+                character++;
+            }
+            currentOffset++;
+        }
+        return { line, character };
+    }
+}
+//# sourceMappingURL=resolver.js.map

package/dist/schemas.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Zod schemas for MCP tool inputs and outputs.
+ * @internal
+ */
+import * as z from 'zod/mini';
+export declare const FuzzyPositionSchema: z.ZodMiniObject<{
+    uri: z.ZodMiniString<string>;
+    symbol_name: z.ZodMiniString<string>;
+    line_hint: z.ZodMiniNumber<number>;
+    order_hint: z.ZodMiniDefault<z.ZodMiniOptional<z.ZodMiniNumber<number>>>;
+}, z.core.$strip>;
+export declare const ApplyEditSchema: z.ZodMiniObject<{
+    uri: z.ZodMiniString<string>;
+    search_text: z.ZodMiniString<string>;
+    replace_text: z.ZodMiniString<string>;
+    description: z.ZodMiniString<string>;
+}, z.core.$strip>;
+export declare const CallHierarchySchema: z.ZodMiniObject<{
+    uri: z.ZodMiniString<string>;
+    symbol_name: z.ZodMiniString<string>;
+    line_hint: z.ZodMiniNumber<number>;
+    order_hint: z.ZodMiniDefault<z.ZodMiniOptional<z.ZodMiniNumber<number>>>;
+    direction: z.ZodMiniEnum<{
+        incoming: "incoming";
+        outgoing: "outgoing";
+    }>;
+}, z.core.$strip>;
+export declare const GlobalFindSchema: z.ZodMiniObject<{
+    query: z.ZodMiniString<string>;
+    case_sensitive: z.ZodMiniDefault<z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>>;
+    exact_match: z.ZodMiniDefault<z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>>;
+    regex_mode: z.ZodMiniDefault<z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>>;
+}, z.core.$strip>;
+export declare const GlobalReplaceSchema: z.ZodMiniObject<{
+    query: z.ZodMiniString<string>;
+    case_sensitive: z.ZodMiniDefault<z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>>;
+    exact_match: z.ZodMiniDefault<z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>>;
+    regex_mode: z.ZodMiniDefault<z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>>;
+    replace_with: z.ZodMiniString<string>;
+}, z.core.$strip>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.js

@@ -0,0 +1,62 @@
+/**
+ * Zod schemas for MCP tool inputs and outputs.
+ * @internal
+ */
+import * as z from 'zod/mini';
+const uri = z.string().check(z.describe('The relative file path'));
+const symbol_name = z
+    .string()
+    .check(z.describe('The text of the symbol to find'));
+const line_hint = z
+    .number()
+    .check(z.int(), z.positive(), z.describe('Approximate 1-based line number where the symbol is expected'));
+const order_hint = z
+    ._default(z.optional(z.number().check(z.int(), z.minimum(0))), 0)
+    .check(z.describe('0-based index of which occurrence to target if symbol appears multiple times'));
+export const FuzzyPositionSchema = z.object({
+    uri,
+    symbol_name,
+    line_hint,
+    order_hint,
+});
+export const ApplyEditSchema = z.object({
+    uri,
+    search_text: z
+        .string()
+        .check(z.describe('Exact text to replace (must exist uniquely in the file)')),
+    replace_text: z.string().check(z.describe('New text to insert')),
+    description: z.string().check(z.describe('Rationale for the edit')),
+});
+export const CallHierarchySchema = z.object({
+    uri: z.string().check(z.describe('The file URI or path')),
+    symbol_name,
+    line_hint,
+    order_hint,
+    direction: z
+        .enum(['incoming', 'outgoing'])
+        .check(z.describe('Direction of the call hierarchy')),
+});
+const query = z.string().check(z.describe('The search query'));
+const case_sensitive = z
+    ._default(z.optional(z.boolean()), false)
+    .check(z.describe('Whether the search is case-sensitive'));
+const exact_match = z
+    ._default(z.optional(z.boolean()), false)
+    .check(z.describe('Whether to match exact words only'));
+const regex_mode = z
+    ._default(z.optional(z.boolean()), false)
+    .check(z.describe('Whether the query is a regular expression'));
+export const GlobalFindSchema = z.object({
+    query,
+    case_sensitive,
+    exact_match,
+    regex_mode,
+});
+export const GlobalReplaceSchema = z.object({
+    query,
+    case_sensitive,
+    exact_match,
+    regex_mode,
+    replace_with: z.string().check(z.describe('The replacement text')),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/server.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MCP Server Implementation for LSP Driver SDK
+ *
+ * The SDK automatically registers tools based on which capability providers
+ * are defined in the IdeCapabilities configuration.
+ */
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { IdeCapabilities } from './capabilities.js';
+import { type ResolverConfig } from './resolver.js';
+/**
+ * Configuration options for the MCP LSP Driver.
+ */
+export interface McpLspDriverConfig {
+    /** Configuration for the symbol resolver */
+    resolverConfig?: ResolverConfig;
+}
+/**
+ * Register LSP-based tools and resources on the provided MCP server.
+ */
+export declare function installMcpLspDriver({ server, capabilities, config, }: {
+    server: McpServer;
+    capabilities: IdeCapabilities;
+    config?: McpLspDriverConfig;
+}): {
+    success: boolean;
+    error: unknown;
+    reason: string;
+} | {
+    success: boolean;
+    error?: undefined;
+    reason?: undefined;
+};
+//# sourceMappingURL=server.d.ts.map