---
name: yanhuai-mcp
description: >
  Configure and use 言怀网 MCP at https://yanhuai.net/mcp. Bearer Token comes from
  /settings/profile. An agent can read, comment, write, upload, download, and
  administer the site with the token user's permissions.
  Fetch this file: https://yanhuai.net/mcp/SKILL.md
---

# 言怀网 MCP

远程 **streamable HTTP** MCP。端点：`https://yanhuai.net/mcp`。

读心镜词典（`/canon` 或 `/plants`）、典籍导读、观心案例、疗愈资源和树洞茶寮可以不带 Token。评论、收藏、写作、上传、下载和后台操作要 `Authorization: Bearer <token>`。Token 只在登录后的 `/settings/profile` 生成。能做的事等于这个账号在网站上的权限。

现行工具以对本端点 `tools/list` 的返回为准。

## 1. 获取 Bearer Token

打开 https://yanhuai.net/settings/profile（未登录会去 `/login`）。

1. 找到 **API Token 管理**（徽章「MCP 访问密钥」）。
2. 没有 Token：点 **生成 Token**。
3. 已有 Token：页面只显示掩码 `gya_xxxx****yyyy`。没有「显示全文」。要完整 Token 只能 **重新生成**（旧 Token 立刻失效）。
4. 完整 Token **只出现这一次**。立刻复制，存到密码管理器。刷新后只剩掩码。
5. 格式：`gya_` 开头。请求头写成 `Authorization: Bearer gya_...`。

规则：一用户一 Token；重新生成覆盖旧值；停用账号不能生成。权限等于该账号角色（`user` / `author` / `mod` / `admin` / `super_admin`）。

不要把 Token 全文贴进聊天记录或提交进 git。

## 2. 写入客户端

把 `<TOKEN>` 换成上一步复制的值。

### Claude Desktop / Cursor / Claude Code

```json
{
  "mcpServers": {
    "yanhuai": {
      "type": "streamable-http",
      "url": "https://yanhuai.net/mcp",
      "headers": {
        "Authorization": "Bearer <TOKEN>"
      }
    }
  }
}
```

### Grok

```bash
export YANHUAI_MCP_TOKEN='<TOKEN>'
grok mcp add --transport http yanhuainet https://yanhuai.net/mcp \
  --header "Authorization: Bearer ${YANHUAI_MCP_TOKEN}"
```

或 `~/.grok/config.toml`：

```toml
[mcp_servers.yanhuainet]
url = "https://yanhuai.net/mcp"
headers = { Authorization = "Bearer ${YANHUAI_MCP_TOKEN}" }
```

### 其它 HTTP MCP 客户端

URL：`https://yanhuai.net/mcp`  
Header：`Authorization: Bearer <TOKEN>`

也接受 `X-API-Token`。优先用 Bearer 头（为防止日志泄露，不再接受 URL `?token=` 或 JSON `params._meta.token`）。

本服务不维持会话，没有 `Mcp-Session-Id`。POST 返回一条 JSON-RPC；客户端若只接受 `text/event-stream`，同一条结果会包在一次 SSE 里然后关闭。单独的 GET SSE 长连接不提供（405）。浏览器打开 `/mcp` 是说明书。

## 3. 调用约定

身份来自 Token 对应用户。写操作不要传 `userId`。传了别人的 id 会拒绝。不要经 MCP 传密码。

先 `whoami` 看权限，再 `site_vocab` 看枚举。提示词 `operate_site` 是一份操作顺序。只同步工具、不同步 prompts / resources 的连接器，调用 `list_guides`。协议入口仍是 `prompts/list`、`prompts/get`、`resources/list`、`resources/read`、`resources/templates/list`。

没有参数的工具，`inputSchema.properties` 是对象 `{}`，不是数组。

公开读取：`search`、`get_post`、`list_posts`、`get_plant`、`list_plants`、`list_categories`、`list_forum_replies`、`list_comments`、`get_user`、`site_vocab`、`list_guides`、`studio_planting_schedule`、`ask_landscape`。资源 `yanhuai://health`、`yanhuai://stats`、`yanhuai://plants`。模板 `yanhuai://post/{id}`、`yanhuai://plants{?q,life,habit,autumn}`。

登录后的使用：评论、点赞、收藏、树洞茶寮、改资料、下载、`studio_compile_design`（言怀观心台推演）。

作者（`content.publish`）才能 `save_post`、上传图片和资源文件。新建默认草稿，`action=publish` 才公开。`save_post` 的 `required` 按新建列出：`type`、`title`、`content`、`category`。带 `id` 修改时，服务端仍允许只传要改的字段。案例心性词条必须已在心镜词典。心境议题、陪伴深度和对话流派先调用 `site_vocab`，只使用返回的 key。

内容管理才能上下架、设精选、审词条、看后台列表。论坛版主只能把树洞帖改成 `published` 或 `hidden`。用户管理才能列账号和停用账号。邮箱默认脱敏，`include_email=true` 才返回完整邮箱。改角色只有超级管理员。

心性词条与塔罗牌卡的外文/拉丁标识以库里的经典原典 `source` 为准。库里没有的词条不要编造出处。观心台 `/studio` 已开放 `studio_compile_design`（生成立意、意象控制词包、四层观照分析与经心镜词典外键核验的修心处方表）以及 `studio_planting_schedule`、`ask_landscape`。

`url` 里的中文 slug 保持汉字。空格和斜杠仍会编码。`get_post` 等工具的 `slug` 可以是汉字、百分号编码，或整段网址，服务端会还原。标题仍自动生成 slug：纯英文是 ASCII，中文和中英混合保留汉字。

不超过 1MB 的原文件用 `download_file`，结果是 base64。更大的用 `prepare_download`：返回大约 10 分钟、只能用一次的地址，直接 GET，不必再带 Bearer。`/download/{id}` 在未登录且不接受 HTML 时返回 JSON 401，不会 302 到登录页。浏览器接受 `text/html` 时仍会去登录。一次性地址用过或过期是 JSON 410。

带文件时一次传一个。`data` 是 base64，解码后不超过 10MB。整次 JSON 不超过 18MB。

正文插图用 `upload_bed_image`。登录即可，不要求作者。返回 `url` 和 `markdown`，把 markdown 写进树洞正文或 `save_post` 的 `content`。格式是 SVG、JPG、JPEG、PNG、GIF、AVIF、WEBP。带 script 的 SVG 不收。SVG 文本里没转义的 & 会在上传时写成 &amp;，避免浏览器把图显示成空白。已经写好的 &amp; 不会再转一次。图片经 ipfs.infogaps.net 访问，不写进站内 `/uploads/`。封面仍用 `upload_image`，得到站内路径；也可以把图床 `url` 填进 `cover`。已传过的图用 `list_bed_images` 复用。案例里成组的牌阵和心镜图继续用 `attach_case_images`。

```bash
curl -sS -X POST https://yanhuai.net/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer ${YANHUAI_MCP_TOKEN}" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```

## 4. 工具速查

| 名称 | 认证 | 用途 |
|------|------|------|
| `search` | 公开 | `query`。`type`=`all\|tutorial\|resource\|case\|forum_thread\|blog\|plant`。案例可加 `site` |
| `get_post` | 公开已发布；未发布仅作者或内容管理 | `id` 或 `slug`。`full=true` 时作者可读全文。`files[].id` 用于下载 |
| `list_posts` | 公开 | `type` 必填。`site`、`category`、`page` |
| `get_plant` | 公开已审；未审仅内容管理 | `slug` 或 `name`（查询心镜词典词条） |
| `list_plants` | 公开 | `query`、`life`、`habit`、`autumn`、`page`。返回 `pages`，和 `list_posts` 一样 |
| `list_categories` | 公开 | `type`=`forum\|tutorial\|resource\|case\|blog` |
| `list_forum_replies` | 公开 | `id` 或 `slug` |
| `list_comments` | 公开已发布 | 评论，含 `parent_id` |
| `get_user` | 公开 | `username`。无邮箱 |
| `site_vocab` | 公开 | 心境议题、陪伴深度、许可、图片角色、观心台 7 大模式与固定彩平图例色板 |
| `list_guides` | 公开 | prompts、resources、模板。给只同步工具的连接器 |
| `studio_compile_design` | Bearer | 言怀观心台推演：输出立意、生图正负向词包、四层观照与心镜词典核验修心处方表 |
| `studio_planting_schedule` | 公开/Bearer | 读取方案 `job_id` 的核验修心处方表与 CSV 下载地址，或按 `site_type` + `season` 查询适配心性词条 |
| `ask_landscape` | 公开/Bearer | 站内知识强约束的心理哲思与塔罗道佛问答（RRF 混合检索，零命中诚实拒答） |
| `whoami` | Bearer | 用户、角色、权限。无密码和邮箱 |
| `update_profile` | Bearer | `display_name`、`bio`、`avatar_base64`。不改密码 |
| `create_comment` | Bearer | `content` 2–2000 字。可加 `parentId` |
| `toggle_like` | Bearer | `id`，`type`=`post\|comment` |
| `toggle_favorite` | Bearer | `id`。再调一次取消 |
| `list_favorites` | Bearer | 仍发布的收藏 |
| `create_forum_thread` | Bearer | `title`、`content`、`category` |
| `create_forum_reply` | Bearer | `id` 或 `slug`，`content` |
| `list_my_posts` | Bearer | 自己的内容，含草稿 |
| `save_post` | 作者 | 新建必填 `type`、`title`、`content`、`category`。带 `id` 可只改部分字段。`action`=`draft\|publish\|pending` |
| `attach_case_images` | 作者 | 案例图片。`files`：`{name,data}`，`role`，`caption` |
| `attach_resource_files` | 作者 | 资源原文件。`license`=`own\|cc\|study` |
| `upload_image` | 作者 | 站内封面，返回 `/uploads/` 路径，写入 `cover` |
| `upload_bed_image` | Bearer | 图床。`name`、`data`。返回 `url` 和 `markdown` |
| `list_bed_images` | Bearer | 自己最近的图床图片，用来复用 |
| `update_post_files` | 作者 | `delete_media`、`delete_files`、`licenses` |
| `download_file` | Bearer | 资源文件 id。不超过 1MB，直接返回 base64 |
| `prepare_download` | Bearer | 资源文件 id。一次性 URL，GET 时不必再带 Bearer |
| `delete_post` | 作者删草稿；内容管理删任意 | 必须 `confirm=true` |
| `list_manage_posts` | 内容管理 | 全部状态 |
| `set_post_status` | 内容管理；版主仅论坛 | `published` 或 `hidden` |
| `set_featured` | 内容管理 | `featured` true/false |
| `set_plant_reviewed` | 内容管理 | 审核公开/撤回心镜词典词条 |
| `admin_overview` | 管理 | 计数（含 `studio_jobs` 与 `ask_logs`） |
| `list_users` | 用户管理 | 邮箱默认脱敏。`include_email=true` 才给完整邮箱。无密码 |
| `set_user_active` | 用户管理 | 不能改自己 |
| `set_user_role` | 超级管理员 | `user\|author\|mod\|admin` |

体系维度 `life`：`tree` 心理效应与疗法、`shrub` 韦特塔罗牌卡、`herb` 哲学核心命题、`bamboo` 道家老庄思想、`aquatic` 佛学禅宗名相、`vine` 正念与疗愈练习。属性 `habit`：`evergreen` 经典原典、`deciduous` 实修方法、`semi` 象征原型。

## 5. 排障

| 现象 | 处理 |
|------|------|
| 401 / `Authentication required` | Token 没配、写错，或已经重新生成/撤销。回资料页再生成并更新客户端。 |
| 已有 Token 但看不到全文 | **重新生成** 并立刻复制。掩码揭不开。 |
| 打开 `/mcp` 得到 HTML | 那是说明书。JSON-RPC 必须 POST。 |
| GET 返回 405 | 正常。不要挂长连接，消息用 POST。 |
| 写操作落到别人账号 | 用了另一用户的 Token。 |
| 停用账号 | 生成与调用都会失败。 |
| 工具说需要作者或内容管理 | 当前账号是普通用户。超级管理员可把角色改成 `author`。树洞茶寮仍可用。 |
| 413 或请求体过大 | 图片一次一张，解码后不超过 10MB。 |
| 下载 `/download/{id}` 得到 JSON 401 | 未登录，且请求不接受 HTML。去登录，或先 `prepare_download` / `download_file`。浏览器打开仍会跳到登录页。 |
| 一次性地址 401 | 不应出现。`/download/go/{token}` 本身就是凭证，不要再带 Bearer，也不要把它当成要登录的页面。 |
| 下载地址 410 | 用过或超过大约 10 分钟。重新 `prepare_download`。地址无效时是 JSON，不是登录页 HTML。 |
| `download_file` 说超过 1MB | 改用 `prepare_download`，再 GET 返回的地址。 |
| 心镜词典里没有 | 不要编造一个名字。先 `list_plants` 或 `get_plant`。 |