Locus

Name: Locus
Author: paladini

本地服务

github.com/paladini开发工具014 周前更新

代码仓库

关于 Locus

Locus 是面向编码 Agent 的轻量级 MCP 服务，通过语言服务器提供代码结构导航和诊断。它专注于六种工具，不编辑代码，也不试图替代 IDE。

主要功能

01按名称定位代码符号
02查找引用和实现
03查看类型与文档
04获取文件或工作区诊断
05检查语言服务器状态
06预览重命名影响

适用场景

01查找符号的实际定义
02重构前列出所有调用位置
03编辑后检查编译和 lint 问题
04查看变量或参数的类型信息

MCP 相关

Locus 通过 MCP 向编码 Agent 提供六种代码智能工具，借助语言服务器查询符号、引用、类型和诊断。重命名功能只预览影响，实际编辑由 Agent 完成。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "paladini-locus": {
      "command": "npx",
      "args": [
        "-y",
        "@paladini/locus-mcp"
      ]
    }
  }
}

启动命令npx -y @paladini/locus-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@paladini/locus-mcp0.1.5stdio

工具

收录的工具列表 · 更新于 3 周前

参数	类型	必填	说明
file	string	否	用于限定文档符号概览范围的可选文件路径
name	string	否	符号名称或限定名称（例如 MyClass.method）

详细介绍

Locus

Locus 为你的 AI 编码 Agent 绘制代码库地图。无论你是自己编写代码，还是使用 Cursor、Codex 或 Claude Code，Locus 都能通过 MCP（Model Context Protocol，模型上下文协议）将 Agent 连接到 IDE 使用的转到定义和查找引用功能。MCP 是 AI 工具的标准插件层。只需配置一次，Agent 就能使用六个轻量工具查找符号、追踪调用方、读取类型，并在运行测试前发现错误。

为什么你可能需要它

找到真正的定义——即使 UserService.authenticate 被重新导出、有多个重载，或隐藏在大型文件中，Agent 也能找到它，而不只是查找这个名称出现在哪些文本中。
查看调用关系——重构前，列出函数或类的所有引用，避免问题悄无声息地发生。
读取类型和文档——了解变量或参数的实际类型，而不必根据变量名猜测。
及早发现错误——编辑后立即发现编译器和代码检查工具报告的问题，而不是等到完整运行测试时才发现。

适用对象

Locus 面向 AI 优先的构建者：通过 Agent 开展工作的开发者、独立开发者和产品经理；他们希望 Agent 理解代码结构，而不只是搜索字符串。

如果你的 Agent 已经能很好地编辑文件（例如使用 Cursor 的 Edit 工具、Claude Code 或 Codex），并且你想在此基础上添加语义导航，又不想把 MCP 环境变成第二个 IDE，那么 Locus 就很适合你。

Locus 并不适合那些希望在 MCP 中使用符号编辑、Agent 记忆或完整重构工具包的人。对于这些需求，可以看看 Serena——一个功能更全面、在协议中提供更多能力的选择。Locus 刻意保持轻量：六个工具，通过 npx 安装，并与宿主互补。

5 分钟快速上手

安装语言服务器（如果你还没有）——TypeScript/JavaScript：npm install -g typescript-language-server typescript。Python、Go 和 Rust 的安装方法请参阅安装语言服务器。

在项目文件夹中运行一次性设置：

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

将 Locus 添加到 Agent 的 MCP 配置中——MCP 是 AI 宿主调用 Locus 这类辅助工具的方式；从下方的复制粘贴配置中复制一段配置，并将 cwd 设置为项目的绝对路径。
重新加载 MCP——重启 Cursor、重新加载 Codex，或重新打开 Claude Code，让新服务显示出来。
试着输入提示词——让 Agent：“使用 Locus 查找 UserService 的定义位置，并列出所有引用。”如果它调用了 locate 和 refs 工具，就说明配置成功了。

**要求：**Node.js 22+。你使用的语言对应的语言服务器必须位于 PATH 中。

复制粘贴配置

Agent 宿主会自动启动 Locus——正常使用时无需手动运行 serve。

Cursor

在项目中创建或编辑 .cursor/mcp.json（也可以编辑 Cursor 的全局 MCP 设置）：

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

Codex

添加到 ~/.codex/config.toml（全局）或 .codex/config.toml（项目）：

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

对于项目范围的配置，也可以使用 cwd = "."。

Claude Code

添加到 Claude Code 的 MCP 设置中：

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

更多详情（本地开发、故障排查）：docs/usage.md

可尝试的示例提示词

配置好 Locus 后，将以下内容粘贴到 Agent 中：

"查找 UserService 的定义位置。使用 Locus locate，不要用 grep。"
"重命名 parseConfig 之前，使用 Locus 列出所有调用它的文件。"
"src/api/handler.ts 中的 response.data 是什么类型？使用 Locus hover。"
"编辑完成后，对你修改的文件运行 Locus diagnostics 并修复所有错误。"
"检查 Locus status——语言服务器准备好了吗？"

Locus 不会做什么

编辑代码 — Agent 的 Edit/Write 工具仍会负责修改。Locus 只读取代码结构和诊断信息。
取代 grep — 搜索日志行、配置键、注释和纯文本时，grep 仍然最合适。
在会话之间记住内容 — 没有 Agent 记忆存储；每个会话都会从头开始。
替你运行重构 — rename 会预览影响；实际编辑由 Agent 执行。
提供所有 LSP 功能 — 只有六个专用工具，不是完整的 IDE 协议透传。
与大型工具包竞争 — 如果你需要在一个 MCP 工具栈中实现符号级正文替换、记忆和 40 多种语言支持，可以考虑 Serena。

工具一览

工具	功能
`locate`	按名称查找符号，或列出文件中的符号
`refs`	查找某个位置的所有引用或实现
`hover`	类型信息和文档
`diagnostics`	文件或工作区中的错误和警告
`status`	语言服务器就绪状态和缺失的二进制文件
`rename`	预览重命名（试运行；由 Agent 执行）

了解更多

指南	说明
使用指南	分步设置、工作流和故障排查
入门指南	首次设置——无需 LSP 知识
常见问题	我需要是程序员吗？什么是 MCP？
Locus 适合谁？	适用场景、范围，以及何时选择替代方案
对比	Locus 与 Serena、桥接工具和 grep 的对比
工具参考	全部六个 MCP 工具及示例
配置	`locus.toml`、`locus.json`、语言服务器
网站	简明定位和快速概览