LSP Auto-Detect

Zero-config language, workspace root, and server-availability detection for LSP-driven agents

Zero-config helpers that pick the right language server, its real project root, and tell you plainly when it isn’t installed.

from praisonaiagents import Agent
from praisonaiagents.tools import lsp_definition

agent = Agent(
    name="Coder",
    instructions="Navigate the codebase with LSP accuracy.",
    tools=[lsp_definition],
)

agent.start("Where is `authenticate` defined in this monorepo?")
# The LSP client now finds the nearest pyproject.toml / go.mod / Cargo.toml
# on its own; no rootUri configuration needed.

Quick Start

1. Let the agent do it (nothing to configure)

   from praisonaiagents import Agent
   from praisonaiagents.tools import lsp_definition, lsp_references
   
   agent = Agent(
       name="Coder",
       instructions="Find definitions and references before editing.",
       tools=[lsp_definition, lsp_references],
   )
   agent.start("What calls `parse_config`?")

2. Detect language and root yourself (advanced)

   from praisonaiagents.lsp import detect_language, detect_root_uri
   
   detect_language("services/auth/main.go")     # → "go"
   detect_root_uri("services/auth/main.go")      # → "file:///abs/path/to/repo"  (nearest go.mod)

3. Probe availability before you use LSP

   from praisonaiagents.lsp import probe
   
   available, command, install_hint = probe("rust")
   # → (False, "rust-analyzer", "rustup component add rust-analyzer")
   if not available:
       print(f"Install `{command}` first: {install_hint}")

4. Talk to the client directly with a workspace-aware root

   import asyncio
   from praisonaiagents.lsp import LSPClient
   
   client = LSPClient(language="python", workspace_file="services/api/mod.py")
   started = asyncio.run(client.start())
   if not started:
       print(client.last_error)
       # "language server `pylsp` not found on PATH; install with `pip install python-lsp-server`"

How It Works

Each language maps to a default server, its file extensions, and the root markers that pin a project root — the nearest marker wins.

Adding or Overriding a Language Server

Register a new language or swap a built-in server by passing servers= — no package source edits needed.

import asyncio
from praisonaiagents.lsp import LSPClient

# Register Java once; the LSP layer honours the extension, root markers,
# install hint, and initialization options from this entry.
JAVA_SERVERS = {
    "java": {
        "command": "jdtls",
        "args": ["--stdio"],
        "extensions": [".java"],
        "root_markers": ["pom.xml", ".git"],
        "install_hint": "install eclipse.jdt.ls",
    }
}

client = LSPClient(language="java", servers=JAVA_SERVERS)
started = asyncio.run(client.start())
if not started:
    print(client.last_error)
    # "language server `jdtls` not found on PATH; install with `install eclipse.jdt.ls`"

Four Ways to Configure

from praisonaiagents.lsp import LSPClient

LSPClient(language="java", servers={
    "java": {
        "command": "jdtls",
        "args": ["--stdio"],
        "extensions": [".java"],
        "root_markers": ["pom.xml"],
    }
})

from praisonaiagents.lsp import LSPClient

# Swap the Python server for Pyright.
LSPClient(language="python", servers={
    "python": {"command": "pyright-langserver", "args": ["--stdio"]}
})
# Extensions, root markers, and install hint fall back to the built-in `python` row.

from praisonaiagents.lsp import LSPClient

# `initialization_options` are picked up automatically when you don't pass your own.
LSPClient(language="java", servers={
    "java": {
        "command": "jdtls",
        "args": ["--stdio"],
        "extensions": [".java"],
        "root_markers": ["pom.xml"],
        "initialization_options": {"bundles": []},
    }
})

from praisonaiagents.lsp import resolve_servers

merged = resolve_servers({
    "java": {"command": "jdtls", "args": ["--stdio"], "extensions": [".java"]}
})
merged["python"]["command"]   # → "pylsp"   (built-in kept)
merged["java"]["command"]     # → "jdtls"   (added)

How the Merge Works

User entries override built-ins per language key; unset fields fall back to the built-in row.

DEFAULT_SERVERS is never mutated by a merge — resolve_servers({...}) always returns a fresh dict.

Which Configuration Style?

User Interaction Flow

A registered language behaves exactly like a built-in one.

User: “Where is AuthService.login defined in this Maven repo?” Agent uses a Java LSP client registered via servers=, which finds the nearest pom.xml for the root and queries jdtls. Tool returns: src/main/java/com/acme/AuthService.java:42:5 Agent replies: “AuthService.login is defined in src/main/java/com/acme/AuthService.java at line 42.”

Which Helper Should I Use?

Public API Surface

These are pure helpers plus one new keyword and one new attribute on LSPClient.

Common Patterns

Guarded startup logging — log what the LSP layer would do for each language:

from praisonaiagents.lsp import probe

for lang in ("python", "typescript", "go", "rust"):
    ok, cmd, hint = probe(lang)
    print(f"{lang}: {'ok' if ok else 'missing'} ({cmd or 'no server'})")

Monorepo-aware navigation — prove you’re pointing at the right project root:

from praisonaiagents.lsp import detect_root_uri

assert detect_root_uri("services/api/mod.py").endswith("/services/api")

Fallback to grep with a real reason — surface client.last_error so the model picks a fallback intelligently:

import asyncio
from praisonaiagents.lsp import LSPClient

client = LSPClient(language="go", workspace_file="services/auth/main.go")
if not asyncio.run(client.start()):
    print(f"LSP unavailable — {client.last_error}. Falling back to grep.")

Best Practices

Related