lspi

name	lspi
description	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.
metadata	{"short-description":"LSP semantic navigation via MCP"}

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