v0.0.8: Documentation improvements (Claude Code/README); Fix mypy type errors; MCP Server config refactor (#7)

Author: hect0x7

.github/CONTRIBUTING.md

@@ -148,16 +148,35 @@ jmai mcp --help
 2. **实时日志与热重载**：
     - 使用 `tail -f` 观察项目根目录下的 `jmcomic_ai.log` 日志。
     - **热重载调试**：使用 `jmai mcp --reload` 启动服务。在该模式下，你对 `src/` 目录下代码的任何修改都会触发服务器自动重启，无需反复手动开关服务。
-3. **本地 AI 智能体/编辑器调试**：在你的客户端（如 Cursor, Antigravity, Windsurf, VS Code, Claude Desktop 等）中添加本地开发配置。
-   以 Claude Desktop 为例，在 `claude_desktop_config.json` 中配置：
+3. **本地 AI 智能体/编辑器调试**：在你的客户端（如 Claude Code, Cursor, Antigravity 等）中添加本地开发配置。
+   
+   以 **Claude Code** 为例（最推荐的调试方式），在 `~/.claude.json` (User) 或项目根目录 `.mcp.json` (Project) 中配置：
    ```json
-   "mcpServers": {
-     "jmcomic-ai-dev": {
-       "command": "uv",
-       "args": ["--directory", "D:/你的路径/jmcomic-ai", "run", "jmai", "mcp"]
+   {
+     "mcpServers": {
+       "jmcomic-ai-dev": {
+         "command": "uv",
+         "args": [
+           "--directory",
+           "/path/to/your/jmcomic-ai",
+           "run",
+           "jmai",
+           "mcp",
+           "stdio" 
+         ]
+       }
      }
    }
    ```
+   **验证方式**：修改代码后，在终端运行以下命令检查连接状态：
+   ```bash
+   claude mcp list
+   ```
+
+   **其他客户端 (Cursor/Windsurf)**：
+   推荐使用 SSE 模式进行热重载调试：
+   1. 在终端运行：`uv run jmai mcp sse --reload`
+   2. 在编辑器中配置 Server URL：`http://127.0.0.1:8000/sse`
    如果是 Cursor 或其他支持 MCP 的编辑器，通常在设置界面添加类似的 `command` 和 `args` 即可。
 
 ## 提交 Issue

.github/workflows/mypy.yml

@@ -0,0 +1,36 @@
+name: Run Mypy Checks
+
+on:
+  workflow_dispatch:
+  push:
+    branches: ["dev"]
+    paths:
+      - 'src/**/*.py'
+      - '.github/workflows/mypy.yml'
+      - 'pyproject.toml'
+
+jobs:
+  mypy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          uv sync
+
+      - name: Run mypy
+        run: uv run mypy src/

.gitignore

@@ -87,4 +87,5 @@ reference/jmcomic_src/
 outputs/**/*.png
 assets/downloads/**/*.png
 [0-9]*/
-temp_test_skills/
+temp_test_skills/
+.claude

CHANGELOG.md

@@ -5,7 +5,21 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
-## [0.0.6] - 2026-01-19
+## [0.0.8] - 2026-01-28
+
+### Documentation
+- 📚 **MCP 配置指南重构**：重写 README 和 CONTRIBUTING 文档，新增 **Claude Code** 作为首选调试工具，并完善了 Antigravity、Cursor 和 Claude Desktop 的配置参考。
+- 📖 **配置示例细化**：拆分 MCP 配置为 stdio (默认)、SSE (Cursor 推荐) 和 HTTP (远程) 三种流式模式，提供了更直观的 JSON 片段。
+
+### Fix
+- 🛡️ **类型安全增强**：修复了 `src/` 下所有的 MyPy 类型检查错误，增强了 `fastmcp` 上下文调用和 lambda 表达式的健壮性。
+- 🐛 **导入修复**：修正了 `core.py` 中 `Context` 重复导入和 `server.py` 中 `Transport` 类型断言的问题。
+
+### Changed
+- ♻️ **脚本适配**：`ranking_tracker.py`、`search_export.py` 等技能脚本现在统一使用新的 `browse_albums` API，逻辑更收敛。
+- ⚙️ **开发工作流**：新增 `.github/workflows/mypy.yml`，在 CI 中强制进行严格的静态类型检查。
+
+## [0.0.7] - 2026-01-19
 
 ### Changed
 - 🔄 **工具输出结构化**：`download_album` 与 `post_process` 现在返回结构化的字典（包含 `status`, `download_path` 等字段）而非纯文本，以提升 AI 代理的自动化处理与验证能力。

CLAUDE.md

@@ -0,0 +1,41 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 🛠 Common Commands
+
+This project uses `uv` for dependency and environment management.
+
+### Development & Execution
+- **Run CLI**: `uv run jmai [args]` or `uv run jmcomic-ai [args]`
+- **Start MCP Server (SSE)**: `uv run jmai mcp` (Port 8000 by default)
+- **Start MCP Server (stdio)**: `uv run jmai mcp stdio`
+- **Start MCP with Hot Reload**: `uv run jmai mcp --reload`
+- **Install AI Skills**: `uv run jmai skills install` (Exports to `~/.claude/skills/jmcomic`)
+- **Manage Options**: `uv run jmai option show|path|edit`
+
+### Build & Quality Control
+- **Build Package**: `uv build`
+- **Linting**: `uv run ruff check src/`
+- **Type Checking**: `uv run mypy src/`
+- **Run All Tests**: `uv run python -m unittest discover tests`
+- **Run Integration Test**: `uv run python tests/test_mcp_integration.py`
+
+## 🏗 High-Level Architecture
+
+JMComic AI is an intermediary layer that exposes the `jmcomic` crawler's capabilities to AI agents via the Model Context Protocol (MCP).
+
+### Core Components
+- **Transport Layer (`src/jmcomic_ai/mcp/`)**: Built using `FastMCP`. Handles communication between AI clients (Cursor, Claude, etc.) and the server via SSE/HTTP or stdio.
+- **Service Layer (`src/jmcomic_ai/cli.py` & others)**: Connects MCP tools to the underlying crawler logic and manages the CLI application.
+- **Knowledge Layer (`src/jmcomic_ai/skills/`)**: Contains `SKILL.md` and related logic to inject domain-specific expertise into AI agents.
+- **Configuration System**: Manages `option.yml` which controls proxies, download paths, threading, and crawler behavior.
+
+### Critical Reference
+- **`reference/`**: This directory contains a local copy of the upstream `jmcomic` source code. Because the upstream library is complex and frequently updated, developers should consult this directory to understand the implementation of core entities (like `JmAlbumDetail`) before modifying MCP tools.
+
+## 📝 Coding Guidelines
+- **Type Safety**: Use static type hints and verify with `mypy`.
+- **Linting**: Follow the rules defined in `pyproject.toml` (120 character line length).
+- **Tool Definitions**: When adding or modifying MCP tools in `src/jmcomic_ai/mcp/`, ensure clear docstrings as they are directly consumed by AI agents.
+- **Environment**: Prefer `uv run` for executing commands to ensure consistent environment usage.

README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <h1>🚀 JMComic AI</h1>
+  <img src="images/header.png" alt="JMComic AI" width="200" />
 
   <p><i>都什么时代了还在用传统方式看本？</i></p>
   <p><i>从<code>人机交互</code> 到 <code>人智交互</code>，<b>把你的一切本子需求都扔给 AI</b>！</i></p>
@@ -118,50 +118,109 @@ JMComic AI 提供了两个维度的能力，你可以根据需求，选择以下
 ### 🔌 模块 A：接入 MCP 工具 (推荐)
 
 **功能**：为 AI 安装“手脚”，使其能够直接调用 `search`, `download` 等核心功能。
-**适用场景**：你希望在 AI 客户端（如 Cursor, Antigravity, Claude 等）中直接下载漫画，无需打开终端。
+**适用场景**：你希望在 AI 客户端中直接下漫画，无需打开终端。
 
-**配置方法:**
+#### 📂 客户端配置文件位置指南
+在开始配置前，请先找到你的 AI 客户端使用的配置文件。
 
-不同的本地 AI 客户端配置方式略有不同。MCP 支持两种连接模式：**推荐使用 SSE/HTTP 模式**以获得最佳性能，或使用传统的 **stdio 模式**。
+| 软件 (Software) | 配置文件路径 (Config File Path) |
+| :--- | :--- |
+| **Antigravity** | **Windows**: `%USERPROFILE%/.gemini/antigravity/mcp_config.json`<br>**macOS**: `~/Library/Application Support/Gemini/antigravity/mcp_config.json` |
+| **Cursor** | **Global**: `%USERPROFILE%/.cursor/mcp.json` (Win) / `~/.cursor/mcp.json` (Mac/Linux)<br>**Project**: 项目根目录下的 `.cursor/mcp.json` |
+| **Claude Code** | **User-Scoped**: `%USERPROFILE%/.claude.json` (Win) / `~/.claude.json` (Mac/Linux)<br>**Project-Scoped**: 项目根目录下的 `.mcp.json` |
+| **Claude Desktop** | **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`<br>**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` |
 
-#### 1. 启动服务端 (SSE/HTTP 模式 - 推荐)
-在终端运行以下命令开启服务：
-```bash
-jmai mcp          # 默认开启 SSE 服务，端口 8000
-jmai mcp --reload # 开启热重载模式（推荐开发/调试使用）
-```
+---
+
+根据你的需求，选择以下其中一种传输协议（Transport）进行配置：
 
-#### 2. 在客户端中配置
-在你的 AI 客户端（如 Cursor 设置、Windsurf 配置或 Claude 配置文件）中添加以下内容：
+#### 1. stdio 模式 (最简单)
+最简单的配置方式，AI 客户端会自动在后台启动并管理 `jmai` 进程。
 
-- **以 URL 方式连接 (推荐)**:
-  ```json
-  "jmcomic-ai": {
-    "url": "http://127.0.0.1:8000/sse"
+- **配置内容**:
+```json
+{
+  "mcpServers": {
+    "jmcomic-ai": {
+      "command": "jmai",
+      "args": ["mcp", "stdio"]
+    }
   }
-  ```
-- **以子进程方式连接 (stdio)**:
-  ```json
-  "jmcomic-ai": {
-    "command": "jmai",
-    "args": ["mcp", "stdio"]
+}
+```
+
+- 如果你是clone了源码，希望用本地源码安装，可以这样配置：
+```json
+{
+  "mcpServers": {
+    "jmcomic-ai": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/path/to/your/jmcomic-ai",
+        "run",
+        "jmai",
+        "mcp",
+        "stdio"
+      ]
+    }
   }
+}
+```
+
+> **注意**：请将 `/path/to/your/jmcomic-ai` 替换为您本地源码的实际绝对路径。
+
+#### 2. SSE 模式 (推荐)
+推荐用于大部分桌面端 AI 客户端。
+
+- **第一步：启动服务**
+  ```bash
+  jmai mcp sse  # 默认端口 8000
   ```
+- **第二步：配置客户端**
+```json
+{
+  "mcpServers": {
+    "jmcomic-ai": {
+      "url": "http://127.0.0.1:8000/sse"
+    }
+  }
+}
+```
 
-> 💡 **常见客户端配置文件路径参考**:
-> - **Claude Desktop (Windows)**: `%APPDATA%\Claude\claude_desktop_config.json`
-> - **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-> - **Cursor / Windsurf**: 通常在首选项 (Preferences) -> MCP 设置界面中直接图形化添加。
+#### 3. HTTP 流式模式 (生产/远程)
+适用于远程部署或对性能有更高要求的场景。
 
-4.  配置完成后重启你的 AI 客户端，你会在工具栏或界面中看到 🔨 图标，表示 MCP 服务已成功加载。
+- **第一步：启动服务**
+  ```bash
+  jmai mcp http
+  ```
+- **第二步：配置客户端**
+```json
+{
+  "mcpServers": {
+    "jmcomic-ai": {
+      "url": "http://127.0.0.1:8000/mcp"
+    }
+  }
+}
+```
 
+4.  配置完成后：
+    *   **通用客户端**：重启客户端，检查状态指示灯或工具栏（通常显示为 🔨 图标）。
+    *   **Claude Code**：在终端运行以下命令以验证连接：
+        ```bash
+        claude mcp list
+        ```
+        如果看到 `jmcomic-ai` (connected)，说明配置成功。
 
 ---
 
 ### 🧠 模块 B：为 Agent 注入“经验” (Skills)
 
 
 **功能**：为 AI 注入作者总结的“老司机经验”（如：如何处理 403 错误，如何避免重复下载）。
+
 **适用场景**：你希望 AI 不仅仅是执行命令，还能像真人一样思考和规划任务（*配合模块 A 使用效果最佳*）。
 
 **配置方法:**

images/header.png

@@ -1,6 +1,6 @@
 [project]
 name = "jmcomic-ai"
-version = "0.0.7"
+version = "0.0.8"
 description = "AI-powered JMComic crawler with MCP server and skills management for seamless AI agent integration"
 readme = "README.md"
 license = "MIT"
@@ -24,7 +24,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
-    "jmcomic>=2.6.11",
+    "jmcomic>=2.6.12",
     "mcp",
     "typer",
     "watchdog>=6.0.0",

pyproject.toml

@@ -1 +1 @@
-__version__ = "0.0.7"
+__version__ = "0.0.8"