llms.txt: machine-readable documentation index. Markdown version of this page is also available.

CLion 2026.3 Help

MCP 服务器

从版本 2025.2 开始,CLion 随附集成的 MCP 服务器 ,允许 Claude Code、Codex、VS Code 等外部客户端访问 IDE 提供的工具。 这使用户能够在不离开所选应用程序的情况下控制 JetBrains IDE 并与之交互。

启用 MCP 服务器插件

此功能依赖于 MCP 服务器插件,该插件默认在 CLion 中捆绑并启用。 如果相关功能不可用,请确保您未禁用该插件。

  1. 按下 Ctrl+Alt+S 打开设置,然后选择 插件。

  2. 找到 MCP 服务器 插件并点击 Enable。

启用 MCP Server

要启用 MCP 服务器,请执行以下操作:

  1. 转到 设置 | AI | MCP 服务器。

  2. 请选择 启用 MCP Server 复选框。

  3. 在 启用 MCP 服务器? 对话框中,查看第三方应用程序将获得对 IDE 中打开项目的哪些访问权限,然后点击 Enable 继续。

  4. 点击 Apply。

启用 MCP 服务器后,可以继续配置外部客户端。

外部客户端设置

对于检测到的外部客户端,例如 Junie、 VS Code、 Claude Code、 Codex、 Air 和 GitHub Copilot CLI ,可以自动执行配置。 设置客户端意味着将 IDE MCP 服务器的地址添加到该客户端的配置文件中。

为此:

  1. 转到 设置 | AI | MCP 服务器。

  2. 在 客户端自动配置 部分中,针对要设置为与 MCP 服务器配合使用的每个客户端,点击 自动配置。 这会自动更新客户端的配置文件。 配置的传输设置取决于客户端。

    MCP 服务器设置

    要自行配置特定传输,请点击 ,它位于 自动配置 旁边,然后从列表中选择所需选项。

    配置选项
  3. 请重启客户端以使配置生效。

项目级客户端设置

某些客户端还会从项目的工作目录读取配置文件。 对于这些客户端,IDE 可以将连接设置直接写入当前打开项目中的配置文件,因此 MCP 服务器仅在处理该项目时可用。

如果处理多个项目,并且不希望为每个客户端会话注册 MCP 服务器,请使用此选项。

  1. 转到 设置 | AI | MCP 服务器。

  2. 在 项目客户端自动配置 部分中,为要设置的每个客户端点击 自动配置。 这会自动更新客户端的项目级配置文件。

    自动配置客户端的项目级配置

    如果要配置特定传输机制,请点击 ,它位于 自动配置 旁边,然后从列表中选择所需选项。

  3. 请重启客户端以使配置生效。

手动客户端设置

如果要连接的客户端不在列表中,请手动配置。

  1. 在 手动配置客户端 部分,根据连接类型点击 复制 SSE 配置、 复制 Stdio 配置 或 复制 HTTP 流配置。

    MCP 服务器手动配置
  2. 将复制的配置粘贴到客户端的设置或配置文件中。

  3. 请重启客户端以使配置生效。

无需确认即可执行操作

MCP 服务器允许已连接的外部客户端执行终端命令或运行 IDE 中的运行配置,而无需每次提示用户确认。

要启用此模式:

  1. 转到 设置 | AI | MCP 服务器。

  2. 在 命令执行 部分中,启用 在无需确认的情况下运行 Shell 命令或运行配置(勇敢模式) 设置。

  3. 点击 Apply。

在终端会话中显示设置建议

当 Codex 或 Claude 在没有匹配 MCP 服务器设置的终端会话中启动时,IDE 可以显示横幅,建议配置连接。

要控制此行为:

  1. 转到 设置 | AI | MCP 服务器。

  2. 在 终端会话 部分,选中或清除 显示 Codex 和 Claude 终端会话的设置建议 复选框。

  3. 点击 Apply。

支持的工具

MCP 服务器公开了一组工具,允许外部客户端与 IDE 和项目交互,例如分析代码、修改文件、运行配置或执行终端命令。

可以在 设置 | AI | MCP 服务器 | Exposed 工具 查看并管理所有可用工具列表。 对于每个工具,选中或清除 已启用 复选框,以控制是否向外部客户端公开该工具。

Exposed 工具设置页面

还可以为工具选中 仅路由器 复选框。 仅路由器工具会从直接 MCP 工具列表中隐藏,并且只能通过专用路由器 工具使用。 这样可以避免工具列表中出现不必要的工具描述,并节省上下文。 使用 为以下对象启用路由器专用模式 设置指定仅路由器模式的适用时间,例如用于 所有智能体 或 仅限 ACP 智能体。

下面可查看 MCP 服务器提供的工具列表。

分析工具

analyze_calls

为方法、函数、构造函数或受支持的类型目标构建 IDE 调用层次结构树。 使用它可以查看谁调用符号 (INCOMING_CALLS ),或该符号调用什么 (OUTGOING_CALLS)。

按实际调用评估依赖项时,优先使用此工具,而不是用法搜索、文本搜索或正则表达式搜索。 它使用 IDE 调用层次结构数据,因此相比基础搜索,可以提供更精确的调用关系,噪声更少,后续调用也更少。

将 symbolFqn 作为完全限定名称传递,例如 com.example.Service.run。 如果名称不明确,工具会返回确切签名;请将其中一个作为 symbolFqn 传回。 如果只知道短名称或片段,请先使用 搜索符号 查找目标。

结果是一个可展开的文本树。 每个节点都包含 filePath 和 treePath ;在可能的情况下, filePath 是相对于项目的。 将 treePath 传回以渲染子树。 使用 childOffset 在截断的 后继续…… 还有 n 个 行之后继续。 depth、 maxChildren 和 maxNodes 会限制渲染的树。 如果 IDE 能够解析符号,符号可以来自项目源代码、源 jar 或反编译的二进制 jar 依赖项。

参数:

  • symbolFqn (必需):纯完全限定符号名称,或由歧义错误返回或从渲染的子节点复制的确切签名。 如果只知道短名称或片段,请先使用 搜索符号 ,并在此处传递最佳的完全限定可调用名称。 示例: com.example.Service.run、 com.example.Service.run(String) 或 org.assertj.core.api.Assertions.assertThat(String)。 不要传递文件路径、行、列或单独的目标签名。

  • analysisKind (必需):调用分析方向。 使用 INCOMING_CALLS 显示 symbolFqn 的调用方,或使用 OUTGOING_CALLS 显示从 symbolFqn 调用的符号。

  • depth :要在请求的子树根下渲染的最大调用级别数。 默认为 5。 使用 0 仅渲染子树根。

  • maxChildren :为每个节点渲染的直接子节点最大数量。 默认为 50。

  • maxNodes :渲染的调用节点总数上限。 默认为 1000。

  • treePath :指向子树根的可选路径,从先前的 analyze_calls 结果中准确复制。 Null 或省略表示根路径 []。 每个组件都是确切签名,而不是显示名称。

  • childOffset :对由 treePath 指定的节点的直接子节点进行分页的偏移量。 默认为 0。

  • timeout :超时(毫秒)。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

构建项目名称

触发项目或指定文件的构建、等待完成并返回构建错误。 可使用此工具构建项目或编译文件,并获取有关编译错误和警告的详细信息。

编辑后需使用此工具以验证更改是否有效。

参数:

  • rebuild :是否对项目进行完全重建。 默认为 false。 仅当未指定 filesToRebuild 时生效。

  • filesToRebuild :如指定,则仅编译指定路径下的文件。 路径相对于项目根目录。

  • timeout :超时(毫秒)。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

get_file_problems

使用 IntelliJ 检查分析指定文件中的错误和警告。 使用此工具识别特定文件中的代码问题、语法错误及其他问题。

返回问题列表,包括严重性、描述和位置信息。

参数:

  • filePath :相对于项目根目录的路径。

  • errorsOnly :是否仅包含错误,或同时包含错误和警告。

  • timeout :超时(毫秒)。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

get_project_dependencies

返回项目中定义的所有依赖项列表。 提供有关库名称的结构化信息。

参数:

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

get_project_modules

返回项目中所有模块及其类型的列表。 提供每个模块的结构化信息,包括其名称和类型。

参数:

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

lint_files

使用 IntelliJ 检查分析指定文件中的错误和警告。 编辑多个文件后,使用此工具对它们进行 lint 检查。 返回每个文件的问题,包括严重性、描述和位置信息。

当单个文件超出可用预算时,批量响应可能包含带有 timedOut: true 且 problems 为空的文件条目。 带有 notAnalyzedReason 的文件条目表示无法分析的文件,例如项目内容根之外的文件、已排除的文件或不支持的文件类型。 顶级 more: true 表示批处理不完整。

参数:

  • 个文件 (必需):要分析的项目相对文件列表。 规范化后会忽略重复路径。

  • min_severity :要包含的最低严重性: warning 或 error。 默认为 warning。

  • timeout :超时(毫秒)。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

代码洞察工具

get_symbol_info

检索指定文件中指定位置处符号的信息。 提供与 IntelliJ IDEA 的 快速文档 功能相同的信息。 这些信息可能包括符号的名称、签名、类型、文档及其他详细信息,具体取决于编程语言。

如果该位置引用了某个符号,且声明可用,该工具将返回包含该符号声明的代码片段。 使用此工具了解符号的声明、语义及位置。

参数:

  • filePath :相对于项目根目录的路径。

  • line :从 1 开始的行号。

  • column :从 1 开始的列号。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

数据库特定工具

要严格保证 AI 代理仅有只读访问权限,请使用权限受限(只读)的数据库用户,并将数据源配置为使用该用户。

取消 SQL 查询

使用唯一 ID 取消正在运行的查询。

参数:

  • sessionId :查询会话 ID。

创建数据库连接对象

按名称、DBMS (dbms )、JDBC URL (url) 以及用于检查连接的标志 (needToCheckDs) 创建新的数据库连接(数据源)。 所有参数均为必需。 返回连接诊断信息。

参数:

  • 名称 (必需):数据库连接的唯一名称。

  • dbms :数据库管理系统 (DBMS) 的名称。

  • url :数据库连接的完整 JDBC URL,例如 jdbc:postgresql://<host>:<port>/<database>。

  • needToCheckDs :是否在创建或编辑数据源后立即测试连接。 批量配置多个连接时设置为 false — 每个连接的探测成本较高,并且可以为重要的连接显式调用 测试数据库连接。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

编辑数据库连接

编辑由 connectionId 标识的现有数据库连接(数据源)。 更新连接的 DBMS 驱动程序和 JDBC URL;连接 名称 会被保留。 返回连接诊断信息。

参数:

  • connectionId :唯一连接 ID。

  • dbms :数据库管理系统 (DBMS) 的名称。

  • url :数据库连接的完整 JDBC URL,例如 jdbc:postgresql://<host>:<port>/<database>。

  • needToCheckDs :是否在创建或编辑数据源后立即测试连接。 批量配置多个连接时设置为 false — 每个连接的探测成本较高,并且可以为重要的连接显式调用 测试数据库连接。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

执行 SQL 查询

对给定的数据库连接执行 SQL 查询。

该工具报告执行状态:success 或 error。 出现错误时还会提供错误描述。

如果查询返回数据,则以 CSV 格式附加到工具响应中。

参数:

  • connectionId :唯一连接 ID。

  • queryText :要执行的 SQL 查询。

获取查询结果

按 ID 从已执行的查询中提取行,从给定的行偏移量开始。 返回与 执行 SQL 查询 相同的结构: resultSetId 以及以 CSV 格式呈现的结果。

使用此工具对先前由 执行 SQL 查询 或 预览表数据 返回的 resultSetId 进行分页。

参数:

  • resultSetId (必需):先前 执行 SQL 查询 或 预览表数据 调用返回的不透明结果集 ID。

  • offset (必需):开始提取的行偏移量。 默认为 0。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

获取数据库对象描述

检索特定架构中数据库对象(列、类型、密钥、索引)的结构,并以分层文本形式表示。

如遇歧义,将返回所有相关对象的定义。

参数:

  • connectionId :唯一连接 ID。

  • databaseName :架构所属数据库的名称。 如果 DBMS 没有数据库而只有架构,则可为空。

  • schemaName :架构的名称。

  • kind :将此参数设置为特定对象种类代码,以仅列出该种类的对象。 将其设置为 null 可检索架构中的所有对象。

  • objectName :指定类型的对象名称(如表或视图名称)。 不得为空。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

内省架构

内省数据库架构,将其元数据(表、列和索引)加载到本地模型中。 当架构的 isIntrospected 标志为 false 且需要调查架构结构,或需要刷新过时元数据时使用此工具。 返回架构标识符以及更新后的内省状态。

参数:

  • connectionId :唯一连接 ID。

  • databaseName :架构所属数据库的名称。 如果 DBMS 没有数据库而只有架构,则可为空。

  • schemaName :架构的名称。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

列出数据库连接

检索项目中已配置的数据库连接或数据源的列表。 对于每个连接,返回其唯一 ID、名称、DBMS 和驱动程序名称。

列出数据库架构

检索指定数据库连接中的数据库架构列表。

对于每个架构,该工具会返回架构自身的名称以及数据库名称(不适用时为空)。

参数:

  • connectionId :唯一连接 ID。

  • selectedOnly :如果只应列出数据库树中选定的架构,则为 True;如果应列出所有架构,则为 false。

列出最近的 SQL 查询

此功能在免费订阅方案中不可用。

检索给定数据库连接的最近查询列表,包括当前正在运行的查询。

对于每个查询返回:

  • 查询会话的唯一 ID。

  • 运行查询所花费的时间(以毫秒为单位)。

  • 查询的当前状态。 例如,正在运行、正在取消、已完成等。

  • 查询的补全状态。 例如,success、finished with error、cancelled 等。

  • 查询文本。

参数:

  • connectionId :唯一连接 ID。

列出架构对象类型

检索给定数据库连接支持的架构对象种类列表。 对于每种对象种类,返回对象种类的唯一代码和可读名称。

参数:

  • connectionId :唯一连接 ID。

列出架构对象

检索给定架构内的数据库对象列表。 对每个对象返回其在架构中的名称及其类型。

参数:

  • connectionId :唯一连接 ID。

  • schemaName :架构的名称。

  • databaseName :架构所属数据库的名称。 如果 DBMS 没有数据库而只有架构,则可为空。

  • kind :将此参数设置为特定对象种类代码,以仅列出该种类的对象。 将其设置为 null 可检索架构中的所有对象。

预览表数据

使用给定的数据库连接返回表、视图、物化视图或其他类似表对象的预览数据。

该工具以 CSV 格式返回表内容。

参数:

  • connectionId :唯一连接 ID。

  • schemaName :架构的名称。

  • databaseName :架构所属数据库的名称。 如果 DBMS 没有数据库而只有架构,则可为空。

  • tableName :表的名称。

  • maxRowCount :要返回的最大行数。 默认值为 100。

测试数据库连接

返回连接诊断信息:

  • 指示连接是否存在问题的标志:yes、no 或 unknown。

  • 关于数据库连接的详细信息,如 DBMS 类型、版本和 JDBC 驱动。

  • 连接尝试结果的摘要。 如果失败,则包含 DBMS 提供的错误描述。

参数:

  • id :唯一连接 ID。

调试器工具

这些工具使外部客户端能够控制 IDE 的调试器:它可以设置、列出和移除断点,启动调试会话并逐步执行,还可以在运行时检查调用堆栈、线程和变量值。

xdebug_control_session

控制调试会话的执行。 使用此工具可以逐步执行代码、恢复执行、暂停或停止调试会话。

前提条件:

  • 必须存在调试会话。

  • STEP_* 和 RESUME 需要挂起的会话。

操作:

  • STEP_INTO :步入下一个方法调用

  • STEP_OVER :步过当前行

  • STEP_OUT :步出当前方法

  • RESUME :恢复程序执行,直到下一个断点

  • PAUSE :暂停程序执行

  • STOP :停止调试会话

  • WAIT_FOR_PAUSE :等待会话暂停(命中断点或手动暂停)

  • DRAIN_EVENTS :排空会话的跟踪点输出(所有操作都会排空断点错误)

重要说明:

  • 如果程序正在运行,请使用 WAIT_FOR_PAUSE 或 PAUSE ,然后再使用 STEP_*/RESUME。

  • 使用来自 获取 xdebug 调试器状态 或 启动 xdebug 调试器会话 的当前 sessionId。 如果会话停止、超时或消失,请在下一次会话范围调用之前刷新会话列表。

  • RESUME 不会设置断点。 如果没有启用的断点(或接下来不会命中任何断点),程序可能会运行至完成,并且会话可能会在不暂停的情况下停止。

  • 在 RESUME 后,调用 WAIT_FOR_PAUSE 以确认下一次挂起。 如果 WAIT_FOR_PAUSE 超时,请考虑使用 PAUSE 并重新检查断点。

  • DRAIN_EVENTS 也需要现有会话;会话终止后,请勿重复使用过时的 sessionId。

下一次调用:

结果中的状态值:

  • 正在运行 :程序正在执行

  • 已暂停 :执行已挂起(断点、步进或手动暂停);暂停结果还包括 frameValues ,即在可用时以 xdebug_get_frame_values(depth=0) 格式提供的当前帧快照

  • stopped :调试会话已终止

  • 任何操作都会返回 breakpointErrorsTail

  • tracepointOutputsTail 仅针对 DRAIN_EVENTS 返回

事件支持作用域:

  • 目前,只有基于 JVM 的调试器(Java、Kotlin 等)会报告断点错误和跟踪点输出事件。

  • 在其他调试器后端,即使已配置断点/日志记录,这些事件尾部也可能为空。

参数:

  • sessionId :调试会话 ID。 使用 获取 xdebug 调试器状态 或 启动 xdebug 调试器会话 返回的当前 ID。 如果会话已停止、超时或消失,请在重用旧 ID 之前刷新会话列表。 格式:默认使用会话名称作为 ID;如果多个会话共享同一名称,则 ID 为 <sessionName>#<executionId>。 如果为 null 且只存在一个活动会话,则会自动选择该会话。 如果多个会话处于活动状态且省略了 sessionId ,则调用会失败。 默认值: null。

  • action: 要执行的操作: STEP_INTO、 STEP_OVER、 STEP_OUT、 RESUME、 PAUSE、 STOP、 WAIT_FOR_PAUSE、 DRAIN_EVENTS。 事件耗尽目前仅由基于 JVM 的调试器填充(Java、Kotlin 等)。

  • timeout :超时时间,以毫秒为单位,用于等待操作完成。 指导: STEP_*/PAUSE 通常为 5000-15000; WAIT_FOR_PAUSE 通常为 30000-120000,具体取决于工作负载和断点。 默认值: 30000。

  • eventsLimit: 每个事件列表要耗尽的最新事件的最大数量。 对于 DRAIN_EVENTS ,此限制会独立应用于 breakpointErrorsTail 和 tracepointOutputsTail。 默认值: 100。

  • clearEventsAfterRead: 兼容性标志。 无论此值如何,返回的事件始终会从内部缓冲区移除。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

xdebug_evaluate_expression

在当前堆栈帧的上下文中对表达式求值。 使用此工具在调试期间计算值、调用方法或检查表达式。

前提条件:

  • 会话必须已挂起。

  • 所选帧/语言必须支持求值。

  • expression 必须是当前帧语言中的有效表达式。

结果返回为:

  • depth == 0: 仅求值表达式的呈现形式

  • depth > 0: 呈现形式加上其子级的伪图形树,深度不超过请求的深度

输入规则:

  • 按调试器求值器应解析的方式准确传递原始表达式文本。

  • 不要传递经过 JSON 转义的载荷或文字转义序列,例如 \\"text\\"。

下一次调用:

参数:

  • sessionId :调试会话 ID。 使用 获取 xdebug 调试器状态 或 启动 xdebug 调试器会话 返回的当前 ID。 如果会话已停止、超时或消失,请在重用旧 ID 之前刷新会话列表。 格式:默认使用会话名称作为 ID;如果多个会话共享同一名称,则 ID 为 <sessionName>#<executionId>。 如果为 null 且只存在一个活动会话,则会自动选择该会话。 如果多个会话处于活动状态且省略了 sessionId ,则调用会失败。 默认值: null。

  • frameIndex: 作为整数的堆栈帧索引(0 = 顶部帧)。 请从当前暂停的 获取 xdebug 堆栈 结果中获取;在 RESUME、 STEP_*、 xdebug_run_to_line 或暂停位置发生任何变化后,不要重用缓存的帧索引。 如果为 null,则使用顶部帧。 默认值: null。

  • expression: 要在当前上下文中求值的表达式。 传递当前帧语言中的原始表达式文本;不要传递经过 JSON 转义的载荷或文字反斜杠转义的引用文本。

  • depth: 展开求值结果子级的最大深度(0 = 仅值,1 = 直接子级,2 = 子级 + 孙级,依此类推)。 默认值: 0。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

xdebug_get_debugger_status

返回调试器的当前状态,包括所有活动的调试会话。 使用此工具概览所有正在运行的调试会话及其状态。

前提条件:

  • 无。

返回显式的 sessions[] 和 activeSessionId。

下一次调用:

  • 如果没有正在运行的会话,请调用 启动 xdebug 调试器会话。

  • 如果多个会话处于活动状态,请在后续调用中使用返回的 id 作为 sessionId。

参数:

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

xdebug_get_frame_values

返回指定堆栈帧中可见的值,以树状结构表示。 使用此工具检查调用堆栈中特定点可用的局部变量、参数、字段或其他值。

前提条件:

  • 会话必须已挂起。

  • 帧索引应来自当前暂停的 获取 xdebug 堆栈 结果(0 = 顶部帧)。

Format:

  • 具有子级的节点会标记为 +。

下一次调用:

  • 使用 按路径获取 xdebug 值 深入查看嵌套字段。

  • 使用 计算 xdebug 表达式 在同一帧中进行计算检查。

  • 不要重用缓存的 frameIndex ,如果已执行 RESUME、 STEP_*、 xdebug_run_to_line 或暂停位置有任何变化。

参数:

  • sessionId :调试会话 ID。 使用 获取 xdebug 调试器状态 或 启动 xdebug 调试器会话 返回的当前 ID。 如果会话已停止、超时或消失,请在重用旧 ID 之前刷新会话列表。 格式:默认使用会话名称作为 ID;如果多个会话共享同一名称,则 ID 为 <sessionName>#<executionId>。 如果为 null 且只存在一个活动会话,则会自动选择该会话。 如果多个会话处于活动状态且省略了 sessionId ,则调用会失败。 默认值: null。

  • frameIndex: 作为整数的堆栈帧索引(0 = 顶部帧)。 请从当前暂停的 获取 xdebug 堆栈 结果中获取;在 RESUME、 STEP_*、 xdebug_run_to_line 或暂停位置发生任何变化后,不要重用缓存的帧索引。 如果为 null,则使用顶部帧。 默认值: null。

  • depth: 展开求值结果子级的最大深度(0 = 仅值,1 = 直接子级,2 = 子级 + 孙级,依此类推)。 默认值: 0。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

xdebug_get_stack

返回调试会话中线程的调用堆栈。 使用此工具查看导致当前执行点的方法调用序列。

前提条件:

  • 会话必须已挂起。

行为:

  • threadId 应来自 获取 xdebug 线程 ,并与调试器线程显示名称匹配(默认为活动线程)。

  • 即使缺少源位置,也会包含帧(文件/line 可能为 null)。

分页:

  • offset/limit 在收集完整堆栈后应用。

帧字段包括:

  • index

  • 文件

  • line

  • isCurrent

  • presentation

文件 按调试器提供的内容报告(不进行路径规范化)。

下一次调用:

参数:

  • sessionId :调试会话 ID。 使用 获取 xdebug 调试器状态 或 启动 xdebug 调试器会话 返回的当前 ID。 如果会话已停止、超时或消失,请在重用旧 ID 之前刷新会话列表。 格式:默认使用会话名称作为 ID;如果多个会话共享同一名称,则 ID 为 <sessionName>#<executionId>。 如果为 null 且只存在一个活动会话,则会自动选择该会话。 如果多个会话处于活动状态且省略了 sessionId ,则调用会失败。 默认值: null。

  • threadId: 要获取其堆栈的线程 ID。 此值应来自 获取 xdebug 线程 ,并与调试器线程显示名称匹配,而不是不透明的数字 ID。 如果未指定,则使用当前/活动线程。 默认值: null。

  • limit: 要返回的最大帧数。 默认值: 200。

  • offset: 页面偏移量。 默认值: 0。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

xdebug_get_threads

返回调试会话中的线程列表。 使用此工具查看所有线程及其当前状态。

前提条件:

  • 会话必须已挂起。

下一次调用:

分页:

  • offset/limit 在收集所有堆栈后应用。

排序:

  • 活动线程优先。

  • 其余线程按堆栈深度降序排序。

架构字段包括:

  • id

  • 名称

  • state

  • isCurrent

  • additionalInfo

  • additionalInfoTooltip

  • frameCount

additionalInfo/additionalInfoTooltip 在可用时使用其他显示信息。

参数:

  • sessionId :调试会话 ID。 使用 获取 xdebug 调试器状态 或 启动 xdebug 调试器会话 返回的当前 ID。 如果会话已停止、超时或消失,请在重用旧 ID 之前刷新会话列表。 格式:默认使用会话名称作为 ID;如果多个会话共享同一名称,则 ID 为 <sessionName>#<executionId>。 如果为 null 且只存在一个活动会话,则会自动选择该会话。 如果多个会话处于活动状态且省略了 sessionId ,则调用会失败。 默认值: null。

  • limit: 页面大小。 默认值: 50,最大值: 200。

  • offset: 页面偏移量。 默认值: 0。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

xdebug_get_value_by_path

通过属性名称路径获取嵌套对象的值。 使用此工具深入查看复杂对象并检查其嵌套属性。

前提条件:

  • 会话必须已挂起。

  • 路径必须为非空,并引用所选帧/对象中可见的名称。

结果返回为:

  • depth == 0: 仅指定路径处的值的呈现形式

  • depth > 0: 值的呈现形式加上其子级的伪图形树,深度不超过请求的深度

示例:

  • 要获取 obj.field.subField 的值,请使用 path = ["obj", "field", "subField"]。

  • 对于数组/列表索引器,请将索引令牌作为常规路径元素(子名称)传递,例如 items[0].name-> path = ["items", "[0]", "name"]。

  • 使用当前暂停的 获取 xdebug 帧值/ 上一个 按路径获取 xdebug 值 输出中的精确子名称,因为索引节点名称可能因语言/调试器而异(例如 "[0]" 与 "0")。

  • 刷新 path 令牌,在 RESUME、 STEP_*、 xdebug_run_to_line 或暂停位置发生任何其他变化之后。

下一次调用:

参数:

  • sessionId :调试会话 ID。 使用 获取 xdebug 调试器状态 或 启动 xdebug 调试器会话 返回的当前 ID。 如果会话已停止、超时或消失,请在重用旧 ID 之前刷新会话列表。 格式:默认使用会话名称作为 ID;如果多个会话共享同一名称,则 ID 为 <sessionName>#<executionId>。 如果为 null 且只存在一个活动会话,则会自动选择该会话。 如果多个会话处于活动状态且省略了 sessionId ,则调用会失败。 默认值: null。

  • frameIndex: 作为整数的堆栈帧索引(0 = 顶部帧)。 请从当前暂停的 获取 xdebug 堆栈 结果中获取;在 RESUME、 STEP_*、 xdebug_run_to_line 或暂停位置发生任何变化后,不要重用缓存的帧索引。 如果为 null,则使用顶部帧。 默认值: null。

  • path: 要导航经过的子名称列表,例如 ['myObject', 'field', 'subField'] 或 ['items', '[0]', 'name']。 使用当前暂停的 获取 xdebug 帧值/按路径获取 xdebug 值 输出中的精确节点名称,并在暂停位置变化后刷新过期的路径令牌。

  • depth: 展开求值结果子级的最大深度(0 = 仅值,1 = 直接子级,2 = 子级 + 孙级,依此类推)。 默认值: 0。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

xdebug_list_breakpoints

列出项目或特定文件中的所有断点。 使用此工具查看当前设置的所有断点及其属性。

行为:

  • 如果提供了 filePath ,则仅返回该文件中的断点。

  • 返回每个断点的丰富特性(id、 type、 文件、 line、 已启用、 owner、 condition、 isLogMessage、 isLogStack、 temporary、 suspendPolicy、 hitCount)。

下一次调用:

  • 如果不存在合适的断点,请调用 设置 xdebug 断点。

  • 然后使用 xdebug_control_session(action=RESUME) 和 xdebug_control_session(action=WAIT_FOR_PAUSE) 继续执行。

参数:

  • filePath :用于筛选断点的可选文件路径。 文件路径。 支持相对于项目的路径、带有 .. 的路径、绝对路径、类似 /path/lib.jar!/pkg/Foo.class 的归档条目,以及如 file:// 、 jar:// 、 jrt:// 的 URL。 可以直接传递其他工具返回的路径(例如来自 search_* 工具的路径)。 如果未指定,则返回所有断点。 默认值: null。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

xdebug_remove_breakpoint

移除按所有者和可选选择器筛选的断点。 使用此工具移除先前设置的断点。

行为:

  • owner 默认为 agent。

  • 如果仅提供 owner ,则移除该所有者的所有断点。

  • 如果提供了 breakpointId ,则会移除所选所有者的匹配断点(s)。

  • 如果提供了 filePath + line ,则会移除所选所有者的匹配行断点(s)。

  • 如果提供了多个选择器,则会组合所有选择器(逻辑 AND)。

  • 幂等: 移除不存在的断点会返回 removed=false。

  • 要无论所有者如何都移除所有断点,请调用两次:一次使用 owner=user ,一次使用 owner=agent。

下一次调用:

参数:

  • breakpointId: 由 设置 xdebug 断点 或 列出 xdebug 断点 返回的规范断点 ID。

  • filePath :用于筛选断点的可选文件路径。 文件路径。 支持相对于项目的路径、带有 .. 的路径、绝对路径、类似 /path/lib.jar!/pkg/Foo.class 的归档条目,以及如 file:// 、 jar:// 、 jrt:// 的 URL。 可以直接传递其他工具返回的路径(例如来自 search_* 工具的路径)。 如果未指定,则返回所有断点。 默认值: null。

  • line: 可选输入: 要移除的断点的行号(从 1 开始)。

  • owner: 断点所有者筛选器。 默认值: agent。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

xdebug_run_to_line

恢复执行至目标行。 使用此工具运行到特定源位置,而无需手动步进。

前提条件:

  • 会话必须已挂起。

  • 目标文件/行必须有效。

结果:

  • paused: 会话在目标处或目标之后暂停。

  • stopped: 会话在暂停前终止。

  • timeout: 超时窗口内没有暂停/停止。

下一次调用:

参数:

  • sessionId :调试会话 ID。 使用 获取 xdebug 调试器状态 或 启动 xdebug 调试器会话 返回的当前 ID。 如果会话已停止、超时或消失,请在重用旧 ID 之前刷新会话列表。 格式:默认使用会话名称作为 ID;如果多个会话共享同一名称,则 ID 为 <sessionName>#<executionId>。 如果为 null 且只存在一个活动会话,则会自动选择该会话。 如果多个会话处于活动状态且省略了 sessionId ,则调用会失败。 默认值: null。

  • filePath :相对于项目根目录的路径。

  • line: 目标行号(从 1 开始)。

  • timeout :超时时间,以毫秒为单位,用于等待暂停/停止结果。 默认值: 30000。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

xdebug_set_breakpoint

创建或更新断点。 使用此工具设置行断点、按 ID 更新现有断点,并控制跟踪点/日志记录行为。

目标模式:

  • 按位置: 提供 filePath + line ,并省略 breakpointId (或传递 null)。 不要使用占位符字符串,例如 ""、 "/" 或 "__omit__"。

  • 按 ID: 提供由 设置 xdebug 断点 或 列出 xdebug 断点 返回的现有不透明规范 breakpointId (可选的 filePath/line 可重新定位行断点)。

验证:

  • 在位置模式下, filePath 和 line 都是必需的。

  • 在 ID 模式下,断点必须存在,并且可由 breakpointId 唯一标识。

  • 在位置模式下, filePath 相对于项目根目录, line 从 1 开始,并且目标位置必须为可执行文件位置。

事件报告:

  • 无效的 condition 表达式会通过 xdebug_control_session(...).breakpointErrorsTail 异步报告。

  • 来自带有 isLogMessage 和/或 isLogStack 的断点的跟踪点输出会通过 xdebug_control_session(action=DRAIN_EVENTS).tracepointOutputsTail 耗尽。

  • 断点错误和跟踪点输出报告目前仅受基于 JVM 的调试器支持(Java、Kotlin 等)。

  • 成功的 设置 xdebug 断点 响应并不保证 condition 或跟踪点表达式有效;请稍后检查 breakpointErrorsTail 后再依赖它们。

  • 成功的行断点响应还包括 lineText ,即断点当前所在实际源代码行的截断摘录。 恢复前检查它以确认放置位置。

应用语义:

  • 提供的字段会作为目标断点的结果状态应用。

  • condition=null 会清除现有条件。

  • isLogMessage=true 会记录断点命中位置。

  • isLogStack=true 会记录当前堆栈跟踪。

  • 如果两个标志均为 true,则会同时记录位置和堆栈。

  • 使用 isLogMessage/isLogStack + suspendPolicy=NONE 时,断点会表现为跟踪点。

  • 在 ID 模式下,如果为行断点提供了 filePath/line ,则会在新位置重新定位(重新创建)该断点。

  • 在 ID 模式下,对于非行断点, filePath/line 会被忽略并在 消息 中报告。

  • 任何成功的操作都会将断点标记为 agent 所有权(mcpBreakpointMarker)。

下一次调用:

  • 使用返回的 lineText 和/或 列出 xdebug 断点 验证放置位置。

  • 通过 xdebug_start_debugger_session 或 xdebug_control_session(action=RESUME) 启动/继续执行。

参数:

  • breakpointId: 由 设置 xdebug 断点 或 列出 xdebug 断点 返回的规范断点 ID。

  • filePath :用于筛选断点的可选文件路径。 文件路径。 支持相对于项目的路径、带有 .. 的路径、绝对路径、类似 /path/lib.jar!/pkg/Foo.class 的归档条目,以及如 file:// 、 jar:// 、 jrt:// 的 URL。 可以直接传递其他工具返回的路径(例如来自 search_* 工具的路径)。 如果未指定,则返回所有断点。 默认值: null。

  • line :从 1 开始的行号。 仅在位置模式下必需。 在 ID 模式下可选,用于重新定位行断点。

  • condition: 可选条件表达式 - 仅当其求值为 true 时,断点才会触发。 验证错误会通过 xdebug_control_session(...).breakpointErrorsTail 异步报告(仅限基于 JVM 的调试器)。 默认值: null。

  • isLogMessage: 当到达断点时,是否记录断点命中位置(源位置)。 在基于 JVM 的调试器中,可通过 xdebug_control_session(action=DRAIN_EVENTS).tracepointOutputsTail 获取输出。 默认值: false。

  • isLogStack: 当到达断点时,是否记录堆栈跟踪。 在基于 JVM 的调试器中,可通过 xdebug_control_session(action=DRAIN_EVENTS).tracepointOutputsTail 获取输出。 默认值: false。

  • temporary: 临时断点(首次命中后移除)。 默认值: false。

  • suspendPolicy :挂起策略: ALL、 THREAD、 NONE。 默认值: ALL。

  • 已启用: 断点是否已启用。 默认值: true。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

xdebug_set_variable

根据所选堆栈帧中的路径改变变量值。 使用此工具在调试期间更改状态。

前提条件:

路径格式与 按路径获取 xdebug 值 中的相同。 newValue 必须是当前帧语言中的原始表达式,并且必须可由调试器/求值器赋值给目标值。 不要传递经过 JSON 转义的有效负载或文字转义序列,例如 \\"text\\"。

结果:

  • 返回 oldValue/newValue/applied。

  • 不支持的变更会返回带有文本消息的错误。

下一次调用:

参数:

  • sessionId :调试会话 ID。 使用 获取 xdebug 调试器状态 或 启动 xdebug 调试器会话 返回的当前 ID。 如果会话已停止、超时或消失,请在重用旧 ID 之前刷新会话列表。 格式:默认使用会话名称作为 ID;如果多个会话共享同一名称,则 ID 为 <sessionName>#<executionId>。 如果为 null 且只存在一个活动会话,则会自动选择该会话。 如果多个会话处于活动状态且省略了 sessionId ,则调用会失败。 默认值: null。

  • frameIndex: 作为整数的堆栈帧索引(0 = 顶部帧)。 请从当前暂停的 获取 xdebug 堆栈 结果中获取;在 RESUME、 STEP_*、 xdebug_run_to_line 或暂停位置发生任何变化后,不要重用缓存的帧索引。 如果为 null,则使用顶部帧。 默认值: null。

  • path :目标值的路径,格式与 按路径获取 xdebug 值 相同。 使用当前已暂停 获取 xdebug 帧值/按路径获取 xdebug 值 输出中的确切节点名称,并在暂停位置更改后刷新过时的路径令牌。

  • newValue :要赋值的新值表达式。 传递当前帧语言中的原始表达式文本;它必须可由调试器/求值器赋值给目标值。 不要传递经过 JSON 转义的载荷或文字反斜杠转义的引用文本。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

xdebug_start_debugger_session

为当前项目中按名称指定的现有运行配置或代码位置(filePath + line )启动调试器会话。 使用此工具启动调试器会话。 将此工具与现有运行配置名称一起使用,或与 filePath + line 一起使用。 使用 filePath + line 时,包含 runnable 方法例如 main 、测试或其他可执行文件入口点的行几乎总是可用。 如果不确定要使用哪一行, get_run_configurations 可帮助发现文件中的 runnable 位置。 会话将会启动,然后可以使用其他调试器工具控制执行。

前提条件:

  • 使用 configurationName 时,请传递确切的现有运行配置名称;不要传递测试方法名称或其他派生的目标标识符。

  • 使用 filePath + line 时,请指向 runnable 代码位置,例如 main 、测试或其他可执行文件入口点。

  • 请先设置至少一个断点;否则程序可能会运行至完成而不暂停。

  • 请传递 configurationName ,或与 filePath 及 line 一起传递。 这些模式互斥。

行为:

  • 等待会话创建,最长不超过 timeout。

  • 会话启动后应用宽限等待(graceWaitMs )并返回已刷新的状态。

  • 可选启动重写项(programArguments、 workingDirectory、 envs )仅应用于此次调试启动,且不会持久保存。

  • get_run_configurations 是重写支持的真实来源:仅当所选运行配置报告 supportsDynamicLaunchOverrides=true 时,才传递启动重写项。

  • 除非明确需要更改此次调试启动的已配置启动值,否则不要传递这些重写参数。

  • 如缺失/为空,重写参数保持已有运行配置值不变。

  • 对于字符串重写项(programArguments、 workingDirectory ),缺失/null 或空字符串("" )会保持现有值不变。

  • 传递仅含空格的字符串,例如 " " ,以清除此调试启动的现有值。

下一次调用:

返回一个扁平结果,其中包含调试器会话元数据以及启动中的执行快照字段:

  • sessionId、 名称、 status 和可选的 runConfigurationName

  • 输出 预览和可选的 fullOutputPath

  • 在进程终止已知时可选的 exitCode

参数:

  • configurationName :要调试的现有运行配置的名称。

  • filePath :相对于项目根目录的文件路径。 与 line 一起提供,以从代码位置开始调试。

  • line: filePath 的 1 基准行号。 请与 filePath 一同提供,且不要与 configurationName 同时使用。

  • timeout :等待调试会话启动的超时时间,单位为毫秒。 默认值:60000。

  • graceWaitMs :会话启动后用于刷新状态的宽限等待时间,单位为毫秒。 默认值:2000。

  • programArguments :此次启动可选程序实参重写。 仅当所选运行配置在 get_run_configurations 中报告 supportsDynamicLaunchOverrides=true 时才传递此项。 如缺失/为空字符串则保持现有值,仅空格字符串将其清空。

  • workingDirectory :此次启动仅重写的可选工作目录。 仅当所选运行配置在 get_run_configurations 中报告 supportsDynamicLaunchOverrides=true 时才传递此项。 如缺失/为空字符串则保持现有值,仅空格字符串将其清空。

  • envs :此次启动仅重写的可选环境变量。 仅当所选运行配置在 get_run_configurations 中报告 supportsDynamicLaunchOverrides=true 时才传递此项。 如缺失/null 则保持现有环境变量不变;如提供则将值合并到现有环境变量。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

执行工具

execute_run_configuration

在当前项目中按名称运行已存在的运行配置,或从代码位置(filePath + line )创建临时运行配置运行,然后等待其在指定超时时间内完成。 可使用此工具,根据 get_run_configurations 返回的配置名称,或与 get_run_configurations(filePath = ...) 返回的运行点(filePath + line )配合使用。

可选的启动重写(programArguments、 workingDirectory、 envs )仅对此次运行生效,不会被持久保存。 仅当确实需要更改此次运行的启动值时才传递这些重写参数。 如缺失/为空,重写参数保持已有运行配置值不变。 对于字符串重写(programArguments、 workingDirectory ),如缺失/为空字符串("" )则保持已有值。 传递如 " " 这样的仅包含空格的字符串可以清除此次启动已有值。

请传递 configurationName ,或与 filePath 及 line 一起传递。 这些模式互斥。

行为:

  • 当 waitForExit=true 时,最多等待 timeout 毫秒以等待进程终止。 如超时,进程将在后台继续运行,并且结果中省略 exitCode。

  • 当 waitForExit=false 时,仅等待进程启动后立即返回,不应用 timeout。

  • fullOutputPath 指向包含完整原始输出的临时文件,并且在进程存活期间可能持续增长。

返回执行结果,包含当前输出快照、可选退出码及可选 fullOutputPath。

参数:

  • configurationName :要执行的现有运行配置名称。

  • filePath :相对于项目根目录的文件路径。 请与 line 一起以代码上下文创建并执行临时运行配置。

  • line: filePath 的 1 基准行号。 请与 filePath 一同提供,且不要与 configurationName 同时使用。

  • timeout :超时(毫秒)。

  • waitForExit :是否等待进程终止。 如为 false,工具将在进程启动后立即返回并忽略 timeout。

  • programArguments :此次启动可选程序实参重写。 如缺失/为空字符串则保持现有值,仅空格字符串将其清空。

  • workingDirectory :此次启动仅重写的可选工作目录。 如缺失/为空字符串则保持现有值,仅空格字符串将其清空。

  • envs :此次启动仅重写的可选环境变量。 如缺失/null 则保持现有环境变量不变;如提供则将值合并到现有环境变量。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

get_run_configurations

根据输入返回项目运行配置或可执行文件代码位置。

无 filePath 时,该工具会列出现有的项目运行配置。 结果包含配置名称,且在可用时,包含启动详情,如程序实参、工作目录、环境变量和 supportsDynamicLaunchOverrides。

supportsDynamicLaunchOverrides 是一次性启动重写(programArguments、 workingDirectory、 envs )在 execute_run_configuration 和 xdebug_start_debugger_session 中的真实来源能力标志。 仅当该标记为 true 时才传递重写参数到所选配置。

借助 filePath ,该工具可发现此文件中的可执行文件入口点(运行点),如测试方法、main 方法或 IDE 显示运行装订区域图标的其他可执行文件入口点。 结果包含 filePath 和 runPoints ,可配合 execute_run_configuration 返回的行号实现代码运行。

参数:

  • filePath :可选的相对于项目根目录的文件路径。 如提供,则返回文件中的运行点(可执行文件入口点),而不是项目范围的运行配置。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

文件工具

create_new_file

在项目目录中的指定路径创建新文件。 可选择将提供的文本写入该文件。

参数:

  • pathInProject :应创建文件的路径,相对于项目根目录。

  • 文本 (可选):要写入新文件的内容。

  • overwrite :是否覆盖现有文件。 如果设置为 false ,发生冲突时将抛出异常。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

get_all_open_file_paths

返回在活动编辑器或任何其他已打开的编辑器中打开进行编辑的所有文件的路径,相对于项目根目录。 使用此工具探索当前打开的编辑器。

参数:

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

list_directory_tree

以伪图形格式提供指定目录的树状表示,类似于 tree 实用工具。 使用此工具浏览目录或整个项目的内容。 列出目录时,优先使用此工具,而非 ls 或 dir 等命令行实用工具。

参数:

  • directoryPath :相对于项目根目录的路径。

  • maxDepth :最大递归深度。

  • timeout :超时(毫秒)。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

open_file_in_editor

在 JetBrains IDE 编辑器中打开指定文件。 需要一个 filePath 参数,其中包含要打开的文件路径。 文件路径可以是绝对路径,也可以是相对于项目根目录的路径。

参数:

  • filePath :相对于项目根目录的路径。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

格式设置工具

reformat_file

在 JetBrains IDE 中重新格式化指定文件。 使用此工具对通过其路径标识的文件应用代码格式化。

参数:

  • path :相对于项目根目录的路径。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

检查生成器 MCP 工具

验证检查 KTS

校验 inspection.kts 脚本是否符合规范示例。 编译该检查并在正例/反例上运行。 返回编译状态和详细验证结果。

正例应触发检查(预期存在问题)。 反例不应触发检查(禁止行上应无问题)。

返回整体成功信息、按示例结果以及聚合统计。

参数:

  • inspectionKtsCode :要编译并校验的 inspection.kts 脚本内容。

  • pathToSpecification :包含用于校验的示例的规范路径。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

检查 KTS MCP 工具

生成检查 KTS 接口

返回目标语言的检查 KTS API 文档。 提供可用于编写 inspection.kts 文件的可用类和函数。

参数:

  • language :目标语言:'Java' 或 'Kotlin'。

  • wrapInTags :如为 true,则会将 API 内容包裹在 <API> 和 <api.kt> 标记中。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

生成检查 KTS 示例

返回目标语言的示例 inspection.kts 模板,用于指导代码生成。 提供 XML 已包装的示例,演示如何使用 InspectionKts API 编写检查。

参数:

  • language :目标语言:'Java' 或 'Kotlin'。

  • includeAdditionalExamples :如为 true,则除模板外含更多精选示例。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

生成 PSI 树

针对所提供的 Java 或 Kotlin 代码创建 PSI 树,并以缩进文本形式返回。 当编写检查时,可使用此工具了解代码段的 PSI 结构。 输出会显示元素类型及其层次结构,并提示何时需要 node.children()。

参数:

  • code :要解析的源代码段。

  • language :目标语言:'Java' 或 'Kotlin'。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

运行检查 KTS

编译 inspection.kts 脚本并在目标文件上运行。 如有编译错误则返回,否则返回检查发现的问题列表。 开发期间可使用此工具测试 inspection.kts 脚本。

参数:

  • inspectionKtsCode :要编译并运行的 inspection.kts 脚本内容。

  • contextPath :项目内要分析的目标文件相对路径(例如 src/my/package/Example.kt )。

  • targetFileContent :要分析的目标文件内容。 如未指定,则文件必须在项目中存在。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

补丁工具

apply_patch

应用 Codex apply_patch 格式或统一 Git 差异格式的补丁。 支持添加、删除和更新操作,并为更新提供可选的移动目标路径。 路径必须位于项目目录内。

参数:

  • input: apply_patch 格式或统一 Git 差异格式的补丁文本。

  • patch: input 的别名,用于兼容发送 {patch: ...} 的客户端。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

读取工具

读取文件

读取项目目录、项目依赖或其他项目源根下的文件。 可以读取 Jar/Jrt 文件内的源代码,并反编译 Jar/Jrt 文件或磁盘中的 Java 类文件。 以文本形式返回带编号的行(从 1 开始索引)。

模式:

  • slice

  • lines

  • line_columns

  • offsets

  • indentation

模式详情:

  • slice 使用 start_line 和 max_lines。

  • lines 使用 start_line/end_line (包含边界)。

  • line_columns 使用 start_line/start_column 和 end_line/end_column (end 为不包含, end_line 默认为 start_line)。

  • offsets 使用 start_offset/end_offset (end 为不包含)。

  • indentation 使用 start_line ,并与 max_levels/include_* 一起。

max_lines 限制所有模式下的总输出; context_lines 适用于区间模式(每侧)。

参数:

  • file_path :文件的路径。 支持相对于项目的路径、带有 '..' 的路径、绝对路径、类似 /path/lib.jar!/pkg/Foo .class 的归档条目,以及如 file:// 、 jar:// 、 jrt:// 的 URL。 可以直接传递其他工具返回的路径(例如来自 search_* 工具的路径)。

  • mode :读取模式: slice、 lines、 line_columns、 offsets 或 indentation。

  • start_line :从第 1 行开始读取的行号。

  • max_lines :返回的最大行数(切片用作行数;所有模式都会限制输出)。

  • end_line: lines/line_columns 模式下基于 1 的结束行号(lines 包含, line_columns 不包含)。

  • start_column: line_columns 模式下基于 1 的起始列。

  • end_column :区间读取时基于 1 的结束列(不包含)。

  • start_offset :偏移量模式下基于 0 的起始偏移(需要 end_offset)。

  • end_offset :偏移量模式下基于 0 的结束偏移(不包含)。

  • context_lines :区间每侧需包含的上下文行数。

  • max_levels :缩进模式:要包含的最大缩进级别(0 = 仅锚块)。

  • include_siblings :缩进模式:包含同一缩进级的兄弟代码块。

  • include_header :缩进模式:包含直接位于锚点上方的页眉注释/注解。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

重构工具

rename_refactoring

重命名指定文件中的符号(变量、函数、类等)。 使用此工具执行重命名重构操作。

与简单的文本查找并替换不同, rename_refactoring 工具是理解代码结构的上下文感知型实用工具。 它会智能更新整个项目中对指定符号的所有引用,确保代码完整性并防止引用失效。 它始终是重命名编程符号的首选方法。

如果重命名操作成功,该工具将返回成功消息;如果找不到文件或符号,或重命名操作失败,则返回错误消息。

参数:

  • pathInProject :相对于项目根目录的路径。

  • symbolName :要重命名的符号名称。

  • newName :符号的新名称。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

搜索工具

搜索文件

通过全局模式在项目中搜索文件。 需要用全局语法匹配文件路径时请使用此工具。

全局模式是相对于项目根目录的。

示例:

  • "**/*.kt"

  • "src/**/Foo*.java"

  • "build.gradle.kts"

不包含 '/' 的模式被视为 "**/pattern"。 paths 是相对于项目根目录的可选全局筛选器。

参数:

  • q :要搜索的 glob 模式。

  • paths :可选项目相对的全局模式列表,用于筛选器结果。 支持 ! 排除。 结尾的 / 会扩展为 **。 不包含 / 的模式被视为 **/pattern。 空字符串会被忽略。

  • includeExcluded :是否在结果中包含已排除/忽略的文件。

  • limit :返回的最大结果数。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

搜索正则表达式

在项目文件中按正则表达式搜索匹配项。 需要正则表达式并带有代码段结果时请使用此工具。 结果会在可用时包含匹配坐标(基于 1 的行/列,基于 0 的偏移)。

路径为相对于项目根目录的全局模式。

示例:

  • ["src/**", "!**/test/**"]

  • ["**/*.kt"]

  • ["foo/"]

参数:

  • q :要搜索的正则表达式模式。

  • paths :可选项目相对的全局模式列表,用于筛选器结果。 支持 ! 排除。 结尾的 / 会扩展为 **。 不包含 / 的模式被视为 **/pattern。 空字符串会被忽略。

  • limit :返回的最大结果数。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

搜索符号

搜索符号(类、方法、字段)。 使用此工具可通过标识符片段进行语义查找。 结果会在可用时包含匹配坐标(基于 1 的行/列,基于 0 的偏移)。

路径为相对于项目根目录的全局模式。

默认仅搜索项目内的符号。 如果没找到合适结果,可使用 include_external=true 重新进行 SDK 及库符号搜索。

参数:

  • q :符号查询文本。

  • paths :可选项目相对的全局模式列表,用于筛选器结果。 支持 ! 排除。 结尾的 / 会扩展为 **。 不包含 / 的模式被视为 **/pattern。 空字符串会被忽略。

  • include_external :是否包含 SDK 和库符号。 默认禁用;如未找到合适结果,请尝试使用 include_external=true。

  • limit :返回的最大结果数。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

搜索文本

在项目文件中搜索文本子字符串。 需要快速文本搜索和代码段结果时请使用此工具。 结果会在可用时包含匹配坐标(基于 1 的行/列,基于 0 的偏移)。

路径为相对于项目根目录的全局模式。

示例:

  • ["src/**", "!**/test/**"]

  • ["**/*.kt"]

  • ["foo/"]

参数:

  • q :要搜索的文本。

  • paths :可选项目相对的全局模式列表,用于筛选器结果。 支持 ! 排除。 结尾的 / 会扩展为 **。 不包含 / 的模式被视为 **/pattern。 空字符串会被忽略。

  • limit :返回的最大结果数。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

技能搜索工具

使用显式模式执行统一项目搜索:

  • 文件 :glob 路径搜索。

  • 文本 :文字内容搜索。

  • regex :正则表达式内容搜索。

  • symbol :语义符号查找。

符号搜索默认聚焦于项目。 如果找不到合适的符号,请使用 include_external=true 重试,以同时搜索 SDK 和库符号。

参数:

  • mode (必需):搜索模式: 文件、 文本、 regex 或 symbol。

  • q (必需):搜索查询。 对于 mode=file ,这是一个 glob 模式。

  • paths :可选的项目相对 glob 筛选器。 支持 ! 排除和末尾的 /。

  • include_external :是否为 mode=symbol 包含 SDK 和库符号。 默认禁用;如果找不到合适的内容,请使用 include_external=true 重试。

  • includeExcluded :是否包含已排除或已忽略的文件。 仅支持 mode=file。

  • limit :返回的最大结果数。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

终端工具

execute_terminal_command

在 IDE 的集成终端中执行指定的 shell 命令。 使用此工具在 IDE 环境中运行终端命令。

重要功能和限制:

  • 在收集输出之前检查进程是否在运行。

  • 将输出限制为 2000 行(超出部分将被截断)。

  • 在指定的超时时间后超时,并发出通知。

  • 除非在设置中启用了 Brave Mode ,否则需要用户确认。

返回的可能响应:

  • 终端输出(超过 2000 行时将被截断)。

  • 如果命令超时,输出将包含中断通知。

  • 针对各种失败情况的错误消息。

参数:

  • 命令 :要执行的 shell 命令。

  • executeInShell :是否在用户的默认 shell(bash、zsh 等)中执行该命令。 如果该命令是 shell 脚本,或需要保留用户终端的真实环境,则非常有用。 如果设置为 false ,将以进程方式启动该命令。

  • reuseExistingTerminalWindow :是否重用现有终端窗口,以避免创建多个终端。

  • timeout :超时(毫秒)。

  • maxLinesCount :返回的最大行数。

  • truncateMode :如何截断文本:从开头、中间、末尾截断,或不截断。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

通用工具

execute_tool

通用工具执行器,可从命令行字符串动态调用特定的 IDE MCP 工具。

参数:

  • 命令 (必需):包含工具名称和实参的命令行字符串。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

VCS 工具

get_repositories

检索项目中的 VCS 根列表。 在多仓库项目中使用此工具识别所有仓库。

参数:

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

Git 状态

检索当前项目中一个或多个仓库的 Git 状态。 返回 porcelain 风格的索引和工作树状态代码以及汇总计数器。 默认返回所有 Git 仓库。

参数:

  • repositoryPathRelativeToProject :相对于项目根目录的可选路径,用于选择单个包含它的仓库。

  • includeUntracked :是否包含未跟踪的文件。

  • includeIgnored :是否包含已忽略的文件。

  • limit :每个仓库返回的最大条目数。

  • projectPath :项目路径。 如已知,请始终提供此值,以减少歧义调用。 如果仅知道当前工作目录,您可以将其用作项目路径。

2026年 11月 6日