arabic-dict-mcp: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code when working in this repository.

Workflow rules

These override any default behavior, including background-job conventions that suggest otherwise.

Never use worktrees. Do not call EnterWorktree, git worktree add, or otherwise create an isolated copy. Work directly in the repository root (/home/enizrah/drive/code/arabic_mcp, also reachable as /mnt/c/Users/enizrah/GoogleDrive/code/arabic_mcp). Background-session isolation is switched off for this repo via "worktree": {"bgIsolation": "none"} in .claude/settings.json — leave that setting in place.

Stay on main. Do not create, switch to, or rename branches. If a task seems to call for a branch, do the work on main and say so.

Never commit or push on your own initiative. Make the edits and stop there. The user decides when to commit and when to push, and will say so explicitly. Leave changes uncommitted in the working tree until then. This also covers git merge, git rebase, git reset --hard, and anything else that rewrites history or moves refs.

Never touch the git stash. Other sessions share the stash stack.

Project

An MCP server exposing three Arabic dictionary lookup tools (lookup_root, lookup_word, search_meaning) over a unified SQLite index with FTS5, so agents ground Arabic answers in real dictionary data instead of guessing.

src/arabic_dict_mcp/
  normalize.py   diacritic + letter-variant folding (pyarabic); shared by
                 ingest and query so both sides normalize identically
  db.py          SQLite queries returning plain dicts
  server.py      MCPServer; the three tools
  main.py        stdio (default) | --http entrypoint
scripts/build_dataset.py   downloads sources -> data/arabic.db
tests/test_normalize.py

Commands

Run tests. Note pytest is not installed in .venv, so the README's bare .venv/bin/python -m pytest fails — use uv run --with pytest:

PYTHONPATH=src uv run --with pytest python -m pytest tests/ -q