@treedy/lsp-mcp 0.2.6 → 0.2.8

package/README.md

@@ -50,7 +50,12 @@ git_diagnostics
 Use these directly; language is inferred from file/path:
 
 - 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`
@@ -64,8 +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`)
@@ -76,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`
@@ -89,7 +133,15 @@ Paged responses include:
 - 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` (counts + per-language concise status + latest lookup stats) for quick LLM triage.
+- `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.
+  - If benchmark cases include `*_cold` and `*_warm` pairs, `benchmarkInsights.warmup` summarizes warm-start 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:
 
@@ -122,6 +174,30 @@ Example fields exposed for client/LLM orchestration:
       "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
+    }
   }
 }
 ```
@@ -168,12 +244,15 @@ When `LSP_MCP_AUTO_UPDATE=true`:
 - 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)
 
@@ -189,6 +268,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