noval-ranks

This MCP server exposes a tool for retrieving and decoding the番茄小说榜单 data. It uses a dedicated API client within the mcp.api.client module to fetch book lists, then processes dynamic pages to map encrypted fonts via OCR and decode the content for readable output. The server is designed to be invoked from an MCP client and supports parameters to control the API query such as page size, gender, category, status and sort order. To use it, you first ensure MCP (uvx) is installed, then call the novel-ranks tool through the MCP client, passing a JSON payload with the desired options. For example, you can fetch female-oriented, latest content or adjust the per-page count and the page index. The tool also includes an OCR-based font mapping workflow and an optional OCR review page for manual verification.

Prerequisites:

• Python 3.7 or higher
• Git (optional, for cloning)
• uvx (MCP toolchain) installed in your environment

Installation steps:

1. Clone or download the repository:

git clone https://github.com/your-org/noval-ranks-mcp-server.git
cd noval-ranks-mcp-server

2. Create and activate a Python virtual environment (recommended):

python -m venv venv
# Windows
venv\Scripts\activate.bat
# macOS/Linux
source venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

4. Ensure Chrome and ChromeDriver are installed if you plan to use dynamic page scraping (as described in the README). Add ChromeDriver to your PATH if necessary.

5. Run the MCP server entry once configured (see mcp_config). You can also install uvx tooling if required by your environment.

6. Optional: adjust the working directory in mcp_config to point to your local project root where the mcp.api.client module resides.

Tips and notes:

• The MCP integration relies on the mcp.api.client module's get_book_list() to fetch data. You can provide parameters like page_count, page_index, gender, category_id, creation_status, word_count, book_type, and sort to tailor API requests.
• If OCR mapping or font decoding encounters issues, use the --force-ocr-mapping flag to regenerate mappings and consider using --review-html to open the OCR verification UI for manual corrections.
• Ensure the cache/mappings and output directories exist or are writable to avoid runtime errors.
• The environment variable guidance suggests keeping PYTHONPATH clean; the recommended approach is to specify cwd in the MCP configuration to the project root.
• When using MCP from a client, avoid mismatches between gender and category_id by consulting category_list.json to ensure valid combinations.