1. 为什么 LaTeX 写作者需要一个「会动手」的 MCP
如果你平时用 TeXstudio 写论文或技术文档，大概率遇到过这种场景：想让 AI 帮忙改一段公式、补一条参考文献、排查一个编译报错，结果它只能给你一段「看起来对」的文本，你还得自己复制粘贴、手动编译、翻日志找问题。整个过程 AI 像个只会聊天的旁观者，真正动手的还是你。
texstudio-mcp 想解决的就是这件事。它是一层面向 LaTeX 工程的 MCP 服务，把「读源码、改 .tex、跑编译、看日志、查 PDF」这些动作封装成结构化工具，让 Cursor、Claude Desktop 这类支持 MCP 的 AI 客户端能真正操作你的工程目录。核心机制是一个 workspace_root 沙箱：所有文件读写都限制在你指定的工程根目录内，绝对路径和带..的逃逸路径会被直接拒绝，AI 批处理时不容易误删系统里的其它文件。
它适合谁？本地已经装好 TeXstudio 和 TeX Live、希望把 AI 接进现有 LaTeX 工作流的写作者。你不需要换编辑器，TeXstudio 继续当主力，texstudio-mcp 作为一层桥，把工程能力暴露给 AI 客户端。这篇先讲清楚它能做什么、怎么配 TaoToken 统一通道、怎么跑一次编译验证；下一篇再单独写完整部署与踩坑。
2. TaoToken 前置：统一 Key 与 API 通道
texstudio-mcp 本身不绑定任何模型供应商，它只负责「动手」，具体用哪个大模型来驱动，由你的 AI 客户端决定。问题在于，Cursor、Claude Desktop 这类客户端各自要配 Key、配 Base URL，多套配置散落各处，换模型时改起来很烦。TaoToken 在这里的角色是统一入口：一个 Key、一个 API 通道，兼容主流客户端的接入方式，省掉到处找 Key 的麻烦。
你需要先拿到两样东西：
- 一个 API Key，在控制台的 API Keys 页面创建，形如
sk-...，注意只显示一次，创建后立刻复制保存。 - 接入地址，对话与补全类请求走
https://taotoken.net/api，这个地址不带任何查询参数，直接填进客户端的 Base URL 字段即可。
如果你只是想让 AI 读工程、改 .tex、跑编译，用按量计费的 API Key 就够了。但如果你打算长期让 AI 参与编码和 Agent 流程（比如反复编译、批量改稿、多轮文献编排），调用量会明显上去，这时候 Coding Plan 更划算，额度更宽松，适合高频交互场景。两种方式用的是同一套接入地址，切换时只改 Key 或套餐，客户端配置基本不用动。
注意：TaoToken 是合规的 API 聚合通道，不是任何形式的网络代理工具。配置时只填官方给的接入地址，不要自行拼接其它域名。
3. 可复制配置：MCP 服务端与客户端骨架
这一节给两份可直接改的配置骨架。第一份是 texstudio-mcp 服务端自身的配置，第二份是 AI 客户端里声明这个 MCP 服务的配置。两份都只是骨架，路径和 Key 换成你自己的即可。
3.1 服务端配置骨架（config.toml）
texstudio-mcp 通常通过 stdio 方式被客户端拉起，服务端配置主要声明工程根目录和工具链行为。下面是一个config.toml示例：
# texstudio-mcp 服务端配置骨架 [workspace] # 你的 LaTeX 工程根目录，建议与 TeXstudio 的当前工作目录一致 root = "/home/yourname/papers/thesis" # 主 tex 文件相对 workspace_root 的路径 main_tex = "main.tex" # 路径策略：strict 表示拒绝一切逃逸 workspace_root 的访问 path_policy = "strict" [toolchain] # 编译引擎，latexmk 会据此选择 pdflatex/xelatex 等 engine = "pdflatex" # 文献后端：auto 会先编译再根据 .aux/.bcf 判断用 bibtex 还是 biber bibliography_tool = "auto" # bib 成功后再跑几次 latexmk，0~2 post_bibliography_latexmk_passes = 1 # 「bib + 后续 latexmk」的轮数上限，1~4 bibliography_cycles = 2 [limits] # 单次读取文件的最大字符数，避免把巨型文件塞进上下文 max_chars = 200000 # 编译输出截断长度，控制返回给 AI 的 JSON 体积 stdout_tail_chars = 8000几个参数值得单独说。root一定要指向主 .tex 所在的那一层，这样只传main.tex这样的 basename 时，服务会自动避免多余的latexmk -cd；如果 root 是仓库根、主文件在子目录，就写相对路径如thesis/main.tex，由 latexmk 在子目录里编译。path_policy = "strict"建议保持，这是沙箱安全的关键。bibliography_tool = "auto"适合大多数场景，服务会在首次编译后读.aux/.bcf判断该用哪个后端。
3.2 客户端配置骨架（settings.json）
在 Cursor 或 Claude Desktop 里，MCP 服务一般声明在settings.json或对应的 MCP 配置段。下面以 stdio 方式为例：
{ "mcpServers": { "texstudio-mcp": { "command": "python", "args": [ "-m", "texstudio_mcp", "--config", "/home/yourname/.config/texstudio-mcp/config.toml" ], "env": { "TAOTOKEN_API_KEY": "sk-你的Key", "TAOTOKEN_BASE_URL": "https://taotoken.net/api" } } } }这里command和args按你实际的 Python 环境和安装方式调整，如果用虚拟环境，command指向 venv 里的 python 可执行文件。env里的两个变量是给上层 AI 客户端用的统一通道，texstudio-mcp 本身不消费它们，但同一份配置里放一起，换模型时只改这一处。
提示：
TAOTOKEN_BASE_URL填https://taotoken.net/api，不要加尾部斜杠，也不要带查询参数。Key 建议用环境变量注入，不要硬编码进会提交到 Git 的文件。
4. 验证请求：一次编译确认 AI 能读工程并触发构建
配置写完，别急着让 AI 大改稿，先做一次最小验证：确认它能读到工程、能触发编译、能拿到日志。整个过程分三步。
第一步，让 AI 调用health_check_tex_toolchain。这个工具只做which探测，不启动编译，返回 latexmk、pdflatex、xelatex、bibtex、biber、chktex、pdfinfo、pdftotext、synctex 等是否在 PATH 里。如果这里就报缺失，说明本机 TeX 工具链没装全，先补装再往下走。
第二步，让 AI 调用read_project_file读你的main.tex，再调用parse_tex_dependencies做一次静态扫描。后者会解析\input、\include、\includegraphics、\usepackage、\bibliography、\addbibresource等依赖，返回一张依赖图。这一步能确认 AI 真的读到了你的工程，而不是在凭空猜。注意它不执行 TeX，带\、\#这类动态路径的会进unresolved，属于正常现象。
第三步，触发一次真实编译。调用compile_latex_document，对main.tex执行latexmk -pdf。返回结构里你会看到：
{ "summary": "latexmk -pdf main.tex 成功，用时 3.2s", "exit_code": 0, "timed_out": false, "wall_clock_ms": 3210, "stdout_tail": "...", "stderr_tail": "..." }exit_code为 0、summary显示成功，就说明 AI 已经能读取工程并触发构建。如果失败，接着调用analyze_latex_log读.log尾部，它会启发式提取 error 和 warning，比你自己翻几千行日志快得多。需要看全文时，用read_project_file直接读.log。
一个容易忽略的点：同一 MCP 进程、同一 workspace_root 同时只能跑一个「会改产物」的任务，编译、bib、编排流水线互斥。如果你并行发第二次编译请求，会收到concurrent_workspace_exclusive_blocked。这是设计如此，不是 bug，串行发就行。
5. 本篇常见错排查
配置和验证过程中，下面几个问题出现频率最高，逐个说清楚。
PATH 里找不到 latexmk。health_check_tex_toolchain返回 false，多半是 TeX Live 装了但没进 PATH，或者 MCP 服务启动时的环境变量和你终端里不一致。先在你平时编译的终端里跑which latexmk确认路径，再把这个路径所在的 bin 目录补进 MCP 配置的env.PATH。macOS 上 TeX Live 常在/usr/local/texlive/2024/bin/universal-darwin，Linux 上多在/usr/local/texlive/2024/bin/x86_64-linux，按你的版本改。
编译报 concurrent_workspace_exclusive_blocked。说明同一 workspace_root 上已有编译任务在跑。等前一个返回，或者检查是不是开了多个 Cursor 窗口、多个 MCP 实例同时指向了同一个文件夹。多实例并发写同一目录是真实风险，建议一个工程只挂一个 MCP 实例。
PDF 或 SyncTeX 工具报缺失。read_pdf_metadata、extract_pdf_text_preview、resolve_synctex_forward/backward依赖本机 Poppler 和 SyncTeX，且工程内要已有对应的.pdf和.synctex.gz。这两个文件通常编译后才生成，先成功编译一次再调用。Poppler 在 Linux 上是poppler-utils包，macOS 上brew install poppler。
文献后端选错。如果bibliography_tool = "auto"判断不准，可以先调guess_job_bibliography_backend只读查看JOB.bcf、JOB.aux片段，它会返回建议用 biber 还是 bibtex 及置信度，不启动子进程。确认后把bibliography_tool显式设成biber或bibtex。跑完若还有问题，用analyze_bibliography_log读.blg，它能区分 biber 和 BibTeX 两种风格的问题。
job_name 推导不出来。编排流水线里job_name可为空，默认从main_tex文件名推导。如果主文件名和实际 job 名对不上，可以开启read_texstudio_profile_snapshot的include_parsed_hints=true，它会启发式解析 TeXstudio 的texstudio.ini、lastSession.txss，给出suggested_job_basename，对齐你 IDE 里最近打开的那篇稿子。注意这个工具只读白名单文件名，禁止子路径，也不应把 TeXstudio 里的绝对路径自动纳入 workspace_root。
日志太长看不完。analyze_latex_log返回的是摘要型结果，不是全文。大段 latexmk 输出请用read_project_file读工程内的.log文件，配合max_chars控制读取量。
6. 把 AI 接进 LaTeX 工作流的下一步
到这里，你已经有了一个能跑通的最小闭环：TaoToken 提供统一 Key 和 API 通道，texstudio-mcp 提供工程沙箱和工具集，AI 客户端负责编排。接下来按你的使用强度选路径。
如果你主要做排障和接入调试，先把 API Keys 建好、把接入文档过一遍，确认 Base URL 和 Key 填对，再回到上面的三步验证。如果你只是想先试试模型能不能读懂你的 LaTeX 工程，去模型对话页面直接聊，把main.tex内容贴进去问依赖关系，感受一下再决定要不要上 MCP。如果你打算长期让 AI 参与编码和 Agent 流程，反复编译、批量改稿、多轮文献编排，那 Coding Plan 更合适，额度宽松，高频交互不会卡。
texstudio-mcp 的能力边界也要心里有数：它不替代完整 IDE，不提供 PDF 预览 UI 和正反向同步的交互界面，只提供数据接口；编译收敛有轮数上限，复杂引用仍可能需要你手动多编几次；日志是截断的，全文要自己读.log。把这些边界认清楚，再把它当成 TeXstudio 旁边的一个自动化助手，而不是替代品，用起来会顺很多。下一篇会写完整部署与接入，包括从仓库克隆、虚拟环境安装、workspace_root 与 main_tex 的推荐组合，以及文献流水线参数怎么选。
