# 海棠诗社 MCP

海棠诗社提供公开的 [Model Context Protocol](https://modelcontextprotocol.io)
接口：`https://haitang.app/mcp`，使用 Streamable HTTP。
只读，无需登录或 API Key，仅提供站点公开的古典诗词、作者和分类数据。
不提供账号、收藏、评论、邮箱、支付、环境变量、管理接口或未公开内容。

## 工具

建议先用 `search_poetry` 搜索，或用 `list_dynasties`、`list_collections`、`list_types` 了解分类，再浏览列表、读取详情。
所有工具都返回文本和结构化 JSON，作品和作者包含公开链接：
`https://haitang.app/works/{id}`、`https://haitang.app/authors/{id}`。
不接受参数表以外的额外字段。

### search_poetry

搜索作者及作品，摘要由站点搜索 API 截断：作者简介最多 80 字符，作品正文最多 120 字符。
不返回总命中数；用详情工具读取完整内容。

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `query` | 是 | 去除首尾空格后 1–60 字符的关键词 |
| `authorLimit` | 否 | 最多返回的作者数，整数 1–20，默认 10 |
| `workLimit` | 否 | 最多返回的作品数，整数 1–20，默认 10 |

### list_dynasties、list_collections、list_types

分别返回完整静态朝代、选集、作品类型列表：

| 工具 | 返回结构 |
| --- | --- |
| `list_dynasties` | `{ dynasties: [{ name, slug }] }` |
| `list_collections` | `{ collections: [{ name, slug }] }` |
| `list_types` | `{ types: [{ name, slug }] }` |

这三个工具接受以下可选筛选参数。传入任一参数时，额外返回现有 API 提供的实时
`facets: { collections, dynasties, types }`，分别为可用选集 ID、朝代名称、
作品类型 slug；静态列表仍完整保留。不传筛选参数时只返回静态列表，不查询实时 facets。

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `collection` | 否 | 选集 ID 字符串，例如 `"1"`（唐诗三百），1–10 位正整数 |
| `category` | 否 | 朝代名称，例如 `唐`，1–60 字符；不是分类组名 |
| `tag` | 否 | 作品类型：`shi`（诗）、`ci`（词）、`qu`（曲）、`wen`（文） |

浏览作品时，`category` 使用朝代名称，`tag` 使用类型 slug，`collection` 使用
`list_collections` 返回的选集 slug（ID 字符串）。

### list_sorts

无需参数，返回 `{ sorts: [{ label, slug }] }`。
`slug: null` 表示不传 `sort`，沿用站点默认顺序。

### 分类组工具

以下工具无需参数，各自返回 `{ name, slug, categories: [{ name, slug }] }`：

| 工具 | 分类组 |
| --- | --- |
| `list_themes` | 主题 |
| `list_festivals` | 节日 |
| `list_solar_terms` | 节气 |
| `list_cipai` | 词牌 |
| `list_seasons` | 时令 |
| `list_geography` | 地理 |

### list_groups

无需参数，返回 `{ groups: [{ name, slug, categories: [{ name, slug }] }] }`。
仅包含其余分类组：选集、写景、时间、花卉、课本、城市、名山、用典、书籍；
不重复返回上面六个专用工具提供的分类组。
所有无需参数的工具只接受空对象 `{}`，不接受筛选或额外字段。

### list_works

返回作品 `items` 和 `page`、`pageSize`（48）、`total`、`totalPages`。
选集内作品也使用作品本身的 ID 和 URL。

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `collection` | 否 | 选集 ID 字符串，使用 `list_collections` 返回的选集 slug |
| `category` | 否 | 朝代名称，例如 `唐`，1–60 字符 |
| `tag` | 否 | `shi`、`ci`、`qu`、`wen` |
| `sort` | 否 | `views_count_asc`；省略沿用站点默认顺序。选集使用编排顺序，升序选项反转编排顺序 |
| `page` | 否 | 整数 1–1000，默认 1 |

### list_authors

返回作者 `items` 和 `page`、`pageSize`（24）、`total`、`totalPages`。

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `category` | 否 | 朝代名称，例如 `唐`，1–60 字符 |
| `page` | 否 | 整数 1–1000，默认 1 |

### get_work

返回公开作品正文、作者、朝代、类型、序言、简介、注释、译文、赏析、评语，
以及所属选集和名句。数据缺失的字段为 `null`；作品不存在时 `work: null`。

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `id` | 是 | 搜索或列表返回的作品 ID，正安全整数 |

### get_author

返回公开作者资料和该作者的作品分页，分页字段同 `list_authors`。
作者不存在时 `author: null`，作品列表为空。

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `id` | 是 | 搜索或列表返回的作者 ID，正安全整数 |
| `page` | 否 | 作者作品页码，整数 1–1000，默认 1 |

## Cursor

```json
{
  "mcpServers": {
    "haitang": {
      "url": "https://haitang.app/mcp"
    }
  }
}
```

## 试用

```bash
curl -sS https://haitang.app/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

```bash
curl -sS https://haitang.app/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_poetry","arguments":{"query":"明月","workLimit":3}}}'
```

本地开发地址为 `http://localhost:3000/mcp`。
接口接受 JSON-RPC POST；OPTIONS 返回 204，其余方法返回 405，不建立会话或 GET 事件流。
支持协议版本 `2025-03-26`、`2025-06-18`、`2025-11-25`。
每个客户端在单个 Worker 实例内每分钟最多 60 次 POST，请求体最多 8192 字节；
超过限流返回 429 和 `Retry-After`。限流响应包含 `X-RateLimit-Limit` 和
`X-RateLimit-Remaining`。这是实例内限制，不是全局配额。