@cyanheads/gutenberg-mcp-服务器
搜索、浏览和阅读Gutenberg项目78,000+公共域名书籍,通过MCP进行全文检索并抵消/限制块。 (原始内容存档于2012-10-12). STIO or Streamable HTTP.
概览
古腾堡项目图书馆藏书7.8万多册. 按标题、作者、主题或语言搜索,获取完整的书本元数据,并读取支持的 UTF-8 纯文本和 HTML 版本的可管理块.
工具
| 工具 | 说明 |
|---|---|
gutenberg_search_books | 按标题、作者、话题、翻译、语言或作者寿命搜索目录,并进行页标和受欢迎度排序 |
gutenberg_get_book | 由 ID 获取一本书的完整元数据——作者、翻译、编辑、完整格式地图、主题、版权状况 |
gutenberg_get_text | 取出一本书的纯文本内容,取出牌照锅炉板,并有抵消/限制块或一个 find 跳转到一段 |
gutenberg_browse_popular | 浏览最下行的书,可选择按语言或主题过滤 |
发表 gunenberg 向导 技能包括决定是否可读出一本书,在将一本书调出之前排除搜索盲点,寻找打开处和章节过去前题,呼出长文本,以及排名版本。 插件安装包括它;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块( 默认)limit2万元,封顶为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: stdio和可流式的 HTTP 传输器,可插接式(none 编号 : jwt 编号 : oauth),可互换存储(in-memory, (中文(简体) ), filesystem, (中文(简体) ), Supabase, (中文(简体) ), Cloudflare KV/R2/D1),结构化记录,可选择的OpenTeleometry tracking.
古腾堡特有:
- 搜索和浏览读取了本地SQLite+FTS5目录镜像. 当镜子冷的时候,搜索会回到 古滕德克斯语Name; 镜像所缺少的一本书从内容镜上的 RDF 记录读取
- 从 Gutenberg 工程内容镜像中获取完整纯文本, 并带有 UTF-8/ HTML 倒置
- 每个租户会缓存书本, 所以以后的块会读取跳过抓取
- 不需要 API 密钥
方便代理输出 :
is_readable旗帜 带有 UTF-8 纯文本的文本记录, 或者没有音频格式的 HTML; 缺少的镜像文件仍然返回text_file_not_foundoffset, (中文(简体) ),length, (中文(简体) ),totalChars, (中文(简体) ),remainingChars,以及hasMore支持可靠顺序读取provenance财务报告和审定财务报表sourceFormat每一文本答复都涉及归属和忠诚
开始
连接到主机实例, 没有安装 :
claude mcp add --transport http gutenberg-mcp-server https://gutenberg.caseyjhand.com/mcp
或者在当地运行它:
claude mcp add gutenberg-mcp-server -- npx -y @cyanheads/gutenberg-mcp-server
对于其他客户端,请将此添加到 MCP 配置文件中 :
{
"mcpServers": {
"gutenberg-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/gutenberg-mcp-server"]
}
}
}
不需要 API 密钥 。 对于 Docker 或源构建,请参见 运行服务器。 。 。 .
配置
| 变量 | 说明 | 默认 |
|---|---|---|
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 仪器。 。 。 . | 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 (单位:千美元) 或更高(或Node.js v24+).
-
克隆并安装 :
git clone https://github.com/cyanheads/gutenberg-mcp-server.git cd gutenberg-mcp-server && bun install cp .env.example .env # optional overrides -
构建和运行 :
# One-time build bun run rebuild # Run the built server bun run start:stdio # or bun run start:http -
运行检查和测试 :
bun run devcheck # Lint, format, typecheck, security bun run test # Vitest test suite bun run lint:mcp # Validate MCP definitions against spec
夹克
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 编号 : AGENTS.md 发展准则和建筑规则。 简本:
- 搬运工投掷,框架渔获量——否
try/catch在工具逻辑中 - 使用
ctx.log请求范围伐木,ctx.state租户范围储存 - 通过输入数组在
src/index.ts - 环绕外部 API 调用: 验证 生 → 规范到域类型 → 返回输出计划; 永远不要编织缺失的字段
捐款
问题值得欢迎。 提交前进行检查和测试:
bun run devcheck
bun run test
数据属性
数据来自 古腾堡项目 属于公有领域。 Catalog元数据来自Gutenberg项目RDF目录,为了进行现场搜索, 古滕德克斯语Name (麻省理工学院执照).
许可证
阿帕奇-2.0 — 见 自由主义 详细情况.