@paladini/locus-mcp

Locus is an MCP server that gives AI coding agents semantic code intelligence — the same go-to-definition, find-references, type information, and diagnostics your IDE uses, through six focused tools.

What problem does this solve?

AI agents are great at reading and editing files, but text search alone is not enough for typed code:

| Problem | Without Locus | With Locus | |---------|---------------|------------| | Find a symbol definition | Grep returns every string match | locate finds the real definition | | Refactor safely | Easy to miss callers | refs lists every reference | | Understand types | Guess from variable names | hover returns compiler types and docs | | Catch errors after edits | Wait for tests or manual build | diagnostics surfaces compiler/linter issues |

Locus connects your agent to language servers (TypeScript, Python, Go, Rust, and more) through MCP — a standard plug-in layer for AI tools like Cursor, Claude Code, and Codex.

Who is this for?

• Developers and builders who work through an AI agent and want semantic navigation, not just grep
• Teams using Cursor, Claude Code, Codex, or any MCP-capable host
• People who want a small, predictable setup (npx, six tools) instead of a full IDE-inside-MCP stack

Locus does not replace your agent's edit tools, grep for plain text, or provide agent memory. It complements hosts that already edit well with a focused navigation layer.

Quick start

1. Prerequisites

• Node.js 22+
• A language server for your project's language(s)

# TypeScript / JavaScript
npm install -g typescript-language-server typescript

# Python
pip install pyright

# Go
go install golang.org/x/tools/gopls@latest

# Rust
rustup component add rust-analyzer

2. One-time project setup

Run in your project root:

npx @paladini/locus-mcp init
npx @paladini/locus-mcp check

• init — creates locus.toml / locus.json config files
• check — verifies language-server binaries are installed and on your PATH

3. Add to your agent (MCP config)

Replace /absolute/path/to/your/project with your real project path.

Cursor — .cursor/mcp.json:

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

Claude Code / Codex — same JSON shape in your host's MCP settings.

Reload MCP servers or restart your agent host after saving.

4. Try it

Ask your agent:

Use Locus to find where UserService is defined and list all references.

Your agent should call the locate and refs MCP tools — not run grep in a terminal.

CLI commands

| Command | Description | |---------|-------------| | locus serve | Start the MCP server (used by your agent host) | | locus init | Create config files in the current directory | | locus check | Verify language-server binaries are available | | locus warm | Pre-start language servers before a long session |

npx @paladini/locus-mcp --help

MCP tools

Locus exposes exactly six tools. All return compact text with a leading status: line.

| Tool | What it does | |------|----------------| | locate | Find a symbol by name or list symbols in a file | | refs | Find all references or implementations at a position | | hover | Get type information and documentation | | diagnostics | Get compiler/linter errors for a file or workspace | | status | Check language-server readiness and missing binaries | | rename | Preview a rename (dry-run by default; agent applies edits) |

Example prompts

• "Find where UserService is defined. Use Locus locate, not grep."
• "Before we rename parseConfig, use Locus to list every file that calls it."
• "What type does response.data have? Use Locus hover."
• "After your edits, run Locus diagnostics on the files you changed."

What Locus does NOT do

• Edit code — your agent's Edit/Write tools apply changes; Locus only reads structure
• Replace grep — grep is still best for logs, config keys, comments, and plain text
• Remember between sessions — no agent memory store
• Run refactors automatically — rename previews impact; your agent applies edits
• Expose every LSP feature — six focused tools only

Configuration

Locus discovers config by walking up from the project root:

| File | Purpose | |------|---------| | locus.toml | Project root, warm languages | | locus.json | Language server definitions | | .lsp.json | Compatibility with Claude Code Open Plugins |

Run locus init to generate defaults. Built-in servers cover TypeScript/JavaScript, Python, Go, and Rust when no custom config is provided.

Install options

# Recommended — no global install
npx @paladini/locus-mcp init

# Global install
npm install -g @paladini/locus-mcp

# From GitHub Packages
npm install @paladini/locus-mcp --registry https://npm.pkg.github.com

Requires a GitHub PAT with read:packages for GitHub Packages installs.

Troubleshooting

| Problem | Fix | |---------|-----| | check reports MISSING binary | Install that language server; ensure it is on your PATH | | Agent uses grep instead of Locus | Remind it: "Use the Locus MCP tool locate, not grep." | | server_starting in tool output | Wait a few seconds and retry, or run locus warm | | MCP server not listed in host | Confirm cwd is an absolute path to your project root; reload MCP |

Documentation

Full guides live in the Locus repository:

| Guide | Description | |-------|-------------| | Getting started | First-time setup | | Usage guide | Host setup and workflows | | Tools reference | All six tools with examples | | Configuration | locus.toml, language servers | | FAQ | Common questions | | Comparison | Locus vs Serena, grep, LSP bridges |

Related packages

• @paladini/locus-core — LSP client library used by this server (for library authors and contributors)

License

MIT