Locus MCP：用语言服务器为AI编码代理补全语义导航能力

An AI coding agent can edit a file quickly and still misunderstand the codebase. Text search finds matching strings, but it does not reliably tell you which definition is active, which callers will be affected, or what type a value has.

This tutorial shows how to connect an MCP-capable coding agent to Locus MCP, an open-source server that delegates semantic code questions to language servers. You will install the published v0.1.5 package, create project configuration, add a host entry, and verify the connection with a real prompt.

Install a language server, run Locus setup in the project root, and add an MCP server entry that points cwd at that project:

npm install -g typescript-language-server typescript
npx @paladini/locus-mcp init
npx @paladini/locus-mcp check

Then configure your agent host to run npx -y @paladini/locus-mcp@0.1.5 serve. Ask the agent to use the locate, refs, or hover tool instead of guessing from grep output.

What problem does this solve?

Suppose an agent must rename parseConfig. Grep can list every occurrence of that text, including comments, strings, tests, generated files, and unrelated symbols. An LSP can answer a narrower question: which declaration does this identifier refer to, and which source locations reference that declaration?

Locus is a small MCP layer between the agent host and those language servers. The released documentation describes six tools:

• locate finds a symbol or lists symbols in a file.
• refs finds references or implementations.
• hover returns type information and documentation.
• diagnostics reports errors and warnings.
• status reports language-server readiness.
• rename previews the impact of a rename without applying edits.

The distinction matters. Locus reads code structure and diagnostics; your agent still performs edits, and grep remains useful for plain text such as logs, comments, and configuration keys. See the Locus usage guide for the supported workflow.

Prerequisites

• An MCP-capable host such as Cursor, Codex, or Claude Code.
• A language server installed for the language you want to inspect.
• A project directory where you can create configuration files.

For a TypeScript or JavaScript project, install the TypeScript language server and compiler:

npm install -g typescript-language-server typescript

For Python, the documented option is pip install pyright. The getting started guide also lists gopls for Go and rust-analyzer for Rust.

Install and check Locus

Open a terminal in the root of the project you want the agent to understand. Run the published package explicitly so the example is tied to the stable v0.1.5 release:

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

init creates locus.toml and locus.json. check verifies that the language-server binaries are available on PATH. A successful TypeScript check should identify typescript-language-server; a missing binary is a setup problem, not an MCP problem.

If your project uses more than one language, install only the servers it needs and configure the warm languages in locus.toml:

root = "."
warm = ["typescript", "python"]

The configuration reference documents the file priority and custom server fields. Locus looks for locus.toml, then locus.json, then .lsp.json while walking up from the current directory.

Add the MCP server to your host

The host starts the server on demand. You normally do not run serve manually in a terminal.

For Cursor, create .cursor/mcp.json in the project:

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

For Codex, the equivalent project-scoped entry is TOML:

[mcp_servers.locus]
command = "npx"
args = ["-y", "@paladini/locus-mcp", "serve"]
cwd = "/absolute/path/to/your/project"

Replace the placeholder with the absolute project path. The cwd value is important because it tells Locus which codebase and configuration to inspect. After saving the file, reload MCP servers or restart the host.

The official setup walkthrough shows the corresponding Claude Code shape and the host-specific reload step.

Verify the complete path

First ask the agent to call status:

Call the Locus MCP tool status and tell me which language servers are ready.

A readiness response confirms that the host can start Locus and that Locus can see the configured language server. If the response says server_starting, wait briefly and retry. If it says server_unavailable, run check again and inspect the binary path.

Then test a semantic lookup in a project with a known symbol:

Use Locus locate to find where UserService.authenticate is defined. Do not use grep.

For a refactor review, use a two-step request:

Before changing parseConfig, use Locus to find its definition and list every reference. Show me the files and lines before editing anything.

Finally, ask for diagnostics on a changed file:

Run Locus diagnostics on src/api/handler.ts and report errors and warnings.

These prompts test different boundaries: server readiness, symbol resolution, reference discovery, and diagnostics. They also make the agent's intended tool visible in the conversation.

How Locus works

Locus does not implement a parser for every language. It starts configured language-server processes and translates MCP tool calls into language-server requests. This lets the agent use the same general semantic services that IDEs expose, while keeping the MCP surface focused.

The configuration separates project settings from server definitions. locus.toml is convenient for the root and warm languages; locus.json can describe commands, arguments, language IDs, and file extensions. When no custom servers array is supplied, Locus uses its built-in defaults for TypeScript, Python, Go, and Rust.

That architecture also explains the limits. Results depend on the language server, its project configuration, its indexing state, and the files visible from the selected root. A green check means the executable exists on PATH; it does not guarantee that every workspace can produce a useful answer immediately.

Failure modes and safe boundaries

If the MCP server does not appear, confirm that the host configuration is valid, cwd is an absolute project path, and the host was reloaded. If a language is missing, install its server and rerun check. If indexing is still in progress, retry after server_starting rather than treating it as a definitive failure.

Review locus.json and .lsp.json before trusting a project. Locus runs language servers as child processes and spawns the configured command and arguments. Its security policy explicitly warns that configuration should be reviewed before use. A language server is also a separate dependency with its own security and trust boundary.

Locus does not edit code, store agent memory, replace grep, or promise complete IDE coverage. rename is a preview; the agent applies any actual change. For symbolic editing, persistent memory, or a much broader toolkit, the project documentation points readers to alternatives such as Serena.

FAQ

Do I need to understand LSP?

No. You need a compatible language server and the documented setup commands. Locus exposes the agent-facing MCP tools while the language server handles semantic analysis.

Do I have to install Locus globally?

No. The documented recommended path uses npx, so the host can start the package without a global Locus installation.

Can I keep using grep?

Yes. Use Locus for symbols, references, types, and diagnostics. Use grep for strings, comments, logs, and configuration text.

What if my language is not listed?

Check whether your language server can be described in locus.json or .lsp.json. The configuration reference documents custom server entries, but compatibility still depends on the language server's behavior.

Next steps

The useful change is not adding another search command to an agent. It is giving the agent a deliberate boundary between text search and semantic code navigation. Install the language server, run init and check, point the MCP host at the correct project root, and ask for status before relying on locate, refs, hover, or diagnostics.

This article was prepared with AI assistance. The repository, v0.1.5 package metadata, release-tagged documentation, security policy, and --help output were checked before publication; the article does not claim results beyond those sources and smoke checks.

What is the first code-navigation task you would delegate to an MCP server: finding definitions, reviewing references before a refactor, or checking diagnostics after an edit?