Clarity

mcp

工具參考

Clarity 伺服器公開的所有 11 個 MCP 工具的完整參考。

Clarity MCP 伺服器公開 11 個工具，分為四大類別。以下是每個工具、其參數以及使用時機。

專案與檔案工具

list_projects

列出 Clarity 工作區中的所有專案。 回傳所有非垃圾桶專案的中繼資料。

參數類型必填描述
（無）——無參數

使用時機： 從此開始以取得其他工具所需的 project_id。

list_files

列出專案中的所有檔案。 回傳名稱、類型、路徑和主檔案標記。

參數類型必填描述
project_idstring是專案 ID

使用時機： 探索專案的檔案樹並取得其他工具所需的 file_id 值。

read_file

讀取檔案的完整內容。

參數類型必填描述
file_idstring是要讀取的檔案 ID

使用時機： 在編輯、診斷錯誤或回答有關檔案的問題之前。

write_file

更新現有檔案的內容。 取代整個檔案。

參數類型必填描述
file_idstring是要更新的檔案 ID
contentstring是新的檔案內容

這會覆寫整個檔案。請務必先讀取檔案，然後傳送完整的更新內容。

create_file

在專案中建立新檔案。 當使用者需要新的 .tex、.typ、.bib、.sty 或任何其他檔案時使用。

參數類型必填描述
project_idstring是要建立檔案的專案
namestring是含副檔名的檔案名稱（例如 chapter2.tex、refs.bib）
contentstring否初始檔案內容（預設為空）
parent_idstring否父資料夾 ID。省略則放在專案根目錄。

安全功能：

  • 驗證檔案名稱（不可含斜線，最多 255 字元）
  • 防止同一資料夾中的重複名稱
  • 驗證父資料夾是否存在

使用時機： 當使用者要求建立新的章節、參考文獻、樣式檔案、圖表檔案或任何新文件時。

delete_file

從專案中刪除檔案。 此操作為永久性。

參數類型必填描述
file_idstring是要刪除的檔案 ID

安全功能：

  • 無法刪除主要入口檔案 — 需先設定其他主要檔案
  • 無法刪除非空資料夾 — 需先刪除內容
  • 刪除前驗證所有權

刪除為永久性操作。請謹慎使用。

編譯與除錯

compile

編譯專案並回傳結果。 自動偵測 LaTeX 或 Typst 以及正確的引擎。

參數類型必填描述
project_idstring是要編譯的專案 ID

回傳：狀態、PDF 標記、診斷資訊（含行號的錯誤）和截斷的編譯日誌。

debug_compile

編譯並回傳結構化的錯誤分析。 當編譯失敗時使用 — 它提供分類的錯誤、建議修正和逐步除錯工作流程。

參數類型必填描述
project_idstring是要除錯的專案 ID

超越 `compile` 的功能：

  • 分類錯誤（未定義的命令、缺少的檔案、語法問題）
  • 為每種錯誤類型建議具體的修正操作
  • 擷取最相關的日誌行
  • 回傳除錯工作流程：讀取 → 修正 → 寫入 → 再次編譯

使用時機： 當先前的 compile 失敗時，或當使用者表示「我的文件無法編譯」時。

Typst 文件

typst_docs_search

搜尋內建的 Typst 文件庫。 涵蓋 Typst 語言功能和 Touying 簡報框架。

參數類型必填描述
querystring是搜尋查詢（例如 "table"、"slide animation"、"bibliography"）

回傳：符合的文件，包含標題、路徑、相關性分數和內容片段。

在撰寫 Typst 程式碼之前使用此工具，以確保您使用的語法和模式正確。

使用時機： 當撰寫或編輯 Typst 檔案且需要查閱函式、語法或模式時。

typst_docs_read

讀取特定的 Typst 文件檔案。 在 typst_docs_search 之後使用以取得完整內容。

參數類型必填描述
pathstring是搜尋結果中的 relativePath

使用時機： 當搜尋結果看起來相關且您需要完整文件時。

TikZ 插圖

tikz_illustrate

生成專業的 TikZ 插圖。 建立新檔案並提供產生高品質圖表的結構化指引。

參數類型必填描述
project_idstring是專案 ID
descriptionstring是要繪製的內容（例如 "flowchart of ML pipeline"）
file_namestring否圖表的檔案名稱（例如 figures/pipeline.tex）

功能：

  • 流程圖和程序圖
  • 神經網路架構
  • 數學繪圖（透過 pgfplots）
  • 交換圖（透過 tikz-cd）
  • 費曼圖（透過 tikz-feynman）
  • 樹狀結構和層次結構
  • 一般科學插圖

使用時機： 當使用者要求在其 LaTeX 文件中加入圖表、圖形、插圖或視覺化內容時。

典型工作流程

編輯並編譯

  1. 1list_projects → 找到專案
  2. 2list_files → 探索結構
  3. 3read_file → 讀取目標檔案
  4. 4write_file → 套用變更
  5. 5compile → 驗證是否可編譯

建立新檔案

  1. 1list_projects → 找到專案
  2. 2create_file → 建立含有初始內容的新檔案
  3. 3對主要檔案執行 read_file → 新增 \input{} 或 #include 參考
  4. 4write_file → 更新主要檔案
  5. 5compile → 驗證一切正常

除錯失敗的建置

  1. 1debug_compile → 取得結構化的錯誤分析
  2. 2read_file → 讀取有錯誤的檔案
  3. 3write_file → 修正問題
  4. 4compile → 確認修正成功

自信地撰寫 Typst

  1. 1typst_docs_search → 查閱您需要的語法
  2. 2typst_docs_read → 閱讀完整文件
  3. 3write_file 或 create_file → 撰寫正確的 Typst 程式碼
  4. 4compile → 驗證渲染是否正確

您可以在單一提示中完成所有操作：「建立一個名為 methodology.tex 的新章節檔案，新增一個 TikZ 流程圖，將其納入 main.tex，然後編譯。」

這對您有幫助嗎？
上一頁設定指南下一頁 API 金鑰與安全性
工具參考 — Clarity Docs