mcp-lsp-driver 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EFLKumo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,468 @@
+# MCP LSP Driver SDK
+
+A TypeScript SDK that bridges Language Server Protocol (LSP) capabilities with the Model Context Protocol (MCP). Designed for IDE plugin developers building AI-assisted coding tools for VS Code, JetBrains, and other editors.
+
+## Core Philosophy
+
+- **Fuzzy-to-Exact Resolution**: LLMs interact via semantic anchors (`symbolName`, `lineHint`), and the SDK resolves them to precise coordinates
+- **Disk-Based Truth**: All read operations reflect the state of files on disk, ignoring unsaved IDE buffers
+- **Human-in-the-Loop Edits**: Write operations require explicit user approval before applying changes
+- **Type Safety**: Strict TypeScript with no `any` types
+
+## Installation
+
+```bash
+npm install mcp-lsp-driver
+# or
+pnpm add mcp-lsp-driver
+```
+
+## Quick Start
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { installMcpLspDriver, type IdeCapabilities } from 'mcp-lsp-driver'
+import * as fs from 'fs/promises'
+
+// 1. Create your MCP server
+const server = new McpServer({
+  name: 'my-ide-mcp-server',
+  version: '1.0.0'
+})
+
+// 2. Implement File Access (required)
+const fileAccess = {
+  readFile: async (uri: string) => {
+    return await fs.readFile(uri, 'utf-8')
+  }
+}
+
+// 3. Implement User Interaction (required for edits)
+const userInteraction = {
+  previewAndApplyEdits: async (operation) => {
+    // Show diff in your IDE and get user approval
+    return await showDiffDialog(operation)
+  }
+}
+
+// 4. Implement LSP Capability Providers
+const definition = {
+  provideDefinition: async (uri, position) => {
+    // Call your IDE's LSP to get definition
+    return await lspClient.getDefinition(uri, position)
+  }
+}
+
+const diagnostics = {
+  provideDiagnostics: async (uri) => {
+    // Get diagnostics from your IDE for the file
+    return await lspClient.getDiagnostics(uri)
+  },
+  getWorkspaceDiagnostics: async () => {
+    // Optional: Get all diagnostics in the workspace
+    return await lspClient.getWorkspaceDiagnostics()
+  }
+}
+
+const outline = {
+  provideDocumentSymbols: async (uri) => {
+    // Get document symbols from your IDE
+    return await lspClient.getDocumentSymbols(uri)
+  }
+}
+
+const filesystem = {
+  getFileTree: async (folderPath) => {
+    // Get file tree excluding git-ignored files
+    return await yourIDE.getFileTree(folderPath)
+  }
+}
+
+// 5. Register LSP tools and resources on the server
+const capabilities: IdeCapabilities = {
+  fileAccess,
+  userInteraction,
+  definition,
+  diagnostics,
+  outline,
+  filesystem,
+  onDiagnosticsChanged: (callback) => {
+    // Register for diagnostic changes
+    yourIDE.onDiagnosticsChanged((uri) => callback(uri))
+  },
+  // Add more capabilities as needed
+}
+
+installMcpLspDriver({ server, capabilities })
+
+// 6. Connect to transport (you control the server lifecycle)
+const transport = new StdioServerTransport()
+await server.connect(transport)
+```
+
+## API Reference
+
+### Core Interfaces
+
+#### `FileAccessProvider` (Required)
+
+Provides disk access for reading files:
+
+```typescript
+interface FileAccessProvider {
+  readFile(uri: UnifiedUri): Promise<string>
+}
+```
+
+#### `UserInteractionProvider` (Required for edits)
+
+Handles user approval for edit operations:
+
+```typescript
+interface UserInteractionProvider {
+  previewAndApplyEdits(operation: PendingEditOperation): Promise<boolean>
+}
+```
+
+### Capability Providers
+
+All capability providers receive `ExactPosition` coordinates (0-based). The SDK handles fuzzy-to-exact conversion before calling these.
+
+#### `DefinitionProvider`
+
+```typescript
+interface DefinitionProvider {
+  provideDefinition(uri: UnifiedUri, position: ExactPosition): Promise<CodeSnippet[]>
+}
+```
+
+#### `ReferencesProvider`
+
+```typescript
+interface ReferencesProvider {
+  provideReferences(uri: UnifiedUri, position: ExactPosition): Promise<CodeSnippet[]>
+}
+```
+
+#### `HierarchyProvider`
+
+```typescript
+interface HierarchyProvider {
+  provideCallHierarchy(
+    uri: UnifiedUri,
+    position: ExactPosition,
+    direction: 'incoming' | 'outgoing'
+  ): Promise<CodeSnippet[]>
+}
+```
+
+#### `DiagnosticsProvider`
+
+```typescript
+interface DiagnosticsProvider {
+  provideDiagnostics(uri: UnifiedUri): Promise<Diagnostic[]>
+  getWorkspaceDiagnostics?(): Promise<Diagnostic[]>  // Optional workspace diagnostics
+}
+```
+
+#### `OutlineProvider`
+
+```typescript
+interface OutlineProvider {
+  provideDocumentSymbols(uri: UnifiedUri): Promise<DocumentSymbol[]>
+}
+```
+
+#### `FilesystemProvider`
+
+```typescript
+interface FilesystemProvider {
+  getFileTree(folderPath: string): Promise<string[]>
+}
+```
+
+Provides filesystem access with git-ignore support. Returns file/folder paths in a directory tree, excluding git-ignored files.
+
+#### `GlobalFindProvider`
+
+```typescript
+interface GlobalFindProvider {
+  globalFind(query: string, options: GlobalFindOptions): Promise<GlobalFindMatch[]>
+  globalReplace(query: string, replaceWith: string, options: GlobalFindOptions): Promise<number>
+}
+```
+
+Provides global find and replace functionality across the workspace. `GlobalFindOptions` includes:
+- `caseSensitive`: Whether the search is case-sensitive (default: false)
+- `exactMatch`: Whether to match exact words only (default: false)
+- `regexMode`: Whether the query is a regular expression (default: false)
+
+`GlobalFindMatch` includes:
+- `uri`: File URI containing the match
+- `line`: 1-based line number
+- `column`: 1-based column number
+- `matchText`: The matching text
+- `context`: Context around the match (e.g., the full line)
+
+### IdeCapabilities
+
+Combine all providers into a single configuration:
+
+```typescript
+interface IdeCapabilities {
+  fileAccess: FileAccessProvider           // Required
+  userInteraction?: UserInteractionProvider // Required for apply_edit tool
+  definition?: DefinitionProvider           // Enables goto_definition tool
+  references?: ReferencesProvider           // Enables find_references tool
+  hierarchy?: HierarchyProvider             // Enables call_hierarchy tool
+  diagnostics?: DiagnosticsProvider         // Enables diagnostics resources
+  outline?: OutlineProvider                 // Enables outline resource
+  filesystem?: FilesystemProvider           // Enables filesystem resource
+  globalFind?: GlobalFindProvider           // Enables global_find and global_replace tools
+  onDiagnosticsChanged?: (callback: OnDiagnosticsChangedCallback) => void
+}
+```
+
+## MCP Tools
+
+The SDK automatically registers tools based on which capabilities you provide:
+
+### `goto_definition`
+
+Navigate to the definition of a symbol.
+
+**Inputs:**
+- `uri`: File path or URI
+- `symbol_name`: Text of the symbol to find
+- `line_hint`: Approximate line number (1-based)
+- `order_hint`: Which occurrence if symbol appears multiple times (0-based, default: 0)
+
+### `find_references`
+
+Find all references to a symbol.
+
+**Inputs:** Same as `goto_definition`
+
+### `call_hierarchy`
+
+Get call hierarchy for a function or method.
+
+**Inputs:**
+- Same as `goto_definition`, plus:
+- `direction`: `'incoming'` (callers) or `'outgoing'` (callees)
+
+### `apply_edit`
+
+Apply a text edit to a file (requires user approval).
+
+**Inputs:**
+- `uri`: File path or URI
+- `search_text`: Exact text to replace (must be unique in file)
+- `replace_text`: New text to insert
+- `description`: Rationale for the edit
+
+### `global_find`
+
+Search for text across the entire workspace.
+
+**Inputs:**
+- `query`: The search query (required)
+- `case_sensitive`: Whether the search is case-sensitive (optional, default: false)
+- `exact_match`: Whether to match exact words only (optional, default: false)
+- `regex_mode`: Whether the query is a regular expression (optional, default: false)
+
+**Returns:**
+- Array of matches with file URI, line, column, matching text, and context
+- Total number of matches found
+
+### `global_replace`
+
+Replace all occurrences of text across the entire workspace.
+
+**Inputs:**
+- `query`: The search query (required)
+- `replace_with`: The replacement text (required)
+- `case_sensitive`: Whether the search is case-sensitive (optional, default: false)
+- `exact_match`: Whether to match exact words only (optional, default: false)
+- `regex_mode`: Whether the query is a regular expression (optional, default: false)
+
+**Returns:**
+- Number of replacements made
+- Success status and message
+
+## MCP Resources
+
+The SDK automatically registers resources based on which capabilities you provide:
+
+### `lsp://diagnostics/{path}`
+
+Get diagnostics (errors, warnings) for a specific file.
+
+**Resource URI Pattern:** `lsp://diagnostics/{path}`
+
+**Example:** `lsp://diagnostics/src/main.ts`
+
+Returns diagnostics formatted as markdown with location, severity, and message information.
+
+**Subscription Support:** If your IDE implements `onDiagnosticsChanged` capability, these resources become subscribable. When diagnostics change, the driver sends resource update notifications.
+
+### `lsp://diagnostics/workspace`
+
+Get diagnostics across the entire workspace.
+
+**Resource URI:** `lsp://diagnostics/workspace`
+
+Only available if your `DiagnosticsProvider` implements the optional `getWorkspaceDiagnostics()` method.
+
+Returns workspace diagnostics grouped by file, formatted as markdown.
+
+**Subscription Support:** If your IDE implements `onDiagnosticsChanged` capability, this resource becomes subscribable.
+
+### `lsp://outline/{path}`
+
+Get the document outline (symbol tree) for a file.
+
+**Resource URI Pattern:** `lsp://outline/{path}`
+
+**Example:** `lsp://outline/src/components/Button.tsx`
+
+Returns document symbols formatted as a hierarchical markdown outline, including:
+- Symbol names and kinds (class, function, method, etc.)
+- Source locations
+- Nested children (e.g., methods within classes)
+
+No subscription support for this resource (read-only).
+
+### `lsp://files/{path}`
+
+Get the file tree for a directory, excluding git-ignored files.
+
+**Resource URI Pattern:** `lsp://files/{path}`
+
+**Example:** `lsp://files/src`
+
+Returns a list of file/folder paths in the directory tree, formatted as markdown. Git-ignored files and directories are automatically excluded from the results.
+
+No subscription support for this resource (read-only).
+
+## Subscription and Change Notifications
+
+When your IDE supports the `onDiagnosticsChanged` capability, diagnostic resources become subscribable:
+
+```typescript
+const capabilities: IdeCapabilities = {
+  fileAccess,
+  diagnostics: {
+    provideDiagnostics: async (uri) => { /* ... */ },
+    getWorkspaceDiagnostics: async () => { /* ... */ }
+  },
+  onDiagnosticsChanged: (callback) => {
+    // Register your IDE's diagnostic change listener
+    yourIDE.onDiagnosticsChanged((uri) => {
+      // Call the callback when diagnostics change
+      callback(uri)
+    })
+  }
+}
+```
+
+When diagnostics change, call the registered callback with the affected file URI. The driver will send MCP resource update notifications to subscribers.
+
+## Symbol Resolution
+
+The SDK uses a robust algorithm to handle imprecise LLM positioning:
+
+1. Target the `lineHint` (converting 1-based to 0-based)
+2. Search for `symbolName` in that line
+3. **Robustness Fallback**: If not found, scan +/- 2 lines (configurable)
+4. Use `orderHint` to select the Nth occurrence if needed
+
+Configure the search radius:
+
+```typescript
+installMcpLspDriver({ server, capabilities, config: {
+  resolverConfig: {
+    lineSearchRadius: 5  // Default: 2
+  }
+}})
+```
+
+## Type Definitions
+
+### Position Types
+
+```typescript
+// 0-based exact coordinates (internal)
+interface ExactPosition {
+  line: number
+  character: number
+}
+
+// Fuzzy position from LLM
+interface FuzzyPosition {
+  symbolName: string
+  lineHint: number      // 1-based
+  orderHint?: number    // 0-based, default: 0
+}
+
+// Range on disk
+interface DiskRange {
+  start: ExactPosition
+  end: ExactPosition
+}
+```
+
+### Result Types
+
+```typescript
+interface CodeSnippet {
+  uri: UnifiedUri
+  range: DiskRange
+  content: string
+}
+
+interface Diagnostic {
+  uri: UnifiedUri
+  range: DiskRange
+  severity: 'error' | 'warning' | 'information' | 'hint'
+  message: string
+  source?: string
+  code?: string | number
+}
+
+type EditResult =
+  | { success: true; message: string }
+  | { success: false; message: string; reason: 'UserRejected' | 'IOError' | 'ValidationFailed' }
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Run tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Lint
+pnpm lint
+
+# Format
+pnpm format
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.7.0
+
+## License
+
+MIT

package/dist/capabilities.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Capability Providers for MCP LSP Driver SDK
+ *
+ * The Plugin Developer provides an implementation of IdeCapabilities.
+ * The SDK exposes tools based on which optional providers are defined.
+ *
+ * Note: All inputs here use ExactPosition. The SDK handles the
+ * Fuzzy -> Exact conversion before calling these.
+ */
+import type { FileAccessProvider, UserInteractionProvider } from './interfaces.js';
+import type { CodeSnippet, Diagnostic, DocumentSymbol, ExactPosition, UnifiedUri } from './types.js';
+/**
+ * Provides go-to-definition functionality.
+ */
+export interface DefinitionProvider {
+    /**
+     * Returns definition location reading strictly from disk context.
+     *
+     * @param uri - The URI of the file
+     * @param position - The exact position to find the definition for
+     * @returns Array of code snippets representing definition locations
+     */
+    provideDefinition(uri: UnifiedUri, position: ExactPosition): Promise<CodeSnippet[]>;
+}
+/**
+ * Provides find-references functionality.
+ */
+export interface ReferencesProvider {
+    /**
+     * Finds all references to the symbol at the given position.
+     *
+     * @param uri - The URI of the file
+     * @param position - The exact position to find references for
+     * @returns Array of code snippets representing reference locations
+     */
+    provideReferences(uri: UnifiedUri, position: ExactPosition): Promise<CodeSnippet[]>;
+}
+/**
+ * Provides call hierarchy functionality.
+ */
+export interface HierarchyProvider {
+    /**
+     * Provides call hierarchy information for the symbol at the given position.
+     *
+     * @param uri - The URI of the file
+     * @param position - The exact position to get call hierarchy for
+     * @param direction - Whether to get incoming or outgoing calls
+     * @returns Array of code snippets representing call hierarchy items
+     */
+    provideCallHierarchy(uri: UnifiedUri, position: ExactPosition, direction: 'incoming' | 'outgoing'): Promise<CodeSnippet[]>;
+}
+/**
+ * Provides diagnostics (errors, warnings) for a file.
+ */
+export interface DiagnosticsProvider {
+    /**
+     * Gets diagnostics for a file.
+     *
+     * @param uri - The URI of the file
+     * @returns Array of diagnostics for the file
+     */
+    provideDiagnostics(uri: UnifiedUri): Promise<Diagnostic[]>;
+    /**
+     * Gets diagnostics for all files in the workspace.
+     * If not provided, the workspace diagnostics resource will not be available.
+     *
+     * @returns Array of diagnostics for all files in the workspace
+     */
+    getWorkspaceDiagnostics?(): Promise<Diagnostic[]>;
+}
+/**
+ * Provides document outline (symbols) for a file.
+ */
+export interface OutlineProvider {
+    /**
+     * Gets the document symbols (outline) for a file.
+     *
+     * @param uri - The URI of the file
+     * @returns Array of document symbols representing the file's outline
+     */
+    provideDocumentSymbols(uri: UnifiedUri): Promise<DocumentSymbol[]>;
+}
+/**
+ * Provides filesystem access with git-ignore support.
+ */
+export interface FilesystemProvider {
+    /**
+     * Gets the file tree for a directory, excluding git-ignored files.
+     *
+     * @param folderPath - The path to the folder to read
+     * @returns Array of file/folder paths in the directory tree
+     */
+    getFileTree(folderPath: string): Promise<string[]>;
+}
+/**
+ * Search options for global find operations.
+ */
+export interface GlobalFindOptions {
+    /** Whether the search is case-sensitive */
+    caseSensitive: boolean;
+    /** Whether to match exact words only */
+    exactMatch: boolean;
+    /** Whether the query is a regular expression */
+    regexMode: boolean;
+}
+/**
+ * A match result from a global find operation.
+ */
+export interface GlobalFindMatch {
+    /** The URI of the file containing the match */
+    uri: UnifiedUri;
+    /** 1-based line number of the match */
+    line: number;
+    /** 1-based column of the match */
+    column: number;
+    /** The matching text */
+    matchText: string;
+    /** Context around the match (e.g., the full line) */
+    context: string;
+}
+/**
+ * Provides global find functionality across the workspace.
+ */
+export interface GlobalFindProvider {
+    /**
+     * Performs a global find operation across the workspace.
+     *
+     * @param query - The search query
+     * @param options - Search options (case sensitivity, exact match, regex mode)
+     * @returns Array of matches found
+     */
+    globalFind(query: string, options: GlobalFindOptions): Promise<GlobalFindMatch[]>;
+    /**
+     * Performs a global replace operation across the workspace.
+     * The query and options are decoded from the ID generated by globalFind.
+     *
+     * @param query - The search query (decoded from the ID)
+     * @param replaceWith - The replacement text
+     * @param options - Search options (decoded from the ID)
+     * @returns The number of replacements made
+     */
+    globalReplace(query: string, replaceWith: string, options: GlobalFindOptions): Promise<number>;
+}
+/**
+ * Callback that gets invoked when diagnostics change.
+ * Used for MCP resource subscription support.
+ */
+export type OnDiagnosticsChangedCallback = (uri: UnifiedUri) => void;
+/**
+ * The complete set of capabilities that an IDE plugin can provide.
+ * The SDK will automatically register tools based on which providers are defined.
+ */
+export interface IdeCapabilities {
+    /** Mandatory: Provides file system access for reading files from disk */
+    fileAccess: FileAccessProvider;
+    /** Optional: Provides user interaction for edit operations */
+    userInteraction?: UserInteractionProvider;
+    /** Optional: Provides go-to-definition functionality */
+    definition?: DefinitionProvider;
+    /** Optional: Provides find-references functionality */
+    references?: ReferencesProvider;
+    /** Optional: Provides call hierarchy functionality */
+    hierarchy?: HierarchyProvider;
+    /** Optional: Provides diagnostics for files */
+    diagnostics?: DiagnosticsProvider;
+    /** Optional: Provides document outline (symbols) for files */
+    outline?: OutlineProvider;
+    /** Optional: Provides filesystem access with git-ignore support */
+    filesystem?: FilesystemProvider;
+    /** Optional: Provides global find and replace functionality */
+    globalFind?: GlobalFindProvider;
+    /**
+     * Optional: Called by the driver to register a callback for diagnostics changes.
+     * When this is provided, the diagnostics resources become subscribable.
+     * The plugin should call the registered callback whenever diagnostics change for a URI.
+     *
+     * @param callback - The callback to invoke when diagnostics change
+     */
+    onDiagnosticsChanged?: (callback: OnDiagnosticsChangedCallback) => void;
+}
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.js

@@ -0,0 +1,11 @@
+/**
+ * Capability Providers for MCP LSP Driver SDK
+ *
+ * The Plugin Developer provides an implementation of IdeCapabilities.
+ * The SDK exposes tools based on which optional providers are defined.
+ *
+ * Note: All inputs here use ExactPosition. The SDK handles the
+ * Fuzzy -> Exact conversion before calling these.
+ */
+export {};
+//# sourceMappingURL=capabilities.js.map