squiggles

squiggles

让你的 Agent 看到你在 IDE 中会看到的波浪线。

squiggles 是一个连接编码 Agent 与语言服务器协议（LSP）服务的 MCP 服务。配置一个或多个 LSP 服务后，squiggles 会将它们的功能——诊断、跳转到定义、查找引用、重命名、格式化等——作为 MCP 工具提供。服务会在首次使用工具时按需启动，因此不会为你不使用的语言产生启动开销。

除了标准协议，squiggles 还解锁了各语言服务器自带的定制超能力：编辑器很少展示这些功能，Agent 通常也无从得知。例如展开 Rust 宏、发现 Ruby 测试、在 C++ 源文件与头文件之间切换、移动 TypeScript 文件后修复所有导入，以及通过 gopls 运行 govulncheck。

快速开始

claude mcp add squiggles -- npx -y squiggles

然后，在项目根目录中运行：

npx squiggles init

这会为检测到的语言写入一个 squiggles.yaml（例如，tsconfig.json 表示 TypeScript，Cargo.toml 表示 Rust，依此类推）。也可以自行指定服务名称：npx squiggles init typescript ruby。typescript、rust、ruby、go、python、cpp 和 lua 均有预设；每种语言都需要将对应的语言服务器添加到 PATH 中，init 会为写入的每个配置打印安装命令。

TypeScript 项目的生成结果：

servers:
  typescript:
    command: ["typescript-language-server", "--stdio"]
    filePatterns: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]

配置

squiggles 会在项目根目录中查找 squiggles.yaml、squiggles.yml、.squiggles.yaml 或 .squiggles.yml（旧版 mclsp.yaml 名称仍然有效）。每个服务条目支持：

字段	必填	描述
command	是	用于启动 LSP 服务的命令（字符串数组）
filePatterns	是	此服务处理的文件 glob 模式
initializationOptions	否	初始化时传递给 LSP 服务的选项
rootUri	否	覆盖工作区根 URI
env	否	LSP 服务进程的环境变量

可以为不同语言配置多个服务：

servers:
  typescript:
    command: ["typescript-language-server", "--stdio"]
    filePatterns: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
  rust:
    command: ["rust-analyzer"]
    filePatterns: ["**/*.rs"]
  ruby:
    command: ["ruby-lsp"]
    filePatterns: ["**/*.rb"]
  go:
    command: ["gopls"]
    filePatterns: ["**/*.go", "go.mod", "go.sum"]
  cpp:
    command: ["clangd"]
    filePatterns: ["**/*.c", "**/*.h", "**/*.cpp", "**/*.hpp"]

工具

配置匹配的服务后，所有标准 LSP 工具都会注册并可用。

导航： goto_definition、goto_type_definition、goto_implementation、goto_declaration、find_references

检查： hover、signature_help、document_symbols、workspace_symbols

重构： code_actions、rename_prepare、rename、format

层级结构： call_hierarchy_incoming、call_hierarchy_outgoing、type_hierarchy

始终可用： open_file、diagnostics

基于位置的工具接受 file（相对路径）、line（从 1 开始计数）和 col（从 1 开始计数）。rename 接受 apply: true，可将编辑写入磁盘，而非返回编辑内容；format 始终会写入磁盘。code_actions 会自动传入与请求范围重叠的诊断信息，因此会显示快速修复选项。

服务端扩展

最优秀的语言服务远不止实现标准协议，而 squiggles 正是在此发挥作用：它会订阅 IDE 插件使用、但 Agent 框架忽略的自定义方法和命令。配置匹配的服务端后，扩展工具会自动注册。

Ruby（ruby-lsp）

工具	功能
ruby_discover_tests	在文件中发现测试用例（Minitest、RSpec）
ruby_go_to_relevant_file	在实现文件和测试文件之间跳转
ruby_show_syntax_tree	显示文件的 Prism AST
ruby_dependencies	列出项目的 gem 依赖项

TypeScript（typescript-language-server）

工具	功能
ts_go_to_source_definition	跳转到实现，而不是 .d.ts 声明
ts_organize_imports	对导入进行排序和清理，并写入磁盘
ts_rename_file	文件移动后修复所有导入——先移动文件，再调用此工具

typescript-language-server 需要能找到 typescript 安装（通常是工作区自己的安装）。TypeScript 7 不再提供 tsserver.js，因此目前请在工作区中保留 typescript@5。

Rust（rust-analyzer）

工具	功能
rust_expand_macro	显示宏调用生成的代码
rust_parent_module	导航到父模块
rust_open_cargo_toml	查找所属 crate 的 Cargo.toml
rust_external_docs	获取符号对应的 docs.rs / rustdoc URL
rust_related_tests	查找覆盖某个位置的测试
rust_view_syntax_tree	显示文件的语法树
rust_runnables	列出可运行的目标（测试、二进制文件、文档测试）
rust_reload_workspace	编辑 Cargo.toml 后重新加载 Cargo 元数据
rust_dependencies	列出依赖关系图中的所有 crate

Go（gopls）

工具	功能
go_list_known_packages	列出可从文件导入的包
go_list_imports	列出文件的导入项及其所属包
go_add_import	添加导入项，并写入磁盘
go_mod_tidy	运行 go mod tidy
go_vulncheck	对模块运行 govulncheck
go_modules	列出目录下的模块

C/C++（clangd）

工具	功能
clangd_switch_source_header	在源文件和头文件之间跳转
clangd_symbol_info	获取 USR 和符号详情
clangd_ast	显示指定范围的 Clang AST

当服务端自行应用更改（整理导入、添加导入、重命名文件）时，squiggles 会接收工作区编辑并将其写入磁盘，使服务端看到的文件保持同步。

扩展贡献

要为新的语言服务端添加扩展，请在 src/extensions/ 中创建文件（例如 src/extensions/zig.ts）：

import { executeCommand, type ServerExtension } from "./index.js";

const extensions: ServerExtension[] = [
  {
    name: "zls_something",
    description: "What this does",
    input: "position", // "none" | "file" | "position" | "custom"
    request: ({ uri, position }) => ({
      method: "zls/customMethod",
      params: { textDocument: { uri }, position },
    }),
  },
];

export default extensions;

request 接收已打开文件的 URI、绝对路径和从 0 开始的索引位置，并返回要发送的 LSP 请求——对于将功能作为 workspace/executeCommand 命令公开的服务端，请使用 executeCommand 辅助函数。在 src/extensions/index.ts 中，按服务端的二进制名称注册该模块。

从 mclsp 迁移

squiggles 是此前以 mclsp 名义发布的项目。将 MCP 配置指向 npx -y squiggles，并将 mclsp.yaml 重命名为 squiggles.yaml——旧配置名称仍可使用，工具名称保持不变。

许可证

MIT