AI导哈

EPUB解析服务

一个基于TypeScript的EPUB解析服务，用于提取元数据、目录结构和文本内容，支持AI辅助的高级搜索功能。

  • by kala51773
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 kala51773/epub-parser-mcp

使用说明

EPUB 解析器 MCP 服务器 📚

一个基于TypeScript的强大模型上下文协议（MCP）服务器，用于解析EPUB文件并借助人工智能提取内容。该服务器旨在与Claude Desktop等人工智能助手实现无缝集成。

✨ 特点

  • 📄（文件或纸张的符号，无具体文字含义，可理解为“文件”或“纸张”） 元数据提取 - 提取EPUB元数据（标题、作者、出版商、语言等）
  • 📑 表示“文件夹”或“文件”的图标。 目录 - 解析层次化的目录结构表
  • 📖 书籍 文本内容提取 - 从带格式的章节中提取干净文本
  • 🔍 看起来像是一个放大镜的符号，通常用于表示搜索、查看细节或观察。在中文中，这个符号本身没有直接的翻译，但可以根据上下文理解为“放大镜”、“搜索”或“查看细节”等意思。例如：“🔍 我们需要使用放大镜来仔细观察这个细节。” 高级搜索 - 在EPUB文件中搜索文本，并可选择区分大小写
  • 🌐（表示“互联网”或“全球连接”的符号） 资源访问 - 通过URI模板访问EPUB资源
  • 🚀 这个符号本身在中文中没有直接对应的翻译，它通常被用作表示火箭、快速移动或高科技等意象的图形符号。在中文语境下，我们可以简单地将其描述为“火箭”或“飞速前进”的象征，但具体翻译时往往保留原符号以传达其视觉和文化含义。因此，这个符号在中文中可以解释为“🚀（火箭/飞速前进）”。 TypeScript - 使用TypeScript构建，以确保类型安全并提供更好的开发体验
  • ⚡（闪电符号，常用于表示速度、活力或电力） 高性能 - 优化了EPUB解析算法
  • 🔧 修理工具或扳手的符号（无实际翻译意义，仅为符号表示） MCP标准 - 完全符合模型上下文协议标准

🚀 快速入门

先决条件

  • Node.js 18 或更高版本
  • npm 或 yarn

安装

方法1：从源码安装

# Clone the repository
git clone https://github.com/your-username/epub-parser-mcp.git
cd epub-parser-mcp

# Install dependencies
npm install

# Build the project
npm run build

方法2: 使用npx（推荐用于生产环境）

# 直接使用npx运行，无需安装
npx epub-parser-mcp

方法3：全局安装

# 全局安装
npm install -g epub-parser-mcp

# 然后直接运行
epub-parser-mcp

🔧 MCP 配置

服务器配置 (Server Config)

以下是完整的MCP服务配置，可用于Claude Desktop或其他MCP客户端：

{
  "mcpServers": {
    "epub-parser": {
      "command": "npx",
      "args": ["-y", "epub-parser-mcp"]
    }
  }
}

环境变量配置 (Environment Variables):

{
  "env": {
    "NODE_ENV": "production"
  }
}

Claude 桌面配置

在您的Claude桌面配置文件中添加以下内容：

使用npx（推荐）:

{
  "mcpServers": {
    "epub-parser": {
      "command": "npx",
      "args": ["-y", "epub-parser-mcp"]
    }
  }
}

备选方案：使用node直接运行（如果npx不支持）：

{
  "mcpServers": {
    "epub-parser": {
      "command": "node",
      "args": ["/path/to/epub-parser-mcp/build/index.js"]
    }
  }
}

注意： Claude Desktop目前支持以 python -m、uv、uvx 或者 npx 开头的命令。在某些环境中，node 命令可能不被支持。

配置文件位置

  • Windows： %APPDATA%\Claude\claude_desktop_config.json
  • macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux（发音类似“林克斯”）： ~/.config/Claude/claude_desktop_config.json

配置步骤

  1. 构建项目 （如尚未构建）：

    npm run build

  2. 找到您的Claude桌面配置文件 （见上文地点）

  3. 添加MCP服务器配置 到……的 mcpServers 部分；章节

  4. 重启Claude桌面版 加载新配置

  5. 验证服务器是否正在运行 通过检查Claude桌面日志

配置验证

配置完成后，您可以通过以下方式验证服务器是否正常工作：

  1. 检查Claude Desktop日志 对于任何与MCP相关的错误
  2. 测试工具 通过请求克劳德使用EPUB解析工具
  3. 验证服务器启动 - 当Claude Desktop启动时，服务器应自动启动

故障排除

常见问题：

  1. 路径问题确保路径到 build/index.js 是正确且可访问的
  2. Node.js 版本确保已安装 Node.js 18+ 且已将其添加到系统路径 (PATH) 中
  3. 权限确保构建文件具有适当的执行权限
  4. 依赖项跑 npm install 如果缺少依赖项

错误信息：

  • “命令未找到”：请检查 Node.js 的安装和 PATH 设置
  • “文件未找到”：请验证构建/index.js的路径
  • “权限被拒绝”：检查构建目录的文件权限

高级配置

为了开发，您可以手动运行服务器：

# Build and start the server
npm run build
npm start

# Or run directly
node build/index.js

服务器将把连接信息和任何错误输出到控制台。

📖 使用示例

获取EPUB信息

{
  "filePath": "/path/to/book.epub"
}

提取目录

{
  "filePath": "/path/to/book.epub"
}

提取文本内容

{
  "filePath": "/path/to/book.epub",
  "chapterIds": ["chapter-1", "chapter-2"],
  "maxLength": 5000
}

在EPUB中搜索

{
  "filePath": "/path/to/book.epub",
  "query": "artificial intelligence",
  "caseSensitive": false
}

🔧 可用工具

1. epub_info

获取完整的EPUB文件信息，包括元数据和结构。

参数：

  • filePath （字符串）：EPUB 文件的路径

2. epub_toc

解析并显示目录结构表。

参数：

  • filePath (字符串)：EPUB 文件的路径

3. epub_extract_text

从指定章节中提取文本内容。

参数：

  • filePath (字符串)：EPUB 文件的路径
  • chapterIds （数组，可选）：要提取的章节ID列表
  • maxLength （数字，可选）：最大文本长度限制

4. epub_search

在EPUB文件中搜索文本。

参数：

  • filePath (字符串)：EPUB 文件的路径
  • query (字符串)：搜索查询
  • caseSensitive （布尔值，可选）：区分大小写的搜索（默认：false）

🌐 资源模板

通过URI访问EPUB资源：

  • epub://{file}/metadata - 以JSON格式表示的EPUB元数据
  • epub://{file}/toc - 目录结构
  • epub://{file}/chapter/{id} - 具体章节内容

🛠️ 开发

项目结构

epub-parser-mcp/
├── src/
│   ├── index.ts          # MCP server implementation
│   ├── epub-parser.ts    # EPUB parsing core
│   └── types.ts          # TypeScript type definitions
├── build/                # Compiled JavaScript
├── package.json
└── README.md

从源代码构建

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

测试

# Run tests (if available)
npm test

📊 性能

  • 快速解析优化了EPUB容器和内容解析
  • 内存高效针对大型EPUB文件的流式处理
  • 并发安全支持多个并发请求

🤝 贡献（或：参与贡献）

我们欢迎贡献！请随时提交问题、功能请求或拉取请求。

开发环境设置

  1. 为仓库创建分支
  2. 创建一个特性分支： git checkout -b feature/amazing-feature
  3. 提交您的更改： git commit -m 'Add amazing feature'
  4. 推送至分支： git push origin feature/amazing-feature
  5. 打开一个拉取请求

代码风格

  • 使用 TypeScript 确保类型安全
  • 遵循现有的代码格式
  • 添加适当的注释和文档说明

📄 许可证

这个项目遵循GPL许可证 - 详见 许可证 详情见文件。

🙏 致谢

赋予AI助手阅读和理解EPUB文档的能力

相关 MCP