---
title: 如何为 Next.js App Router 添加 MCP Server
description: 为 Next.js 添加本地 stdio 与经过鉴权的 Streamable HTTP MCP 端点，并将页面搜索和显式公开的 Action 暴露为工具。
canonical_url: https://nextaiready.com/zh/docs/guides/mcp-integration
url: https://nextaiready.com/zh/docs/guides/mcp-integration
last_updated: 2026-08-24
updated: 2026-08-24
author: next-ai-ready 团队
summary: 为 Next.js 添加本地 stdio 与经过鉴权的 Streamable HTTP MCP 端点，并将页面搜索和显式公开的 Action 暴露为工具。
topics: [nextjs, app-router, mcp-server, model-context-protocol, claude-desktop, cursor, tutorial]
---

# 如何为 Next.js App Router 添加 MCP Server

最短路径是初始化 `next-ai-ready`、安装可选 MCP peer 依赖，并部署生成的 `/api/mcp`
路由。本地客户端使用 stdio，托管客户端使用经过鉴权的 Streamable HTTP；两种传输方式
暴露同一组显式公开的 Action 与构建期文档图谱。

```bash
pnpm add next-ai-ready zod@^4 @modelcontextprotocol/sdk mcp-handler
pnpm exec next-ai-ready init --with-capabilities
pnpm exec next-ai-ready build
```

模型上下文协议（MCP）让 Claude Desktop 和 Cursor 等 AI 客户端将你的 Action 作为工具发现和
调用。`next-ai-ready` 在 `/api/mcp` 提供 MCP Server。

## MCP 能做什么

- **工具发现** — MCP 客户端将你的公开 action 视为可调用的工具。
- **资源访问** — 你的页面作为 MCP 资源暴露（Markdown 内容）。
- **页面发现** — 客户端无需预先知道资源 URI，即可列出、读取和搜索 graph 页面。
- **两种传输方式** — Streamable HTTP（生产环境）和 stdio（本地桌面客户端）。

## HTTP 端点（生产环境）

运行 `next-ai-ready init --with-capabilities` 后，MCP 服务器在 `/api/mcp` 可用。它通过 `vercel/mcp-handler` 处理 Streamable HTTP、SSE 和会话管理。

将任何 MCP 兼容客户端连接到 `https://your-site.com/api/mcp`。

## Stdio（本地客户端）

对于 Claude Desktop 等桌面客户端，运行 stdio 服务器：

```bash
npx next-ai-ready mcp
```

这会启动通过 stdin/stdout 的 MCP 服务器。添加到 Claude Desktop 配置：

```json
{
  "mcpServers": {
    "my-site": {
      "command": "npx",
      "args": ["next-ai-ready", "mcp"]
    }
  }
}
```

使用 `--no-resources` 跳过基于 graph 的页面资源和发现工具（启动更快）：

```bash
npx next-ai-ready mcp --no-resources
```

## 工作原理

MCP 包（`@next-ai-ready/mcp`）是一个薄适配器：

1. 读取 action 注册表（由 `defineActions()` 填充）。
2. 每个公开 action 成为一个 MCP 工具，包含名称、描述和输入 schema。
3. SemanticGraph 中的每个页面成为 MCP 资源，URI 为 `airead://page/<route>`。
4. 传入 graph 时还会自动注册 `list_pages`、`get_page` 和 `search_pages`。
5. action 工具调用通过 `invokeAction()` —— 与 HTTP 端点相同的验证、认证和错误处理。

## 页面发现工具

只要 `registerAiReady(server, { graph })` 收到 SemanticGraph，就会提供三个只读工具：

| 工具             | 参数                         | 行为与限制                                                               |
| -------------- | -------------------------- | ------------------------------------------------------------------- |
| `list_pages`   | `cursor?`、`limit?`         | 按稳定路由顺序进行游标分页。默认返回 20 条，最多 50 条；游标必须是长度不超过 512 字符的安全绝对路由。           |
| `get_page`     | `route`                    | 返回页面元数据和完整 AI-ready Markdown；路由必须是长度 1–512 字符的安全绝对路由。               |
| `search_pages` | `query`、`locale?`、`limit?` | 支持中文分词的确定性本地词法搜索。查询长度为 1–200 字符，可按 locale 缩小多语言结果，默认返回 5 条，最多 20 条。 |

搜索只读取预构建的 SemanticGraph，不需要外部 API、Embedding 服务或向量数据库。将 `list_pages` 或 `search_pages` 返回的路由传给 `get_page` 即可读取全文。

## 多协议共用一套检索实现

`search_pages` 与文档站的 HTTP `search_docs` Action 都使用公开的 `PageSearchProvider` 契约。内置 `createGraphSearchProvider(graph)` 保持确定性且无需数据库；运行时索引只需实现同一契约，再通过 `registerAiReady(server, { graph, searchProvider })` 注入，无需修改 MCP 客户端。

## 前置条件

MCP 需要两个可选的 peer 依赖：

```bash
pnpm add @modelcontextprotocol/sdk mcp-handler
```

这些在 `@next-ai-ready/next` 中声明为可选。如果未安装，MCP route handler 返回 501。

## 安全

- 仅 `public: true` 的 action 作为 MCP 工具暴露。
- 每个 action 的 `auth` hook 在 handler 之前运行。
- **Token 认证（生产环境）：** 当 `NODE_ENV === "production"` 时，HTTP 端点需要 `NEXT_AI_READY_MCP_TOKEN` 环境变量。客户端必须发送 `Authorization: Bearer <token>`。缺少有效 token 的请求将收到 401。开发环境中，所有请求均被允许。
- stdio 服务器在本地运行，不需要 token 认证。
- **Stdio 与 auth action：** stdio 使用合成 `Request`，无浏览器 cookie/会话。依赖 HTTP 上下文的 `auth` 钩子在 stdio 下可能返回 401 — 本地测试请用 HTTP MCP 或将 demo action 设为 `public: true`（C-70）。
- 可通过 `createAiReadyMcpHandler({ auth: false })` 关闭 HTTP 鉴权，生产环境不推荐。