# Lspi

> Use lspi (an MCP server) to give Codex LSP-powered semantic navigation and safe refactoring. Use this when you need symbol-level understanding (hover/definition/references/implementation/typeDefinition), or when doing a rename across a real codebase and you want a preview-first workflow.

- Skill: `latias94/lspi` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add latias94/lspi`
- Raw SKILL.md: https://api.skillmd.com/api/skills/latias94/lspi/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: latias94 (https://skillmd.com/u/latias94)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/latias94/lspi

---


# lspi (Giving AI the sight of LSP)

`lspi` bridges Language Server Protocol (LSP) capabilities to Codex via an MCP server over stdio.

## When to use

- You need semantic navigation: definition / references / implementation / type definition.
- You need call graph insights: incoming calls / outgoing calls (call hierarchy).
- You need quick type/doc info at a cursor: hover.
- You want to list symbols in a file or search symbols across the workspace.
- You want a safe rename workflow (preview first, apply only when confirmed).

## Core rules

- All `*_at` tools use **1-based** `line` / `character`.
- Prefer `*_at` tools when you have a cursor position: they apply bounded position fuzzing.
- For multi-language workspaces: `search_workspace_symbols` MUST include `file_path` if multiple language servers are configured.
- If `lspi` is started in read-only mode (`lspi mcp --read-only` or `mcp.read_only=true`), rename and server-control tools are disabled.
- `rename_symbol` / `rename_symbol_strict` defaults to preview (`dry_run=true`). Only apply edits when explicitly requested.
- If a tool call returns an error, look for `structuredContent.next_steps` and follow them (introspection tools + config hints).
- If you can run local commands, prefer `lspi doctor --workspace-root . --json` for a machine-readable environment/config report.
- After each tool call, briefly summarize what you did and what you got (method, key inputs like `file_path`/position, number of results, and whether output was truncated).
- Most tools accept `max_results` and `max_total_chars`. For reproducible behavior, set them explicitly when needed.
- For large result sets, consider disabling snippets (`include_snippet=false`) to keep outputs small and deterministic.
- If a generic LSP server returns empty/odd results, suggest tuning per-server config: `initialize_options`, `client_capabilities`, and `workspace_configuration`.

## Recommended workflow (read -> verify -> change)

1) Gather context:
   - `hover_at` (fast type/doc check)
   - `get_document_symbols` (what symbols exist in this file?)
   - `search_workspace_symbols` (find candidate symbols by name)
2) Verify target:
   - `find_definition_at` / `find_references_at`
   - optionally: `find_implementation_at` / `find_type_definition_at`
3) Change safely:
   - `rename_symbol_strict` (position-based) or `rename_symbol` (name-based)
   - start with `dry_run=true`, inspect the preview edit, then rerun with `dry_run=false`
4) Validate and recover:
   - `get_diagnostics`
   - `restart_server` or `stop_server` if the LSP process is stuck or needs to be released

## Tool cheat sheet

- Read-only:
  - `get_current_config`
  - `list_servers`
  - `get_server_status`
  - `hover_at`
  - `get_document_symbols`
  - `search_workspace_symbols`
  - `find_definition` / `find_definition_at`
  - `find_references` / `find_references_at`
  - `find_implementation_at`
  - `find_type_definition_at`
  - `find_incoming_calls` / `find_incoming_calls_at`
  - `find_outgoing_calls` / `find_outgoing_calls_at`
  - `get_diagnostics`
- Control:
  - `restart_server`
  - `stop_server`