Skip to main content
Glama
ComicK MCP Server

ComicK MCP Server

by edmer664
README.md
# ComicK MCP Server (`comick-mcp`)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-0D0D0D.svg)](pyproject.toml)
[![MCP Protocol](https://img.shields.io/badge/MCP-stdio-0047DF.svg)](https://modelcontextprotocol.io)

An open-source **Model Context Protocol (MCP)** server connecting any AI coding agent or desktop assistant directly to the **ComicK (`comick.dev`)** manga, manhwa, and manhua database—with natural-language trope parsing, verified tag matching, and multi-mirror failover.

> **Demo Video (60s):** Watch [`demo.mp4`](demo.mp4) (generated programmatically with HyperFrames + Gemini TTS) or explore the composition source in [`video-demo/`](video-demo/).

---

## Fast-Copy Agent Installation

Copy the prompt below and paste it directly into your AI coding agent (**Antigravity**, **Claude Code**, **Cursor**, **Windsurf**, **Cline**, or **Codex**) to clone, install, test, and register `comick-mcp` automatically:

```text
Install and configure the ComicK MCP server (https://github.com/edmer664/comick-mcp) in my environment:

1. Ensure Python >= 3.10 and Git are available. Clone `https://github.com/edmer664/comick-mcp.git` into a clean local directory (such as `~/.local/share/comick-mcp` on macOS/Linux, `%USERPROFILE%\.local\share\comick-mcp` on Windows, or `./comick-mcp` inside the current workspace).
2. Inside the cloned directory, create a Python virtual environment `.venv` and install the package with `<venv-python> -m pip install -e .`.
3. Register the `"comick"` stdio MCP server in my active agent MCP config using the full path to the `.venv` Python interpreter and `server.py`:
   - command: "<absolute path to .venv python executable>"
   - args: ["<absolute path to comick-mcp/server.py>"]
   - env: {"PYTHONIOENCODING": "utf-8", "PYTHONUNBUFFERED": "1"}
   (Targets: Antigravity `~/.gemini/config/mcp_config.json` or workspace `.mcp.json`, Claude Code `.mcp.json` / `claude mcp add`, Cursor `~/.cursor/mcp.json`, Windsurf `~/.codeium/windsurf/mcp_config.json`.)
4. Run `<venv-python> test_mcp.py` inside the `comick-mcp` folder and confirm all checks pass, then report the install path and registered config file.
```

---

## Key Features

- **Natural-Language Discovery**: Ask `"I want a badass MC manhwa with swords and magic"` and `comick-mcp` extracts origin (`kr` -> Manhwa), genres (`action`, `fantasy`, `magic`), and category tropes (`overpowered-protagonist`, `sword-and-sorcery`, `reincarnation`), running multi-pass queries sorted by popularity and relevance.
- **Verified Taxonomy Cache**: Automatically indexes ComicK's genre list and MangaUpdates category tags in a local `taxonomy_cache.json` (7-day TTL) for fuzzy slug matching.
- **Resilient API Routing**: Automatically fails over between `api.comick.dev`, `comick-api-proxy.notaspider.dev/api`, and legacy endpoints if an upstream mirror rate-limits or blocks automated traffic.
- **Zero Auth Required**: Works out of the box with no ComicK API keys.

---

## Available MCP Tools

| Tool | Purpose |
| :--- | :--- |
| `search_comics` | Search using natural-language prompts or explicit filters (`genres`, `tags`, `country`, `status`, `demographic`, `sort`, `min_chapters`, `excluded_genres`, `excluded_tags`). |
| `recommend_comics_by_prompt` | Conversational recommendation engine with multi-pass search, concurrent MangaUpdates category verification, and relevance scoring. |
| `get_comic_details` | Retrieve full series metadata, alt titles, synopsis, genres, MangaUpdates tags, creators, ratings, and recommendations by `slug` or `hid`. |
| `get_comic_chapters` | List translated chapters with language filters and pagination. |
| `get_trending_comics` | Fetch trending, newly followed, or top-followed `manhwa`, `manga`, or `manhua` over `7`, `30`, `90`, or `180` days. |
| `search_genres_and_tags` | Look up exact ComicK genre and tag slugs by keyword. |

---

## Manual Installation

### 1. Clone and install

```bash
git clone https://github.com/edmer664/comick-mcp.git
cd comick-mcp
python -m venv .venv

# Windows (PowerShell):
.venv\Scripts\Activate.ps1
# macOS / Linux:
# source .venv/bin/activate

pip install -e .
```

### 2. Configure your MCP client

Add `"comick"` to `.mcp.json` (project-scoped) or your client's global MCP config (`~/.gemini/config/mcp_config.json`, `~/.cursor/mcp.json`, `~/.claude.json`):

```json
{
  "mcpServers": {
    "comick": {
      "command": "/absolute/path/to/comick-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/comick-mcp/server.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

> On Windows, replace `.venv/bin/python` with `C:\\path\\to\\comick-mcp\\.venv\\Scripts\\python.exe` and use Windows paths in `args`.

---

## Verification

Run the included end-to-end suite to verify natural-language search, API/mirror connectivity, taxonomy lookup, and a live stdio MCP client handshake:

```bash
python test_mcp.py
```

---

## Project Structure

- [`server.py`](server.py) — `MCPServer("comick")` entrypoint registering the 6 stdio MCP tools.
- [`comick_client.py`](comick_client.py) — Resilient ComicK client, taxonomy cache manager, trope parser, and multi-pass relevance scorer.
- [`test_mcp.py`](test_mcp.py) — End-to-end tool & stdio JSON-RPC verification script.
- [`video-demo/`](video-demo/) — HyperFrames + Gemini TTS 60-second demo project and asset generator.
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — Guide for extending trope rules, endpoints, and tests.

## License

Released under the [MIT License](LICENSE).

TDQS

A3.9/5.0

Scored across 6 tools

Disambiguation3/5

search_comics and recommend_comics_by_prompt both accept natural-language input and return ranked comic lists, so an agent must read carefully to pick between 'structured search that parses NL into filters' and 'multi-pass recommendation with explanations'. The remaining tools (details, chapters, trending, genre/tag lookup) are cleanly distinct.

Naming Consistency5/5

All six tools follow a consistent snake_case verb_noun pattern (search_comics, get_comic_details, get_comic_chapters, get_trending_comics, search_genres_and_tags). recommend_comics_by_prompt is longer but still obeys the same verb-first convention.

Tool Count5/5

Six tools is well within the ideal range and each maps to a distinct step in the discovery workflow: find slugs, search, recommend, inspect, list chapters, browse trending. No tool feels redundant padding.

Completeness4/5

The discovery lifecycle is well covered: filter discovery, search, recommendation, details (including similar comics), chapter listing, and trending rankings. Minor gaps remain, such as no pagination cursor exposed on trending and no way to retrieve chapter page content or reader links, but the stated search/discovery purpose is largely satisfied.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues