git:20260128.0c96833 to git:20260628.009ad5a

- # 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.

-