内容创作工具
这是 YouTeacher MCP server 中让 agent（Claude Code、Claude Desktop）直接撰写和管理博客的那一片。这里每个工具都是内容服务 HTTP API 之上的一层薄封装（thin pass-through）——输入相同、返回的 JSON 相同——这样 agent 就不必在自己的 prompt 里重建那套 API。这里没有客户端侧的鉴权：授权由服务端强制，每次调用都携带调用方 auth client 手里持有的凭据（一个由密钥派生出的 admin 会话）。写入类端点在服务端要求 admin 权限，无论调用来自哪个工具都一样。
文章 CRUD
文章工具封装 /api/content/v1/posts/*。
- 读 ——
list_posts（按状态、分类 id 或 slug、作者过滤，外加limit/page）、get_post_by_id（按 cuid）、get_post_by_slug。管理员既能看到已发布文章，也能看到草稿。 - 写 ——
create_post、update_post（部分更新——只有传入的字段会改）、delete_post（幂等；附件由服务清理）。
文章正文按 contentFormat 选定的三种格式之一原样存储：blocknote（默认编辑器格式）、html、markdown。如果想要一个"给我 markdown、剩下你搞定"的入口，应优先用 markdown 导入工具，而不是 create_post。
定时发布与撤回
省略 publishedAt 时，publish_post 立即发布。若传入一个未来的 ISO-8601 publishedAt，文章就被排期：在该日期之前，它对公开站点以及 list_posts(status=published) 都不可见，而作者用不带状态过滤的方式列出仍能看到它。正是这一点让 agent 可以现在写一批、再分散到未来的日期上陆续发布。unpublish_post 把已发布的文章退回草稿，此时它的公开 URL 在重新发布前不再解析。
URL 别名
除了规范 URL /content/{slug}，一篇文章还能带一个便于阅读的别名。set_post_alias 设置或替换它（与已有别名冲突时返回 HTTP 409）；delete_post_alias 移除它，两种情况下规范 URL 都照常可用。
分类
分类封装 /api/content/v1/categories。它们本身不是博客内容，但 create_post / import_markdown_post 接受 categorySlug 或 categoryId，所以 agent 通常会先查一个或建一个。list_categories 返回扁平数组；get_category_tree 返回把子分类内联进父分类的树形，便于按层级挑选。create_category 接受可选的 parentId（省略即顶层）；update_category 改名称和/或描述；delete_category 会把原本属于该分类的文章的 categoryId 清空，而不是删掉那些文章。
Markdown → BlockNote 导入
import_markdown_post 是对 agent 最友好的撰写路径。它把整段 markdown 正文（以 multipart form data 的形式）发给服务端，服务端把 markdown 转成 BlockNote，在未给标题时从第一个 # H1 推断标题，并按 slug 关联分类。有三样东西随 markdown 一起送出：
- 内联图片 —— 在 markdown 里写成
，同时在mediaPaths里传每个文件的绝对路径；文件名（basename）必须与media:引用对应。markdown 中的外部http(s)图片 URL 原样保留。单张主图（hero）走featuredImagePath。只接受图片类型（PNG、JPEG、GIF、WEBP、SVG）。 - 通过 directive 语法写自定义块 —— 叶子块是
::name{key="value"}，容器块是:::name… 正文 …:::。directive 名与 BlockNote 块类型一一对应。容器的正文成为props.content的原始字符串（faq / cta / callout 这类内容型块在这里存 JSON）；叶子的属性成为块的 props。例如::youtube{url="…"}是一个嵌入，而:::faq块携带一个问答对的 JSON 数组。
实时块注册表
get_supported_blocks 返回编辑器实时的 slash 命令注册表（/api/seo/embed-registry）：编辑器能渲染的每一个自定义块——youtube、instagram、tiktok、pdf、faq、cta、callout，以及未来新增的——每个块的 directive 语法，还有一篇用到所有块的范例文章，用作 few-shot 示范。这个注册表是单一真相来源：往 web 应用的 embed 注册表里加一个块，下一次部署它就出现在这里，无需改动 MCP server。这样可导入的自定义块集合与编辑器保持同步，而不必碰这份代码。
单篇导出
两个导出工具把已有文章再渲染出来：export_post_markdown（内联返回 markdown 正文并写到磁盘）和 export_post_pdf（写出 PDF 并返回一份 base64 副本，好让没有文件系统访问权的调用方也能消费这些字节）。两者都写到 YOUTEACHER_MCP_DOWNLOAD_DIR，未设置时写到操作系统临时目录，并且都要求 admin 会话。
本节内容
- youteacher_mcp —— 这套创作面所属的 MCP server
- youteacher_content —— 这些工具所封装的内容服务 HTTP API