mdx-cli

365 Open Source Project #004 · Command-line MDX dictionary lookup tool

中文

A fast, modern command-line dictionary tool for MDX files. Fuzzy search, multi-dictionary, colored output, pipe-friendly.

$ mdx hello
━━━ OALD ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
hello  /həˈləʊ/

 1. used as a greeting
    • Hello, how are you?
    • Say hello to your sister for me.

 2. used when answering the telephone
    • Hello? Who's speaking?
━━━ LONGMAN ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
hello  /hɛˈloʊ/
  ...

Features

• Fuzzy search -- exact match, prefix, and FTS5 trigram substring search with automatic fallback
• Multi-dictionary -- query multiple MDX dictionaries at once, sorted by priority
• Colored output -- Rich terminal rendering with bold, italic, lists; auto-degrades in pipes
• Pipe-friendly -- --json, --raw, auto plain-text when piped
• Fast -- SQLite index with mtime-based cache; sub-millisecond repeated lookups
• Interactive REPL -- tab completion, history, quick dict/group switching
• Audio playback -- pronounce words from MDD resources (cross-platform)

Install

pipx install mdx-cli

Or with pip:

pip install mdx-cli

Requires Python 3.10+.

Quick Start

# Scan a directory for MDX files and register them
mdx init ~/Dictionaries

# Look up a word
mdx hello

# Specify a dictionary
mdx hello -d oald

# Query multiple dictionaries
mdx hello -d oald -d longman

# Fuzzy search (substring match)
mdx ello --fuzzy

# JSON output (for scripts)
mdx hello --json

# Play pronunciation
mdx hello --play

# Interactive mode
mdx repl

Configuration

Config file: ~/.config/mdx-cli/config.toml

[general]
default_dicts = ["oald", "longman"]
fuzzy_threshold = 3
pager = true                           # (reserved, not yet implemented)

[dict.oald]
path = "/path/to/oald.mdx"
priority = 1

[dict.longman]
path = "/path/to/longman.mdx"
priority = 2

[groups.english]
dicts = ["oald", "longman"]

Dictionary Management

mdx add /path/to/dictionary.mdx           # Add a dictionary
mdx add /path/to/dictionary.mdx -a mydict # Add with custom alias
mdx list                                   # List registered dictionaries
mdx rebuild                                # Rebuild all indexes
mdx rebuild oald                           # Rebuild one index

Search Behavior

Queries cascade through three strategies:

1. Exact match -- case-insensitive, instant
2. Prefix match -- hel finds hello, help, helicopter
3. Trigram substring -- ello finds hello (FTS5 trigram tokenizer)

Use --fuzzy to skip directly to trigram search.

Output Formats

Mode	When	Example
Rich	Terminal (tty)	Colored, styled, with rules
Plain	Piped (mdx hello | less)	Auto-detected, no ANSI codes
JSON	--json	Structured data with phonetic, html, text
Raw	--raw	Original HTML from MDX

JSON output:

{
  "query": "hello",
  "results": [
    {
      "dict": "oald",
      "headword": "hello",
      "phonetic": "/həˈləʊ/",
      "html": "<p>...</p>",
      "text": "plain text definition"
    }
  ]
}

REPL Mode

$ mdx repl
mdx repl — type a word to look up, :q to quit
mdx> hello
━━━ OALD ━━━━━━━━━━━━━━━━━━
  ...
mdx> :d longman        # switch dictionary
mdx> :g english        # switch to group
mdx> :play             # replay last pronunciation
mdx> :history          # recent lookups
mdx> :q                # quit

Tab completion works -- type a few letters and press Tab.

Architecture

CLI (click) ─> DictMgr ─> Searcher ─> SQLite (FTS5)
                  │            │
                  v            v
              Indexer      Formatter ─> Rich / Plain / JSON / Raw
                  │            │
                  v            v
            Reader        Renderer (HTML ─> terminal)
          (readmdict)

• Reader wraps readmdict for MDX/MDD parsing
• Indexer builds SQLite databases with FTS5 trigram indexes (atomic writes, mtime caching)
• Searcher cascades exact/prefix/fuzzy queries
• Renderer converts HTML definitions to terminal-friendly Rich text
• Formatter dispatches output to the appropriate format
• DictMgr coordinates indexing, caching, and multi-dictionary queries

Development

git clone <repo-url>
cd mdx-cli
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"
python -m pytest -v

101 tests covering all modules.

About 365 Open Source Project

This is project #004 of the 365 Open Source Project.

One person + AI, 300+ open source projects in a year. Submit your idea ->

License

MIT