LSP Assist

Precise code navigation via Language Server Protocol.

Modes

| Mode | How | When to use | |------|-----|-------------| | Daemon (recommended) | daemon --port 9876 then HTTP queries | Multiple queries in a session (start once, query many) | | One-shot | goto/refs/hover/diag/symbols directly | Single quick query, or scripting |

Requirements

• Runtime: Python 3.10+ (standard library only)
• OS: Linux, macOS
• Language servers (install separately):
  • TypeScript: npm i -g typescript-language-server typescript
  • Python: pip install pyright
• Project config:
  • TypeScript: tsconfig.json in project root
  • Python: pyproject.toml or pyrightconfig.json

Security

Binding

Daemon binds to 127.0.0.1 only — no external/remote access:

server = HTTPServer(("127.0.0.1", port), DaemonHandler)

File Access Control

All file reads go through _open_file(), which enforces project-root containment:

def _open_file(self, filepath: str):
    path = Path(filepath).resolve()          # resolve symlinks, .., etc.
    if str(path) in self._opened_files:
        return                               # skip duplicate opens
    common = os.path.commonpath([str(path), self.root_path])
    if common != self.root_path:             # must be direct ancestor of root
        raise ValueError(f"File outside project root: {path}")
    # Only then: read file content and send didOpen to language server

• Path.resolve() canonicalizes the path (resolves symlinks, .., ~)
• os.path.commonpath rejects sibling dirs (e.g. /root/openclaw-backup/ when root is /root/openclaw)
• Tested against: symlink escape, .. traversal, trailing-slash differences, sibling-prefix collision

Auth Token (optional)

When --token <secret> is passed, every HTTP request must include Authorization: Bearer <secret>:

def _check_auth(self) -> bool:
    expected = getattr(self.server, "auth_token", None)
    if expected is None:
        return True                          # no token required
    header = self.headers.get("Authorization", "")
    if header == f"Bearer {expected}":
        return True
    self._respond({"error": "unauthorized"}, 401)
    return False

• Checked in both do_GET and do_POST before any handler logic
• Without --token, daemon is open on localhost (intended for local single-user use)

Shutdown Handling

elif self.path == "/shutdown":
    self._respond({"status": "shutting down"})
    threading.Thread(target=lambda: (time.sleep(0.5), os._exit(0)), daemon=True).start()

Responds first, then exits after 0.5s delay to ensure the HTTP response is flushed.

Process Isolation

• One-shot mode: fresh server per query, auto-terminates (15s timeout)
• Daemon mode: persistent server, but is_alive() check returns 503 if the language server crashes
• Language server communication is local stdio only

Quick Reference

Daemon Mode (recommended for multi-query)

# Start daemon (blocks, run in background or separate terminal)
python3 scripts/lsp_client.py daemon --lang typescript --root /path/to/project --port 9876

# Start with auth token (requests need Bearer token)
python3 scripts/lsp_client.py daemon --lang typescript --root /path/to/project --port 9876 --token mysecret

# Query via HTTP (all output JSON)
curl -s http://127.0.0.1:9876/goto   -d '{"file":"src/main.ts","line":10,"col":5}'
curl -s http://127.0.0.1:9876/refs   -d '{"file":"src/main.ts","line":10,"col":5}'
curl -s http://127.0.0.1:9876/hover  -d '{"file":"src/main.ts","line":10,"col":5}'
curl -s http://127.0.0.1:9876/diag   -d '{"file":"src/main.ts"}'
curl -s http://127.0.0.1:9876/symbols -d '{"query":"UserService"}'
curl -s http://127.0.0.1:9876/shutdown
curl -s http://127.0.0.1:9876/ping   # health check

# With auth token
curl -s -H "Authorization: Bearer mysecret" http://127.0.0.1:9876/ping

One-shot Mode

| Action | Command | |--------|---------| | Go to definition | python3 scripts/lsp_client.py --lang ts --root <dir> goto --file <f> --line <n> --col <n> | | Find references | python3 scripts/lsp_client.py --lang ts --root <dir> refs --file <f> --line <n> --col <n> | | Hover type info | python3 scripts/lsp_client.py --lang ts --root <dir> hover --file <f> --line <n> --col <n> | | Diagnostics | python3 scripts/lsp_client.py --lang ts --root <dir> diag --file <f> | | Symbol search | python3 scripts/lsp_client.py --lang ts --root <dir> symbols [--query <text>] |

Language shorthand: --lang typescript or --lang ts or --lang python.

Output Format

All commands output JSON for structured consumption:

// goto / refs
[{"file": "/path/to/file.ts", "line": 42, "col": 10}]

// hover
"function foo(bar: string): number"

// diag
[{"severity": "ERROR", "line": 10, "message": "Cannot find name 'x'"}]

// symbols
[{"name": "UserService", "kind": 5, "file": "/path/to/file.ts", "line": 12, "container": "models"}]

When to Use vs Grep

| Scenario | Use | |----------|-----| | "Where is this function defined?" | LSP goto | | "Who calls this function?" | LSP refs | | "What type is this variable?" | LSP hover | | "Any compile errors?" | LSP diag | | "Find all classes matching X" | LSP symbols | | "Search for text pattern 'TODO'" | grep | | "Find all .json files" | glob | | "Search across non-code files" | grep |

Supported Languages

| Language | Server | Install | |----------|--------|---------| | TypeScript/JavaScript | typescript-language-server | npm i -g typescript-language-server typescript | | Python | pyright | pip install pyright |

Adding a language: edit SERVERS dict in lsp_client.py — add the server command and file extensions.