@treedy/lsp-mcp 0.2.5 → 0.2.7

package/README.md

@@ -40,7 +40,7 @@ git_diagnostics
 - Language-specific refactor tools where needed:
   - Python: `python_move`, `python_change_signature`, `python_function_signature`
   - TypeScript: `typescript_move`, `typescript_function_signature`
-- Meta/admin tools: `status`, `list_backends`, `check_versions`, `update_backend`, `reload_config`, `switch_workspace`, `switch_workspace_for_language`, `discover_language_workspaces`, `doctor`, `expand_result`
+- Meta/admin tools: `status`, `list_backends`, `check_versions`, `update_backend`, `reload_config`, `switch_workspace`, `switch_workspace_for_language`, `discover_language_workspaces`, `semantic_session_start`, `doctor`, `expand_result`
 - Built-in prompts for agent workflows and best practices
 
 ## Tool Model (Current)
@@ -49,8 +49,14 @@ git_diagnostics
 
 Use these directly; language is inferred from file/path:
 
-- Navigation: `hover`, `definition`, `references`, `peek_definition`, `workspace_symbol`
-- Editing support: `completions`, `signature_help`, `rename`, `code_action`, `run_code_action`
+- Navigation: `hover`, `definition`, `implementation`, `type_definition`, `call_hierarchy`, `type_hierarchy`, `document_highlight`, `selection_range`, `folding_range`, `document_link`, `linked_editing_range`, `semantic_tokens`, `moniker`, `references`, `peek_definition`, `workspace_symbol`
+  - `type_hierarchy`, `semantic_tokens`, `linked_editing_range`, and `inlay_hint_resolve` use strict backend methods when available, otherwise return explicit `fallback_used=true` + `approximate=true` results.
+- Hinting: `inlay_hints`, `inlay_hint_resolve`, `read_file_with_hints`
+- Composite semantic workflow: `semantic_navigate` (optional search -> definition -> references -> read_file_with_hints)
+  - `mode='deep'` (default) runs full workflow; `mode='fast'` skips heavy hint reads unless explicitly requested
+  - `strategy='balanced'|'definition_first'|'references_first'` controls step ordering for latency/recall tradeoffs
+- Incremental diagnostics: `diagnostics_delta` (delta vs previous diagnostics snapshot)
+- Editing support: `completions`, `signature_help`, `prepare_rename`, `rename`, `code_action`, `run_code_action`, `code_lens`
 - Analysis: `diagnostics`, `git_diagnostics`, `symbols`, `search`, `summarize_file`, `read_file_with_hints`, `project_structure`
 - Sync/edit loop: `update_document`
 
@@ -63,7 +69,13 @@ For large repos, use preview arguments to reduce token usage:
 
 - `search` / `workspace_symbol`: `preview_limit` or `page_size` (default `200`), plus `cursor` for next page
 - `diagnostics`: `preview_limit` or `page_size` (default `200`), `summary_only` (default `false`), plus `cursor`
+- `diagnostics_delta`: `preview_limit`/`page_size` plus optional `severity`, `source`, `hotspot_limit` filters, and `cursor` for paged change items
+  - Returns `delta.file_summary[]` and `delta.top_hotspots[]` for per-file triage in large workspaces
 - `doctor`: `page_size` (default `50`) plus `cursor` for long environment reports
+- `doctor`: set `check_latest_versions=true` to probe registry latest version drift (slower, network-dependent)
+- `doctor`: use `capability_snapshot_id` to reuse probed capability matrix and skip repeated backend capability probing
+- Strict semantic errors include structured `recovery_plan[]` (`type`, `tool`, `args`, `command`) and cost fields: `latency_ms`, `result_size`, `truncated`, `cursor_available`
+- Semantic responses include `confidence` and `confidence_reason` for fallback/approximation awareness
 - `project_structure`: `max_depth` (default `3`), `max_entries` (default `300`)
 - `summarize_file`: `max_symbols` (default `200`)
 - `read_file_with_hints`: `start_line` (default `1`), `max_lines` (default `300`)
@@ -74,6 +86,40 @@ Paged responses include:
 - `next`: ready-to-call arguments for the next page (via `expand_result`)
 - Cursors are signed and expire automatically (TTL-based) for safer paging.
 
+Strict semantic error shape (example):
+
+```json
+{
+  "error": "LANGUAGE_WORKSPACE_REQUIRED",
+  "error_code": "LANGUAGE_WORKSPACE_REQUIRED",
+  "tool": "hover",
+  "strict_mode": true,
+  "resolved_language": "typescript",
+  "resolved_workspace": null,
+  "next_step": "Call switch_workspace_for_language(language='typescript', path='/abs/project/root') before using semantic tools.",
+  "recovery_plan": [
+    {
+      "step": 1,
+      "action": "set_language_workspace",
+      "type": "tool_call",
+      "tool": "switch_workspace_for_language",
+      "args": {
+        "language": "typescript",
+        "path": "/abs/project/root"
+      },
+      "command": "switch_workspace_for_language(language='typescript', path='/abs/project/root')",
+      "reason": "Semantic tools require an explicit per-language workspace mapping."
+    }
+  ],
+  "latency_ms": null,
+  "result_size": 0,
+  "cursor_available": false,
+  "truncated": false,
+  "confidence": 0.25,
+  "confidence_reason": "Strict workspace precondition failed; no semantic result available."
+}
+```
+
 ### Language-specific tools
 
 - Python-only: `python_move`, `python_change_signature`, `python_function_signature`
@@ -81,10 +127,79 @@ Paged responses include:
 
 ### Server/meta tools
 
-- `status`, `list_backends`, `start_backend`, `update_backend`, `check_versions`, `reload_config`, `switch_python_backend`, `switch_workspace`, `switch_workspace_for_language`, `discover_language_workspaces`, `doctor`, `expand_result`
+- `status`, `list_backends`, `start_backend`, `update_backend`, `check_versions`, `reload_config`, `switch_python_backend`, `switch_workspace`, `switch_workspace_for_language`, `discover_language_workspaces`, `semantic_session_start`, `doctor`, `expand_result`
 - `discover_language_workspaces` input: `root` (optional), `max_depth` (optional, default `2`), `apply` (optional, default `false`)
+- `semantic_session_start` input: `language` (optional), `workspace` (optional), `file` (optional), `start_backend` (optional, default `true`)
 - In mixed-language monorepos, semantic tools require language workspace mapping (set via `switch_workspace_for_language` or `discover_language_workspaces(..., apply=true)`).
 - `doctor` now includes `workspaceDependencyChecks.language_workspace_discovery` with suggested per-language workspace commands.
+- `doctor` includes `backendPackageDrift` to show installed backend version vs latest policy and upgrade next steps.
+- `doctor` includes `backendVersionSummary` (stable schema with `schema_version`, `counts`, `by_language`, `lookup_stats`) for quick LLM triage.
+- `doctor` includes `workspaceDependencyChecks.python_bundled_runtime` in bundled mode, with optional executable probe results when `probe_backends=true`.
+- `doctor` includes `benchmarkInsights` from the latest benchmark report (`.tmp/benchmark-latest.json` by default) for runtime budget recommendations.
+  - If baseline exists (`.tmp/benchmark-baseline.json` by default), `benchmarkInsights.trend` includes regression/improvement deltas.
+- `doctor` includes `llmSemanticDefaults` with ready-to-use parameter presets for:
+  - `semantic_navigate` (`mode`, `strategy`, `page_size`, `reference_preview`, `hint_max_lines`)
+  - `diagnostics_delta` (`page_size`, `preview_limit`, `hotspot_limit`)
+  - plus `rationale[]` explaining why these defaults were chosen
+
+Example fields exposed for client/LLM orchestration:
+
+```json
+{
+  "backend_runtime_mode": "registry",
+  "backend_packages": [
+    {
+      "language": "typescript",
+      "package": "@treedy/typescript-lsp-mcp",
+      "package_ref": "@treedy/typescript-lsp-mcp@latest",
+      "registry": "npm",
+      "resolver": "npx",
+      "provider": "typescript-lsp-mcp",
+      "install_command": "npx --yes @treedy/typescript-lsp-mcp@latest",
+      "update_command": "npx --yes @treedy/typescript-lsp-mcp@latest",
+      "default_channel": "latest",
+      "auto_update_enabled": true,
+      "minimum_supported_version": "0.1.0"
+    }
+  ],
+  "backendPackageDrift": {
+    "typescript": {
+      "installed_version": "0.2.0",
+      "minimum_supported_version": "0.1.0",
+      "minimum_status": "supported",
+      "drift_status": "policy_aligned",
+      "latest_registry_version": "0.2.0",
+      "latest_status": "up_to_date",
+      "next_step": "No action needed.",
+      "latest_next_step": "Installed version matches latest policy."
+    }
+  },
+  "backendVersionSummary": {
+    "schema_version": 1,
+    "check_latest_versions": true,
+    "lookup_stats": {
+      "schema_version": 1,
+      "enabled": true,
+      "cache_ttl_ms": 300000,
+      "requested": 3,
+      "cache_hits": 2,
+      "inflight_hits": 0,
+      "executed": 1,
+      "succeeded": 1,
+      "failed": 0,
+      "skipped": 0
+    },
+    "counts": {
+      "languages": 3,
+      "below_minimum": 0,
+      "outdated": 0,
+      "policy_drift": 0,
+      "bundled_static": 0,
+      "unknown_latest": 0
+    }
+  }
+}
+```
 
 ## Prompts (Skills)
 
@@ -109,6 +224,8 @@ You can configure with env vars or `.lsp-mcp.json` in your workspace.
 | `LSP_MCP_TYPESCRIPT_ENABLED` | `true` | Enable TypeScript backend |
 | `LSP_MCP_VUE_ENABLED` | `true` | Enable Vue backend |
 | `LSP_MCP_AUTO_UPDATE` | `true` | Update backend packages to latest on startup/update |
+| `LSP_MCP_BACKEND_RUNTIME_MODE` | `registry` | Backend runtime strategy: `registry` (default), `auto`, `bundled` |
+| `LSP_MCP_REQUIRE_BUNDLED_BACKENDS` | `false` | Legacy strict bundled mode (equivalent to runtime mode `bundled`) |
 | `LSP_MCP_EAGER_START` | `false` | Start all enabled backends when server boots |
 | `LSP_MCP_IDLE_TIMEOUT` | `600` | Backend idle timeout in seconds |
 
@@ -123,14 +240,18 @@ When `LSP_MCP_AUTO_UPDATE=true`:
 
 ### Runtime dependency expectations
 
-- Lean mode (default): backend packages are fetched when first used.
+- Lean mode (default): backend packages are fetched when first used (`LSP_MCP_BACKEND_RUNTIME_MODE=registry`).
+- Bundled mode: set `LSP_MCP_BACKEND_RUNTIME_MODE=bundled` or `LSP_MCP_REQUIRE_BUNDLED_BACKENDS=true`.
 - Required host tools:
-  - TypeScript/Vue/Pyright backends: `node` + `npx`
-  - Python backend: `uv` (or `uvx`)
+- TypeScript/Vue/Pyright backends: `node` + `npx`
+- Python backend: `uv` (or `uvx`)
 - Vue semantic features additionally require project-local deps in the Vue workspace:
   - `typescript`
   - `@vue/language-server`
 - Use `doctor` to get structured dependency checks and install commands.
+- Optional benchmark paths:
+  - `LSP_MCP_BENCHMARK_REPORT_PATH` (default `.tmp/benchmark-latest.json`)
+  - `LSP_MCP_BENCHMARK_BASELINE_PATH` (default `.tmp/benchmark-baseline.json`)
 
 ## Better Out-of-Box Experience (Recommended)
 
@@ -146,6 +267,11 @@ When `LSP_MCP_AUTO_UPDATE=true`:
 # Install deps
 bun install
 
+# Machine-readable benchmark report
+bun run benchmark:report
+# Optional trend diff (compare with .tmp/benchmark-baseline.json)
+bun run benchmark:diff
+
 # Build local dist/ (lean default, no bundled backends)
 bun run build