dict-cli 전체 사용 설명서

1) 기능

• SQLite DB 파일/디렉터리 기반 사전 검색
• 검색 방식: 기본 --term / 의미 검색 --query
• 실행 모드: 로컬 CLI / HTTP REST API / MCP(stdio)

2) 요구 사항

• dict-cli 실행 파일
• 사전 DB 경로(로컬 조회 기능 사용 시 필요)
• 단일 통합 DB 파일: /path/to/dictionary_fts5.db
• 또는 개별 DB 디렉터리: /path/to/dicts

3) 실행 예시 (CLI)

dictcli --db /absolute/path/to/dictionary-data/dictionary_fts5.db groups
dictcli --db /absolute/path/to/dictionary-data/dicts --term 사전
dictcli --db /absolute/path/to/dictionary-data/dicts --term 'dict*'
dictcli --db /absolute/path/to/dictionary-data/dicts --term 'com*uter'
dictcli --db /absolute/path/to/dictionary-data/dicts --query dictionary

와일드카드:

*  : 임의의 문자열 (예: '*ter', 'com*uter')
?  : 임의의 한 글자 (예: c?mputer)

릴리스 사전 목록 조회/다운로드:

dictcli download --list
dictcli download-list
dictcli download --name lingoes-naver-english-korean --out /absolute/path/to/dictionary-data/dicts
dictcli download --name cc-kedict.zip --out ./downloads --extract=false

download 명령은 다운로드 중 진행률 바(퍼센트/전송량/속도)를 표시합니다.

출력 모드:

dictcli --db /absolute/path/to/dictionary-data/dicts --term 옥편 --output rich
dictcli --db /absolute/path/to/dictionary-data/dicts --term 옥편 --output plain
dictcli --db /absolute/path/to/dictionary-data/dicts --term 옥편 --output md
dictcli --db /absolute/path/to/dictionary-data/dicts --term 옥편 --output json
dictcli --db /absolute/path/to/dictionary-data/dicts --term 옥편 --output xml

4) 설정

config.ini는 선택 사항이며 config.example.ini를 참고합니다.

DB 경로 우선순위:

1. --db <path>
2. DICTCLI_DB_PATH
3. config.ini의 [database] path

설정 파일 경로 우선순위:

1. --config <path>
2. DICTCLI_CONFIG
3. 현재 경로의 ./config.ini

5) REST API (전체 사용법)

서버 실행:

dictcli \
  --db /absolute/path/to/dictionary-data/dicts \
  --limit 20 \
  --timeout 60 \
  rest --host 127.0.0.1 --port 8080

엔드포인트:

• GET /healthz
• GET /groups
• GET /search

공통 쿼리 파라미터:

• limit: 결과 개수
• timeout: 초 단위 타임아웃
• source_prefix: source_dict 접두어 필터 (예: lingoes)

/search 파라미터:

• term 또는 query 중 하나를 필수로 사용
• term: 표제어 검색 (와일드카드 *, ? 지원)
• query: 의미/본문 FTS 검색

/search 전용 파라미터:

• ranking=true|false (기본 false)
• ranking은 query 검색에서만 사용 (false: fast, true: ranked)

요청 예시:

curl -s "http://127.0.0.1:8080/healthz"
curl -s "http://127.0.0.1:8080/groups"
curl -s --get --data-urlencode "term=가게" --data-urlencode "limit=3" "http://127.0.0.1:8080/search"
curl -s --get --data-urlencode "term=*ter" --data-urlencode "limit=5" "http://127.0.0.1:8080/search"
curl -s --get --data-urlencode "query=dictionary" --data-urlencode "limit=5" --data-urlencode "ranking=false" "http://127.0.0.1:8080/search"

성공 응답 예시:

{
  "results": [
    {
      "group": "ko-en",
      "headword": "사전",
      "source_dict": "stardict-koreanenglish",
      "overlap_count": 2,
      "definition": "dictionary ...",
      "duplicates": [
        {
          "source_dict": "stardict-koreanenglish",
          "definition": "dictionary ..."
        }
      ]
    }
  ]
}

에러 응답 예시:

{
  "error": "search requires one of query params: term, query"
}

/groups 응답 예시:

{
  "groups": ["en-ko", "ko-en", "ko-ko"]
}

/healthz 응답 예시:

{
  "status": "ok"
}

6) MCP 서버 (상세)

실행:

dictcli \
  --db /absolute/path/to/dictionary-data/dicts \
  --limit 20 \
  --timeout 60 \
  mcp --name dictcli

등록되는 MCP 도구:

• groups (인자 없음, 응답 { "groups": [...] })
• search (필수: term 또는 query, 응답 { "results": [...] })

MCP 클라이언트 설정 예시 파일: manual/mcp_client_config.example.json

7) Ubuntu systemd 서비스

추가된 파일:

• 서비스 유닛: deploy/systemd/dictcli-api.service
• 실행 스크립트: scripts/run_dictcli_api.sh

1) 배포 경로 예시:

sudo mkdir -p /opt/dictcli/bin /opt/dictcli/scripts
sudo cp dictcli /opt/dictcli/bin/dictcli
sudo cp ./scripts/run_dictcli_api.sh /opt/dictcli/scripts/run_dictcli_api.sh
sudo chmod +x /opt/dictcli/scripts/run_dictcli_api.sh

2) 서비스 사용자 생성(예시):

sudo useradd --system --no-create-home --shell /usr/sbin/nologin dictcli || true
sudo chown -R dictcli:dictcli /opt/dictcli

3) 환경 파일 /etc/default/dictcli 생성:

DICTCLI_BIN=/opt/dictcli/bin/dictcli
DICTCLI_DB_PATH=/absolute/path/to/dictionary-data/dicts
DICTCLI_HOST=127.0.0.1
DICTCLI_PORT=8080
DICTCLI_GROUP=ko-en
DICTCLI_LIMIT=20
DICTCLI_TIMEOUT=60
# DICTCLI_SOURCE_PREFIX=lingoes

4) 서비스 등록 및 시작:

sudo cp ./deploy/systemd/dictcli-api.service /etc/systemd/system/dictcli-api.service
sudo systemctl daemon-reload
sudo systemctl enable --now dictcli-api
sudo systemctl status dictcli-api