anki-addons-mcp 0.1.0__tar.gz

anki_addons_mcp-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+.idea

anki_addons_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksey Yablokov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

anki_addons_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: anki-addons-mcp
+Version: 0.1.0
+Summary: MCP server providing access to the Anki Addons dataset (HuggingFace Ya-Alex/anki-addons).
+Project-URL: Homepage, https://github.com/Aleks-Ya/anki-addons-mcp
+Project-URL: Repository, https://github.com/Aleks-Ya/anki-addons-mcp
+Project-URL: Issues, https://github.com/Aleks-Ya/anki-addons-mcp/issues
+Project-URL: Dataset, https://huggingface.co/datasets/Ya-Alex/anki-addons
+Author-email: Aleksey Yablokov <alex_ya@mailbox.org>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: addons,anki,dataset,huggingface,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Requires-Dist: duckdb
+Requires-Dist: huggingface-hub
+Requires-Dist: mcp
+Requires-Dist: pydantic-settings
+Requires-Dist: pydantic>=2
+Requires-Dist: uvicorn
+Description-Content-Type: text/markdown
+
+# Anki Addons MCP
+
+An [MCP](https://modelcontextprotocol.io) server that gives LLM clients read-only access to the
+[Anki Addons dataset](https://huggingface.co/datasets/Ya-Alex/anki-addons): every addon in the AnkiWeb
+catalog, enriched with GitHub, Anki Forum and AI-summary data, published as monthly snapshots.
+
+It answers questions such as "which addon does X?", "will it work on Anki 25.02?", "is it maintained?",
+and "what changed since last month?".
+
+## Links
+- [Anki Addons dataset](https://huggingface.co/datasets/Ya-Alex/anki-addons) on HuggingFace
+- [anki-addons-dataset](https://github.com/Aleks-Ya/anki-addons-dataset), the pipeline that builds the dataset
+- [Developer Guide](https://github.com/Aleks-Ya/anki-addons-mcp/blob/main/README-DEV.md): running from sources, debugging, tests, architecture, deployment
+
+## Use it locally (STDIO)
+
+Requires [uv](https://docs.astral.sh/uv/). `uvx` runs the [PyPI package](https://pypi.org/project/anki-addons-mcp/)
+in an isolated, cached environment; to run a working copy instead, see
+[Run from sources](https://github.com/Aleks-Ya/anki-addons-mcp/blob/main/README-DEV.md#run-from-sources).
+
+Register the server in Claude Code:
+
+```bash
+claude mcp add anki-addons -- uvx anki-addons-mcp
+```
+
+Other MCP clients use the same command (`uvx anki-addons-mcp`) in their server configuration, e.g.:
+
+```json
+{
+  "mcpServers": {
+    "anki-addons": { "command": "uvx", "args": ["anki-addons-mcp"] }
+  }
+}
+```
+
+The first start downloads the latest snapshot (~15 MB) into the HuggingFace cache. Older snapshots are
+downloaded on demand by history tools, so the first history question can take a minute.
+
+## Use it remotely (Streamable HTTP)
+
+Connect to a hosted instance (e.g. a HuggingFace Space) by URL:
+
+```bash
+claude mcp add --transport http anki-addons https://<user>-anki-addons-mcp.hf.space/mcp
+```
+
+To host your own instance, see [Run over HTTP](https://github.com/Aleks-Ya/anki-addons-mcp/blob/main/README-DEV.md#run-over-http) and
+[Deploy to a HuggingFace Space](https://github.com/Aleks-Ya/anki-addons-mcp/blob/main/README-DEV.md#deploy-to-a-huggingface-space).
+
+## Capabilities
+
+**Tools** (all read-only, every data tool takes an optional `snapshot`, `YYYY-MM-DD` or `latest`):
+`search_addons`, `filter_addons`, `get_addon`, `get_addon_readme`, `get_addon_description`,
+`check_compatibility`, `assess_maintenance`, `find_similar_addons`, `list_addons_by_author`,
+`get_addon_history`, `diff_snapshots`, `get_statistics`, `top_addons`, `list_snapshots`, and
+`query_sql` (one sandboxed DuckDB `SELECT` over an `addons` table; only offered by SQL-capable backends).
+
+**Resources**: `anki-addons://dataset/readme`, `anki-addons://dataset/schema`, `anki-addons://snapshots`,
+`anki-addons://snapshots/{snapshot}/metadata`, `anki-addons://snapshots/{snapshot}/aggregation`,
+`anki-addons://addons/{addon_id}` (and `/readme`, `/description`, `/history`),
+`anki-addons://authors/{github_user}`.
+
+**Prompts**: `find_addon_for_task`, `compare_addons`, `addon_health_report`, `upgrade_readiness`,
+`monthly_ecosystem_digest`, `before_you_build`, `author_portfolio`.
+
+AI summaries in the dataset are LLM-generated; the server labels them as such.
+
+## Configuration
+
+CLI flags override environment variables (prefix `ANKI_MCP_`, also read from `.env`).
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `ANKI_MCP_TRANSPORT` | `stdio` | `stdio` or `http` |
+| `ANKI_MCP_HOST` / `ANKI_MCP_PORT` / `ANKI_MCP_PATH` | `127.0.0.1` / `8000` / `/mcp` | HTTP binding |
+| `ANKI_MCP_ALLOWED_HOSTS` | `[]` | JSON list of Host headers to allow (enables DNS-rebinding protection) |
+| `ANKI_MCP_BACKEND` | `hf_parquet` | `hf_parquet` (HuggingFace Hub) or `local_parquet` (a local copy) |
+| `ANKI_MCP_HF_REPO_ID` / `ANKI_MCP_HF_REVISION` | `Ya-Alex/anki-addons` / `main` | Dataset to serve |
+| `ANKI_MCP_DATA_DIR` | | Dataset directory for `local_parquet` (`latest/`, `history/<date>/`) |
+| `ANKI_MCP_CACHE_DIR` | HF cache | Download cache |
+| `ANKI_MCP_REFRESH_INTERVAL_SECONDS` | `3600` | Check for a new dataset revision; `0` disables |
+| `ANKI_MCP_SQL_ENABLED` / `_SQL_MAX_ROWS` / `_SQL_TIMEOUT_SECONDS` | `true` / `200` / `10` | `query_sql` limits |
+| `ANKI_MCP_MAINTENANCE_ACTIVE_DAYS` / `_STALE_DAYS` | `180` / `730` | Maintenance label thresholds |
+| `ANKI_MCP_LOG_LEVEL` | `INFO` | Logs go to stderr |
+| `HF_TOKEN` | | Optional HuggingFace token for higher download rate limits (a Space secret) |

anki_addons_mcp-0.1.0/README.md

@@ -0,0 +1,98 @@
+---
+title: Anki Addons MCP
+emoji: 🗂️
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+short_description: MCP server for the Anki Addons dataset
+---
+
+# Anki Addons MCP
+
+An [MCP](https://modelcontextprotocol.io) server that gives LLM clients read-only access to the
+[Anki Addons dataset](https://huggingface.co/datasets/Ya-Alex/anki-addons): every addon in the AnkiWeb
+catalog, enriched with GitHub, Anki Forum and AI-summary data, published as monthly snapshots.
+
+It answers questions such as "which addon does X?", "will it work on Anki 25.02?", "is it maintained?",
+and "what changed since last month?".
+
+## Links
+- [Anki Addons dataset](https://huggingface.co/datasets/Ya-Alex/anki-addons) on HuggingFace
+- [anki-addons-dataset](https://github.com/Aleks-Ya/anki-addons-dataset), the pipeline that builds the dataset
+- [Developer Guide](README-DEV.md): running from sources, debugging, tests, architecture, deployment
+
+## Use it locally (STDIO)
+
+Requires [uv](https://docs.astral.sh/uv/). `uvx` runs the [PyPI package](https://pypi.org/project/anki-addons-mcp/)
+in an isolated, cached environment; to run a working copy instead, see
+[Run from sources](README-DEV.md#run-from-sources).
+
+Register the server in Claude Code:
+
+```bash
+claude mcp add anki-addons -- uvx anki-addons-mcp
+```
+
+Other MCP clients use the same command (`uvx anki-addons-mcp`) in their server configuration, e.g.:
+
+```json
+{
+  "mcpServers": {
+    "anki-addons": { "command": "uvx", "args": ["anki-addons-mcp"] }
+  }
+}
+```
+
+The first start downloads the latest snapshot (~15 MB) into the HuggingFace cache. Older snapshots are
+downloaded on demand by history tools, so the first history question can take a minute.
+
+## Use it remotely (Streamable HTTP)
+
+Connect to a hosted instance (e.g. a HuggingFace Space) by URL:
+
+```bash
+claude mcp add --transport http anki-addons https://<user>-anki-addons-mcp.hf.space/mcp
+```
+
+To host your own instance, see [Run over HTTP](README-DEV.md#run-over-http) and
+[Deploy to a HuggingFace Space](README-DEV.md#deploy-to-a-huggingface-space).
+
+## Capabilities
+
+**Tools** (all read-only, every data tool takes an optional `snapshot`, `YYYY-MM-DD` or `latest`):
+`search_addons`, `filter_addons`, `get_addon`, `get_addon_readme`, `get_addon_description`,
+`check_compatibility`, `assess_maintenance`, `find_similar_addons`, `list_addons_by_author`,
+`get_addon_history`, `diff_snapshots`, `get_statistics`, `top_addons`, `list_snapshots`, and
+`query_sql` (one sandboxed DuckDB `SELECT` over an `addons` table; only offered by SQL-capable backends).
+
+**Resources**: `anki-addons://dataset/readme`, `anki-addons://dataset/schema`, `anki-addons://snapshots`,
+`anki-addons://snapshots/{snapshot}/metadata`, `anki-addons://snapshots/{snapshot}/aggregation`,
+`anki-addons://addons/{addon_id}` (and `/readme`, `/description`, `/history`),
+`anki-addons://authors/{github_user}`.
+
+**Prompts**: `find_addon_for_task`, `compare_addons`, `addon_health_report`, `upgrade_readiness`,
+`monthly_ecosystem_digest`, `before_you_build`, `author_portfolio`.
+
+AI summaries in the dataset are LLM-generated; the server labels them as such.
+
+## Configuration
+
+CLI flags override environment variables (prefix `ANKI_MCP_`, also read from `.env`).
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `ANKI_MCP_TRANSPORT` | `stdio` | `stdio` or `http` |
+| `ANKI_MCP_HOST` / `ANKI_MCP_PORT` / `ANKI_MCP_PATH` | `127.0.0.1` / `8000` / `/mcp` | HTTP binding |
+| `ANKI_MCP_ALLOWED_HOSTS` | `[]` | JSON list of Host headers to allow (enables DNS-rebinding protection) |
+| `ANKI_MCP_BACKEND` | `hf_parquet` | `hf_parquet` (HuggingFace Hub) or `local_parquet` (a local copy) |
+| `ANKI_MCP_HF_REPO_ID` / `ANKI_MCP_HF_REVISION` | `Ya-Alex/anki-addons` / `main` | Dataset to serve |
+| `ANKI_MCP_DATA_DIR` | | Dataset directory for `local_parquet` (`latest/`, `history/<date>/`) |
+| `ANKI_MCP_CACHE_DIR` | HF cache | Download cache |
+| `ANKI_MCP_REFRESH_INTERVAL_SECONDS` | `3600` | Check for a new dataset revision; `0` disables |
+| `ANKI_MCP_SQL_ENABLED` / `_SQL_MAX_ROWS` / `_SQL_TIMEOUT_SECONDS` | `true` / `200` / `10` | `query_sql` limits |
+| `ANKI_MCP_MAINTENANCE_ACTIVE_DAYS` / `_STALE_DAYS` | `180` / `730` | Maintenance label thresholds |
+| `ANKI_MCP_LOG_LEVEL` | `INFO` | Logs go to stderr |
+| `HF_TOKEN` | | Optional HuggingFace token for higher download rate limits (a Space secret) |

anki_addons_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["hatchling", "hatch-fancy-pypi-readme"]
+build-backend = "hatchling.build"
+
+[project]
+name = "anki-addons-mcp"
+dynamic = ["version", "readme"]
+description = "MCP server providing access to the Anki Addons dataset (HuggingFace Ya-Alex/anki-addons)."
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Aleksey Yablokov", email = "alex_ya@mailbox.org" }]
+keywords = ["anki", "addons", "mcp", "dataset", "huggingface"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Education",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "mcp",
+    "pydantic>=2",
+    "pydantic-settings",
+    "duckdb",
+    "huggingface-hub",
+    "uvicorn",
+]
+
+[project.urls]
+Homepage = "https://github.com/Aleks-Ya/anki-addons-mcp"
+Repository = "https://github.com/Aleks-Ya/anki-addons-mcp"
+Issues = "https://github.com/Aleks-Ya/anki-addons-mcp/issues"
+Dataset = "https://huggingface.co/datasets/Ya-Alex/anki-addons"
+
+[project.scripts]
+anki-addons-mcp = "anki_addons_mcp.__main__:main"
+
+[tool.hatch.version]
+path = "src/anki_addons_mcp/__init__.py"
+
+[tool.hatch.metadata.hooks.fancy-pypi-readme]
+content-type = "text/markdown"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "README.md"
+start-at = "# Anki Addons MCP"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = '\]\((?!https?://)([^)]+)\)'
+replacement = '](https://github.com/Aleks-Ya/anki-addons-mcp/blob/main/\1)'
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/anki_addons_mcp"]
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "anyio",
+    "ruff",
+    "mypy",
+    "pyarrow",
+    "bump-my-version",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.mypy]
+python_version = "3.13"
+files = ["src"]
+
+[[tool.mypy.overrides]]
+module = ["anki_addons_mcp.domain.*", "anki_addons_mcp.application.*"]
+strict = true

anki_addons_mcp-0.1.0/src/anki_addons_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

anki_addons_mcp-0.1.0/src/anki_addons_mcp/__main__.py

@@ -0,0 +1,56 @@
+import argparse
+import logging
+import sys
+from typing import Any
+
+from anki_addons_mcp import __version__
+from anki_addons_mcp.bootstrap import create_app
+from anki_addons_mcp.config import Settings
+
+
+def _parse_args(argv: list[str] | None) -> dict[str, Any]:
+    parser = argparse.ArgumentParser(prog="anki-addons-mcp", description="MCP server for the Anki Addons dataset")
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument("--transport", choices=["stdio", "http"])
+    parser.add_argument("--host")
+    parser.add_argument("--port", type=int)
+    parser.add_argument("--path")
+    parser.add_argument("--backend", choices=["hf_parquet", "local_parquet"])
+    parser.add_argument("--data-dir", dest="data_dir")
+    parser.add_argument("--cache-dir", dest="cache_dir")
+    parser.add_argument("--hf-revision", dest="hf_revision")
+    parser.add_argument("--refresh-interval", dest="refresh_interval_seconds", type=int)
+    parser.add_argument("--no-sql", dest="sql_enabled", action="store_const", const=False)
+    parser.add_argument("--log-level", dest="log_level", choices=["DEBUG", "INFO", "WARNING", "ERROR"])
+    return {k: v for k, v in vars(parser.parse_args(argv)).items() if v is not None}
+
+
+def _run_http(mcp: Any, settings: Settings) -> None:
+    import uvicorn
+    from mcp.server.transport_security import TransportSecuritySettings
+
+    security = None
+    if settings.allowed_hosts:
+        security = TransportSecuritySettings(enable_dns_rebinding_protection=True,
+                                             allowed_hosts=settings.allowed_hosts)
+    app = mcp.streamable_http_app(streamable_http_path=settings.path, json_response=True, stateless_http=True,
+                                  host=settings.host, transport_security=security)
+    uvicorn.run(app, host=settings.host, port=settings.port, log_level=settings.log_level.lower())
+
+
+def main(argv: list[str] | None = None) -> None:
+    settings = Settings(**_parse_args(argv))
+    logging.basicConfig(stream=sys.stderr, level=settings.log_level,
+                        format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+    if settings.log_level != "DEBUG":
+        for noisy in ("httpx", "httpx2", "huggingface_hub"):
+            logging.getLogger(noisy).setLevel(logging.WARNING)
+    mcp, _ = create_app(settings)
+    if settings.transport == "http":
+        _run_http(mcp, settings)
+    else:
+        mcp.run("stdio")
+
+
+if __name__ == "__main__":
+    main()

anki_addons_mcp-0.1.0/src/anki_addons_mcp/adapters/hf_parquet/mapping.py

@@ -0,0 +1,106 @@
+import json
+from typing import Any
+
+from anki_addons_mcp.domain.models import (
+    AddonCard,
+    AddonDetails,
+    AiInfo,
+    AnkiWebInfo,
+    Branch,
+    ForumInfo,
+    GithubInfo,
+    GithubLink,
+    LanguageBytes,
+    Manifest,
+)
+
+CARD_COLUMNS = [
+    "id", "title", "url", "rating", "likes", "dislikes", "update_date", "anki_version", "ai_summary", "ai_model",
+    "github_user", "github_repo", "github_stars", "github_last_commit", "github_archived", "github_license",
+    "forum_posts_count",
+]
+
+
+def _list(value: Any) -> list[Any]:
+    return [v for v in value if v is not None] if isinstance(value, list) else []
+
+
+def _structs(value: Any) -> list[dict[str, Any]]:
+    return [v for v in _list(value) if isinstance(v, dict)]
+
+
+def _manifest(value: Any) -> Manifest | None:
+    if not value:
+        return None
+    raw = json.loads(value) if isinstance(value, str) else value
+    if not isinstance(raw, dict):
+        return None
+    raw["conflicts"] = _list(raw.get("conflicts"))
+    return Manifest.model_validate(raw)
+
+
+def row_to_card(row: dict[str, Any], score: float | None = None) -> AddonCard:
+    return AddonCard(
+        id=row["id"], title=row["title"] or "", url=row["url"] or "", rating=row["rating"] or 0,
+        likes=row["likes"] or 0, dislikes=row["dislikes"] or 0, update_date=row["update_date"] or None,
+        anki_version=row["anki_version"] or None, ai_summary=row["ai_summary"], ai_model=row["ai_model"],
+        github_user=row["github_user"], github_repo=row["github_repo"], github_stars=row["github_stars"],
+        github_last_commit=row["github_last_commit"], github_archived=row["github_archived"],
+        license=row["github_license"], forum_posts_count=row["forum_posts_count"], score=score,
+    )
+
+
+def row_to_details(row: dict[str, Any]) -> AddonDetails:
+    anki_web = AnkiWebInfo(
+        title=row["title"] or "",
+        addon_page_url=row["url"] or "",
+        contact_author_url=row["contact_author_url"],
+        rating=row["rating"] or 0,
+        update_date=row["update_date"] or None,
+        anki_version=row["anki_version"] or None,
+        branches=[Branch.model_validate(b) for b in _structs(row["branches"])],
+        links=_list(row["links"]),
+        likes=row["likes"] or 0,
+        dislikes=row["dislikes"] or 0,
+        ai_declaration_markers=_list(row["ai_declaration_markers"]),
+        description_language=row["description_language"],
+        description_language_confidence=row["description_language_confidence"],
+    )
+    github = None
+    if row["has_github"]:
+        github = GithubInfo(
+            user=row["github_user"],
+            repo=row["github_repo"],
+            languages=_list(row["github_languages"]),
+            stars=row["github_stars"] or 0,
+            last_commit=row["github_last_commit"],
+            links=[GithubLink.model_validate(link) for link in _structs(row["github_links"]) if link.get("url")],
+            action_count=row["github_action_count"],
+            tests_count=row["github_tests_count"],
+            license=row["github_license"],
+            forks=row["github_forks"],
+            open_issues=row["github_open_issues"],
+            size_kb=row["github_size_kb"],
+            topics=_list(row["github_topics"]),
+            repo_description=row["github_repo_description"],
+            homepage=row["github_homepage"],
+            archived=row["github_archived"],
+            pushed_at=row["github_pushed_at"],
+            created_at=row["github_created_at"],
+            primary_language=row["github_primary_language"],
+            language_bytes=[LanguageBytes.model_validate(lb) for lb in _structs(row["github_language_bytes"])],
+            manifest=_manifest(row["github_manifest"]),
+            dependencies=_list(row["github_dependencies"]),
+            ai_tooling_markers=_list(row["github_ai_tooling_markers"]),
+        )
+    forum = None
+    if row["has_forum"] or row["forum_topic_id"] is not None:
+        forum = ForumInfo(
+            anki_forum_url=row["forum_url"],
+            topic_slug=row["forum_topic_slug"],
+            topic_id=row["forum_topic_id"],
+            last_posted_at=row["forum_last_posted_at"],
+            posts_count=row["forum_posts_count"],
+        )
+    ai = AiInfo(summary=row["ai_summary"], model=row["ai_model"]) if row["ai_summary"] or row["ai_model"] else None
+    return AddonDetails(id=row["id"], anki_web=anki_web, github=github, forum=forum, ai=ai)