@theupsider/lsp-mcp 1.0.9 → 1.1.0

package/README.md

@@ -32,6 +32,9 @@ A Model Context Protocol (MCP) server that gives language models access to **Lan
 
 - **🔍 Automatic Language Detection** — Scans project root for language markers (`package.json`, `Cargo.toml`, `go.mod`, etc.)
 - **🔄 Auto Language Server Selection** — Hardcoded mapping with fallback servers; installs missing LSPs automatically
+- **🤖 Hands-Free Initialization** — Clients that support [MCP Roots](https://modelcontextprotocol.io/docs/concepts/roots) auto-initialize on connect — `lsp_init` disappears from the tool list once all servers start cleanly
+- **💾 Cross-Session Persistence** — Initialized workspaces and their ready languages are remembered across server restarts
+- **🔁 Graceful Degradation** — `lsp_init` reappears if a previously-working server starts failing (e.g. language added, binary missing)
 - **🛠 12 LSP Tools** — Definition, references, symbols, diagnostics, rename, code actions, formatting, and more
 - **📝 Read & Write Operations** — Both inspection and modification of code via LSP
 - **🌐 Polyglot Support** — Multiple language servers run simultaneously in the same project
@@ -45,10 +48,10 @@ A Model Context Protocol (MCP) server that gives language models access to **Lan
 
 ```bash
 # npm
-npm install -g @theupsider/lsp-mcp
+npm install -g @theupsider/lsp-mcp@latest
 
 # bun
-bun install -g @theupsider/lsp-mcp
+bun install -g @theupsider/lsp-mcp@latest
 ```
 
 ## Quickstart
@@ -63,7 +66,7 @@ Add to your **workspace** `.vscode/mcp.json` (recommended — ensures the server
     "lsp-mcp": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@theupsider/lsp-mcp"]
+      "args": ["-y", "@theupsider/lsp-mcp@latest"]
     }
   }
 }
@@ -78,7 +81,9 @@ Add to your **workspace** `.vscode/mcp.json` (recommended — ensures the server
 lsp-mcp
 ```
 
-The server starts with no active project. The first action the model must take is calling `lsp_init`:
+The server starts with no active project. **Most clients auto-initialize** when they support the MCP Roots protocol (VS Code, Copilot, etc.), but `lsp_init` remains available as a manual override.
+
+For clients without Roots support, the first action the model must take is calling `lsp_init`:
 
 ```
 lsp_init({ root: "/path/to/your/project" })
@@ -87,7 +92,7 @@ lsp_init({ root: "/path/to/your/project" })
 `lsp_init` will:
 
 1. Scan the root for language markers and start matching language servers (best-effort)
-2. Disappear from the tool list — subsequent calls to any LSP tool trigger lazy server startup for that file's language if no server was detected at init time
+2. Disappear from the tool list when you called it explicitly — subsequent calls to any LSP tool trigger lazy server startup for that file's language if no server was detected at init time
 3. Return health status for all servers that were started eagerly
 
 **Optional: pre-warm specific languages** (skips detection, faster cold start):
@@ -96,36 +101,40 @@ lsp_init({ root: "/path/to/your/project" })
 lsp_init({ root: "/path/to/project", languages: ["python", "typescript"] })
 ```
 
+**Persistence:** Once initialized, the workspace configuration (detected languages) is saved to your OS-standard config directory (`~/.config/lsp-mcp/` on Linux, `~/Library/Application Support/lsp-mcp/` on macOS, `%APPDATA%\lsp-mcp\` on Windows). On subsequent server startups, the MCP server will automatically reconnect using the last-known root, so you rarely need to call `lsp_init` again.
+
+**Re-emergence:** If a language server that was previously healthy fails to start (e.g. you added a new language or removed a binary), `lsp_init` will reappear in the tool list, signaling the model should re-initialize.
+
 ## Available Tools
 
 ### Read-Only Tools
 
-| Tool                    | Description                             | Key Parameters                                         |
-| ----------------------- | --------------------------------------- | ------------------------------------------------------ |
-| `lsp_init`              | Initialize server for a project root    | `root` (required), `languages` (optional string array) |
-| `lsp_definition`        | Go to definition                | `file`, `line`, `character`           |
-| `lsp_references`        | Find all references             | `file`, `line`, `character`           |
-| `lsp_document_symbols`  | List symbols in a file          | `file`                                |
-| `lsp_workspace_symbols` | Search symbols across workspace | `query` (limit: 100–500 results)      |
-| `lsp_diagnostics`       | Get errors & warnings           | `file` (scope: `file` or `workspace`) |
-| `lsp_type_definition`   | Go to type definition           | `file`, `line`, `character`           |
-| `lsp_implementation`    | Find implementations            | `file`, `line`, `character`           |
-| `lsp_health`            | Check status of all LSP servers | _(none)_                              |
+| Tool                    | Description                          | Key Parameters                                         | Visibility                                                       |
+| ----------------------- | ------------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------- |
+| `lsp_init`              | Initialize server for a project root | `root` (required), `languages` (optional string array) | Conditional — hidden after a successful explicit `lsp_init` call |
+| `lsp_definition`        | Go to definition                     | `file`, `line`, `character`                            | Always                                                           |
+| `lsp_references`        | Find all references                  | `file`, `line`, `character`                            | Always                                                           |
+| `lsp_document_symbols`  | List symbols in a file               | `file`                                                 | Always                                                           |
+| `lsp_workspace_symbols` | Search symbols across workspace      | `query` (limit: 100–500 results)                       | Always                                                           |
+| `lsp_diagnostics`       | Get errors & warnings                | `file` (scope: `file` or `workspace`)                  | Always                                                           |
+| `lsp_type_definition`   | Go to type definition                | `file`, `line`, `character`                            | Always                                                           |
+| `lsp_implementation`    | Find implementations                 | `file`, `line`, `character`                            | Always                                                           |
+| `lsp_health`            | Check status of all LSP servers      | _(none)_                                               | Always                                                           |
 
 ### Write Tools
 
-| Tool                       | Description               | Key Parameters                         |
-| -------------------------- | ------------------------- | -------------------------------------- |
-| `lsp_rename`               | Rename symbol             | `file`, `line`, `character`, `newName` |
-| `lsp_code_action`          | Apply / list code actions | `file`, `line`, `character`, `apply`   |
-| `lsp_formatting`           | Format document           | `file`                                 |
-| `lsp_range_formatting`     | Format code range         | `file`, `range`                        |
+| Tool                   | Description               | Key Parameters                         |
+| ---------------------- | ------------------------- | -------------------------------------- |
+| `lsp_rename`           | Rename symbol             | `file`, `line`, `character`, `newName` |
+| `lsp_code_action`      | Apply / list code actions | `file`, `line`, `character`, `apply`   |
+| `lsp_formatting`       | Format document           | `file`                                 |
+| `lsp_range_formatting` | Format code range         | `file`, `range`                        |
 
 ## Configuration
 
-| Environment Variable | Description                         | Default      |
-| -------------------- | ----------------------------------- | ------------ |
-| `LSP_MCP_LOG_LEVEL`  | Log level: `error`, `info`, `debug` | `info`       |
+| Environment Variable | Description                         | Default |
+| -------------------- | ----------------------------------- | ------- |
+| `LSP_MCP_LOG_LEVEL`  | Log level: `error`, `info`, `debug` | `info`  |
 
 ## Setup Scripts
 

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

@@ -45,6 +45,9 @@ function getHandler(schema) {
         throw new Error(`No handler registered for schema`);
     return call[1];
 }
+async function flushAutoInit() {
+    await new Promise((resolve) => setImmediate(resolve));
+}
 describe("McpServer", () => {
     beforeEach(() => {
         jest.clearAllMocks();
@@ -87,7 +90,7 @@ describe("McpServer", () => {
         expect(result.tools.map((t) => t.name)).toContain("lsp_init");
         expect(result.tools.map((t) => t.name)).toContain("lsp_definition");
     });
-    it("hides lsp_init after successful auto-init (all servers ready)", async () => {
+    it("keeps lsp_init visible after successful auto-init (all servers ready)", async () => {
         const readTools = jest.requireMock("../tools/read-tools")
             .registerReadTools;
         const writeTools = jest.requireMock("../tools/write-tools")
@@ -114,11 +117,11 @@ describe("McpServer", () => {
         const { ListToolsRequestSchema } = jest.requireActual("@modelcontextprotocol/sdk/types.js");
         const server = new server_1.McpServer("info", factory);
         await server.start();
-        // Trigger the oninitialized callback
-        await mockInnerServer.oninitialized();
+        mockInnerServer.oninitialized();
+        await flushAutoInit();
         const listHandler = getHandler(ListToolsRequestSchema);
         const result = await listHandler({});
-        expect(result.tools.map((t) => t.name)).not.toContain("lsp_init");
+        expect(result.tools.map((t) => t.name)).toContain("lsp_init");
         expect(result.tools.map((t) => t.name)).toContain("lsp_definition");
     });
     it("keeps lsp_init visible after auto-init when a server has errors", async () => {
@@ -147,7 +150,8 @@ describe("McpServer", () => {
         const { ListToolsRequestSchema } = jest.requireActual("@modelcontextprotocol/sdk/types.js");
         const server = new server_1.McpServer("info", factory);
         await server.start();
-        await mockInnerServer.oninitialized();
+        mockInnerServer.oninitialized();
+        await flushAutoInit();
         const listHandler = getHandler(ListToolsRequestSchema);
         const result = await listHandler({});
         expect(result.tools.map((t) => t.name)).toContain("lsp_init");
@@ -166,9 +170,43 @@ describe("McpServer", () => {
         mockGetClientCapabilities.mockReturnValue(undefined); // no roots capability
         const server = new server_1.McpServer("info", factory);
         await server.start();
-        await mockInnerServer.oninitialized();
+        mockInnerServer.oninitialized();
+        await flushAutoInit();
         expect(manager.start).toHaveBeenCalled();
-        expect(server.isInitToolHidden()).toBe(true);
+        expect(server.isInitToolHidden()).toBe(false);
+    });
+    it("hides lsp_init after a successful explicit init", async () => {
+        const readTools = jest.requireMock("../tools/read-tools")
+            .registerReadTools;
+        const writeTools = jest.requireMock("../tools/write-tools")
+            .registerWriteTools;
+        readTools.mockImplementationOnce((registrar, _lifecycle, options) => {
+            registrar.registerTool("lsp_init", { description: "init" }, async (args) => {
+                const result = await options.initializeManager(args.root);
+                return {
+                    content: [{ type: "text", text: result.root }],
+                    raw: result,
+                };
+            });
+        });
+        writeTools.mockImplementationOnce(() => undefined);
+        const health = [{ language: "typescript", status: "ready" }];
+        const manager = {
+            start: jest.fn().mockResolvedValue(undefined),
+            shutdown: jest.fn().mockResolvedValue(undefined),
+            getHealth: jest.fn().mockReturnValue(health),
+        };
+        const factory = jest.fn().mockReturnValue(manager);
+        const { CallToolRequestSchema, ListToolsRequestSchema } = jest.requireActual("@modelcontextprotocol/sdk/types.js");
+        const server = new server_1.McpServer("info", factory);
+        await server.start();
+        const callHandler = getHandler(CallToolRequestSchema);
+        await callHandler({
+            params: { name: "lsp_init", arguments: { root: "/workspace/project" } },
+        });
+        const listHandler = getHandler(ListToolsRequestSchema);
+        const result = await listHandler({});
+        expect(result.tools.map((t) => t.name)).not.toContain("lsp_init");
     });
     it("returns no-root error for non-init tools before initialization", async () => {
         const readTools = jest.requireMock("../tools/read-tools")

package/dist/mcp/server.js

@@ -44,8 +44,8 @@ class McpServer {
         (0, read_tools_1.registerReadTools)(registrar, lifecycleProxy, {
             initializeManager: async (root, languages) => {
                 const result = await this.initializeManager(root, languages);
-                // When lsp_init is called explicitly, hide it on success, re-expose on error
-                this.updateInitVisibility(result.health);
+                // Hide lsp_init only after an explicit init call.
+                this.updateInitVisibility(result.health, "explicit");
                 await this.server.server.sendToolListChanged();
                 return result;
             },
@@ -53,9 +53,12 @@ class McpServer {
         (0, write_tools_1.registerWriteTools)(registrar, lifecycleProxy);
         this.configureToolHandlers();
         // Hook into post-handshake to attempt auto-init from roots or persisted config.
-        // Cast to `() => void` to satisfy the SDK type while still returning the promise
-        // so test harnesses can await it when needed.
-        this.server.server.oninitialized = (() => this.tryAutoInit());
+        const onInitialized = async () => {
+            await this.tryAutoInit();
+        };
+        this.server.server.oninitialized = () => {
+            void onInitialized();
+        };
         // Handle roots/list_changed: client switched workspace
         this.server.server.setNotificationHandler(types_js_1.RootsListChangedNotificationSchema, async () => {
             await this.tryAutoInitFromRoots();
@@ -94,9 +97,9 @@ class McpServer {
     isInitToolHidden() {
         return this.hideInitTool;
     }
-    updateInitVisibility(health) {
+    updateInitVisibility(health, source) {
         const hasErrors = health.some((entry) => entry.status === "error");
-        this.hideInitTool = !hasErrors;
+        this.hideInitTool = source === "explicit" && !hasErrors;
     }
     async tryAutoInit() {
         // Prefer roots from the client if supported
@@ -134,7 +137,7 @@ class McpServer {
         const saved = await (0, workspace_config_1.loadWorkspaceConfig)(root);
         const languages = saved?.languages;
         const result = await this.initializeManager(root, languages);
-        this.updateInitVisibility(result.health);
+        this.updateInitVisibility(result.health, "auto");
         // Persist successful init so we can restore on next startup
         const readyLanguages = result.health
             .filter((e) => e.status === "ready")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theupsider/lsp-mcp",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "description": "Universal LSP MCP server",
   "license": "Apache-2.0",
   "type": "commonjs",