# @cyanheads/gutenberg-mcp-server 中文文档

规范地址：https://npmcn.com/package/%40cyanheads/gutenberg-mcp-server/

版本：0\.3\.3
npm 元数据更新时间：2026-11-11T16:54:03.335Z
中文译文更新时间：2026-11-16T00:23:47.525Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cyanheads/gutenberg-mcp-server
原文对照：https://npmcn.com/package/%40cyanheads/gutenberg-mcp-server/?lang=original
项目主页：https://github.com/cyanheads/gutenberg-mcp-server#readme
源码仓库：https://github.com/cyanheads/gutenberg-mcp-server

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：540 kB，102 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：9 个
- 首次发布：2026-06-01T10:30:06.592Z
- 最新版本发布：2026-11-11T16:54:03.128Z
- 近 30 天下载量：1973（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

搜索、浏览和阅读Gutenberg项目78,000+公共域名书籍,通过MCP进行全文检索并抵消/限制块。 (原始内容存档于2012-10-12). STIO or Streamable HTTP.

## 安装

```sh
npm install @cyanheads/gutenberg-mcp-server
```

也可以使用：`pnpm add @cyanheads/gutenberg-mcp-server`、`yarn add @cyanheads/gutenberg-mcp-server`、`bun add @cyanheads/gutenberg-mcp-server`

## README

# @cyanheads/gutenberg-mcp-服务器

**搜索、浏览和阅读Gutenberg项目78,000+公共域名书籍,通过MCP进行全文检索并抵消/限制块。 (原始内容存档于2012-10-12). STIO or Streamable HTTP.**

4 个工具

[![Version](https://img.shields.io/badge/Version-0.3.3-blue.svg?style=flat-square)](https://npmcn.com/package/%40cyanheads/gutenberg-mcp-server/CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](https://npmcn.com/package/%40cyanheads/gutenberg-mcp-server/LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/gutenberg-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-%5E2.4.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/gutenberg-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/gutenberg-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-%5E7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4-blueviolet.svg?style=flat-square)](https://bun.sh/)

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/gutenberg-mcp-server/releases/latest/download/gutenberg-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=gutenberg-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvZ3V0ZW5iZXJnLW1jcC1zZXJ2ZXIiXX0=) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22gutenberg-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fgutenberg-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

**公共主机服务器 :** [https://gutenberg.caseyjhand.com/mcp 页面存档备份,存于互联网档案馆](https://gutenberg.caseyjhand.com/mcp)

* * *

## 概览

古腾堡项目图书馆藏书7.8万多册. 按标题、作者、主题或语言搜索,获取完整的书本元数据,并读取支持的 UTF-8 纯文本和 HTML 版本的可管理块.

### 工具

| 工具 | 说明 |
| :-- | :-- |
| `gutenberg_search_books` | 按标题、作者、话题、翻译、语言或作者寿命搜索目录,并进行页标和受欢迎度排序 |
| `gutenberg_get_book` | 由 ID 获取一本书的完整元数据——作者、翻译、编辑、完整格式地图、主题、版权状况 |
| `gutenberg_get_text` | 取出一本书的纯文本内容,取出牌照锅炉板,并有抵消/限制块或一个 `find` 跳转到一段 |
| `gutenberg_browse_popular` | 浏览最下行的书,可选择按语言或主题过滤 |

发表 [gunenberg 向导](https://npmcn.com/package/%40cyanheads/gutenberg-mcp-server/skills/gutenberg-guide/SKILL.md) 技能包括决定是否可读出一本书,在将一本书调出之前排除搜索盲点,寻找打开处和章节过去前题,呼出长文本,以及排名版本。 插件安装包括它;MCP客户端可以通过技能扩展及其技能资源来发现它.

* * *

## 能力参考

### `gutenberg_search_books` 工具

-   过滤器 : `query` (标题/作者词), `topic`, (中文(简体) ), `translator`, (中文(简体) ), `languages` (目录编码恰好是结果报告,两到三个字母: `en`没有 `eng`, (中文(简体) ), `author_year_start`编号 :`author_year_end`, (中文(简体) ), `ids`, (中文(简体) ), `mime_type`,以及 `copyright` (单位:千美元)`"true"`, (中文(简体) ), `"false"`, (中文(简体) ), `"null"`;假指在美国的公有领域. 直播倒计时 拒绝超过四个字的询问 `translator` 过滤器
-   在两个作者年限内,一位作者必须同时与两位作者会面。 现场倒计时检查界限 并在通知中说
-   `sort` 实值 `popular` (违约)或 `ascending`编号 :`descending` 由古腾堡身份证。 每页最多32本;使用 `totalCount` 财务报告和审定财务报表 `hasMore` 到页面
-   每个结果都包含 `is_readable` (合格文本格式;无法保证镜像文件可用性)和 `has_plain_text`。本地镜像在查询、翻译和专题匹配中忽略了大小写和口音;现场匹配是上游定义的。 结果行省略了翻译; `gutenberg_get_book` 报告他们。 失败者 `translator_requires_mirror`, (中文(简体) ), `query_requires_mirror`, (中文(简体) ), `page_out_of_range`, (中文(简体) ), `catalog_rejected`,或 `catalog_unavailable`

* * *

### `gutenberg_get_book` 工具

-   返回全部内容 `formats` 地图(MIME类型-下载 URL)和作者、翻译和有出生/死亡年数的编辑
-   还带着 `is_readable`, (中文(简体) ), `has_plain_text`, (中文(简体) ), `summary`, (中文(简体) ), `source_notes`,以及 `download_count` (过去30天的负载,而不是一生)
-   读取当地镜像,后由本作在内容镜上自行收录. 失败者 `not_found`, (中文(简体) ), `catalog_rejected`,或 `catalog_unavailable`

* * *

### `gutenberg_get_text` 工具

-   读取一本书 `offset`编号 :`limit` 块( 默认) `limit` 2万元,封顶为5万元),古腾堡牌照头和脚被剥去. `requestedLimit` 财务报告和审定财务报表 `appliedLimit` 两个报告
-   优先使用 UTF-8 纯文本并返回 HTML 转换为文本; `sourceFormat` 说哪一个。 回返 `totalChars`, (中文(简体) ), `length`, (中文(简体) ), `remainingChars`, (中文(简体) ), `hasMore`,以及 `provenance` (ID,标题,许可证 URL). 使用 `length`没有 `limit`,用于计算下一个 `offset`
-   `find` 跳转到一段而不是呼它:块从第一次比赛开始,时间或之后 `offset`,以及 `match` 报告 `offset`, (中文(简体) ), `length`,以及 `laterMatches`。匹配忽略了字母大小写和白空间运行,对直线和卷曲的引文一视同仁;口音和平分必须匹配
-   转换的 HTML 版本空白了没有可见字符的每行, 将每个表格行保留在有分页单元格的一行上, 并将一行换行保留为一行
-   当镜像支持时, 8 MiB 以上的文件会被读取为 4 个平行字节区域; 40 个以上的 MiB 文件失败 `text_too_large`
-   失败者 `not_found`, (中文(简体) ), `audio_book` (单位:千美元)`media_type "Sound"`, (中文(简体) ), `no_text_format`, (中文(简体) ), `offset_out_of_range`, (中文(简体) ), `passage_not_found`, (中文(简体) ), `text_file_not_found`, (中文(简体) ), `text_fetch_rejected`, (中文(简体) ), `text_too_large`, (中文(简体) ), `invalid_text_response`, (中文(简体) ), `text_fetch_failed`, (中文(简体) ), `catalog_rejected`,或 `catalog_unavailable`

* * *

### `gutenberg_browse_popular` 工具

-   最多32个头衔`limit`,默认为 20),大多数下载时间为前30天. `requestedLimit` 财务报告和审定财务报表 `appliedLimit` 报告上限
-   可选 `languages`, (中文(简体) ), `topic`, (中文(简体) ), `mime_type`,以及 `copyright` 过滤器在搜索中有效 . `totalInCatalog` 给出全部数
-   产出报告截断并带有 `continuation` 指点 `gutenberg_search_books`。空结果在通知中成功;失败 `catalog_rejected` 或者说 `catalog_unavailable`

* * *

## 特征

建造在 [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio和可流式的 HTTP 传输器,可插接式(`none` 编号 : `jwt` 编号 : `oauth`),可互换存储(`in-memory`, (中文(简体) ), `filesystem`, (中文(简体) ), `Supabase`, (中文(简体) ), `Cloudflare KV/R2/D1`),结构化记录,可选择的OpenTeleometry tracking.

古腾堡特有:

-   搜索和浏览读取了本地SQLite+FTS5目录镜像. 当镜子冷的时候,搜索会回到 [古滕德克斯语Name](https://gutendex.com/); 镜像所缺少的一本书从内容镜上的 RDF 记录读取
-   从 Gutenberg 工程内容镜像中获取完整纯文本, 并带有 UTF-8/ HTML 倒置
-   每个租户会缓存书本, 所以以后的块会读取跳过抓取
-   不需要 API 密钥

方便代理输出 :

-   `is_readable` 旗帜 带有 UTF-8 纯文本的文本记录, 或者没有音频格式的 HTML; 缺少的镜像文件仍然返回 `text_file_not_found`
-   `offset`, (中文(简体) ), `length`, (中文(简体) ), `totalChars`, (中文(简体) ), `remainingChars`,以及 `hasMore` 支持可靠顺序读取
-   `provenance` 财务报告和审定财务报表 `sourceFormat` 每一文本答复都涉及归属和忠诚

* * *

## 开始

连接到主机实例, 没有安装 :

```sh
claude mcp add --transport http gutenberg-mcp-server https://gutenberg.caseyjhand.com/mcp
```

或者在当地运行它:

```sh
claude mcp add gutenberg-mcp-server -- npx -y @cyanheads/gutenberg-mcp-server
```

对于其他客户端,请将此添加到 MCP 配置文件中 :

```json
{
  "mcpServers": {
    "gutenberg-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/gutenberg-mcp-server"]
    }
  }
}
```

不需要 API 密钥 。 对于 Docker 或源构建,请参见 [运行服务器](https://npmcn.com/package/%40cyanheads/gutenberg-mcp-server/#readme-running-the-server)。 。 。 .

* * *

## 配置

| 变量 | 说明 | 默认 |
| :-- | :-- | :-- |
| `GUTENDEX_BASE_URL` | Gutendex目录 API 基础 URL,当本地目录镜像无法回答时用于搜索和受欢迎浏览. | `https://gutendex.com/books/` |
| `GUTENBERG_TEXT_BASE_URL` | 内容镜像服务 `/cache/epub` 文件树:书籍文本,批量目录存档,和每册目录记录. | `https://gutenberg.pglaf.org` |
| `GUTENBERG_MIRROR_PATH` | SQLite 目录路径;在容器中使用持续体积. | `$XDG_DATA_HOME/gutenberg-mcp-server/gutenberg-catalog.sqlite` (单位:千美元)`~/.local/share` 何时 `XDG_DATA_HOME` 未设置、 空或相对) |
| `GUTENBERG_MIRROR_REFRESH_CRON` | 进程目录更新的 Cron 排程 . | 未设置 |
| `MCP_TRANSPORT_TYPE` | 运输: `stdio` 或者说 `http`。 。 。 . | `stdio` |
| `MCP_SESSION_MODE` | HTTP 会话模式 : `auto`, (中文(简体) ), `stateful`,或 `stateless`覆盖 `stateless` 服务器声明的状态 `createApp()`。 。 。 . | `stateless` |
| `MCP_HTTP_PORT` | HTTP 服务器端口 . | `3010` |
| `MCP_AUTH_MODE` | Auth 模式 : `none`, (中文(简体) ), `jwt`,或 `oauth`。 。 。 . | `none` |
| `MCP_LOG_LEVEL` | 日志级别(RFC 5424). | `info` |
| `LOGS_DIR` | 日志文件目录(只有Node.js). | `<project-root>/logs` |
| `STORAGE_PROVIDER_TYPE` | 存储后端. | `in-memory` |
| `OTEL_ENABLED` | 启用 [OpenTelemet 仪器](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry)。 。 。 . | `false` |

构建本地目录 `npx -y @cyanheads/gutenberg-mcp-server mirror init` 检查一下 `mirror verify`· ; `mirror refresh` 档案重建后重新收割。 每个都从任何目录和打印中运行在节点或 Bun 下 `mirror path: <absolute path>` 先说 从一个源检出, `bun run mirror:init`, (中文(简体) ), `mirror:verify`,以及 `mirror:refresh` 运行已建 `dist/` (建设先行. 服务器在启动时从未收成,并回复了从Gutendex的搜索和从每本书的RDF记录中查看书籍,直到第一次收成完成. 随时更新目录 `mirror refresh` 在主机调度器上,或设置 `GUTENBERG_MIRROR_REFRESH_CRON`。 。 。 .

现有 `./.mirror/gutenberg-catalog.sqlite` 仅在 `GUTENBERG_MIRROR_PATH` 点它。 空白或未替换 `${…}` 中任何一个变量的值为未设置.

* * *

## 运行服务器

### 地方发展

要求数 [Bun v 1.4.4 (单位:千美元)](https://bun.sh/) 或更高(或Node.js v24+).

-   **克隆并安装 :**
    
    ```sh
    git clone https://github.com/cyanheads/gutenberg-mcp-server.git
    cd gutenberg-mcp-server && bun install
    cp .env.example .env   # optional overrides
    ```
    
-   **构建和运行 :**
    
    ```sh
    # One-time build
    bun run rebuild
    
    # Run the built server
    bun run start:stdio
    # or
    bun run start:http
    ```
    
-   **运行检查和测试 :**
    
    ```sh
    bun run devcheck   # Lint, format, typecheck, security
    bun run test       # Vitest test suite
    bun run lint:mcp   # Validate MCP definitions against spec
    ```
    

### 夹克

```sh
docker run --rm -p 3010:3010 ghcr.io/cyanheads/gutenberg-mcp-server:latest
```

图像默认为 HTTP 传输、 无国籍会话模式和日志到 `/var/log/gutenberg-mcp-server`运行到一个 MCP 客户端的 stdio,使用 `"command": "docker"` 与 `"args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/gutenberg-mcp-server:latest"]`为了在当地建设, `docker build -t gutenberg-mcp-server .`; OpenTeleometry 端点依赖性默认安装——用 `--build-arg OTEL_ENABLED=false` 以略去它们.

* * *

## 项目结构

| 目录 | 目的 |
| :-- | :-- |
| `src/index.ts` | `createApp()` 进入点——登记工具及其服务. |
| `src/config/server-config.ts` | 服务器特定环境变量剖析(Gutendex和内容-迷信URL,目录镜像路径和刷新时间表). |
| `src/mcp-server/tools/definitions/` | 工具定义`*.tool.ts`) (中文(简体) ). |
| `src/services/gutendex/` | Catalog service——镜像读取,活出Gutendex搜索和浏览,每本作的RDF取景. |
| `src/services/catalog-mirror/` | 本地 SQLite+FTS5 目录镜像 – RDF 摄取,读取帮助器,以及 `mirror` CLI(英语:CLI). |
| `src/services/gutenberg-text/` | 完全的纯文字取回,锅炉板剥取,租户入洞,并分解. |
| `skills/gutenberg-guide/` | 出版的读取和发现工作流程的代理技能,也服务于MCP. |
| `tests/` | 单位和综合测试镜像 `src/`。 。 。 . |

* * *

## 发展指南

见 [`CLAUDE.md`](https://npmcn.com/package/%40cyanheads/gutenberg-mcp-server/CLAUDE.md) 编号 : [`AGENTS.md`](https://npmcn.com/package/%40cyanheads/gutenberg-mcp-server/AGENTS.md) 发展准则和建筑规则。 简本:

-   搬运工投掷,框架渔获量——否 `try/catch` 在工具逻辑中
-   使用 `ctx.log` 请求范围伐木, `ctx.state` 租户范围储存
-   通过输入数组在 `src/index.ts`
-   环绕外部 API 调用: 验证 生 → 规范到域类型 → 返回输出计划; 永远不要编织缺失的字段

* * *

## 捐款

问题值得欢迎。 提交前进行检查和测试:

```sh
bun run devcheck
bun run test
```

* * *

## 数据属性

数据来自 [古腾堡项目](https://www.gutenberg.org/) 属于公有领域。 Catalog元数据来自Gutenberg项目RDF目录,为了进行现场搜索, [古滕德克斯语Name](https://gutendex.com/) (麻省理工学院执照).

* * *

## 许可证

阿帕奇-2.0 — 见 [自由主义](https://npmcn.com/package/%40cyanheads/gutenberg-mcp-server/LICENSE) 详细情况.

## 常见问题

### @cyanheads/gutenberg-mcp-server 是什么？

搜索、浏览和阅读Gutenberg项目78,000\+公共域名书籍,通过MCP进行全文检索并抵消/限制块。 \(原始内容存档于2012-10-12\)\. STIO or Streamable HTTP\.

### 如何安装 @cyanheads/gutenberg-mcp-server？

在项目目录运行 npm install @cyanheads/gutenberg-mcp-server，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 gutenberg-mcp-server，可以用 npx gutenberg-mcp-server 直接运行。

### @cyanheads/gutenberg-mcp-server 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cyanheads/gutenberg-mcp-server 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cyanheads/gutenberg-mcp-server 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cyanheads/gutenberg-mcp-server 可以商用吗？

@cyanheads/gutenberg-mcp-server 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cyanheads/gutenberg-mcp-server 的下载量有多少？

根据 npm 官方下载统计，@cyanheads/gutenberg-mcp-server 在 2026/10/11 – 2026/11/09 这 30 天内被下载 1,973 次，日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cyanheads/gutenberg-mcp-server 还在维护吗？

最新版本 0\.3\.3 发布于 2026/11/12（4 天前）；至今共发布 16 个版本，其中过去 12 个月发布了 16 个；首次发布于 2026/06/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

