Merge fix/issue-8-python-version-check: Python version check with AbortAddonImport (#8)

Author: anatoly314

CLAUDE.md

@@ -229,7 +229,32 @@ All `print()` statements and `logging` output appears in the terminal.
 - [MCP Protocol](https://modelcontextprotocol.io/) - Model Context Protocol specification
 - [FastMCP](https://github.com/jlowin/fastmcp) - MCP SDK used by this addon
 
-## Common Issues
+## Known Gotchas
+
+### Imports Must Be Relative
+
+All imports in this addon use **relative imports** (e.g., `from ....tool_decorator import Tool`). This is the Anki addon ecosystem standard — AnkiConnect does this too. Absolute imports (`from anki_mcp_server.config import ...`) break AnkiWeb installs because AnkiWeb uses the addon ID (`124672614/`) as the directory name, not the package name.
+
+### Anki Scheduler API Pitfalls
+
+- `col.sched.deck_due_tree()` — correct way to get deck stats (AnkiConnect pattern). Tree nodes have: `deck_id`, `name`, `new_count`, `learn_count`, `review_count`, `total_in_deck` (Anki 2.1.46+)
+- `col.sched.counts()` — returns (new, learning, review) for the **currently selected** deck
+- `col.sched.counts_for_deck_today()` — does **NOT** work in modern Anki, silently returns wrong values
+- Raw SQL (`col.db`) is acceptable for analytics/stats (revlog, card stats) — AnkiConnect does this too. For deck stats, always prefer `deck_due_tree()` over SQL.
+
+### Python Version Compatibility
+
+- MCP Python SDK requires Python >= 3.10 (uses `match`/`case`, `X | Y` syntax) — hard blocker, no workaround
+- Anki 25.02 and earlier: Python 3.9 (**not supported**)
+- Anki 25.07+: Python 3.13 (supported)
+- No Anki version ships Python 3.10/3.11/3.12 — went directly from 3.9 → 3.13
+- `__init__.py` has an early version check that raises `ImportError` with a clear message on Python < 3.10
+
+### Install Methods
+
+Always test both install methods when making changes:
+- `.ankiaddon` file (double-click or *Tools → Add-ons → Install from file...*)
+- AnkiWeb code (`124672614`) — directory name is the addon ID, not the package name
 
 ### UI Freezes During Operations
 

README.md

@@ -138,7 +138,8 @@ These tools interact with Anki's user interface:
 
 ## Requirements
 
-- Anki 25.x or later (Python 3.13)
+- **Anki 25.07 or later** (ships Python 3.13)
+- Anki 25.02 and earlier ship Python 3.9, which is **not supported** — the MCP SDK requires Python 3.10+ ([#8](https://github.com/ankimcp/anki-mcp-server-addon/issues/8))
 
 ## Architecture
 

anki_mcp_server/__init__.py

@@ -1,8 +1,23 @@
-# Vendor imports - must be first, before any other imports
+# Python version check - must be first, before any vendor imports that use 3.10+ syntax
 import sys
+
+if sys.version_info < (3, 10):
+    from aqt.addons import AbortAddonImport
+    from aqt.utils import showWarning
+
+    showWarning(
+        f"<b>AnkiMCP Server</b> requires <b>Anki 25.07 or later</b>.<br><br>"
+        f"Your Anki is running Python {sys.version_info.major}.{sys.version_info.minor}, "
+        f"but the MCP protocol SDK requires Python 3.10+.<br><br>"
+        f"Please upgrade Anki to continue using this addon.<br>"
+        f'<a href="https://github.com/ankimcp/anki-mcp-server-addon/issues/8">More info</a>',
+        title="AnkiMCP Server",
+    )
+    raise AbortAddonImport()
+
 from pathlib import Path
 
-__version__ = "0.1.1"
+__version__ = "0.3.4"
 
 # Packages we vendor that might conflict with other addons
 _VENDOR_PACKAGES = ['mcp', 'pydantic', 'pydantic_core', 'starlette', 'uvicorn', 'anyio', 'httpx', 'websockets']