Slidev 内置 MCP Server 使用与原理指南让 AI Agent 结构化读写、编排并导航演示文稿【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidevSlidev 从 v52.17.0 起内置了基于 Model Context ProtocolMCP的服务器为 AI Agent如 Claude Code、Codex、Cursor、VS Code Copilot 等暴露一组结构化工具用于读取、编辑、插入、删除、排序幻灯片甚至驱动正在运行的演示跳页。本文以仓库内技能文档 tool-mcp.md 为核心骨架结合其官方说明页 mcp.md 与真实源码实现完整讲解接入方式、全部工具参数、行为边界以及底层如何正确切分 Slidev 复合分隔符并触发热更新。与纯文本式的整文件改写不同这些工具面向“幻灯片级别”的操作update/insert/remove/move能够正确处理 Slidev 中---复合分隔符产生的歧义把修改精确写回 Markdown 文件并由正在运行的开发服务器即时热更新。读完本文你将掌握把任意 MCP 客户端接入 Slidev 的两种方式以及每一个内置工具的参数、语义、约束与源码实现依据。为什么需要内置 MCP Server一个 Slidev 演示文稿本质上是一个或多个用---分隔的 Markdown 文件。传统 AI 编辑方式通常是“读整个文件 → 文本替换 → 写回”存在两个痛点分隔符歧义Slidev 的一页幻灯片由 YAML frontmatter、Markdown/Vue 内容与尾部 HTML 注释形式的演讲备注复合而成页与页之间用---分隔。Agent 直接做文本级增删很容易切错边界缺少“语义定位”Agent 无法知道“第几页”对应文件哪一段也无法获知当前演示播放到哪一页。Slidev 内置的 MCP 服务器将上述能力抽象为 8 个结构化工具有效解决这两个问题。MCP 本身是一种开放协议由官方与 Anthropic 提出用于让 LLM 应用通过统一的 client/server 边界调用外部工具Slidev 的实现位于仓库 mcp 目录 下通过 server.ts 中的createSlidevMcpServer()统一创建同一套工具集合并分别暴露在开发服务器 HTTP 端点与独立的 stdio 进程上。接入方式一开发服务器上的 Streamable HTTP 端点当slidev开发服务器slidev命令默认模式运行时MCP 服务器会作为一个 Vite 插件挂载在如下地址使用 streamable HTTP 传输http://localhost:port/__mcp端点路径常量在 packages/slidev/node/vite/mcp.ts 中被定义为MCP_ENDPOINT /__mcp且仅在mode dev时生效。以官方文档示例默认端口 3030为例接入 Claude Codeclaude mcp add --transport http slidev http://localhost:3030/__mcp对于 VS Code / Cursor 这类读取.mcp.json或 IDE 配置的客户端则在mcpServers中声明同类型服务{ mcpServers: { slidev: { type: http, url: http://localhost:3030/__mcp } } }启动开发服务器时CLI 会在控制台打印端点提示见 cli.ts 附近形如mcp server http://localhost:3030/__mcpHTTP 模式独有的能力因为插件持有开发服务器上下文所以额外提供slidev-goto-slide工具可把当前已连接的所有浏览器含演示者视图与观众页面导航到指定页。这在 AI 编辑完某一页后“跳到该页做视觉验证”时非常实用。编辑类工具写回 Markdown 后开发服务器会像收到外部编辑一样即时推送 HMR浏览器无需刷新即可看到更新。接入方式二无开发服务器的 Stdio 模式不需要跑开发服务器时可直接以 stdio 传输方式启动一个独立 MCP 服务器它直接读写磁盘上的 Markdown 文件slidev mcp [entry]其中[entry]是入口 Markdown 文件路径缺省时解析工作目录下的默认入口。该子命令注册于 cli.ts内部调用 stdio.ts 的startMcpStdioServer()它通过getRoots()解析项目根然后用StdioServerTransport连接服务器。值得注意的实现细节见 stdio.ts 的注释每次工具调用都会从磁盘重新加载数据getData: () parser.load(...)因为两次调用之间文件可能被外部编辑器改动stdio 模式下stdout 被 MCP 协议独占任何其他进程都不得向其打印日志否则会污染协议流。对于npx启动型的 MCP 客户端典型配置是{ mcpServers: { slidev: { command: npx, args: [slidev, mcp, slides.md] } } }该模式下没有开发服务器因此工具列表中不会出现slidev-goto-slide——这一点由源码直接印证createSlidevMcpServer()只有在ctx.nav存在时才注册该工具见 server.ts。测试 mcp.test.ts 也验证了这一点。内置工具全景两种接入方式暴露的是同一套工具集唯一差异是slidev-goto-slide是否出现。工具概览如下描述来自技能文档与 server.ts 各registerTool声明工具说明传输限制slidev-get-info甲板概览入口文件、标题、幻灯片数、Markdown 文件列表、开发服务器 URL 与当前播放位置HTTP / stdioslidev-list-slides列出全部幻灯片编号、标题、布局、来源文件HTTP / stdioslidev-get-slide获取某一页的完整源码frontmatter、正文内容、演讲备注HTTP / stdioslidev-update-slide更新某一页的内容、备注和/或 frontmatterHTTP / stdioslidev-insert-slide在某一页之后插入新幻灯片HTTP / stdioslidev-remove-slide删除某一页HTTP / stdioslidev-move-slide将某一页移动到另一页之前/之后以重排甲板HTTP / stdioslidev-goto-slide将实时演示导航到某一页仅 HTTP开发服务器只读查询类工具都带readOnlyHint标注slidev-remove-slide带destructiveHintslidev-goto-slide带idempotentHint见 server.ts 中各工具声明便于客户端正确呈现安全提示。查询类工具slidev-get-info甲板总览无参数。返回的 JSON 包含slidevVersion、entry入口文件绝对路径、titleheadmatter 标题缺失时回落到第一页标题、theme、totalSlides、markdownFiles数组。若在开发服务器模式下还会附加server.url、server.currentPage、server.currentClicks——其中currentPage为 0 表示尚无任何客户端连接见 server.ts。slidev-list-slides列出全部页无参数。返回数组每个元素形如{ no: 2, title: Slide 2, layout: two-cols, file: /abs/path/slides.md, hasNote: true, importedBySrcDirective: true }其中layout仅在存在时出现通过src:导入的页会有importedBySrcDirective: true由importChain推导见 server.ts 的slideSummary()。slidev-list-slides返回的是“渲染层”的页凡是被hide/disabledfrontmatter 隐藏的页不会被包含——这是实现层面在 vite/mcp.ts 与 data 解析 上游就过滤掉的。slidev-get-slide获取单页源码参数no幻灯片编号1 起始、按演示中实际显示的数字。返回该页frontmatter、content已 trim、note无则null以及继承自列表的no/title/layout/file/hasNote等字段对src:导入的页会额外给出importedBy数组如[/abs/sub.md#1]。编辑类工具slidev-update-slide参数no必填目标页编号content可选该页新的 Markdown 正文不含 frontmatter 与备注传空字符串即清空内容note可选新的演讲备注同样传空串清空frontmatter可选对象。只 patch 传入的键若要删除某个键把该键的值置为null。一次调用可只更新其中任意几个字段至少提供一个否则抛 “Nothing to update” 错误。成功返回类似Updated slide 3 in /abs/slides.md.的文本。从源码看该工具走applySlidePatch()见 operations.ts若提供content/note直接覆盖source.content/source.note若提供frontmatter对象则调用updateFrontmatterPatch()做键级合并null值删除键——测试 mcp.test.ts 验证了“传入{ background: null }后该键被移除”的行为patch 完成后会先parser.prettifySlide(source)再parser.save()写回文件。slidev-insert-slide参数after必填在其后插入新页的页号1 起始。若想插到甲板最末尾把after传为最后一页的编号content必填新页 Markdown 正文frontmatter可选对象作为新页 YAML headmatter例如{ layout: two-cols }note可选新页演讲备注。新页总是插入到锚点页所在的同一 Markdown 文件见 operations.ts。返回提示会提醒“其后的页号已偏移如需请重新 list”。slidev-remove-slide参数no。把该页从其源 Markdown 文件中删除返回Removed slide 3 (Slide 3) from /abs/slides.md.。注意入口文件的第一页不可被删除因为它的 frontmatter 是整个甲板的 headmatter全局配置。slidev-move-slide参数from被移动页的编号before与after必须且只能提供一个指定目标位置移动到某页之前 / 之后两者都缺省或都提供都会报错锚点不能与from相同。移动必须发生在同一 Markdown 文件内。测试 mcp.test.ts 覆盖了“未提供before/after”和“同时提供两者”两种非法调用的报错路径。导航类工具slidev-goto-slide仅开发服务器模式参数no目标页编号clicks可选点击动画步骤v-click等缺省为 0。调用后所有已连接的浏览器都会跳转到目标页返回例如Navigated the presentation to slide 4.。注意clicks计数从 0 开始0 表示停留在尚未触发任何点击动画的状态。编号规则与安全边界必须理解的行为契约技能文档列出四条关键行为这里结合源码逐条展开以“渲染后的 1 起始编号”寻址所有工具的no都与演示时显示在幻灯片上的数字一致而不是文件内的文本位置。解析实现resolveSlide()用data.slides[no - 1]直接索引见 operations.ts越界时抛出带总页数提示的错误Slide N does not exist. The deck has M slides (1-M).。参数在 zod 层也做了int().min(1)约束见 server.ts。该编号在插入/删除/移动后会发生偏移所以工具返回信息都会建议“list the slides again if needed”。编辑写回 Markdown 并即时热更新stdio 模式每次调用重新parser.load()HTTP 模式插件直接持有options.data并监听磁盘变更。applySlidePatch()只改写“源页”的 source 数据结构不触碰渲染层结果因此对正在运行的 dev server 而言这等价于一次外部文件编辑——会触发完整 HMR 流程推送给所有客户端见 operations.ts 的注释。入口文件第一页受保护assertNotEntryHeadmatter()operations.ts会检查待操作页是否为入口文件的第 1 页source.filepath data.entry.filepath data.entry.slides.indexOf(source) 0若是则拒绝 remove / move因为该页 frontmatter 承载全局 headmatter 配置。测试 mcp.test.ts 与 #L203-L211 分别验证了 remove 第一页、move 第一页及 move 到第一页之前都会被拒。注意它允许 update 第一页的正文与备注frontmatter 的 headmatter 键会被保留测试 #L93-L100 证明修改第 1 页 note 后headmatter.title不受影响。src:导入的页在自己的文件中编辑且移动不能跨文件对src:导入的页做 update 时改动只落回被导入的那个子文件测试 mcp.test.ts 验证了sub.md内容变化而slides.md不含该内容。而 move 若跨越文件被移动页与目标锚点在不同文件会抛出明确的错误提示要么在自身文件内移动、要么手动编辑入口文件的src:导入列表见 operations.ts。如何禁用 MCP 端点如果你不希望开发服务器暴露 MCP 能力只需在入口文件的 headmatter 中设置--- mcp: false ---mcp属于 frontmatter/headmatter 的可选布尔字段类型定义见 packages/types/src/frontmatter.ts。在 HTTP 模式下Vite 插件的中间件会在请求到达/__mcp时检查options.data.config.mcp false命中则返回403并带 JSON-RPC 错误消息The Slidev MCP server is disabled (mcp: false in the headmatter)见 vite/mcp.ts。CLI 启动横幅也据此判断是否打印端点地址见 cli.ts。源码级实现剖析一次 MCP 请求发生了什么了解底层能帮你更准确地预期工具行为。整个机制分为三层① 统一的工具注册层mcp/server.tscreateSlidevMcpServer(ctx)基于modelcontextprotocol/server构建名为slidev的 McpServer并通过 zod 声明每个工具的输入 schema。写入类工具在操作前会做兜底校验如 update 至少传一个字段最终统一经result()把返回内容序列化为text类型的 content 文本。② 文件操作实现层mcp/operations.ts所有编辑都在LoadedSlidevData之上进行——定位源页 → 修改SourceSlideInfo→prettifySlide保证注释分隔符与格式统一→ 由parser.save()序列化整份文档落盘。正因为走的是slidev/parser的文档模型而非字符串拼接---分隔符、frontmatter 风格frontmatter或---等细节都能被正确还原。③ 传输接入层HTTPcreateMcpPlugin()packages/slidev/node/vite/mcp.ts在 dev server 的中间件栈上拦截/__mcp路径采用无状态模式——每个请求创建一个全新的 server NodeStreamableHTTPServerTransport对响应关闭即销毁导航能力通过共享的navserver-ref 状态实现navigateClients()既会直接 patch 服务器端 nav 状态并使其模块失效又会分别以presenter与viewer两种角色向客户端广播 HMR 自定义事件从而让两类窗口都响应跳页见 vite/mcp.tsstdiostartMcpStdioServer()mcp/stdio.ts不依赖任何服务器用getRoots(entry)定位项目根后建立纯磁盘会话。④ 测试保障test/mcp.test.ts仓库用 vitest 覆盖了完整行为矩阵——6 页 fixture 甲板含src:导入与演讲备注上执行 load/update保留备注、patch frontmatter、null 删键、越界报错、非法 YAML 报错、insert中间/末尾、remove含拒绝删除第 1 页、movebefore/after、同文件内移动、跨文件拒绝、第一页保护、锚点约束以及服务器层工具暴露清单与goto-slide的条件注册。它们既是回归保护也是理解各工具精确语义的最佳“可执行文档”。相关阅读技能文档 tool-mcp.md官方特性文档含版本号since: v52.17.0与更多配置示例 docs/features/mcp.md与 AI 协作的完整工作流 docs/guide/work-with-ai.mdMCP 核心实现 packages/slidev/node/mcp/server.ts、 packages/slidev/node/mcp/operations.tsHTTP 插件与 stdio 入口 packages/slidev/node/vite/mcp.ts、 packages/slidev/node/mcp/stdio.tsCLI 子命令注册 packages/slidev/node/cli.ts行为测试 test/mcp.test.ts【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考