Metadata-Version: 2.5
Name: anki-addons-mcp
Version: 0.2.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) |
