mcp-lsp-driver 0.1.0 → 1.0.1

package/README.md

@@ -6,8 +6,7 @@ A TypeScript SDK that bridges Language Server Protocol (LSP) capabilities with t
 
 - **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
+- **High Abstraction**: Beyond LSP, it also provides functionality related to something like dual chains (graph capability) and metadata (frontmatter capability).
 
 ## Installation
 
@@ -37,14 +36,22 @@ const fileAccess = {
     return await fs.readFile(uri, 'utf-8')
   },
 
-  getFileTree: (uri: string) => yourIDE.workspace.files
+  getFileTree: (uri: string) => yourIDE.workspace.getFileTree(uri),
+
+  readDirectory: (uri: string) => yourIDE.workspace.readDirectory(uri)
 }
 
-// 3. Implement User Interaction (required for edits)
-const userInteraction = {
+// 3. Implement Edit Provider (required for edits)
+const edit = {
+  // Option 1: Preview and apply with user approval
   previewAndApplyEdits: async (operation) => {
     // Show diff in your IDE and get user approval
     return await showDiffDialog(operation)
+  },
+  // Option 2: Apply directly without preview (use one or both)
+  applyEdits: async (operation) => {
+    // Apply edits directly
+    return await yourIDE.applyEdits(operation)
   }
 }
 
@@ -77,7 +84,7 @@ const outline = {
 // 5. Register LSP tools and resources on the server
 const capabilities: IdeCapabilities = {
   fileAccess,
-  userInteraction,
+  edit,
   definition,
   diagnostics,
   outline,
@@ -109,19 +116,25 @@ Provides disk access for reading files:
 interface FileAccessProvider {
   readFile(uri: UnifiedUri): Promise<string>
   getFileTree(folderPath: UnifiedUri): Promise<string[]>
+  readDirectory(folderPath: UnifiedUri): Promise<string[]>
 }
 ```
 
-#### `UserInteractionProvider` (Required for edits)
+#### `EditProvider` (Required for edits)
 
-Handles user approval for edit operations:
+Handles applying changes to files. At least one method must be implemented:
 
 ```typescript
-interface UserInteractionProvider {
-  previewAndApplyEdits(operation: PendingEditOperation): Promise<boolean>
+interface EditProvider {
+  // Apply edits directly without user interaction
+  applyEdits?(operation: PendingEditOperation): Promise<boolean>
+  // Preview edits and get user approval before applying
+  previewAndApplyEdits?(operation: PendingEditOperation): Promise<boolean>
 }
 ```
 
+If both methods are provided, `previewAndApplyEdits` takes precedence.
+
 ### Capability Providers
 
 All capability providers receive `ExactPosition` coordinates (0-based). The SDK handles fuzzy-to-exact conversion before calling these.
@@ -192,6 +205,51 @@ Provides global find and replace functionality across the workspace. `GlobalFind
 - `matchText`: The matching text
 - `context`: Context around the match (e.g., the full line)
 
+#### `GraphProvider`
+
+```typescript
+interface GraphProvider {
+  getLinkStructure(): Promise<Link[]>
+  resolveOutlinks(path: UnifiedUri): Promise<Link[]>
+  resolveBacklinks(path: UnifiedUri): Promise<Link[]>
+  addLink(path: UnifiedUri, pattern: string, linkTo: UnifiedUri): Promise<boolean>
+}
+```
+
+Provides graph/link functionality for document relationships (e.g., wiki-style links, cross-references). `Link` includes:
+- `sourceUri`: The source URI where the link originates
+- `targetUri`: The target URI the link points to
+- `subpath`: Optional subpath within the target (e.g., `#section` for Obsidian-style anchors)
+- `displayText`: Optional display text of the link
+- `resolved`: Whether the link target exists
+- `line`: 1-based line number where the link appears
+- `column`: 1-based column number where the link starts
+
+#### `FrontmatterProvider`
+
+```typescript
+interface FrontmatterProvider {
+  getFrontmatterStructure(property: string, path?: UnifiedUri): Promise<FrontmatterMatch[]>
+  getFrontmatter(path: UnifiedUri): Promise<Frontmatter>
+  setFrontmatter(path: UnifiedUri, property: string, value: FrontmatterValue): Promise<boolean>
+}
+```
+
+Provides frontmatter metadata functionality for documents (e.g., YAML frontmatter in Markdown files). Types:
+
+```typescript
+type FrontmatterValue = string | string[] | number | number[] | boolean | boolean[] | Date | undefined
+type Frontmatter = { [key: string]: FrontmatterValue }
+interface FrontmatterMatch {
+  path: UnifiedUri
+  value: FrontmatterValue
+}
+```
+
+- `getFrontmatterStructure`: Searches for a specific property across documents. If `path` is provided, searches only that document.
+- `getFrontmatter`: Gets all frontmatter for a specific document.
+- `setFrontmatter`: Sets a frontmatter property. Use `undefined` to remove the property.
+
 ### IdeCapabilities
 
 Combine all providers into a single configuration:
@@ -199,13 +257,15 @@ Combine all providers into a single configuration:
 ```typescript
 interface IdeCapabilities {
   fileAccess: FileAccessProvider           // Required
-  userInteraction?: UserInteractionProvider // Required for apply_edit tool
+  edit?: EditProvider                      // 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
   globalFind?: GlobalFindProvider           // Enables global_find and global_replace tools
+  graph?: GraphProvider                     // Enables graph tools and resources
+  frontmatter?: FrontmatterProvider         // Enables frontmatter tools and resource
   onDiagnosticsChanged?: (callback: OnDiagnosticsChangedCallback) => void
 }
 ```
@@ -277,27 +337,71 @@ Replace all occurrences of text across the entire workspace.
 - Number of replacements made
 - Success status and message
 
+### `get_link_structure`
+
+Get all links in the workspace, showing relationships between documents.
+
+**Inputs:** None
+
+**Returns:**
+- Array of links with source URI, target URI, subpath, display text, resolved status, line, and column
+
+### `add_link`
+
+Add a link to a document by finding a text pattern and replacing it with a link.
+
+**Inputs:**
+- `path`: The path to the document to modify
+- `pattern`: The text pattern to find and replace with a link
+- `link_to`: The target URI the link should point to
+
+**Returns:**
+- Success status and message
+
+### `get_frontmatter_structure`
+
+Get frontmatter property values across documents.
+
+**Inputs:**
+- `property`: The frontmatter property name to search for (required)
+- `path`: Optional path to limit the search to a specific document
+
+**Returns:**
+- Array of matches with path and value
+
+### `set_frontmatter`
+
+Set a frontmatter property on a document.
+
+**Inputs:**
+- `path`: The path to the document to modify (required)
+- `property`: The frontmatter property name to set (required)
+- `value`: The value to set. Can be a string, number, boolean, array of these types, or null to remove the property.
+
+**Returns:**
+- Success status and message
+
 ## MCP Resources
 
 The SDK automatically registers resources based on which capabilities you provide:
 
-### `lsp://diagnostics/{path}`
+### `diagnostics://{path}`
 
 Get diagnostics (errors, warnings) for a specific file.
 
-**Resource URI Pattern:** `lsp://diagnostics/{+path}`
+**Resource URI Pattern:** `diagnostics://{+path}`
 
-**Example:** `lsp://diagnostics/src/main.ts`
+**Example:** `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`
+### `diagnostics://workspace`
 
 Get diagnostics across the entire workspace.
 
-**Resource URI:** `lsp://diagnostics/workspace`
+**Resource URI:** `diagnostics://workspace`
 
 Only available if your `DiagnosticsProvider` implements the optional `getWorkspaceDiagnostics()` method.
 
@@ -305,13 +409,13 @@ Returns workspace diagnostics grouped by file, formatted as markdown.
 
 **Subscription Support:** If your IDE implements `onDiagnosticsChanged` capability, this resource becomes subscribable.
 
-### `lsp://outline/{path}`
+### `outline://{path}`
 
 Get the document outline (symbol tree) for a file.
 
-**Resource URI Pattern:** `lsp://outline/{+path}`
+**Resource URI Pattern:** `outline://{+path}`
 
-**Example:** `lsp://outline/src/components/Button.tsx`
+**Example:** `outline://src/components/Button.tsx`
 
 Returns document symbols formatted as a hierarchical markdown outline, including:
 - Symbol names and kinds (class, function, method, etc.)
@@ -320,13 +424,61 @@ Returns document symbols formatted as a hierarchical markdown outline, including
 
 No subscription support for this resource (read-only).
 
-### `lsp://files/{path}`
+### `filetree://{path}`
+
+Get the complete file tree for a directory, excluding git-ignored files.
+
+**Resource URI Pattern:** `filetree://{+path}`
+
+**Example:** `filetree://src`, `filetree://.`
+
+Returns a JSON array of all file paths in the directory tree (recursive). Use "." for the root directory.
+
+No subscription support for this resource (read-only).
+
+### `files://{path}`
+
+For directories: returns directory children (git-ignored files excluded, similar to `ls`). For files: gets file content with optional line range.
+
+**Resource URI Pattern:** `files://{+path}`
+
+**Example:** `files://src`, `files://src/index.ts`, `files://src/index.ts#L1-L2`
+
+No subscription support for this resource (read-only).
+
+### `outlinks://{path}`
+
+Get outgoing links from a specific file.
+
+**Resource URI Pattern:** `outlinks://{+path}`
+
+**Example:** `outlinks://notes/index.md`
+
+Returns a JSON array of links originating from the specified document.
+
+No subscription support for this resource (read-only).
+
+### `backlinks://{path}`
 
-For directories: gets the file tree for a directory, excluding git-ignored files. For files: gets file content with optional line range.
+Get incoming links (backlinks) to a specific file.
 
-**Resource URI Pattern:** `lsp://files/{+path}`
+**Resource URI Pattern:** `backlinks://{+path}`
 
-**Example:** `lsp://files/src`, `lsp://files/src/index.ts`, `lsp://files/src/index.ts#L1-L2`
+**Example:** `backlinks://notes/topic-a.md`
+
+Returns a JSON array of links pointing to the specified document.
+
+No subscription support for this resource (read-only).
+
+### `frontmatter://{path}`
+
+Get frontmatter metadata for a specific file.
+
+**Resource URI Pattern:** `frontmatter://{+path}`
+
+**Example:** `frontmatter://notes/index.md`
+
+Returns a JSON object containing all frontmatter properties and values for the document.
 
 No subscription support for this resource (read-only).
 
@@ -415,6 +567,16 @@ interface Diagnostic {
   code?: string | number
 }
 
+interface Link {
+  sourceUri: UnifiedUri
+  targetUri: UnifiedUri
+  subpath?: string
+  displayText?: string
+  resolved: boolean
+  line: number
+  column: number
+}
+
 type EditResult =
   | { success: true; message: string }
   | { success: false; message: string; reason: 'UserRejected' | 'IOError' | 'ValidationFailed' }