Metadata-Version: 2.4
Name: dhcckb-ctext-mcp-server
Version: 2.1.0
Summary: MCP Server for querying English translations of Chinese classical texts. v2.1 replaces domestic NMT with DeepSeek LLM (deepseek-chat) for the parallel dual-translation pipeline: ctext.org full-text search → parallel ctext human translation + DeepSeek LLM translation, with LRU memory cache and SQLite persistence.
Project-URL: Homepage, https://pypi.org/project/dhcckb-ctext-mcp-server/
Project-URL: Repository, https://pypi.org/project/dhcckb-ctext-mcp-server/
Author: Digital Humanities Platform
License: MIT
Keywords: chinese-classics,ctext,digital-humanities,mcp,model-context-protocol,translation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: jieba>=0.42.1
Requires-Dist: mcp>=2.0.0
Requires-Dist: rapidfuzz>=3.0.0
Requires-Dist: zhconv>=1.4.3
Provides-Extra: tfidf
Requires-Dist: scikit-learn>=1.3.0; extra == 'tfidf'
Description-Content-Type: text/markdown

# ctext-mcp-server

MCP Server for querying standardized English translations of Chinese classical texts via the [ctext.org](https://ctext.org) translation corpus.

## Features

- **search_passage**: Multi-stage matching (exact → normalized → fuzzy) of Chinese classical text passages to English translations
- **get_translation**: Direct lookup by work ID and chapter reference
- **list_works**: Browse the catalog of available translated works with filtering
- **Fuzzy matching engine**: Normalizes variant characters, punctuation differences, and missing/extra characters using edit distance + TF-IDF hybrid strategy
- **SQLite caching**: Local cache with configurable TTL (default 30 days) to reduce API calls
- **Multi-translator support**: Returns available translators list with default selection
- **Dual transport**: stdio (Claude Desktop / Claude Code) and streamable HTTP modes

## Installation

```bash
pip install ctext-mcp-server
```

## Prerequisites

Set your ctext.org API key as an environment variable:

```bash
export CTEXT_API_KEY="your_api_key_here"
```

Optional configuration:

```bash
# Custom cache directory (default: ~/.cache/ctext-mcp/)
export CTEXT_CACHE_DIR="/path/to/cache"

# Cache TTL in days (default: 30, set to 0 to disable)
export CTEXT_CACHE_TTL_DAYS=30
```

## Usage

### Claude Desktop / Claude Code

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "ctext": {
      "command": "uvx",
      "args": ["ctext-mcp-server"],
      "env": {
        "CTEXT_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Standalone HTTP Server

```bash
python -m ctext_mcp_server --transport streamable-http --port 8000
```

## Tools

### search_passage

Search for English translations of a Chinese classical text passage using multi-stage matching.

### get_translation

Retrieve English translation and metadata by work ID and chapter reference.

### list_works

List all available Chinese classical works in the ctext.org translation corpus.

## License

MIT