内容
# mcp-yandex-wiki
最小的MCP服务器，适用于 [Яндекс Вики](https://wiki.yandex.ru/) （读取 + 写入）。
## 安装
```bash
cd ~/.claude/mcp/yandex-wiki
npm install
```
在 `~/.claude.json` 中注册：
```json
{
"mcpServers": {
"yandex-wiki": {
"type": "stdio",
"command": "node",
"args": ["/Users/<user>/.claude/mcp/yandex-wiki/index.mjs"],
"env": {
"YW_OAUTH_TOKEN": "y0__...",
"YW_ORG_ID": "1234567",
"YW_ORG_HEADER": "X-Org-Id"
}
}
}
}
```
## 环境变量
| 变量 | 必需 | 描述 |
|---|---|---|
| `YW_OAUTH_TOKEN` | 是 | 具有 `wiki:read` / `wiki:write` 权限的Яндекс OAuth令牌 |
| `YW_ORG_ID` | 是 | 组织ID |
| `YW_ORG_HEADER` | 否 | Яндекс 360（默认）使用 `X-Org-Id`，Yandex Cloud Organization 使用 `X-Cloud-Org-Id` |
来自 Яндекс 追踪器的令牌如果为同一应用程序授予了 wiki 权限，则可以使用 - 授权机制是通用的（`OAuth` + 组织头）。更多信息 - [关于令牌的权限](#关于令牌的权限)。
Yandex Cloud 的服务账号不适用于 Wiki API - 仅限用户账号。
## 工具
| 工具 | API | 描述 |
|---|---|---|
| `myself` | `GET /users/me` | 当前用户，组织，首页集群 |
| `get_page` | `GET /pages?slug=` / `GET /pages/{id}` | 按slug或id获取页面。仅在 `fields: ["content"]` 时返回正文 |
| `search` | `POST /search` | 全文搜索，最多10个结果 |
| `list_descendants` | `GET /pages/{id}/descendants` | 子页面 |
| `list_resources` | `GET /pages/{id}/resources` | 附件和表格的列表 |
| `list_attachments` | `GET /pages/{id}/attachments` | 附件 |
| `list_grids` | `GET /pages/{id}/grids` | 动态表格 |
| `create_page` | `POST /pages` | 创建页面（必须提供 `slug` 和 `title`） |
| `update_page` | `POST /pages/{id}` | 修改 `title` / `content` / `slug` |
| `delete_page` | `DELETE /pages/{id}` | 删除页面（不可逆） |
### `get_page` 的 `fields`
`redirect`, `breadcrumbs`, `attributes`, `content`, `access_policy`, `access_lists`, `owner`.
如果没有 `fields`，则只返回 `id`, `slug`, `title`, `page_type`.
## API 功能
- **搜索不分页。** `total_pages` 始终为 `1`，最多返回10个结果；忽略 `page` / `offset` 参数。请缩小搜索范围。
- **不支持 `PATCH` 和 `PUT`。** 更新使用 `POST /pages/{id}`。允许的方法：`/pages` → `POST, GET`; `/pages/{id}` → `POST, GET, DELETE`.
- **只读页面返回 HTTP 403** 表示写入失败 - 请参阅 [如何处理 HTTP 403](#如何处理-http-403).
## 检查状态
| 工具 | 状态 |
|---|---|
| `myself`, `get_page`, `search`, `list_descendants`, `list_resources`, `list_attachments`, `list_grids` | 已在实时API上测试 |
| `update_page` | 已测试：在真实页面上进行标题往返测试，内容按字节未更改 |
| `create_page`, `delete_page` | **未测试** - 从API验证错误和 `Allow` 头推断出架构 |
### 关于令牌的权限
文档 [提到两种权限](https://yandex.ru/support/wiki/ru/api-ref/access): `wiki:read` （仅读取）和 `wiki:write` （创建，编辑，删除）。另外还有一个独立的权限控制 - 用户权限：“以用户身份执行请求… 用户必须在维基百科中具有相应的权限”。
**实际上，维基百科的权限被证明是不必要的。** 如果应用程序令牌仅被授予 Яндекс 追踪器的权限而没有任何维基百科的权限，则可以使用该令牌读写维基百科 - 已在实时API上测试，包括页面的 `POST` 请求。
其机制尚未确定，可能有两种解释：
- 维基百科API根本不检查权限，而是允许用户身份验证；
- 追踪器权限设计上涵盖维基百科 - 它们是同一产品集群中的服务。
可以通过具有外部权限的令牌来区分它们（例如，仅 `login:info`）：如果请求成功，则是第一种情况；如果返回 `403`，则是第二种情况。
Яндекс 的权限控制 **是按服务划分的，而不是全局的**：同一个令牌在 Яндекс 磁盘（未授予 `cloud_api:disk.read`）上获得 `HTTP 403 «可能应用程序权限不足»`。也就是说，“磁盘检查权限”并不意味着维基百科也会检查权限 - 不要将一个API的结论推广到另一个API。
实际结果：**如果您已经有一个 Яндекс 追踪器令牌，则无需单独授予维基百科权限。** 反之，单独的“仅限维基百科”令牌不能隔离维基百科：追踪器令牌也可以访问它。
### 如何处理 HTTP 403
权限在此几乎无关紧要 - 请查看权限：
- 用户对页面无权限；
- 页面是只读的：`get_page` with `fields: ["attributes"]` → `attributes.is_readonly`. 系统页面（所有者 `yandex360-wiki`）是只读的 - 例如，首页。
如果 `403` 错误出现在所有请求上，包括读取请求，请检查 `X-Org-Id` 和令牌是否属于用户而非服务账号。
### 写入的副作用
任何 `POST /pages/{id}` 请求都会更新 `modified_at`，即使请求体中没有一个重要字段。页面将被标记为已更改。
