mcp
工具参考
Clarity 服务器提供的全部 11 个 MCP 工具的完整参考。
Clarity MCP 服务器提供 11 个工具，分为四个类别。以下是每个工具的详细说明、参数及使用场景。
项目与文件工具
list_projects
列出 Clarity 工作区中的所有项目。 返回所有未删除项目的元数据。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| （无） | — | — | 无参数 |
使用场景： 从此开始获取其他工具所需的 project_id。
list_files
列出项目中的所有文件。 返回文件名、类型、路径和主文件标识。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
project_id | string | 是 | 项目 ID |
使用场景： 浏览项目文件树并获取其他工具所需的 file_id 值。
read_file
读取文件的完整内容。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
file_id | string | 是 | 要读取的文件 ID |
使用场景： 在编辑、诊断错误或回答文件相关问题之前使用。
write_file
更新现有文件的内容。 替换整个文件。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
file_id | string | 是 | 要更新的文件 ID |
content | string | 是 | 新的文件内容 |
此操作会覆盖整个文件。请务必先读取文件，然后发送完整的更新内容。
create_file
在项目中创建新文件。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
project_id | string | 是 | 要在其中创建文件的项目 |
name | string | 是 | 带扩展名的文件名（例如 chapter2.tex、refs.bib） |
content | string | 否 | 初始文件内容（默认为空） |
parent_id | string | 否 | 父文件夹 ID。省略则放在项目根目录。 |
安全特性：
- 验证文件名（不含斜杠，最多 255 个字符）
- 防止同一文件夹中出现重复名称
- 验证父文件夹是否存在
delete_file
从项目中删除文件。 此操作不可撤销。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
file_id | string | 是 | 要删除的文件 ID |
安全特性：
- 不能删除主入口文件
- 不能删除非空文件夹
- 删除前验证所有权
删除操作不可逆。请谨慎使用。
编译与调试
compile
编译项目并返回结果。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
project_id | string | 是 | 要编译的项目 ID |
返回：状态、PDF 标识、诊断信息（包含行号的错误）和截断的编译日志。
debug_compile
编译并返回结构化的错误分析。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
project_id | string | 是 | 要调试的项目 ID |
除 `compile` 之外的额外功能：
- 对错误进行分类（未定义命令、缺少文件、语法问题）
- 为每种错误类型建议具体的修复操作
- 提取最相关的日志行
- 返回调试工作流：读取 → 修复 → 写入 → 再次编译
Typst 文档
typst_docs_search
搜索内置的 Typst 文档库。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
query | string | 是 | 搜索查询 |
返回：匹配的文档，包含标题、路径、相关性评分和内容片段。
在编写 Typst 代码之前使用此工具，确保您使用了正确的语法和模式。
typst_docs_read
读取特定的 Typst 文档文件。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
path | string | 是 | 搜索结果中的 relativePath |
TikZ 插图
tikz_illustrate
生成专业的 TikZ 插图。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
project_id | string | 是 | 项目 ID |
description | string | 是 | 要绘制的内容描述 |
file_name | string | 否 | 图形的文件名 |
功能：
- 流程图和过程图
- 神经网络架构图
- 数学绘图（通过 pgfplots）
- 交换图（通过 tikz-cd）
- 费曼图（通过 tikz-feynman）
- 树形结构和层次图
- 通用科学插图
典型工作流
编辑并编译
- 1
list_projects→ 找到项目 - 2
list_files→ 浏览结构 - 3
read_file→ 读取目标文件 - 4
write_file→ 应用变更 - 5
compile→ 验证编译通过
调试编译失败
- 1
debug_compile→ 获取结构化错误分析 - 2
read_file→ 读取有错误的文件 - 3
write_file→ 修复问题 - 4
compile→ 确认修复
您可以在一个提示中完成所有操作："创建一个名为 methodology.tex 的新章节文件，添加一个 TikZ 流程图，将其包含到 main.tex 中，然后编译。"
这对您有帮助吗？