Skip to content

CLAUDE.md

Latest commit

 

History

History
41 lines (31 loc) · 2.39 KB

CLAUDE.md

File metadata and controls

41 lines (31 loc) · 2.39 KB

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.