DEV Community

Fernando Paladini
Fernando Paladini

Posted on

Stop Grepping Symbol Names: I Shipped Locus, a Lightweight MCP Server for AI Coding Agents

TL;DR — AI agents are great at editing files, but grep is the wrong tool for definitions, references, and types. Locus is an open-source MCP server that exposes six language-server tools to Cursor, Claude Code, and other MCP hosts. Install with npx @paladini/locus-mcp. v0.1.5 is out now.

If you use Cursor, Claude Code, or Codex, you have probably watched your agent do this:

  1. Grep for UserService
  2. Open three files
  3. Read 400 lines
  4. Still pick the wrong definition

That is not a model problem. Text search is not semantic navigation.

Your IDE already knows where symbols are defined — it uses a language server. Your agent does not, unless you give it one.

So I built Locus: a small MCP server that connects AI agents to the same LSP intelligence your editor uses, through six focused tools and compact output.

No symbolic editing. No agent memory. No second IDE inside MCP.

Just the map.

The problem Locus solves

Task Grep / read files Locus (LSP)
Where is Foo.bar defined? Every text match Real definition via compiler
Who calls this function? Regex hope All references
What type is this? Guess from names Hover / type info
Did my edit break the build? Wait for CI Diagnostics on changed files

Grep stays essential for logs, configs, and comments. Locus is for typed code symbols — the places where the language server already has the answer.

What Locus is (and is not)

Locus is:

  • An MCP server (@paladini/locus-mcp on npm)
  • Six tools: locate, refs, hover, diagnostics, status, rename
  • Compact line output agents can scan fast
  • npx install, Node.js 22+
  • MIT licensed, on GitHub

Locus is not:

  • A code editor for your agent (your host still edits)
  • A replacement for grep
  • A memory store between sessions
  • A 40-tool IDE-inside-MCP stack

If you need symbolic body replacement and agent memory inside MCP, tools like Serena cover more ground. Locus is intentionally narrow: navigation + diagnostics on top of a capable host.

Six tools, six real workflows

1. Find definitions — locate 

Prompt: "Use Locus locate to find where UserService is defined. Do not grep."
Enter fullscreen mode Exit fullscreen mode

Supports qualified names (MyClass.method) and document symbol overviews.

2. Trace callers before refactors — refs 

Prompt: "Before renaming parseConfig, use Locus refs to list every caller."
Enter fullscreen mode Exit fullscreen mode

Find references or implementations at a position.

3. Read types — hover 

Prompt: "What type does response.data have? Use Locus hover."
Enter fullscreen mode Exit fullscreen mode

Returns compiler types and docs — not guesses from variable names.

4. Catch errors early — diagnostics 

Prompt: "After your edits, run Locus diagnostics on the files you changed."
Enter fullscreen mode Exit fullscreen mode

Surface compiler and linter issues without a full test run.

5. Check readiness — status

Language servers missing from PATH? status tells you before the agent wastes a turn.

6. Preview renames — rename

Dry-run rename impact. Your agent applies the actual edits.

Quick start (5 minutes) 

npx @paladini/locus-mcp init
npx @paladini/locus-mcp check
Enter fullscreen mode Exit fullscreen mode

Add to Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "locus": {
      "command": "npx",
      "args": ["-y", "@paladini/locus-mcp", "serve"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Reload MCP, then try:

Check Locus status, then locate where Greeter is defined in this repo.
Enter fullscreen mode Exit fullscreen mode

Works the same pattern for Claude Code and Codex — MCP is the plug-in layer.

Why I kept it lightweight

Most MCP stacks for coding agents grow fast: dozens of tools, symbolic editing, session memory, huge JSON payloads.

That is powerful — and heavy.

Locus takes the opposite bet:

  • Six tools, fixed contract
  • Compact output (src/foo.ts:12:4: symbol | snippet)
  • Host complements Edit + Grep instead of replacing them
  • Smaller surface = less context for the agent to juggle

Performance here is not fake benchmarks. It is fewer moving parts when you only need to answer: where is this defined?

Who this is for

  • Developers working through an AI agent who want semantic navigation
  • Teams on Cursor / Claude Code / Codex with MCP enabled
  • People who want npx simplicity over a full agent IDE toolkit

Probably not for you if you need symbolic editing and memory inside MCP — use a broader stack instead.

Launch links (v0.1.5) 

npm install -g typescript-language-server typescript  # TS/JS example
npx @paladini/locus-mcp init
Enter fullscreen mode Exit fullscreen mode

About me

I'm Fernando Paladini, a developer specialist and open-source builder based in Brazil. I also maintain mcp-me — a community MCP server for exposing personal context to AI assistants — and I have been exploring MCP as a practical layer between LLMs and real developer tooling.

Locus is the tool I wanted for my own agent workflows: ground the model in what the compiler already knows, without turning my setup into a second IDE.

If you try it, I would love feedback — issues and PRs welcome on GitHub.

Tags for search: MCP server, LSP, semantic code navigation, AI coding agent, Cursor MCP, Claude Code, lightweight MCP, find references, go to definition, @paladini/locus-mcp

GitHub logo paladini / locus-mcp

Agent-first MCP server for LSP-based code intelligence

Top comments (0)