企业官网建设流程全解析

ReadAny CLI+MCP完全指南：让外部AI安全访问书库，受控工具而非裸数据

【免费下载链接】ReadAnyAI-powered cross-platform e-book reader with semantic search, RAG chat, local vector store, notes, TTS, and WebDAV sync.项目地址: https://gitcode.com/gh_mirrors/re/ReadAny

ReadAny 是一款跨平台 AI 电子书阅读器，而 ReadAny CLI 是它的本地能力网关——通过 MCP（模型上下文协议）把书籍、章节、笔记、高亮和 RAG 检索安全地开放给外部 AI（如 Claude、Cursor、Codex）。它开放的是一个个受控工具，而不是裸数据库、任意文件系统或任意 shell，这正是它与"直接给 AI 一个数据库文件"的本质区别。本指南带你快速完成安装、接入与权限管理。

为什么是"受控工具"而不是"裸数据"？

把数据库直接交给 AI，等于把整座图书馆的门钥匙都给了它：能读、能删、还能顺手把书房的墙拆了。ReadAny 的设计原则只有一句话：开放能力，不开放裸数据库、任意文件系统、任意 shell。

它的完整链路是这样的：

安装 CLI -> 安装 Skill -> 外部 AI 通过 MCP 发现 ReadAny -> 读取书库 / 章节 / 当前上下文 / 笔记 / 高亮 / RAG -> 创建 EPUB draft -> AI 修改章节 / 元数据 / 目录 -> 用户在 draft 工作区继续编辑 -> 查看 history / diff -> validate -> export 新 EPUB -> audit 全程可追踪

每一层都有明确边界，AI 做什么都绕不开这套流程。

快速上手：三步接入外部 AI

第 1 步：安装 CLI 并诊断

最简单的方式是用桌面客户端：打开设置 → 外部 AI 访问，页面可以直接安装、修复 CLI，无需自己拼命令。也可以手动执行：

readany install readany doctor --json

doctor会输出机器可读的诊断信息：Node 运行时、SQLite 原生模块、CLI 分发形态、工具数量、MCP 默认启动参数等。

第 2 步：一条命令完成 Agent 引导

这是给外部 AI 准备的统一 bootstrap 命令，适合直接复制给你的大模型执行：

readany agent setup --user --client all --profile readonly --json

它会按安全顺序：校验 profile/client → 安装或修复readany命令 → 安装$AGENT_HOME/skills/readany/SKILL.md使用手册 → 把 skill 链接到 Codex / Claude / Cursor / OpenCode 的对应目录 → 返回 MCP 配置片段。注意它不会静默修改任何外部客户端的配置，MCP 片段需要由你显式放入。

第 3 步：复制 MCP 配置到 AI 客户端

readany mcp config --profile readonly --client generic --json

核心配置就长这样，可直接粘贴进支持 MCP 的客户端：

{ "mcpServers": { "readany": { "command": "readany", "args": ["mcp", "serve", "--profile", "readonly"] } } }

不同客户端的格式也不同，CLI 都替你生成好了：claude/cursor复用 JSONmcpServers片段，codex输出config.toml的 TOML 片段，opencode输出opencode.json的mcp.readany片段。

权限 Profiles：只读优先，写入必须确认

ReadAny 把权限分成五级，默认永远是readonly。更高权限必须显式选择并确认风险后才可复制配置：

Profile 到具体 scope 的映射在 packages/cli/src/profiles.ts 中定义，每个权限位（如book.read、epub.export）都是独立声明的。

记住设置页强调的三句话：

• 安装 CLI不等于授权外部 AI；
• 安装 Skill不等于开放写权限；
• 开启 MCP readonly 只允许读取和搜索。

受控工具清单：AI 到底能做什么？

MCPtools/list只暴露真实实现、测试通过的工具，按资源域命名，共 26 个，主要分四类：

📖 只读数据：books.list、books.search、books.get、chapters.list、chapters.get、context.get（当前书/章/选区快照）、bookmarks.list、skills.list

🔍 搜索：notes.search、highlights.search、knowledge.search（聚合书籍/笔记/高亮）、rag.search（BM25 / hybrid / vector 三模式，向量未配置时安全回退到 BM25）

✏️ EPUB 精排（editor 权限）：epub.inspect、epub.draft.create、epub.chapter.read/patch、epub.chapters.patch（1-50 章批量计划）、epub.metadata.patch、epub.toc.rebuild、epub.history、epub.diff、epub.undo、epub.draft.discard

📤 导出（publisher 权限）：epub.validate、epub.export、notes.export、knowledge.export

而shell.exec、sql.query、任意文件读写这类危险工具，不设计、不实现。CLI 与 MCP 使用统一的结构化结果（成功/错误码 + 数据），大结果自动分页限流。

安全边界：5 道防线

1. 原书永不修改：所有 EPUB 修改都发生在 draft 工作区，原始文件的 hash 保持不变，导出也只生成新文件，默认不覆盖；
2. draft-first：写入链路必须"先生成计划 → 应用到 draft → 用户确认导出"，用户和 AI 共用同一套 history / diff，AI 的每笔修改都能追溯、可undo；
3. 参数严格校验：每个工具的 inputSchema 都有required和additionalProperties: false，未声明的参数、超范围的值会被运行时直接拒绝；
4. 审计只记元数据：写操作、导出、同步都会记录来源、profile、工具名和摘要，但绝不记录完整正文、API key、同步密码；
5. 工具清单诚实：规划中的工具只写在设计文档，未真实接线前不会出现在tools/list里，避免"让 AI 知道能力存在"式的虚假承诺。

桌面客户端：图形化一站式管理

桌面端的设置 → 外部 AI 访问页面是普通用户的主入口，四块状态卡片一目了然：

• ReadAny CLI：安装 / 卸载 / 修复 / 诊断；
• External AI Skill：安装、更新、卸载到通用 agent 目录；
• MCP Access：按客户端复制配置、测试连接、切换 profile；
• Activity Log：最近的 agent 调用、权限拒绝、导出记录。

页面支持按来源、失败、时间等条件筛选审计记录。注意用户精排入口不在设置页——章节编辑、diff 查看、撤销都在书籍详情页的draft 工作区里完成，设置页只负责接入和权限管理。

关键文件索引

• CLI 设计总览：docs/readany-cli/00-overview-and-acceptance.md
• 命令与工具规范：docs/readany-cli/05-command-and-tool-spec.md
• 架构与安全模型：docs/readany-cli/02-architecture-security.md
• 桌面设置页设计：docs/readany-cli/06-client-settings.md
• CLI 源码：packages/cli/src/，其中 MCP 服务在 packages/cli/src/mcp.ts、工具注册表在 packages/cli/src/tool-registry.ts、权限模型在 packages/cli/src/profiles.ts

常见问题

Q：readonly 模式下 AI 能写吗？不能。任何写入或导出工具在 readonly 下都会收到permission_denied错误码，这也是每个里程碑验收的必查项。

Q：安装 Skill 后会暴露我的同步凭证吗？不会。Skill 只是一个"使用说明"文件，不存数据、不持密钥；输出内容也不包含密钥、同步配置或本地绝对路径。

Q：AI 改坏了书怎么办？它碰不到原书。所有修改都在 draft 里，你可以随时看 diff、undo单步、或整个 discard；导出前还会先 validate，确认结构无误才生成新 EPUB。

Q：手机能用吗？CLI / MCP 的主入口在桌面端。移动端定位为轻量查看，不承担 CLI 安装和 MCP 注册。

写在最后

ReadAny CLI 把"给 AI 开权限"这件事做成了可分级、可审计、可回滚的工程化能力：先 readonly 让 AI 帮你查书答疑，确认靠谱后再按需开启 editor / publisher 精排导出。如果你希望外部 AI 真正"读得懂你的书"又不越界，这套受控工具链值得一试。

【免费下载链接】ReadAnyAI-powered cross-platform e-book reader with semantic search, RAG chat, local vector store, notes, TTS, and WebDAV sync.项目地址: https://gitcode.com/gh_mirrors/re/ReadAny