diff --git a/.env.example b/.env.example
index 6895090..1aaec0f 100644
--- a/.env.example
+++ b/.env.example
@@ -28,6 +28,13 @@ COMMENTS_GITHUB_PRIVATE_KEY=
 COMMENTS_GITHUB_TOKEN=
 COMMENTS_SESSION_SECRET=
 
+# --- WebMCP (expose site tools to browser AI agents) ---
+# Origin trial token for https://razet.me — register at
+# https://developer.chrome.com/origintrials (Chrome 149+) and, separately,
+# https://developer.microsoft.com/microsoft-edge/origin-trials (Edge 150+).
+# Unset = no meta tag is emitted and the tools stay dormant; the site is unaffected.
+PUBLIC_WEBMCP_ORIGIN_TRIAL_TOKEN=
+
 # --- Keystatic storage mode ---
 # local  = write Markdown on disk (default in `pnpm dev` / local build)
 # github = commit via GitHub App (Netlify sets this in netlify.toml)
diff --git a/.trellis/spec/frontend/index.md b/.trellis/spec/frontend/index.md
index c476e01..2e01796 100644
--- a/.trellis/spec/frontend/index.md
+++ b/.trellis/spec/frontend/index.md
@@ -22,6 +22,7 @@ This directory contains guidelines for frontend development. Fill in each file w
 | [Type Safety](./type-safety.md) | Type patterns, validation | To fill |
 | [Markdown Pipeline](./markdown-pipeline.md) | remark/rehype/Shiki ordering, math & mermaid rendering, Keystatic gotchas | Filled |
 | [Keystatic Admin](./keystatic-admin.md) | Admin customization wiring, toolbar host contract, editor scroll anatomy | Filled |
+| [WebMCP Agent Tools](./webmcp-tools.md) | Agent tool contracts, client/server import boundary, navigation allowlist, search index | Filled |
 
 ---
 
diff --git a/.trellis/spec/frontend/webmcp-tools.md b/.trellis/spec/frontend/webmcp-tools.md
new file mode 100644
index 0000000..79b5b8b
--- /dev/null
+++ b/.trellis/spec/frontend/webmcp-tools.md
@@ -0,0 +1,111 @@
+# WebMCP Agent Tools
+
+> How this site exposes capabilities to browser-integrated AI agents, and the rules
+> that keep it from breaking the site or leaking server code into the browser.
+
+Code lives in `src/lib/webmcp/`, mounted by `src/components/WebMcp.astro` from `BaseLayout.astro`.
+
+Spec: <https://github.com/webmachinelearning/webmcp> — API is
+`document.modelContext.registerTool(tool, { signal })`.
+
+---
+
+## Non-negotiables
+
+### 1. Never import `@/lib/comments` (or `@/lib/github`, `@/lib/comments-token`) from client code
+
+`src/lib/comments.ts` looks like a bag of pure helpers, but it transitively imports
+`@/lib/github` and `@/lib/comments-token`, both of which read server-side env. Importing it
+from a browser module drags secrets-adjacent code into the client bundle.
+
+This is why `src/lib/webmcp/page-context.ts` re-implements `commentKey()` as a one-liner
+instead of importing it. **If you change `commentKey()` in `src/lib/comments.ts`, update
+`toCommentKey()` in `page-context.ts` to match** — the duplication is deliberate, not an oversight.
+
+The same rule is why `Comments.astro` computes the key in its frontmatter and passes it down
+through `data-slug` rather than computing it in the client script.
+
+### 2. Feature-detect, then dynamic-import
+
+`WebMcp.astro` ships **only** a feature check to every visitor (~230 bytes). The ~12KB of tool
+code loads via `import()` and only when `document.modelContext?.registerTool` exists.
+
+Reason: WebMCP is an origin trial (Chrome 149 / Edge 150). Almost no visitor has a host for it,
+so eagerly bundling the tools would be pure waste. Keep this shape when adding tools.
+
+### 3. Navigation is an allowlist, and it must track the routes
+
+`resolveInternalPath()` in `tools/navigation.ts` permits only `/`, `/posts`, `/posts/<slug>`,
+`/leetcode`, `/leetcode/<slug>`. `/keystatic` and `/api/*` are excluded *by construction*,
+not by an explicit ban.
+
+**Adding a public route means adding it to `ALLOWED_PREFIXES`.** Adding a private one means
+doing nothing. Prefix comparison is `=== prefix || startsWith(prefix + '/')` — never a bare
+`startsWith(prefix)`, which would let `/postsevil` through.
+
+### 4. Side-effecting tools stop at the confirmation boundary
+
+`draft-comment` fills the existing textarea and scrolls to it. It **never** calls `submit()`,
+`requestSubmit()`, or clicks the submit button. Publishing a comment writes to a GitHub Issue
+under the visitor's own identity and cannot be undone.
+
+Any future tool that writes, deletes, or spends follows the same shape: prepare the action in
+the existing UI, then return text telling the agent to hand control back to the user.
+
+Guard when reviewing: `grep -rnE 'requestSubmit|\.submit\(' src/lib/webmcp/` must stay empty.
+
+### 5. Tools return error *results*, never throw
+
+Every `execute` returns `err('…')` on failure. A thrown exception reaches the agent as an opaque
+`DOMException`; readable text lets the model fix its arguments and retry. Arguments come from an
+LLM and are untrusted — read them through `src/lib/webmcp/args.ts`, never destructure directly.
+
+---
+
+## Search index
+
+`src/pages/search-index.json.ts` emits `dist/search-index.json` at build time.
+
+It **must** source posts through `getBlogPosts()` / `getLeetcodePosts()` and build paths through
+`postHref()` (both in `src/lib/posts.ts`). That is what makes the index inherit `display: false`
+filtering and stay in sync with real routes for free.
+
+Note the asymmetry: `posts/[...slug].astro` uses an *unfiltered* `getCollection`, so a
+`display: false` post still gets a page — it just never appears in lists or in the index.
+Current counts: 15 indexed of 16 files (`toy-record.md` is hidden).
+
+The index is fetched lazily on first content-tool use, cached in a module-level promise, and
+cleared on failure so a later call can retry. Do not preload it.
+
+Ranking is weighted substring counting (title 8, desc 4, tag 3, body 1 capped at 10 hits),
+not semantic search. Chinese queries work because matching is substring-based, not tokenised.
+
+---
+
+## Adding a tool
+
+1. Put it in the matching `src/lib/webmcp/tools/*.ts`; add a new file if it is a new domain.
+2. Write `description` in **English** (the agent's model reads it); return user-facing text in
+   **Chinese** (the site's language).
+3. Validate every argument via `args.ts`. Return `err()` — never throw.
+4. Export it through the domain array; `register.ts` picks it up automatically.
+5. If it has side effects, apply rule 4 above.
+
+---
+
+## Origin trial
+
+`BaseLayout.astro` emits `<meta http-equiv="origin-trial">` only when
+`PUBLIC_WEBMCP_ORIGIN_TRIAL_TOKEN` is set. Unset → no tag, tools stay dormant, site unaffected.
+Tokens are per-origin and expire; re-register at <https://developer.chrome.com/origintrials>.
+
+## Verifying without a WebMCP browser
+
+Firefox and Safari have no implementation, so most checks are indirect:
+
+- `pnpm build` → `dist/search-index.json` exists with the expected post count
+- Bundle the pure logic with esbuild and exercise it under Node with a mocked `fetch`
+  (`searchPosts`, `findPost`, `resolveInternalPath` are all environment-light by design —
+  keep them that way so they stay testable)
+- Confirm `dist/_astro/WebMcp.*.js` stays tiny and the tool chunk is separate
+- Actual tool invocation needs Chrome 149+ with the trial token/flag, or ChatGPT Desktop
diff --git a/.trellis/tasks/07-24-admin-keystatic-umami/check.jsonl b/.trellis/tasks/08-28-webmcp-tools/check.jsonl
similarity index 100%
rename from .trellis/tasks/07-24-admin-keystatic-umami/check.jsonl
rename to .trellis/tasks/08-28-webmcp-tools/check.jsonl
diff --git a/.trellis/tasks/08-28-webmcp-tools/design.md b/.trellis/tasks/08-28-webmcp-tools/design.md
new file mode 100644
index 0000000..3b5e3a5
--- /dev/null
+++ b/.trellis/tasks/08-28-webmcp-tools/design.md
@@ -0,0 +1,227 @@
+# Design — 基于 WebMCP 暴露站点 agent 工具
+
+## 1. 架构概览
+
+```
+构建期 (Node)                        运行时 (浏览器)
+─────────────────                   ──────────────────────────────────────
+src/pages/search-index.json.ts      BaseLayout.astro
+  ├─ getCollection('blogs')           ├─ <meta http-equiv="origin-trial">  (有 token 时)
+  ├─ getCollection('leetcode')        └─ <WebMcp />
+  ├─ markdownToText(body)                   └─ <script> registerAll()
+  └─ dist/search-index.json                       │
+                                                  ├─ 特性检测 document.modelContext
+        （懒加载，首次工具调用时 fetch）◄──────────┤
+                                                  ├─ tools/content.ts
+                                                  ├─ tools/navigation.ts
+                                                  └─ tools/comments.ts
+                                                         │
+                                       复用现有 API ──────┤
+                                         GET  /api/comments?slug=
+                                         GET  /api/comments/me
+                                       复用现有 DOM ──────┘
+                                         [data-comments][data-slug][data-title]
+                                         [data-comments-input]
+                                         .prose h2/h3/h4[id]
+```
+
+**核心设计原则：不新增任何数据注入点。** 页面上下文（collection / slug / 标题 / 章节）
+全部从现有 DOM 与 `location.pathname` 推断，因此 `<WebMcp />` 无需 props，
+`BaseLayout` 也无需感知文章数据。
+
+## 2. 文件清单
+
+| 文件 | 动作 | 职责 |
+|---|---|---|
+| `src/lib/webmcp/types.ts` | 新增 | `document.modelContext` 全局类型声明（本地自持，避免外部包依赖风险） |
+| `src/lib/webmcp/result.ts` | 新增 | 统一构造 `{ content: [{ type:'text', text }] }` 结果与错误结果 |
+| `src/lib/webmcp/search-index.ts` | 新增 | 索引懒加载（单次 promise 缓存）+ 加权打分检索 |
+| `src/lib/webmcp/page-context.ts` | 新增 | 从 DOM/URL 推断当前页 collection / slug / title / sections |
+| `src/lib/webmcp/tools/content.ts` | 新增 | `search-posts`、`get-post` |
+| `src/lib/webmcp/tools/navigation.ts` | 新增 | `navigate-to-post`、`goto-section`、`get-page-context` |
+| `src/lib/webmcp/tools/comments.ts` | 新增 | `list-comments`、`check-comment-auth`、`draft-comment` |
+| `src/lib/webmcp/register.ts` | 新增 | 特性检测、汇总注册、`AbortController` 生命周期 |
+| `src/lib/markdown-text.ts` | 新增 | markdown 源码 → 纯文本（索引与摘要共用） |
+| `src/pages/search-index.json.ts` | 新增 | 构建期静态 endpoint，产出 `/search-index.json` |
+| `src/components/WebMcp.astro` | 新增 | 客户端脚本挂载点 |
+| `src/layouts/BaseLayout.astro` | 修改 | 注入 origin-trial meta + `<WebMcp />` |
+| `.env.example` | 修改 | 记录 `PUBLIC_WEBMCP_ORIGIN_TRIAL_TOKEN` |
+
+每个文件均远低于 500 行上限；工具按域切分而非堆在单文件。
+
+## 3. 工具契约
+
+| # | name | inputSchema | 复用 | 副作用 |
+|---|---|---|---|---|
+| 1 | `search-posts` | `{ query: string, collection?: 'blogs'\|'leetcode'\|'all', limit?: number(1-20, default 5) }` | 静态索引 | 无 |
+| 2 | `get-post` | `{ path: string }`（站内路径或 slug） | 静态索引 | 无 |
+| 3 | `get-page-context` | `{}` | DOM + URL | 无 |
+| 4 | `navigate-to-post` | `{ path: string }` | `location.assign` | 页面跳转 |
+| 5 | `goto-section` | `{ heading: string }` | `.prose h2-h4[id]` | 滚动 |
+| 6 | `list-comments` | `{ path?: string }`（缺省=当前页） | `GET /api/comments` | 无 |
+| 7 | `check-comment-auth` | `{}` | `GET /api/comments/me` | 无 |
+| 8 | `draft-comment` | `{ text: string }` | `[data-comments-input]` | **仅填入草稿，不提交** |
+
+所有 `execute` 返回 MCP 风格结果；失败路径返回 `isError: true` 的可读文本，**不抛异常**
+（Reason: 抛异常会让 agent 拿到不可读的 DOMException，返回文本能让它自行纠正参数重试）。
+
+### 3.1 `search-posts` 打分
+
+无外部依赖的加权子串计数（兼顾中英文，避免中文分词问题）：
+
+```
+query → terms = query.toLowerCase().split(/\s+/).filter(Boolean)
+score(post) = Σ_terms (
+    8 × count(title, term)
+  + 4 × count(desc,  term)
+  + 3 × count(tag,   term)
+  + 1 × min(count(text, term), 10)   // 正文命中封顶，防长文霸榜
+)
+```
+
+`score > 0` 的结果按分数降序、同分按日期降序，取 `limit` 条。
+每条附 `snippet`：首个命中位置前后各 60 字符。
+
+### 3.2 `navigate-to-post` 安全校验
+
+```
+1. 拒绝含 '//'、':' 的输入（阻断 protocol-relative 与绝对 URL）
+2. new URL(path, location.origin) 后校验 origin === location.origin
+3. pathname 必须匹配白名单：
+     /  |  /posts  |  /posts/<slug>  |  /leetcode  |  /leetcode/<slug>
+4. 显式拒绝 /keystatic 与 /api 前缀
+5. 通过后 location.assign(url.pathname + url.hash)
+```
+
+Reason: 导航是 agent 可直接触发的副作用，必须防止被用作开放重定向或诱导用户离站。
+Keystatic 后台是作者私有区域，不通过 agent 暴露。
+
+### 3.3 `draft-comment` 流程
+
+```
+1. 定位 [data-comments] 根；不存在 → 返回「当前页面没有评论区」
+2. GET /api/comments/me（credentials: 'same-origin'）
+   ├─ 未登录 → 返回「请先用 GitHub 登录，登录入口在评论区」
+   └─ 已登录 → 继续
+3. 校验 text 非空且 ≤ 4000 字（与 sanitizeCommentText 上限对齐）
+4. textarea.value = text
+   textarea.dispatchEvent(new Event('input', { bubbles: true }))   ← 让现有校验/计数生效
+5. root.scrollIntoView({ behavior:'smooth', block:'center' }) + textarea.focus()
+6. 返回「草稿已填入评论框，请确认内容后点击『发表评论』提交」
+```
+
+**永不调用 `form.submit()` 或 `submitButton.click()`。**
+Reason: PRD R4 —— 以用户 GitHub 身份写 Issue 是不可逆的对外发布行为。
+
+## 4. 搜索索引
+
+`src/pages/search-index.json.ts`（`prerender` 默认为 true，`output:'static'` 下产出静态文件）：
+
+```ts
+type IndexedPost = {
+  collection: 'blogs' | 'leetcode'
+  slug: string      // 'vue3-contribution'
+  href: string      // '/posts/vue3-contribution'  ← 复用 postHref()
+  title: string
+  desc?: string
+  tag?: string
+  date: string      // ISO
+  text: string      // markdownToText(entry.body)
+}
+type SearchIndex = { version: 1, posts: IndexedPost[] }
+```
+
+- 数据源复用 `getBlogPosts()` / `getLeetcodePosts()`，因此自动继承 `display !== false` 过滤与日期排序
+- 路径复用 `postHref()`，避免与页面路由脱节
+- 体积预估：约 16 篇 × ~3KB 纯文本 ≈ 50KB（gzip ≈ 15KB）
+
+`markdownToText()` 剥离顺序（顺序有意义，先剥围栏再剥行内）：
+围栏代码块 → 行内代码 → 图片 → 链接（保留文本）→ HTML 标签 → 标题/引用/列表标记 → 强调符号 → 折叠空白。
+
+**懒加载**：`search-index.ts` 用模块级 `let cache: Promise<SearchIndex> | null`，
+仅在 `search-posts` / `get-post` 首次执行时 `fetch('/search-index.json')`。
+索引不进入初始 bundle，满足 PRD R1。
+
+## 5. 生命周期与注册
+
+Astro 是 MPA——每次导航整页刷新，因此每个页面加载都重新注册一次。
+
+```ts
+export async function registerAll() {
+  const mc = (document as any).modelContext
+  if (!mc?.registerTool) return          // 特性检测：不支持则静默退出
+
+  const controller = new AbortController()
+  addEventListener('pagehide', () => controller.abort(), { once: true })
+
+  try {
+    await Promise.all(
+      allTools.map(tool => mc.registerTool(tool, { signal: controller.signal })),
+    )
+  } catch {
+    // Permissions-Policy: tools=() 会 reject NotAllowedError；静默降级
+  }
+}
+```
+
+`<WebMcp />` 只把**特性检测**放进首屏，工具代码走动态 `import()`：
+
+```astro
+<script>
+  // Reason: WebMCP is an origin trial — today almost no visitor has a host for it.
+  // Shipping ~5KB gzip of tool code to everyone would be pure waste.
+  if (document.modelContext?.registerTool) {
+    import('@/lib/webmcp/register').then(({ registerAll }) => registerAll())
+  }
+</script>
+```
+
+实测：首屏 chunk **229 bytes**，工具代码 12KB(gzip 5.1KB) 落在独立的 `register.*.js`，
+仅在检测通过时才请求。
+
+不使用 `exposedTo`——工具只对同源文档与内置 agent 可见（WebMCP 默认行为）。
+
+## 6. 类型策略
+
+npm 上有官方 `webmcp-types` 包，但它随 Origin Trial 演进、版本可能不稳。
+本期在 `src/lib/webmcp/types.ts` **自持最小类型声明**（只声明用到的 `registerTool` 与结果类型）：
+
+```ts
+declare global {
+  interface Document { modelContext?: ModelContext }
+}
+```
+
+Reason: 只需要 API 的一个小切面；自持声明消除外部依赖的版本漂移风险，
+且 `pnpm check` 立即可用。若后续 API 稳定，可一行切换到 `webmcp-types`。
+
+## 7. Origin Trial 注入
+
+`BaseLayout.astro` head 内：
+
+```astro
+{originTrialToken && <meta http-equiv="origin-trial" content={originTrialToken} />}
+```
+
+token 取自 `import.meta.env.PUBLIC_WEBMCP_ORIGIN_TRIAL_TOKEN`（`PUBLIC_` 前缀使其可在静态构建中内联）。
+未配置 → 不输出标签（PRD 验收项）。
+
+## 8. 兼容性与回滚
+
+| 维度 | 结论 |
+|---|---|
+| 不支持 WebMCP 的浏览器 | `registerAll()` 首行返回，零影响 |
+| 新增网络请求 | 仅工具被调用时才 fetch 索引；普通访问者无额外请求 |
+| 新增初始 JS | **229 bytes**（仅特性检测）。12KB 的工具代码走动态 import，只有 WebMCP 宿主才下载 |
+| 现有功能 | 无破坏性修改；`BaseLayout` 只做加法 |
+| 回滚 | 从 `BaseLayout.astro` 移除 `<WebMcp />` 与 meta 两行即完全禁用；新增文件可独立保留 |
+
+## 9. 已知取舍
+
+- **验证受限**：Firefox / Safari 无实现，Chrome 需 Origin Trial token 或本地 flag。
+  自动化验收只能覆盖「构建通过 + 索引正确 + 不支持时零回归」；工具实际调用需在
+  Chrome（带 flag）或 ChatGPT Desktop 中人工验证。
+- **检索是子串计数而非语义检索**：中文场景下「贡献」能命中，「怎么给开源提 PR」可能不命中。
+  接受此取舍——agent 侧的 LLM 通常会自行改写查询词重试，且内容量小时召回压力低。
+- **`get-post` 返回全文**：长文可能超出 agent 上下文预算。本期不做分段，
+  由 agent 侧自行截断；如成为问题再加 `maxChars` 参数。
diff --git a/.trellis/tasks/07-24-admin-keystatic-umami/implement.jsonl b/.trellis/tasks/08-28-webmcp-tools/implement.jsonl
similarity index 100%
rename from .trellis/tasks/07-24-admin-keystatic-umami/implement.jsonl
rename to .trellis/tasks/08-28-webmcp-tools/implement.jsonl
diff --git a/.trellis/tasks/08-28-webmcp-tools/implement.md b/.trellis/tasks/08-28-webmcp-tools/implement.md
new file mode 100644
index 0000000..60a5cc9
--- /dev/null
+++ b/.trellis/tasks/08-28-webmcp-tools/implement.md
@@ -0,0 +1,173 @@
+# Implement — 基于 WebMCP 暴露站点 agent 工具
+
+执行顺序按依赖排列：**基础设施 → 索引 → 工具 → 挂载 → 验证**。
+每个 Step 结束时代码应处于可构建状态。
+
+---
+
+## Step 1 · 类型与结果工具（无依赖）
+
+- [ ] `src/lib/webmcp/types.ts` — `declare global { interface Document { modelContext?: ModelContext } }`，
+      含 `ToolDefinition`、`ToolResult`、`RegisterToolOptions` 最小声明
+- [ ] `src/lib/webmcp/result.ts` — `ok(text)` / `okJson(data)` / `err(text)` 三个构造器，
+      统一产出 `{ content: [{ type: 'text', text }], isError? }`
+
+**验证**：`pnpm check`
+
+---
+
+## Step 2 · Markdown 纯文本化
+
+- [ ] `src/lib/markdown-text.ts` — `markdownToText(md: string): string`
+- [ ] 剥离顺序须为：围栏代码块 → 行内代码 → 图片 → 链接（保留文本）→ HTML 标签 →
+      标题/引用/列表标记 → 强调符号 → 折叠空白
+- [ ] 加 `// Reason:` 注释说明顺序为何重要（先围栏后行内，否则代码块内的反引号会错配）
+
+**验证**：`pnpm check`
+
+---
+
+## Step 3 · 构建期搜索索引
+
+- [ ] `src/pages/search-index.json.ts` — `GET` 返回 `SearchIndex` JSON
+- [ ] 数据源必须走 `getBlogPosts()` / `getLeetcodePosts()`（继承 `display` 过滤与排序）
+- [ ] 路径必须走 `postHref()`（避免与路由脱节）
+- [ ] `Content-Type: application/json; charset=utf-8`
+
+**验证**：
+```bash
+pnpm build && ls -la dist/search-index.json
+node -e "const d=require('./dist/search-index.json');console.log(d.posts.length, d.posts.map(p=>p.href).slice(0,5))"
+```
+预期：`posts.length` 等于 blogs + leetcode 中 `display !== false` 的总数，`href` 形如 `/posts/xxx`、`/leetcode/xxx`。
+
+> **Review gate 1**：确认索引条目数正确，且 `text` 字段非空、不含残留 markdown 语法。
+>
+> 实测基线：**15 条**（6 blogs + 9 leetcode）。`src/content/` 下共 16 个文件，
+> `toy-record.md` 带 `display: false` 被正确排除——这正是 PRD R2 要求的隐藏语义。
+> 注意 `posts/[...slug].astro` 的 `getStaticPaths` 用的是未过滤的 `getCollection`，
+> 所以隐藏文章**仍会生成页面**，只是不进索引、不出现在列表页。
+
+---
+
+## Step 4 · 索引懒加载与检索
+
+- [ ] `src/lib/webmcp/search-index.ts`
+  - 模块级 `let cache: Promise<SearchIndex> | null = null`，`loadIndex()` 单次 fetch
+  - `searchPosts(query, { collection, limit })` — 按 design §3.1 加权打分
+  - `findPost(pathOrSlug)` — 同时接受 `/posts/x`、`posts/x`、`x`
+  - `buildSnippet(text, term)` — 首个命中前后各 60 字符
+
+**验证**：`pnpm check`
+
+---
+
+## Step 5 · 页面上下文推断
+
+- [ ] `src/lib/webmcp/page-context.ts` — `getPageContext()` 返回
+      `{ path, collection, slug, title, hasComments, sections }`
+  - `collection`：`/posts/*` → `blogs`，`/leetcode/*` → `leetcode`，否则 `null`
+  - `slug` / `title`：优先读 `[data-comments]` 的 `data-slug` / `data-title`，回退到 pathname 末段与 `document.title`
+  - `sections`：`document.querySelectorAll('.prose h2[id], .prose h3[id], .prose h4[id]')` → `{ id, text, depth }[]`
+
+**验证**：`pnpm check`
+
+---
+
+## Step 6 · 内容工具
+
+- [ ] `src/lib/webmcp/tools/content.ts`
+  - `search-posts` — schema 含 `query`(required) / `collection` enum / `limit` 1-20 default 5
+  - `get-post` — `path`(required)；未命中返回 `err('未找到文章：…')`，**不抛异常**
+
+**验证**：`pnpm check`
+
+---
+
+## Step 7 · 导航工具
+
+- [ ] `src/lib/webmcp/tools/navigation.ts`
+  - `get-page-context` — 空 schema，返回 `okJson(getPageContext())`
+  - `navigate-to-post` — 按 design §3.2 五步校验；拒绝时返回 `err(...)`
+  - `goto-section` — 对 `sections` 做大小写不敏感的包含匹配；命中则 `scrollIntoView({behavior:'smooth'})` 并更新 `location.hash`
+- [ ] 白名单校验单独抽成 `isAllowedInternalPath(path)` 函数，便于后续复核
+
+**验证**：`pnpm check`
+
+> **Review gate 2**：人工复核 `isAllowedInternalPath` —— 逐条确认
+> `https://evil.example`、`//evil.example`、`/keystatic`、`/api/comments`、`javascript:alert(1)`
+> 全部被拒绝。
+
+---
+
+## Step 8 · 评论工具
+
+- [ ] `src/lib/webmcp/tools/comments.ts`
+  - `list-comments` — `GET /api/comments?slug=`，`credentials:'same-origin'`；
+        `configured === false` 时返回「评论功能未配置」
+  - `check-comment-auth` — `GET /api/comments/me`
+  - `draft-comment` — 严格按 design §3.3 六步执行
+- [ ] **禁止**出现 `form.submit()`、`submitButton.click()`、`requestSubmit()`
+- [ ] 加 `// Reason:` 注释说明为何只填草稿不提交
+
+**验证**：`pnpm check` + `grep -nE 'requestSubmit|\.submit\(|submit.*\.click\(' src/lib/webmcp/` 应无输出
+
+---
+
+## Step 9 · 注册入口与挂载
+
+- [ ] `src/lib/webmcp/register.ts` — 特性检测 + `AbortController` + `pagehide` 清理 + `try/catch` 静默
+- [ ] `src/components/WebMcp.astro` — 首屏只做特性检测；命中后 `import('@/lib/webmcp/register')` 动态加载
+      （Reason: WebMCP 尚在 Origin Trial，绝大多数访客没有宿主，不应为他们下载工具代码）
+- [ ] `src/layouts/BaseLayout.astro` —
+      head 内条件渲染 origin-trial meta；body 末尾（`</body>` 前）放 `<WebMcp />`
+- [ ] `.env.example` — 追加 `PUBLIC_WEBMCP_ORIGIN_TRIAL_TOKEN=` 及注释说明去哪注册
+
+**验证**：
+```bash
+pnpm check && pnpm build
+grep -c 'origin-trial' dist/index.html   # 未配置 token 时应为 0
+```
+
+---
+
+## Step 10 · 全量验收
+
+```bash
+pnpm check                    # 无新增 TS / astro 错误
+pnpm build                    # 构建通过
+ls dist/search-index.json     # 索引存在
+grep -rn 'origin-trial' dist/*.html | head   # 未配置 token 时无输出
+```
+
+浏览器人工验证（`pnpm dev`）：
+
+- [ ] 首页 / 文章页 / leetcode 页正常渲染，控制台无新增报错
+- [ ] 评论区、主题切换、TOC、Mermaid、Presence 行为与改造前一致
+- [ ] DevTools Network：普通浏览时**不应**出现 `search-index.json` 请求
+
+WebMCP 功能验证（需 Chrome 149+ 带 flag，或 ChatGPT Desktop）：
+
+- [ ] `(await document.modelContext.getTools()).map(t => t.name)` 列出 8 个工具
+- [ ] `search-posts({ query: 'vue' })` 命中 `vue3-contribution`
+- [ ] `navigate-to-post({ path: 'https://evil.example' })` 被拒
+- [ ] `draft-comment({ text: '测试' })` 后文本入框、页面滚动到评论区、**GitHub 无新增评论**
+
+> **Review gate 3**：`draft-comment` 未提交表单这一条必须实测确认，
+> 而不是仅凭代码阅读判断。
+
+---
+
+## 回滚点
+
+| 触发 | 操作 |
+|---|---|
+| 任一 Step 构建失败 | 该 Step 为独立新文件，`git checkout -- <file>` 即可 |
+| 上线后发现回归 | 从 `BaseLayout.astro` 删除 `<WebMcp />` 与 origin-trial meta 两行 → 功能完全禁用，其余文件成为死代码不影响运行 |
+| 索引体积过大 | 在 `search-index.json.ts` 中对 `text` 截断（如每篇上限 8000 字符） |
+
+## 完成后
+
+- [ ] 按 Trellis 3.3 更新 spec（WebMCP 工具契约与安全边界值得沉淀到 `.trellis/spec/frontend/`）
+- [ ] 按 Trellis 3.4 提交
+- [ ] 提醒 moka 完成 PRD 中的 Origin Trial 注册前置项
diff --git a/.trellis/tasks/08-28-webmcp-tools/prd.md b/.trellis/tasks/08-28-webmcp-tools/prd.md
new file mode 100644
index 0000000..d2027f3
--- /dev/null
+++ b/.trellis/tasks/08-28-webmcp-tools/prd.md
@@ -0,0 +1,105 @@
+# 基于 WebMCP 暴露站点 agent 工具
+
+## Goal
+
+让 razet.me 在支持 WebMCP 的宿主（Chrome 149+ / Edge 150+ Origin Trial、ChatGPT Desktop、Brave Leo）中，
+把**内容检索**、**站点导航**、**评论读写**以标准 tool 形式注册到 `document.modelContext`，
+使 agent 能直接调用而不再依赖 DOM 抓取与模拟点击。
+
+目标场景（用户对浏览器 agent 说的话）：
+
+- 「这个站里有讲 Vue3 贡献的文章吗？打开它。」→ `search-posts` → `navigate-to-post`
+- 「总结一下当前这篇文章。」→ `get-page-context` → `get-post`
+- 「这篇的评论都在说什么？」→ `list-comments`
+- 「帮我写一条评论说……」→ `check-comment-auth` → `draft-comment`（填入输入框，**由用户点提交**）
+
+## Scope
+
+### In scope
+
+- 内容检索与摘要（跨 blogs / leetcode 两个 collection）
+- 站点导航（跳转文章、跳转当前页标题锚点）
+- 评论读取 + 评论草稿写入（人工确认后提交）
+- 特性检测与渐进增强、Origin Trial token 接入
+
+### Out of scope
+
+- 站内自建 AI 助手 UI（不做 `getTools()` / `executeTool()` 消费侧）
+- 阅读体验控制类工具（主题切换、代码块/Mermaid 控制）
+- Keystatic 后台（`/keystatic/*`、`/api/keystatic/*`）相关工具——后台是作者私有区域，不对 agent 暴露
+- 声明式 `<form>` 工具合成（本期只用命令式 API）
+
+## Requirements
+
+### R1 渐进增强与零回归
+
+- `document.modelContext` 不存在时**完全静默 no-op**，不报错、不影响任何现有功能
+- WebMCP 脚本不得阻塞首屏；搜索索引**按需懒加载**，不进入初始 bundle
+- 现有页面、评论、Presence、Keystatic、主题切换行为完全不变
+
+### R2 内容检索工具
+
+- `search-posts`：按关键词检索，支持 `collection` 与 `limit` 过滤，返回结构化命中列表（标题 / 路径 / 日期 / tag / 摘要 / 匹配片段）
+- `get-post`：按站内路径或 slug 取单篇文章的**纯文本正文** + frontmatter，供 agent 摘要
+- 检索数据来源为构建期预生成的静态索引，**不新增运行时搜索依赖**
+- 索引须遵守 `display: false` 的隐藏语义（与 `src/lib/posts.ts` 的 `isVisible` 一致）
+
+### R3 站点导航工具
+
+- `navigate-to-post`：跳转站内路径。**只接受同源站内路径**，白名单前缀 `/`、`/posts`、`/posts/*`、`/leetcode`、`/leetcode/*`
+- `goto-section`：按标题文本跳转当前页锚点，复用现有 `TableOfContents` 生成的 heading id
+- `get-page-context`：返回当前页 collection / slug / 标题 / 是否有评论区，让 agent 知道自己在哪
+
+### R4 评论工具（读自由、写需人工确认）
+
+- `list-comments`：读取指定（默认当前页）文章评论，走现有 `GET /api/comments?slug=`
+- `check-comment-auth`：走现有 `GET /api/comments/me` 返回登录态，未登录时返回登录引导
+- `draft-comment`：**只把文本填入现有评论输入框**（`[data-comments-input]`）、派发 input 事件、滚动并聚焦，
+  返回「已填入草稿，请用户确认后点击提交」。**绝不自动提交表单。**
+  - Reason: 发评论是不可逆的对外发布行为，且会以用户 GitHub 身份写入 Issue。
+    WebMCP explainer 明确的 human-in-the-loop 原则要求这类副作用保留用户最终确认权。
+- 不注册任何会泄露 session cookie、GitHub token 或 Keystatic 凭据的工具
+
+### R5 Origin Trial 接入
+
+- 支持通过环境变量 `PUBLIC_WEBMCP_ORIGIN_TRIAL_TOKEN` 注入 `<meta http-equiv="origin-trial">`
+- 未配置该变量时**不输出 meta 标签**，站点照常工作
+
+## Constraints
+
+| 约束 | 影响 |
+|---|---|
+| `output: 'static'` + Netlify adapter | 工具注册只能在客户端脚本；索引须构建期生成 |
+| WebMCP 处于 Origin Trial（Chrome 149 / Edge 150），Firefox / Safari 无实现 | 必须特性检测；无法在多数浏览器验证，需接受可观测性有限 |
+| Astro 是 MPA，每次导航整页刷新 | 每页加载重新注册工具；用 `AbortController` + `pagehide` 清理 |
+| 不引入运行时搜索库（Fuse/Pagefind 等） | 自写加权词频打分；内容量（约 16 篇）足以支撑 |
+
+## Prerequisites（外部依赖，需 moka 本人操作）
+
+- [ ] 到 [Chrome Origin Trials](https://developer.chrome.com/origintrials) 为 `https://razet.me` 注册 WebMCP trial，取得 token
+- [ ] 将 token 配置为 Netlify 环境变量 `PUBLIC_WEBMCP_ORIGIN_TRIAL_TOKEN`
+- [ ] （可选）Edge 同名 trial 单独注册
+
+> 未完成上述步骤时，代码仍可合并且不影响站点；WebMCP 只在带 `--enable-features` 标志的本地 Chrome 或 ChatGPT Desktop 中生效。
+
+## Acceptance Criteria
+
+- [ ] `pnpm build` 与 `pnpm check` 通过，无新增 TS / astro check 错误
+- [ ] 构建产物包含 `dist/search-index.json`，内容覆盖全部 `display !== false` 的 blogs + leetcode 文章
+- [ ] 在**不支持** WebMCP 的浏览器（如当前 Safari）中打开首页 / 文章页 / 评论区，功能与改造前一致，控制台无新增报错
+- [ ] 在支持 WebMCP 的宿主中 `await document.modelContext.getTools()` 能列出全部 8 个工具，且每个都有 `description` 与合法 `inputSchema`
+- [ ] `search-posts({ query: 'vue' })` 返回含 `vue3-contribution` 的命中项
+- [ ] `get-post` 对已存在文章返回非空纯文本正文；对不存在的 slug 返回明确的错误文本而非抛异常
+- [ ] `navigate-to-post` 对 `https://evil.example` 与 `/keystatic` 等非白名单输入**拒绝跳转**并返回错误文本
+- [ ] `list-comments` 在评论未配置的环境下返回「未配置」而非报错
+- [ ] `draft-comment` 调用后：文本出现在评论框中、页面滚动到评论区、**表单未被提交**（GitHub 无新增评论）
+- [ ] 未登录时 `draft-comment` 或 `check-comment-auth` 返回可读的登录引导文本
+- [ ] 未配置 `PUBLIC_WEBMCP_ORIGIN_TRIAL_TOKEN` 时，HTML 中不含 `origin-trial` meta
+
+## Notes
+
+- WebMCP 一手资料：<https://github.com/webmachinelearning/webmcp>（explainer）、
+  <https://github.com/webmachinelearning/webmcp/blob/main/implementation-status.md>（浏览器支持）
+- API 形态已核实为 `document.modelContext.registerTool(tool, { signal, exposedTo })`，
+  配套 `getTools()` / `executeTool()` / `toolchange` 事件
+- 本期不使用 `exposedTo`——不向任何跨源 iframe 暴露工具
diff --git a/.trellis/tasks/08-28-webmcp-tools/task.json b/.trellis/tasks/08-28-webmcp-tools/task.json
new file mode 100644
index 0000000..5303a25
--- /dev/null
+++ b/.trellis/tasks/08-28-webmcp-tools/task.json
@@ -0,0 +1,26 @@
+{
+  "id": "webmcp-tools",
+  "name": "webmcp-tools",
+  "title": "基于 WebMCP 暴露站点 agent 工具",
+  "description": "",
+  "status": "in_progress",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "moka",
+  "assignee": "moka",
+  "createdAt": "2026-08-28",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/00-bootstrap-guidelines/prd.md b/.trellis/tasks/archive/2026-08/00-bootstrap-guidelines/prd.md
similarity index 100%
rename from .trellis/tasks/00-bootstrap-guidelines/prd.md
rename to .trellis/tasks/archive/2026-08/00-bootstrap-guidelines/prd.md
diff --git a/.trellis/tasks/00-bootstrap-guidelines/task.json b/.trellis/tasks/archive/2026-08/00-bootstrap-guidelines/task.json
similarity index 92%
rename from .trellis/tasks/00-bootstrap-guidelines/task.json
rename to .trellis/tasks/archive/2026-08/00-bootstrap-guidelines/task.json
index 6fe58c0..4aa83eb 100644
--- a/.trellis/tasks/00-bootstrap-guidelines/task.json
+++ b/.trellis/tasks/archive/2026-08/00-bootstrap-guidelines/task.json
@@ -3,7 +3,7 @@
   "name": "00-bootstrap-guidelines",
   "title": "Bootstrap Guidelines",
   "description": "Fill in project development guidelines for AI agents",
-  "status": "in_progress",
+  "status": "completed",
   "dev_type": "docs",
   "scope": null,
   "package": null,
@@ -11,7 +11,7 @@
   "creator": "priority",
   "assignee": "priority",
   "createdAt": "2026-07-23",
-  "completedAt": null,
+  "completedAt": "2026-08-27",
   "branch": null,
   "base_branch": null,
   "worktree_path": null,
diff --git a/.trellis/tasks/07-24-migrate-astro-yohaku/check.jsonl b/.trellis/tasks/archive/2026-08/07-24-admin-keystatic-umami/check.jsonl
similarity index 100%
rename from .trellis/tasks/07-24-migrate-astro-yohaku/check.jsonl
rename to .trellis/tasks/archive/2026-08/07-24-admin-keystatic-umami/check.jsonl
diff --git a/.trellis/tasks/07-24-admin-keystatic-umami/design.md b/.trellis/tasks/archive/2026-08/07-24-admin-keystatic-umami/design.md
similarity index 100%
rename from .trellis/tasks/07-24-admin-keystatic-umami/design.md
rename to .trellis/tasks/archive/2026-08/07-24-admin-keystatic-umami/design.md
diff --git a/.trellis/tasks/07-24-migrate-astro-yohaku/implement.jsonl b/.trellis/tasks/archive/2026-08/07-24-admin-keystatic-umami/implement.jsonl
similarity index 100%
rename from .trellis/tasks/07-24-migrate-astro-yohaku/implement.jsonl
rename to .trellis/tasks/archive/2026-08/07-24-admin-keystatic-umami/implement.jsonl
diff --git a/.trellis/tasks/07-24-admin-keystatic-umami/prd.md b/.trellis/tasks/archive/2026-08/07-24-admin-keystatic-umami/prd.md
similarity index 100%
rename from .trellis/tasks/07-24-admin-keystatic-umami/prd.md
rename to .trellis/tasks/archive/2026-08/07-24-admin-keystatic-umami/prd.md
diff --git a/.trellis/tasks/07-24-admin-keystatic-umami/task.json b/.trellis/tasks/archive/2026-08/07-24-admin-keystatic-umami/task.json
similarity index 90%
rename from .trellis/tasks/07-24-admin-keystatic-umami/task.json
rename to .trellis/tasks/archive/2026-08/07-24-admin-keystatic-umami/task.json
index 37a6587..60454bb 100644
--- a/.trellis/tasks/07-24-admin-keystatic-umami/task.json
+++ b/.trellis/tasks/archive/2026-08/07-24-admin-keystatic-umami/task.json
@@ -3,7 +3,7 @@
   "name": "admin-keystatic-umami",
   "title": "Admin: Keystatic CMS + Umami analytics",
   "description": "",
-  "status": "planning",
+  "status": "completed",
   "dev_type": null,
   "scope": null,
   "package": null,
@@ -11,7 +11,7 @@
   "creator": "priority",
   "assignee": "priority",
   "createdAt": "2026-07-24",
-  "completedAt": null,
+  "completedAt": "2026-08-27",
   "branch": null,
   "base_branch": "main",
   "worktree_path": null,
diff --git a/.trellis/tasks/archive/2026-08/07-24-migrate-astro-yohaku/check.jsonl b/.trellis/tasks/archive/2026-08/07-24-migrate-astro-yohaku/check.jsonl
new file mode 100644
index 0000000..9dd3234
--- /dev/null
+++ b/.trellis/tasks/archive/2026-08/07-24-migrate-astro-yohaku/check.jsonl
@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
diff --git a/.trellis/tasks/07-24-migrate-astro-yohaku/design.md b/.trellis/tasks/archive/2026-08/07-24-migrate-astro-yohaku/design.md
similarity index 100%
rename from .trellis/tasks/07-24-migrate-astro-yohaku/design.md
rename to .trellis/tasks/archive/2026-08/07-24-migrate-astro-yohaku/design.md
diff --git a/.trellis/tasks/archive/2026-08/07-24-migrate-astro-yohaku/implement.jsonl b/.trellis/tasks/archive/2026-08/07-24-migrate-astro-yohaku/implement.jsonl
new file mode 100644
index 0000000..9dd3234
--- /dev/null
+++ b/.trellis/tasks/archive/2026-08/07-24-migrate-astro-yohaku/implement.jsonl
@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
diff --git a/.trellis/tasks/07-24-migrate-astro-yohaku/implement.md b/.trellis/tasks/archive/2026-08/07-24-migrate-astro-yohaku/implement.md
similarity index 100%
rename from .trellis/tasks/07-24-migrate-astro-yohaku/implement.md
rename to .trellis/tasks/archive/2026-08/07-24-migrate-astro-yohaku/implement.md
diff --git a/.trellis/tasks/07-24-migrate-astro-yohaku/prd.md b/.trellis/tasks/archive/2026-08/07-24-migrate-astro-yohaku/prd.md
similarity index 100%
rename from .trellis/tasks/07-24-migrate-astro-yohaku/prd.md
rename to .trellis/tasks/archive/2026-08/07-24-migrate-astro-yohaku/prd.md
diff --git a/.trellis/tasks/07-24-migrate-astro-yohaku/task.json b/.trellis/tasks/archive/2026-08/07-24-migrate-astro-yohaku/task.json
similarity index 90%
rename from .trellis/tasks/07-24-migrate-astro-yohaku/task.json
rename to .trellis/tasks/archive/2026-08/07-24-migrate-astro-yohaku/task.json
index 8fe453f..3295ed7 100644
--- a/.trellis/tasks/07-24-migrate-astro-yohaku/task.json
+++ b/.trellis/tasks/archive/2026-08/07-24-migrate-astro-yohaku/task.json
@@ -3,7 +3,7 @@
   "name": "migrate-astro-yohaku",
   "title": "Migrate blog to Astro with Yohaku-inspired UI",
   "description": "",
-  "status": "in_progress",
+  "status": "completed",
   "dev_type": null,
   "scope": null,
   "package": null,
@@ -11,7 +11,7 @@
   "creator": "priority",
   "assignee": "priority",
   "createdAt": "2026-07-24",
-  "completedAt": null,
+  "completedAt": "2026-08-27",
   "branch": null,
   "base_branch": "main",
   "worktree_path": null,
diff --git a/src/components/WebMcp.astro b/src/components/WebMcp.astro
new file mode 100644
index 0000000..79442a3
--- /dev/null
+++ b/src/components/WebMcp.astro
@@ -0,0 +1,22 @@
+---
+/**
+ * Exposes this site's capabilities as WebMCP tools for browser-integrated AI agents.
+ *
+ * Progressive enhancement only: in hosts without `document.modelContext` nothing beyond
+ * the feature check is downloaded. The search index is fetched later still — on the first
+ * content tool call — so ordinary visitors pay for none of this.
+ */
+---
+
+<script>
+  // Reason: WebMCP is an origin trial, so today almost no visitor has a host for it.
+  // Keep the ~5KB of tool code out of everyone's bundle by loading it dynamically,
+  // and ship only this check eagerly.
+  if (document.modelContext?.registerTool) {
+    import('@/lib/webmcp/register')
+      .then(({ registerAll }) => registerAll())
+      .catch(() => {
+        // Chunk failed to load (offline, cache miss) — the site works without tools.
+      })
+  }
+</script>
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
index 73c9ab9..bcfbe49 100644
--- a/src/layouts/BaseLayout.astro
+++ b/src/layouts/BaseLayout.astro
@@ -8,6 +8,7 @@ import 'remark-github-alerts/styles/github-colors-dark-class.css'
 import Header from '@/components/Header.astro'
 import Footer from '@/components/Footer.astro'
 import Umami from '@/components/Umami.astro'
+import WebMcp from '@/components/WebMcp.astro'
 import { site } from '@/lib/site'
 
 interface Props {
@@ -24,6 +25,10 @@ const {
 } = Astro.props
 
 const pageTitle = title === site.title ? title : `${title} · ${site.name}`
+
+// WebMCP ships behind an origin trial (Chrome 149 / Edge 150). Absent token → no meta tag,
+// and the tools simply stay dormant. Register at https://developer.chrome.com/origintrials
+const originTrialToken = import.meta.env.PUBLIC_WEBMCP_ORIGIN_TRIAL_TOKEN
 ---
 
 <!doctype html>
@@ -32,6 +37,7 @@ const pageTitle = title === site.title ? title : `${title} · ${site.name}`
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="generator" content={Astro.generator} />
+    {originTrialToken && <meta http-equiv="origin-trial" content={originTrialToken} />}
     <meta name="author" content={site.author} />
     <meta name="description" content={description} />
     <meta property="og:title" content={pageTitle} />
@@ -68,5 +74,6 @@ const pageTitle = title === site.title ? title : `${title} · ${site.name}`
       </div>
     </main>
     <Footer />
+    <WebMcp />
   </body>
 </html>
diff --git a/src/lib/markdown-text.ts b/src/lib/markdown-text.ts
new file mode 100644
index 0000000..507885d
--- /dev/null
+++ b/src/lib/markdown-text.ts
@@ -0,0 +1,51 @@
+/**
+ * Markdown source → plain text, for the agent search index.
+ *
+ * Not a parser: a deliberately small regex pipeline, since the only consumer is
+ * keyword matching and snippet extraction. Astro's Content Layer hands us `entry.body`
+ * with frontmatter already stripped, so this only deals with body syntax.
+ */
+export function markdownToText(md: string): string {
+  return (
+    md
+      // Reason: fenced blocks must be removed before inline code. The inline pattern
+      // would otherwise match a fence's own backtick pair and leave the code body behind.
+      .replace(/```[\s\S]*?```/g, ' ')
+      .replace(/~~~[\s\S]*?~~~/g, ' ')
+      .replace(/`[^`\n]*`/g, ' ')
+
+      // Reason: images before links — `![alt](src)` matches the link pattern too,
+      // which would consume the brackets and leave a stray `!` in the text.
+      .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
+      .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+      .replace(/\[([^\]]*)\]\[[^\]]*\]/g, '$1')
+
+      // Raw HTML, including the <div class="mermaid"> wrappers remark-mermaid emits.
+      .replace(/<[^>]+>/g, ' ')
+
+      // Reason: thematic breaks before list markers, so `- - -` is not mistaken for a list item.
+      .replace(/^\s*([-*_])\s*(?:\1\s*){2,}$/gm, ' ')
+      .replace(/^\s{0,3}#{1,6}\s+/gm, '')
+      .replace(/^\s{0,3}>+\s?/gm, '')
+      // GitHub alert labels surface once the blockquote marker is gone.
+      .replace(/\[!\w+\]/g, ' ')
+      .replace(/^\s*(?:[-*+]|\d+[.)])\s+/gm, '')
+
+      // Table separator rows carry no words; remaining pipes become spaces.
+      .replace(/^\s*\|[\s:|-]+\|\s*$/gm, ' ')
+      .replace(/\|/g, ' ')
+
+      // Reason: strip `*` and `~~` but keep `_`, so identifiers like `use_state`
+      // survive as searchable words.
+      .replace(/\*{1,3}|~{2}/g, '')
+      .replace(/\$\$?/g, ' ')
+
+      // Reason: backslashes last — a hard line break (`text\` at EOL) leaves a dangling
+      // slash, and escapes like `\*` must survive the emphasis pass before being unwrapped.
+      .replace(/\\(?=\s|$)/gm, ' ')
+      .replace(/\\([^\w\s])/g, '$1')
+
+      .replace(/\s+/g, ' ')
+      .trim()
+  )
+}
diff --git a/src/lib/webmcp/args.ts b/src/lib/webmcp/args.ts
new file mode 100644
index 0000000..a49a53e
--- /dev/null
+++ b/src/lib/webmcp/args.ts
@@ -0,0 +1,39 @@
+/**
+ * Runtime argument readers for WebMCP tools.
+ *
+ * Reason: tool arguments are produced by an LLM against a JSON Schema the browser
+ * does not enforce for us. Treat every field as untrusted and coerce explicitly.
+ */
+
+export function readString(
+  args: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  const value = args?.[key]
+  if (typeof value !== 'string') return undefined
+  const trimmed = value.trim()
+  return trimmed ? trimmed : undefined
+}
+
+/** Reads a bounded integer, ignoring NaN / out-of-range values in favour of `fallback`. */
+export function readInt(
+  args: Record<string, unknown>,
+  key: string,
+  { min, max, fallback }: { min: number; max: number; fallback: number },
+): number {
+  const value = args?.[key]
+  const num = typeof value === 'number' ? value : Number(value)
+  if (!Number.isFinite(num)) return fallback
+  return Math.min(max, Math.max(min, Math.trunc(num)))
+}
+
+/** Reads a string constrained to `allowed`, falling back when the model invents a value. */
+export function readEnum<T extends string>(
+  args: Record<string, unknown>,
+  key: string,
+  allowed: readonly T[],
+  fallback: T,
+): T {
+  const value = readString(args, key)
+  return allowed.includes(value as T) ? (value as T) : fallback
+}
diff --git a/src/lib/webmcp/page-context.ts b/src/lib/webmcp/page-context.ts
new file mode 100644
index 0000000..a5fd1c2
--- /dev/null
+++ b/src/lib/webmcp/page-context.ts
@@ -0,0 +1,105 @@
+/**
+ * Current-page facts inferred from the DOM and URL.
+ *
+ * Reason: nothing is injected into the page for WebMCP's benefit. Everything here is
+ * read from markup the site already renders, so `BaseLayout` stays unaware of post data
+ * and the agent layer adds no coupling to page components.
+ */
+
+export type PostCollection = 'blogs' | 'leetcode'
+
+export interface PageSection {
+  id: string
+  text: string
+  depth: number
+}
+
+export interface PageContext {
+  path: string
+  collection: PostCollection | null
+  /** Bare slug, e.g. `vue3-contribution`. Null on list pages. */
+  slug: string | null
+  /** Namespaced key the comments API expects, e.g. `blogs/vue3-contribution`. */
+  commentKey: string | null
+  title: string
+  hasComments: boolean
+  sections: PageSection[]
+}
+
+export function inferCollection(pathname: string): PostCollection | null {
+  if (pathname === '/posts' || pathname.startsWith('/posts/')) return 'blogs'
+  if (pathname === '/leetcode' || pathname.startsWith('/leetcode/')) return 'leetcode'
+  return null
+}
+
+/**
+ * Reason: `@/lib/comments` cannot be imported from client code — it pulls in
+ * `@/lib/github` and `@/lib/comments-token`, which read server-side env and would
+ * leak into the browser bundle. Mirroring this one-line format is the cheaper trade.
+ * Must stay in sync with `commentKey()` in `src/lib/comments.ts`.
+ */
+export function toCommentKey(collection: PostCollection, slug: string): string {
+  return `${collection}/${slug}`
+}
+
+/** Converts a site path (or an already-namespaced key) into a comments API key. */
+export function commentKeyFromPath(input: string): string | null {
+  const raw = input.trim()
+  if (!raw) return null
+
+  const bare = raw.replace(/^\/+|\/+$/g, '')
+  if (/^(blogs|leetcode)\/.+/.test(bare)) return bare
+
+  const path = `/${bare}`
+  const blogMatch = path.match(/^\/posts\/(.+)$/)
+  if (blogMatch) return toCommentKey('blogs', blogMatch[1])
+  const leetcodeMatch = path.match(/^\/leetcode\/(.+)$/)
+  if (leetcodeMatch) return toCommentKey('leetcode', leetcodeMatch[1])
+
+  return null
+}
+
+function deriveSlugFromPath(path: string, collection: PostCollection | null): string | null {
+  if (!collection) return null
+  const rest = path.replace(/^\/(?:posts|leetcode)\/?/, '').replace(/\/$/, '')
+  return rest || null
+}
+
+function readSections(): PageSection[] {
+  const nodes = document.querySelectorAll<HTMLHeadingElement>(
+    '.prose h2[id], .prose h3[id], .prose h4[id]',
+  )
+  return Array.from(nodes)
+    .map(el => ({
+      id: el.id,
+      text: el.textContent?.trim() ?? '',
+      depth: Number(el.tagName.slice(1)),
+    }))
+    .filter(section => section.text)
+}
+
+export function getPageContext(): PageContext {
+  const path = location.pathname
+  const collection = inferCollection(path)
+  const commentsRoot = document.querySelector<HTMLElement>('[data-comments]')
+
+  const commentKey = commentsRoot?.dataset.slug || null
+  const slug = commentKey
+    ? commentKey.slice(commentKey.indexOf('/') + 1)
+    : deriveSlugFromPath(path, collection)
+
+  const title =
+    commentsRoot?.dataset.title
+    || document.querySelector('.article-title')?.textContent?.trim()
+    || document.title
+
+  return {
+    path,
+    collection,
+    slug,
+    commentKey,
+    title,
+    hasComments: Boolean(commentsRoot),
+    sections: readSections(),
+  }
+}
diff --git a/src/lib/webmcp/register.ts b/src/lib/webmcp/register.ts
new file mode 100644
index 0000000..f7973fb
--- /dev/null
+++ b/src/lib/webmcp/register.ts
@@ -0,0 +1,37 @@
+/**
+ * Registration entry point for this site's WebMCP tools.
+ *
+ * Spec: https://github.com/webmachinelearning/webmcp
+ */
+
+import { commentTools } from './tools/comments'
+import { contentTools } from './tools/content'
+import { navigationTools } from './tools/navigation'
+import type { ToolDefinition } from './types'
+
+export const allTools: ToolDefinition[] = [
+  ...contentTools,
+  ...navigationTools,
+  ...commentTools,
+]
+
+export async function registerAll(): Promise<void> {
+  const modelContext = document.modelContext
+  // Feature detection: without a WebMCP host this is a no-op and the site is untouched.
+  if (!modelContext?.registerTool) return
+
+  // Reason: Astro is an MPA — every navigation reloads the document. Tools are registered
+  // once per page load and unregistered on unload by aborting the signal.
+  const controller = new AbortController()
+  addEventListener('pagehide', () => controller.abort(), { once: true })
+
+  try {
+    await Promise.all(
+      allTools.map(tool => modelContext.registerTool(tool, { signal: controller.signal })),
+    )
+  } catch {
+    // Reason: registerTool rejects with NotAllowedError when the `tools` permission policy
+    // is disabled (`Permissions-Policy: tools=()`). There is nothing a visitor can act on,
+    // so degrade silently rather than logging noise into their console.
+  }
+}
diff --git a/src/lib/webmcp/result.ts b/src/lib/webmcp/result.ts
new file mode 100644
index 0000000..e2cae1b
--- /dev/null
+++ b/src/lib/webmcp/result.ts
@@ -0,0 +1,27 @@
+import type { ToolResult } from './types'
+
+/** Successful result carrying human/agent-readable text. */
+export function ok(text: string): ToolResult {
+  return { content: [{ type: 'text', text }] }
+}
+
+/** Successful result carrying structured data the agent can parse. */
+export function okJson(data: unknown): ToolResult {
+  return ok(JSON.stringify(data, null, 2))
+}
+
+/**
+ * Failure result.
+ *
+ * Reason: tools return an error *result* instead of throwing. A thrown exception
+ * reaches the agent as an opaque DOMException, while readable text lets it correct
+ * its arguments and retry on its own.
+ */
+export function err(text: string): ToolResult {
+  return { content: [{ type: 'text', text }], isError: true }
+}
+
+/** Readable message for an unknown thrown value, for use in `err()`. */
+export function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
diff --git a/src/lib/webmcp/search-index.ts b/src/lib/webmcp/search-index.ts
new file mode 100644
index 0000000..cb58aa2
--- /dev/null
+++ b/src/lib/webmcp/search-index.ts
@@ -0,0 +1,171 @@
+/**
+ * Client-side loading and keyword search over the build-time post index.
+ *
+ * The index is fetched lazily — only when a content tool actually runs — so ordinary
+ * visitors never pay for it.
+ */
+
+export interface IndexedPost {
+  collection: 'blogs' | 'leetcode'
+  slug: string
+  /** Site-relative path, e.g. `/posts/vue3-contribution`. */
+  href: string
+  title: string
+  desc?: string
+  tag?: string
+  /** ISO 8601. */
+  date: string
+  /** Plain-text body, used for matching and snippets. */
+  text: string
+}
+
+export interface SearchIndex {
+  version: 1
+  posts: IndexedPost[]
+}
+
+export interface SearchHit {
+  title: string
+  href: string
+  collection: 'blogs' | 'leetcode'
+  date: string
+  tag?: string
+  desc?: string
+  snippet: string
+  score: number
+}
+
+export const SEARCH_INDEX_PATH = '/search-index.json'
+
+let cache: Promise<SearchIndex> | null = null
+
+export function loadIndex(): Promise<SearchIndex> {
+  // Reason: one in-flight promise per page load. On failure the cache is cleared so a
+  // later tool call can retry instead of replaying a rejected promise forever.
+  if (!cache) {
+    cache = fetch(SEARCH_INDEX_PATH, { credentials: 'same-origin' })
+      .then((res) => {
+        if (!res.ok) throw new Error(`search index request failed: ${res.status}`)
+        return res.json() as Promise<SearchIndex>
+      })
+      .catch((error) => {
+        cache = null
+        throw error
+      })
+  }
+  return cache
+}
+
+/** Field weights. Title matches dominate; body matches only break ties. */
+const WEIGHTS = { title: 8, desc: 4, tag: 3, text: 1 } as const
+
+/** Reason: caps body hits so a long article cannot outrank a precise title match. */
+const TEXT_HIT_CAP = 10
+
+export function toTerms(query: string): string[] {
+  return query.toLowerCase().split(/\s+/).filter(Boolean)
+}
+
+function countOccurrences(haystack: string, needle: string): number {
+  if (!needle) return 0
+  let count = 0
+  let from = 0
+  for (;;) {
+    const at = haystack.indexOf(needle, from)
+    if (at === -1) break
+    count += 1
+    from = at + needle.length
+  }
+  return count
+}
+
+function scorePost(post: IndexedPost, terms: string[]): number {
+  const title = post.title.toLowerCase()
+  const desc = (post.desc ?? '').toLowerCase()
+  const tag = (post.tag ?? '').toLowerCase()
+  const text = post.text.toLowerCase()
+
+  let score = 0
+  for (const term of terms) {
+    score += WEIGHTS.title * countOccurrences(title, term)
+    score += WEIGHTS.desc * countOccurrences(desc, term)
+    score += WEIGHTS.tag * countOccurrences(tag, term)
+    score += WEIGHTS.text * Math.min(countOccurrences(text, term), TEXT_HIT_CAP)
+  }
+  return score
+}
+
+/** Text around the earliest matching term, so the agent can judge relevance without opening the post. */
+export function buildSnippet(text: string, terms: string[], radius = 60): string {
+  const lower = text.toLowerCase()
+  let at = -1
+  for (const term of terms) {
+    const found = lower.indexOf(term)
+    if (found !== -1 && (at === -1 || found < at)) at = found
+  }
+  if (at === -1) {
+    const head = text.slice(0, radius * 2).trim()
+    return text.length > radius * 2 ? `${head}…` : head
+  }
+  const start = Math.max(0, at - radius)
+  const end = Math.min(text.length, at + radius)
+  const lead = start > 0 ? '…' : ''
+  const tail = end < text.length ? '…' : ''
+  return `${lead}${text.slice(start, end).trim()}${tail}`
+}
+
+export interface SearchOptions {
+  collection?: 'blogs' | 'leetcode' | 'all'
+  limit?: number
+}
+
+export async function searchPosts(
+  query: string,
+  { collection = 'all', limit = 5 }: SearchOptions = {},
+): Promise<SearchHit[]> {
+  const terms = toTerms(query)
+  if (!terms.length) return []
+
+  const { posts } = await loadIndex()
+  const pool = collection === 'all' ? posts : posts.filter(p => p.collection === collection)
+
+  return pool
+    .map(post => ({ post, score: scorePost(post, terms) }))
+    .filter(entry => entry.score > 0)
+    .sort((a, b) =>
+      // Same relevance → newer first.
+      b.score - a.score || Date.parse(b.post.date) - Date.parse(a.post.date))
+    .slice(0, limit)
+    .map(({ post, score }) => ({
+      title: post.title,
+      href: post.href,
+      collection: post.collection,
+      date: post.date,
+      tag: post.tag,
+      desc: post.desc,
+      snippet: buildSnippet(post.text, terms),
+      score,
+    }))
+}
+
+/** Resolves `/posts/x`, `posts/x`, `x`, or a full same-origin URL to an indexed post. */
+export async function findPost(input: string): Promise<IndexedPost | undefined> {
+  const { posts } = await loadIndex()
+  const raw = input.trim()
+  if (!raw) return undefined
+
+  let pathname = raw
+  try {
+    // Absolute URLs are tolerated here (read-only lookup); navigation validates separately.
+    if (/^https?:\/\//i.test(raw)) pathname = new URL(raw).pathname
+  } catch {
+    // Fall through to slug matching.
+  }
+
+  const normalized = `/${pathname.replace(/^\/+|\/+$/g, '')}`
+  const byHref = posts.find(post => post.href === normalized)
+  if (byHref) return byHref
+
+  const slug = normalized.split('/').pop()?.toLowerCase() ?? ''
+  return posts.find(post => post.slug.toLowerCase() === slug)
+}
diff --git a/src/lib/webmcp/tools/comments.ts b/src/lib/webmcp/tools/comments.ts
new file mode 100644
index 0000000..d421312
--- /dev/null
+++ b/src/lib/webmcp/tools/comments.ts
@@ -0,0 +1,199 @@
+/**
+ * Comment tools: read discussions freely, but never publish without the user.
+ *
+ * Reason for the read/write asymmetry: posting a comment writes to a GitHub Issue under
+ * the visitor's own identity and cannot be undone. Per WebMCP's human-in-the-loop design,
+ * `draft-comment` only fills the existing textarea — the user presses submit.
+ *
+ * Tool descriptions are in English for the agent's model; result text stays in Chinese.
+ */
+
+import { readString } from '../args'
+import { commentKeyFromPath, getPageContext } from '../page-context'
+import { describeError, err, ok, okJson } from '../result'
+import type { ToolDefinition } from '../types'
+
+const COMMENTS_ENDPOINT = '/api/comments'
+const ME_ENDPOINT = '/api/comments/me'
+
+/** Must match `MAX_COMMENT_LENGTH` enforced by `sanitizeCommentText` in src/lib/comments.ts. */
+const MAX_COMMENT_LENGTH = 4000
+
+interface CommentAuthor {
+  login: string
+  name: string | null
+  htmlUrl: string
+}
+
+interface BlogComment {
+  id: number
+  body: string
+  createdAt: string
+  htmlUrl: string
+  author: CommentAuthor
+}
+
+interface CommentsResponse {
+  slug: string
+  issueNumber: number | null
+  issueUrl: string | null
+  comments: BlogComment[]
+  configured: boolean
+}
+
+interface MeResponse {
+  configured: boolean
+  user: { login: string; name: string | null } | null
+}
+
+/** Resolves which post's comments to act on: an explicit path, else the current page. */
+function resolveCommentKey(args: Record<string, unknown>): { key: string } | { error: string } {
+  const path = readString(args, 'path')
+  if (path) {
+    const key = commentKeyFromPath(path)
+    if (!key) {
+      return {
+        error: `无法从路径「${path}」解析出文章，请使用 /posts/<slug> 或 /leetcode/<slug> 形式。`,
+      }
+    }
+    return { key }
+  }
+
+  const { commentKey } = getPageContext()
+  if (!commentKey) {
+    return { error: '当前页面不是文章页，请用 path 参数指定要操作哪篇文章的评论。' }
+  }
+  return { key: commentKey }
+}
+
+async function fetchMe(): Promise<MeResponse> {
+  const res = await fetch(ME_ENDPOINT, { credentials: 'same-origin' })
+  if (!res.ok) throw new Error(`登录状态查询失败（HTTP ${res.status}）`)
+  return (await res.json()) as MeResponse
+}
+
+export const commentTools: ToolDefinition[] = [
+  {
+    name: 'list-comments',
+    description:
+      'Read the comments on an article of this site. Defaults to the article currently open; pass '
+      + '"path" to read a different one. Comments are backed by GitHub Issues.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description:
+            'Optional site path of the article, e.g. "/posts/vue3-contribution". '
+            + 'Omit to use the current page.',
+        },
+      },
+    },
+    async execute(args) {
+      const target = resolveCommentKey(args)
+      if ('error' in target) return err(target.error)
+
+      try {
+        const res = await fetch(
+          `${COMMENTS_ENDPOINT}?slug=${encodeURIComponent(target.key)}`,
+          { credentials: 'same-origin' },
+        )
+        if (!res.ok) return err(`读取评论失败（HTTP ${res.status}）。`)
+
+        const data = (await res.json()) as CommentsResponse
+        if (!data.configured) return ok('本站尚未配置评论功能。')
+        if (!data.comments.length) return ok(`《${target.key}》还没有评论。`)
+
+        return okJson({
+          post: target.key,
+          issueUrl: data.issueUrl,
+          count: data.comments.length,
+          comments: data.comments.map(comment => ({
+            author: comment.author.name || comment.author.login,
+            login: comment.author.login,
+            createdAt: comment.createdAt,
+            body: comment.body,
+            url: comment.htmlUrl,
+          })),
+        })
+      } catch (error) {
+        return err(`读取评论失败：${describeError(error)}`)
+      }
+    },
+  },
+
+  {
+    name: 'check-comment-auth',
+    description:
+      'Check whether the visitor is signed in with GitHub and therefore able to post a comment. '
+      + 'Call this before drafting a comment so you can tell the user to sign in first if needed.',
+    inputSchema: { type: 'object', properties: {} },
+    async execute() {
+      try {
+        const me = await fetchMe()
+        if (!me.configured) return ok('本站尚未配置评论功能，无法评论。')
+        if (!me.user) {
+          return okJson({
+            signedIn: false,
+            hint: '尚未登录。评论区底部有 GitHub 登录入口，登录后即可发表评论。',
+          })
+        }
+        return okJson({ signedIn: true, login: me.user.login, name: me.user.name })
+      } catch (error) {
+        return err(`查询登录状态失败：${describeError(error)}`)
+      }
+    },
+  },
+
+  {
+    name: 'draft-comment',
+    description:
+      'Write a comment draft into the comment box on the current article and scroll it into view. '
+      + 'This does NOT publish anything — the user must review the text and press the submit button '
+      + 'themselves. Only works on an article page where a comment section exists.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: {
+          type: 'string',
+          description: `Comment text to place in the box. At most ${MAX_COMMENT_LENGTH} characters.`,
+        },
+      },
+      required: ['text'],
+    },
+    async execute(args) {
+      const root = document.querySelector<HTMLElement>('[data-comments]')
+      if (!root) return err('当前页面没有评论区，请先打开一篇文章。')
+
+      const text = readString(args, 'text')
+      if (!text) return err('参数 text 不能为空。')
+      if (text.length > MAX_COMMENT_LENGTH) {
+        return err(`评论过长（${text.length} 字），上限为 ${MAX_COMMENT_LENGTH} 字。`)
+      }
+
+      try {
+        const me = await fetchMe()
+        if (!me.configured) return err('本站尚未配置评论功能，无法评论。')
+        if (!me.user) {
+          return err('尚未登录 GitHub。请先在评论区点击 GitHub 登录，登录后我再帮你填写草稿。')
+        }
+      } catch (error) {
+        return err(`查询登录状态失败：${describeError(error)}`)
+      }
+
+      const input = root.querySelector<HTMLTextAreaElement>('[data-comments-input]')
+      if (!input) return err('没有找到评论输入框，评论区可能尚未加载完成。')
+
+      input.value = text
+      // Reason: the comment component listens for `input` to drive its own validation
+      // and button state — setting `.value` alone would leave the UI out of sync.
+      input.dispatchEvent(new Event('input', { bubbles: true }))
+
+      root.scrollIntoView({ behavior: 'smooth', block: 'center' })
+      input.focus()
+
+      // NOTE: intentionally no form submission here. See the file header.
+      return ok('草稿已填入评论框，并已滚动到评论区。请确认内容无误后，由你点击「发表评论」提交。')
+    },
+  },
+]
diff --git a/src/lib/webmcp/tools/content.ts b/src/lib/webmcp/tools/content.ts
new file mode 100644
index 0000000..d11bc0f
--- /dev/null
+++ b/src/lib/webmcp/tools/content.ts
@@ -0,0 +1,103 @@
+/**
+ * Content tools: let an agent find and read this site's articles without scraping the DOM.
+ *
+ * Tool descriptions are written in English because they are consumed by the agent's model;
+ * user-facing result text stays in Chinese to match the site.
+ */
+
+import { readEnum, readInt, readString } from '../args'
+import { describeError, err, ok, okJson } from '../result'
+import { findPost, searchPosts } from '../search-index'
+import type { ToolDefinition } from '../types'
+
+const COLLECTIONS = ['blogs', 'leetcode', 'all'] as const
+
+export const contentTools: ToolDefinition[] = [
+  {
+    name: 'search-posts',
+    description:
+      'Search this site\'s articles by keyword. Covers two collections: "blogs" (essays and notes) '
+      + 'and "leetcode" (algorithm and TypeScript type-challenge write-ups). Returns ranked matches '
+      + 'with title, site path, date and a matching snippet. Call this before navigating so you can '
+      + 'pick the right article path.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Keywords to search for. Space-separated terms are matched independently.',
+        },
+        collection: {
+          type: 'string',
+          enum: ['blogs', 'leetcode', 'all'],
+          description: 'Restrict the search to one collection. Defaults to "all".',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of results, between 1 and 20. Defaults to 5.',
+        },
+      },
+      required: ['query'],
+    },
+    async execute(args) {
+      const query = readString(args, 'query')
+      if (!query) return err('参数 query 不能为空。')
+
+      const collection = readEnum(args, 'collection', COLLECTIONS, 'all')
+      const limit = readInt(args, 'limit', { min: 1, max: 20, fallback: 5 })
+
+      try {
+        const results = await searchPosts(query, { collection, limit })
+        if (!results.length) {
+          return ok(
+            `没有找到匹配「${query}」的文章。`
+            + '可以换个关键词重试，或把 collection 设为 "all" 扩大范围。',
+          )
+        }
+        return okJson({ query, collection, count: results.length, results })
+      } catch (error) {
+        return err(`搜索索引加载失败：${describeError(error)}`)
+      }
+    },
+  },
+
+  {
+    name: 'get-post',
+    description:
+      'Fetch the full plain-text body and metadata of a single article on this site, for summarising '
+      + 'or answering questions about it. Accepts a site path such as "/posts/vue3-contribution" or '
+      + '"/leetcode/awaited", or a bare slug. Use search-posts first if you do not know the path.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Site path or slug of the article, e.g. "/posts/vue3-contribution".',
+        },
+      },
+      required: ['path'],
+    },
+    async execute(args) {
+      const path = readString(args, 'path')
+      if (!path) return err('参数 path 不能为空。')
+
+      try {
+        const post = await findPost(path)
+        if (!post) {
+          return err(`未找到文章：${path}。可以先用 search-posts 查到正确的路径再试。`)
+        }
+        return okJson({
+          title: post.title,
+          href: post.href,
+          collection: post.collection,
+          date: post.date,
+          tag: post.tag,
+          desc: post.desc,
+          text: post.text,
+        })
+      } catch (error) {
+        return err(`搜索索引加载失败：${describeError(error)}`)
+      }
+    },
+  },
+]
diff --git a/src/lib/webmcp/tools/navigation.ts b/src/lib/webmcp/tools/navigation.ts
new file mode 100644
index 0000000..2ef7c7b
--- /dev/null
+++ b/src/lib/webmcp/tools/navigation.ts
@@ -0,0 +1,152 @@
+/**
+ * Navigation tools: move the user around the site, and tell the agent where it currently is.
+ *
+ * Tool descriptions are in English for the agent's model; result text stays in Chinese.
+ */
+
+import { readString } from '../args'
+import { getPageContext } from '../page-context'
+import { err, ok, okJson } from '../result'
+import type { ToolDefinition } from '../types'
+
+/**
+ * Route prefixes an agent may navigate to.
+ *
+ * Reason: an allowlist, not a denylist. `/keystatic` (the author's private CMS) and
+ * `/api/*` are excluded by construction rather than by remembering to ban them.
+ */
+const ALLOWED_PREFIXES = ['/posts', '/leetcode'] as const
+
+export type PathCheck =
+  | { allowed: true; pathname: string; hash: string }
+  | { allowed: false; reason: string }
+
+/** Validates an agent-supplied path before it can drive a navigation. */
+export function resolveInternalPath(input: string): PathCheck {
+  const raw = input.trim()
+  if (!raw) return { allowed: false, reason: '路径不能为空。' }
+
+  // Reason: reject origin-escaping shapes before parsing. `//evil.example` is
+  // protocol-relative and `javascript:` / `https:` carry a scheme — neither should
+  // ever reach `new URL()` with our origin as the base.
+  if (raw.includes('//')) {
+    return { allowed: false, reason: '只接受站内相对路径，不接受绝对 URL 或协议相对路径。' }
+  }
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(raw)) {
+    return { allowed: false, reason: '不接受带协议的地址，只允许站内路径。' }
+  }
+  if (!raw.startsWith('/')) {
+    return { allowed: false, reason: '路径必须以 / 开头，例如 /posts/vue3-contribution。' }
+  }
+
+  let url: URL
+  try {
+    url = new URL(raw, location.origin)
+  } catch {
+    return { allowed: false, reason: '路径格式无效。' }
+  }
+  if (url.origin !== location.origin) {
+    return { allowed: false, reason: '只允许在本站内导航。' }
+  }
+
+  const pathname = url.pathname.replace(/\/+$/, '') || '/'
+  const allowed =
+    pathname === '/'
+    || ALLOWED_PREFIXES.some(prefix => pathname === prefix || pathname.startsWith(`${prefix}/`))
+
+  if (!allowed) {
+    return {
+      allowed: false,
+      reason:
+        `不允许导航到 ${pathname}。`
+        + '只允许 /、/posts、/posts/<slug>、/leetcode、/leetcode/<slug>。',
+    }
+  }
+
+  return { allowed: true, pathname, hash: url.hash }
+}
+
+export const navigationTools: ToolDefinition[] = [
+  {
+    name: 'get-page-context',
+    description:
+      'Report what the user is currently looking at on this site: the path, which collection it '
+      + 'belongs to, the article slug and title, whether a comment section exists, and the list of '
+      + 'section headings on the page. Call this first to ground yourself before other tools.',
+    inputSchema: { type: 'object', properties: {} },
+    execute() {
+      return okJson(getPageContext())
+    },
+  },
+
+  {
+    name: 'navigate-to-post',
+    description:
+      'Navigate the current tab to a page on this site. Only site-internal paths are accepted: '
+      + '"/", "/posts", "/posts/<slug>", "/leetcode", "/leetcode/<slug>". External URLs and admin '
+      + 'routes are rejected. Use search-posts first to obtain a valid path.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Site-internal path to open, e.g. "/posts/vue3-contribution".',
+        },
+      },
+      required: ['path'],
+    },
+    execute(args) {
+      const path = readString(args, 'path')
+      if (!path) return err('参数 path 不能为空。')
+
+      const check = resolveInternalPath(path)
+      if (!check.allowed) return err(check.reason)
+
+      const target = `${check.pathname}${check.hash}`
+      // Reason: navigating tears down this page — and this promise — so hand the result
+      // back to the agent first and let the unload happen on the next task.
+      setTimeout(() => location.assign(target), 0)
+      return ok(`正在跳转到 ${target}。`)
+    },
+  },
+
+  {
+    name: 'goto-section',
+    description:
+      'Scroll the current article to one of its section headings, matched by heading text '
+      + '(exact match preferred, otherwise a case-insensitive substring). Use get-page-context to '
+      + 'see the available headings.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        heading: {
+          type: 'string',
+          description: 'Heading text to scroll to, as shown in get-page-context sections.',
+        },
+      },
+      required: ['heading'],
+    },
+    execute(args) {
+      const heading = readString(args, 'heading')
+      if (!heading) return err('参数 heading 不能为空。')
+
+      const { sections } = getPageContext()
+      if (!sections.length) return err('当前页面没有可跳转的小节标题。')
+
+      const needle = heading.toLowerCase()
+      const match =
+        sections.find(section => section.text.toLowerCase() === needle)
+        ?? sections.find(section => section.text.toLowerCase().includes(needle))
+
+      if (!match) {
+        return err(
+          `未找到标题「${heading}」。当前页可用小节：${sections.map(s => s.text).join('、')}`,
+        )
+      }
+
+      document.getElementById(match.id)?.scrollIntoView({ behavior: 'smooth', block: 'start' })
+      history.replaceState(null, '', `#${match.id}`)
+      return ok(`已跳转到「${match.text}」。`)
+    },
+  },
+]
diff --git a/src/lib/webmcp/types.ts b/src/lib/webmcp/types.ts
new file mode 100644
index 0000000..5af6aef
--- /dev/null
+++ b/src/lib/webmcp/types.ts
@@ -0,0 +1,65 @@
+/**
+ * Minimal local type declarations for the WebMCP `document.modelContext` API.
+ *
+ * Reason: WebMCP is still an Origin Trial (Chrome 149 / Edge 150) and the official
+ * `webmcp-types` package tracks a moving spec. This site only touches `registerTool`,
+ * so self-hosting that one slice removes a version-drift risk while keeping
+ * `astro check` green. Swap to the npm package once the API stabilises.
+ *
+ * Spec: https://github.com/webmachinelearning/webmcp
+ */
+
+/** JSON Schema subset used to describe tool inputs. */
+export interface ToolInputSchema {
+  type: 'object'
+  properties?: Record<string, unknown>
+  required?: string[]
+}
+
+export interface ToolTextContent {
+  type: 'text'
+  text: string
+}
+
+/** MCP-style tool result. `isError` lets the agent distinguish failure from an empty answer. */
+export interface ToolResult {
+  content: ToolTextContent[]
+  isError?: boolean
+}
+
+export interface ToolExecuteOptions {
+  /** Aborted when the user cancels the agent turn (e.g. a "stop" button). */
+  signal?: AbortSignal
+}
+
+export interface ToolDefinition {
+  name: string
+  description: string
+  inputSchema?: ToolInputSchema
+  /**
+   * Args come straight from an LLM, so they are untrusted and loosely typed
+   * on purpose — every tool validates them at runtime via `./args`.
+   */
+  execute: (
+    args: Record<string, unknown>,
+    options?: ToolExecuteOptions,
+  ) => ToolResult | Promise<ToolResult>
+}
+
+export interface RegisterToolOptions {
+  /** Aborting unregisters the tool. */
+  signal?: AbortSignal
+  /** Secure origins allowed to discover this tool. Unused here — we expose nothing cross-origin. */
+  exposedTo?: string[]
+}
+
+export interface ModelContext {
+  registerTool: (tool: ToolDefinition, options?: RegisterToolOptions) => Promise<void>
+}
+
+declare global {
+  interface Document {
+    /** Present only in WebMCP-capable hosts; always feature-detect before use. */
+    modelContext?: ModelContext
+  }
+}
diff --git a/src/pages/search-index.json.ts b/src/pages/search-index.json.ts
new file mode 100644
index 0000000..7339e8f
--- /dev/null
+++ b/src/pages/search-index.json.ts
@@ -0,0 +1,43 @@
+/**
+ * Build-time search index consumed by the WebMCP content tools.
+ *
+ * Static endpoint — emitted as `dist/search-index.json` under `output: 'static'`.
+ * Sourced through `getBlogPosts()` / `getLeetcodePosts()` so it inherits the same
+ * `display !== false` filtering and date ordering as the rendered pages, and through
+ * `postHref()` so indexed paths can never drift from the real routes.
+ */
+
+import type { APIRoute } from 'astro'
+import { getBlogPosts, getLeetcodePosts, postHref, type PostEntry } from '@/lib/posts'
+import { markdownToText } from '@/lib/markdown-text'
+import type { IndexedPost, SearchIndex } from '@/lib/webmcp/search-index'
+
+function toIndexed(entry: PostEntry, collection: 'blogs' | 'leetcode'): IndexedPost {
+  const href = postHref(collection, entry.id)
+  return {
+    collection,
+    slug: href.split('/').pop() ?? entry.id,
+    href,
+    title: entry.data.title,
+    desc: entry.data.desc,
+    tag: entry.data.tag,
+    date: entry.data.date.toISOString(),
+    text: markdownToText(entry.body ?? ''),
+  }
+}
+
+export const GET: APIRoute = async () => {
+  const [blogs, leetcode] = await Promise.all([getBlogPosts(), getLeetcodePosts()])
+
+  const index: SearchIndex = {
+    version: 1,
+    posts: [
+      ...blogs.map(entry => toIndexed(entry, 'blogs')),
+      ...leetcode.map(entry => toIndexed(entry, 'leetcode')),
+    ],
+  }
+
+  return new Response(JSON.stringify(index), {
+    headers: { 'Content-Type': 'application/json; charset=utf-8' },
+  })
+}