jmcomic-ai 0.0.1

AI-powered JMComic crawler with MCP server and skills management for seamless AI agent integration

# 🚀 JMComic AI

都什么时代了还在用传统方式看本？

从人机交互 到 人智交互，把你的一切本子需求都扔给 AI！

🛠️ 开发者注意：如果你想为项目贡献代码，请务必查看 贡献指南，其中包含了开发环境搭建、项目结构说明以及 reference 参考源码库的使用方法。

---

📖 项目简介

JMComic AI 是为 JMComic-Crawler-Python 提供的 MCP (Model Context Protocol) 支持 和 AI Skills 增强。

传统的爬虫工具虽然高效，但在处理模糊需求时往往力不从心。你必须记住精确的 ID 或关键字，还要手动配置各种参数。

本项目通过两个维度解决这个问题：

1. MCP 工具集成 - 将 jmcomic 的核心功能（搜索、下载、排行榜等）封装为标准 MCP 工具，让本地 AI 智能体/编辑器（如 Cursor, Antigravity, Windsurf, Zed, Claude Desktop 等）可以直接调用
2. Skills 知识注入 - 提供精心编写的使用指南和最佳实践，让 AI 理解如何正确使用这些工具

现在，你可以像与人交谈一样，通过自然语言来搜索、筛选并下载漫画，而无需编写任何代码。

📸 使用样例 (Usage Samples)

1. 工具列表加载	2. 智能搜索	3. 获取详情

---

核心能力 / 你能用它做什么

不仅仅是下载，JMComic AI 能够理解复杂的上下文指令：

• 智能搜索与下载

  🤔 "帮我搜索作者 [XXX] 的作品，按浏览量排序，下载前 5 个最热门的本子。"

  🤖 Agent: 自动调用 search_album 获取列表，按 views 排序截取前 5，并发调用 download_album。

  🤔 "下载速度太慢了，帮我把图片并发数改为 50。"

  🤖 Agent: 理解意图，调用 update_option 修改 download.threading.image: 50 并实时生效。

• 模糊决策

  🤔 "我想找一些画风类似 [某作品] 的短篇故事，不要超过 3 章的。"

  🤖 Agent: 结合语义检索与元数据过滤，为你推荐并整理符合口味的阅读清单。

✨ 功能特性

• 🔌 MCP 标准集成 - 基于 FastMCP 构建，支持 stdio、SSE、HTTP 多种传输方式，兼容大部分现代本地 AI 客户端（如 Cursor, Antigravity, Windsurf, Zed, Claude Desktop 等）
• 🛠️ 全功能工具集 - 暴露 search、download、ranking、update_option 等核心能力，让 AI 能够直接操作 jmcomic
• 📚 知识资源 (Resources) - 提供配置 Schema、参考文档和 Skills 手册，让 AI 理解如何正确使用工具
• ⚙️ 自然语言配置 - AI 可理解并动态修改 option.yml 配置（如切换线路、调整下载规则）
• 🎯 统一 CLI - 提供 jmai / jmcomic-ai 命令行工具，统一管理 MCP 服务启动、配置查阅与 Skills 安装
• 🔮 未来规划 - 计划集成 OCR (MangaOCR)、神经机器翻译 (NMT) 与向量检索 (RAG)，实现基于画面的语义搜索

🏗️ 架构概览

graph TD
    User[User / AI Agent] <-->|MCP Protocol| Server[JMAI MCP Server]
    Server <-->|Call| Core[Core Service Layer]
    Core <-->|Invoke| Lib[JMComic Crawler Lib]
    Server <-->|Load| Skills[Agent Skills (Instructional Knowledge)]
    Core -->|Read/Write| Config[Option System]

📦 安装 (Installation)

1、从pypi安装（推荐）

# 使用 uv (推荐)
uv add jmcomic-ai
# 或者
uv tool install jmcomic-ai

# 使用 pip
pip install jmcomic-ai

2、从源码安装

推荐使用 uv 进行依赖管理，一步到位。

# 克隆项目
git clone https://github.com/hect0x7/JMComic-ai.git
cd JMComic-ai

# 同步依赖环境
uv sync

🚀 使用指南 (Usage)

JMComic AI 提供了两个维度的能力，你可以根据需求，选择以下一者或两者来增强你的 AI：

🔌 模块 A：接入 MCP 工具 (推荐)

功能：为 AI 安装“手脚”，使其能够直接调用 search, download 等核心功能。 适用场景：你希望在 AI 客户端（如 Cursor, Antigravity, Claude 等）中直接下载漫画，无需打开终端。

配置方法:

不同的本地 AI 客户端配置方式略有不同。MCP 支持两种连接模式：推荐使用 SSE/HTTP 模式以获得最佳性能，或使用传统的 stdio 模式。

1. 启动服务端 (SSE/HTTP 模式 - 推荐)

在终端运行以下命令开启服务：

jmai mcp          # 默认开启 SSE 服务，端口 8000

2. 在客户端中配置

在你的 AI 客户端（如 Cursor 设置、Windsurf 配置或 Claude 配置文件）中添加以下内容：

• 以 URL 方式连接 (推荐):

  "jmcomic-ai": {
    "url": "http://127.0.0.1:8000/sse"
  }
  

• 以子进程方式连接 (stdio):

  "jmcomic-ai": {
    "command": "jmai",
    "args": ["mcp", "stdio"]
  }
  

💡 常见客户端配置文件路径参考:

• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor / Windsurf: 通常在首选项 (Preferences) -> MCP 设置界面中直接图形化添加。

4. 配置完成后重启你的 AI 客户端，你会在工具栏或界面中看到 🔨 图标，表示 MCP 服务已成功加载。

---

🧠 模块 B：为 Agent 注入“经验” (Skills)

功能：为 AI 注入作者总结的“老司机经验”（如：如何处理 403 错误，如何避免重复下载）。 适用场景：你希望 AI 不仅仅是执行命令，还能像真人一样思考和规划任务（配合模块 A 使用效果最佳）。

配置方法:

1. 在终端运行命令，导出技能手册：

   jmai skills install
   

2. 技能文件将默认安装到 ~/.claude/skills/jmcomic。
3. 使用：将该目录下的 SKILL.md 内容提供给 AI（如复制到其 System Prompt 或 Project Instructions 中），或者在支持 MCP Resource 的客户端中直接查阅 jmcomic://skill。

---

第三步：开始对话 (Start Chatting)

完成以上两步后，AI 就变成了一个专业的漫画策展人。你可以尝试这样跟它交流：

• 模糊搜索：

  “我想看那个...主角是电锯人的漫画，帮我找找。” (AI 会自动搜索 '电锯人'，并展示最相关的结果)

• 批量下载：

  “把搜索结果里浏览量最高的前三个下载下来。” (AI 会分析搜索结果，筛选出 Top 3，并自动调用下载工具)

• 修改配置：

  “下载太慢了，帮我把并发改成 50。” (AI 会调用配置工具，自动帮你修改 option.yml)

---

🔧 常用命令参考

• MCP 服务管理:

  jmai mcp              # 启动 SSE 服务 (推荐方式，默认端口 8000)
  jmai mcp http         # 启动 Streamable HTTP 服务 (专家推荐，支持生产部署)
  jmai mcp stdio        # 启动 stdio 服务 (传统的子进程/管道模式)
  

• Skills 管理:

  jmai skills install   # 安装 Skills 到默认目录 (~/.claude/skills/jmcomic)
  

• 配置文件管理:

  jmai option show      # 查看当前配置内容
  jmai option path      # 查看配置文件路径
  jmai option edit      # 调用编辑器修改配置
  

• 查看帮助:

  jmai --help           # 查看所有命令
  jmai mcp --help       # 查看 MCP 命令帮助
  

📚 文档资源

• JMComic-Crawler-Python - 核心依赖库文档。

---

⚠️ 免责声明 (Disclaimer)

本项目主要由 Antigravity 驱动编写。由于 AI 生成代码的特性，虽然经过了初步验证，但仍可能存在潜在的 Bug 或不符合预期的情况。

如果你在使用过程中遇到任何问题，或者有更好的改进建议，欢迎提交 Issue 或 Pull Request 来支持本项目。让我们一起打造更智能的本子阅读体验！🚀

Build with ❤️ by hect0x7