iflow-mcp_ujisati_anki-mcp 0.1.0__tar.gz

iflow_mcp_ujisati_anki_mcp-0.1.0/.gitignore

@@ -0,0 +1,175 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+.aider*

iflow_mcp_ujisati_anki_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ujisati
+
+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.

iflow_mcp_ujisati_anki_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: iflow-mcp_ujisati_anki-mcp
+Version: 0.1.0
+Summary: Add your description here
+Author-email: ujisati <98663233+ujisati@users.noreply.github.com>
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=2.3.3
+Requires-Dist: httpx>=0.28.1
+Description-Content-Type: text/markdown
+
+# anki-mcp
+
+A Model Context Protocol (MCP) server for interacting with Anki flashcards via the AnkiConnect add-on. This server exposes AnkiConnect actions as MCP tools, organized into logical services.
+
+## Prerequisites
+
+- Anki desktop application
+- AnkiConnect add-on installed and configured in Anki
+- Python 3.8+
+- `uv` (for running and installing dependencies, optional but recommended)
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/ujisati/anki-mcp.git
+cd anki-mcp
+
+# Install dependencies (using uv)
+uv pip install -e .
+```
+
+## Usage
+
+To run the MCP server:
+
+```bash
+uv run anki-mcp
+```
+
+The server will start and listen for MCP requests, typically interfacing with AnkiConnect at `http://127.0.0.1:8765`.
+
+### Inspecting the Server
+
+You can use the MCP Inspector to view the available tools:
+
+```bash
+npx @modelcontextprotocol/inspector uv run anki-mcp
+```
+
+## Configuration for MCP Clients
+
+If you're integrating this with an MCP client (like an AI assistant framework), you'll need to configure it to find this server. Here's an example configuration snippet:
+
+```json
+{
+    "mcpServers": {
+        "anki": {
+            "command": "uv",
+            "args": [
+                "run", // uv will find anki-mcp if run from project root
+                "anki-mcp"
+            ],
+            // If running from outside the project directory, specify the path:
+            // "args": [
+            //     "--directory",
+            //     "/ABSOLUTE/PATH/TO/anki-mcp", // Replace with actual path
+            //     "run",
+            //     "anki-mcp"
+            // ]
+        }
+    }
+}
+```
+
+## Available MCP Tools
+
+This MCP server provides access to Anki functionality through tools grouped by services. The tool names correspond directly to AnkiConnect actions.
+
+### Deck Service (`deck.*`)
+- **`deck.deckNamesAndIds`**: Gets the complete list of deck names and their respective IDs.
+- **`deck.getDeckConfig`**: Gets the configuration group object for a given deck name.
+- **`deck.deckNames`**: Gets the complete list of deck names for the current user.
+- **`deck.createDeck`**: Creates a new empty deck.
+- **`deck.deleteDecks`**: Deletes specified decks.
+- **`deck.changeDeck`**: Moves cards to a different deck.
+- **`deck.saveDeckConfig`**: Saves a deck configuration group.
+
+### Note Service (`note.*`)
+- **`note.findNotes`**: Returns note IDs for a given Anki search query.
+- **`note.notesInfo`**: Returns information for specified note IDs.
+- **`note.getNoteTags`**: Gets the tags for a specific note ID.
+- **`note.addNote`**: Creates a new note.
+- **`note.updateNoteFields`**: Modifies the fields of an existing note.
+- **`note.deleteNotes`**: Deletes specified notes.
+- **`note.addNotes`**: Creates multiple notes.
+- **`note.addTags`**: Adds tags to specified notes.
+- **`note.removeTags`**: Removes tags from specified notes.
+- **`note.updateNote`**: Modifies the fields and/or tags of an existing note.
+
+### Card Service (`card.*`)
+- **`card.findCards`**: Returns card IDs for a given Anki search query.
+- **`card.cardsInfo`**: Returns information for specified card IDs.
+- **`card.cardsToNotes`**: Returns note IDs for given card IDs.
+- **`card.areSuspended`**: Checks if specified cards are suspended.
+- **`card.cardsModTime`**: Returns modification time for specified card IDs.
+- **`card.suspended`**: Checks if a single card is suspended.
+- **`card.suspend`**: Suspends specified cards.
+- **`card.unsuspend`**: Unsuspends specified cards.
+- **`card.setSpecificValueOfCard`**: Sets specific values of a single card (use with caution).
+
+### Model Service (`model.*`) (Note Types)
+- **`model.modelNamesAndIds`**: Gets the complete list of model (note type) names and their IDs.
+- **`model.findModelsByName`**: Gets model definitions for provided model names.
+- **`model.modelFieldNames`**: Gets field names for a given model name.
+- **`model.modelTemplates`**: Gets template content for each card of a specified model.
+- **`model.modelStyling`**: Gets CSS styling for a given model name.
+- **`model.createModel`**: Creates a new model (note type).
+- **`model.updateModelTemplates`**: Modifies templates of an existing model.
+- **`model.updateModelStyling`**: Modifies CSS styling of an existing model.
+- **`model.modelFieldAdd`**: Adds a new field to an existing model.
+- **`model.modelFieldRemove`**: Removes a field from an existing model.
+
+### Media Service (`media.*`)
+- **`media.retrieveMediaFile`**: Retrieves the base64-encoded contents of a media file.
+- **`media.getMediaFilesNames`**: Gets names of media files matching a glob pattern.
+- **`media.storeMediaFile`**: Stores a media file (from base64, path, or URL).
+- **`media.deleteMediaFile`**: Deletes a specified media file.
+
+## Development
+
+To set up for development:
+
+```bash
+uv sync
+source .venv/bin/activate
+
+uv pip install -e .
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+## Todo
+
+- [ ] Finish adding all AnkiConnect tools

iflow_mcp_ujisati_anki_mcp-0.1.0/README.md

@@ -0,0 +1,139 @@
+# anki-mcp
+
+A Model Context Protocol (MCP) server for interacting with Anki flashcards via the AnkiConnect add-on. This server exposes AnkiConnect actions as MCP tools, organized into logical services.
+
+## Prerequisites
+
+- Anki desktop application
+- AnkiConnect add-on installed and configured in Anki
+- Python 3.8+
+- `uv` (for running and installing dependencies, optional but recommended)
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/ujisati/anki-mcp.git
+cd anki-mcp
+
+# Install dependencies (using uv)
+uv pip install -e .
+```
+
+## Usage
+
+To run the MCP server:
+
+```bash
+uv run anki-mcp
+```
+
+The server will start and listen for MCP requests, typically interfacing with AnkiConnect at `http://127.0.0.1:8765`.
+
+### Inspecting the Server
+
+You can use the MCP Inspector to view the available tools:
+
+```bash
+npx @modelcontextprotocol/inspector uv run anki-mcp
+```
+
+## Configuration for MCP Clients
+
+If you're integrating this with an MCP client (like an AI assistant framework), you'll need to configure it to find this server. Here's an example configuration snippet:
+
+```json
+{
+    "mcpServers": {
+        "anki": {
+            "command": "uv",
+            "args": [
+                "run", // uv will find anki-mcp if run from project root
+                "anki-mcp"
+            ],
+            // If running from outside the project directory, specify the path:
+            // "args": [
+            //     "--directory",
+            //     "/ABSOLUTE/PATH/TO/anki-mcp", // Replace with actual path
+            //     "run",
+            //     "anki-mcp"
+            // ]
+        }
+    }
+}
+```
+
+## Available MCP Tools
+
+This MCP server provides access to Anki functionality through tools grouped by services. The tool names correspond directly to AnkiConnect actions.
+
+### Deck Service (`deck.*`)
+- **`deck.deckNamesAndIds`**: Gets the complete list of deck names and their respective IDs.
+- **`deck.getDeckConfig`**: Gets the configuration group object for a given deck name.
+- **`deck.deckNames`**: Gets the complete list of deck names for the current user.
+- **`deck.createDeck`**: Creates a new empty deck.
+- **`deck.deleteDecks`**: Deletes specified decks.
+- **`deck.changeDeck`**: Moves cards to a different deck.
+- **`deck.saveDeckConfig`**: Saves a deck configuration group.
+
+### Note Service (`note.*`)
+- **`note.findNotes`**: Returns note IDs for a given Anki search query.
+- **`note.notesInfo`**: Returns information for specified note IDs.
+- **`note.getNoteTags`**: Gets the tags for a specific note ID.
+- **`note.addNote`**: Creates a new note.
+- **`note.updateNoteFields`**: Modifies the fields of an existing note.
+- **`note.deleteNotes`**: Deletes specified notes.
+- **`note.addNotes`**: Creates multiple notes.
+- **`note.addTags`**: Adds tags to specified notes.
+- **`note.removeTags`**: Removes tags from specified notes.
+- **`note.updateNote`**: Modifies the fields and/or tags of an existing note.
+
+### Card Service (`card.*`)
+- **`card.findCards`**: Returns card IDs for a given Anki search query.
+- **`card.cardsInfo`**: Returns information for specified card IDs.
+- **`card.cardsToNotes`**: Returns note IDs for given card IDs.
+- **`card.areSuspended`**: Checks if specified cards are suspended.
+- **`card.cardsModTime`**: Returns modification time for specified card IDs.
+- **`card.suspended`**: Checks if a single card is suspended.
+- **`card.suspend`**: Suspends specified cards.
+- **`card.unsuspend`**: Unsuspends specified cards.
+- **`card.setSpecificValueOfCard`**: Sets specific values of a single card (use with caution).
+
+### Model Service (`model.*`) (Note Types)
+- **`model.modelNamesAndIds`**: Gets the complete list of model (note type) names and their IDs.
+- **`model.findModelsByName`**: Gets model definitions for provided model names.
+- **`model.modelFieldNames`**: Gets field names for a given model name.
+- **`model.modelTemplates`**: Gets template content for each card of a specified model.
+- **`model.modelStyling`**: Gets CSS styling for a given model name.
+- **`model.createModel`**: Creates a new model (note type).
+- **`model.updateModelTemplates`**: Modifies templates of an existing model.
+- **`model.updateModelStyling`**: Modifies CSS styling of an existing model.
+- **`model.modelFieldAdd`**: Adds a new field to an existing model.
+- **`model.modelFieldRemove`**: Removes a field from an existing model.
+
+### Media Service (`media.*`)
+- **`media.retrieveMediaFile`**: Retrieves the base64-encoded contents of a media file.
+- **`media.getMediaFilesNames`**: Gets names of media files matching a glob pattern.
+- **`media.storeMediaFile`**: Stores a media file (from base64, path, or URL).
+- **`media.deleteMediaFile`**: Deletes a specified media file.
+
+## Development
+
+To set up for development:
+
+```bash
+uv sync
+source .venv/bin/activate
+
+uv pip install -e .
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+## Todo
+
+- [ ] Finish adding all AnkiConnect tools

iflow_mcp_ujisati_anki_mcp-0.1.0/language.json

@@ -0,0 +1 @@
+python

iflow_mcp_ujisati_anki_mcp-0.1.0/package_name

@@ -0,0 +1 @@
+iflow-mcp_ujisati_anki-mcp

iflow_mcp_ujisati_anki_mcp-0.1.0/push_info.json

@@ -0,0 +1,5 @@
+{
+  "push_platform": "github",
+  "fork_url": "https://github.com/iflow-mcp/ujisati-anki-mcp",
+  "fork_branch": "iflow"
+}

iflow_mcp_ujisati_anki_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "iflow-mcp_ujisati_anki-mcp"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "ujisati", email = "98663233+ujisati@users.noreply.github.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "fastmcp>=2.3.3",
+    "httpx>=0.28.1",
+]
+
+[project.scripts]
+anki-mcp = "anki_mcp:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.26.0",
+]
+
+[tool.pytest.ini_options]
+pythonpath = [
+  "."
+]
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/anki_mcp"]

iflow_mcp_ujisati_anki_mcp-0.1.0/src/anki_mcp/__init__.py

@@ -0,0 +1,37 @@
+import asyncio
+
+from fastmcp import FastMCP
+
+from .card_service import card_mcp
+from .deck_service import deck_mcp
+from .media_service import media_mcp
+from .model_service import model_mcp
+from .note_service import note_mcp
+
+
+anki_mcp = FastMCP(
+    name="AnkiConnectMCP",
+    instructions="""
+    This MCP provides a programmatic interface to Anki flashcard functionality through the AnkiConnect API.
+    It allows AI assistants to interact with Anki decks, cards, notes, models, and media
+    without needing to understand the underlying API details. All interactions are through tools.
+    """,
+)
+
+
+async def setup(run_server: bool = True):
+    await anki_mcp.import_server(deck_mcp)
+    await anki_mcp.import_server(note_mcp)
+    await anki_mcp.import_server(card_mcp)
+    await anki_mcp.import_server(model_mcp)
+    await anki_mcp.import_server(media_mcp)
+    if run_server:
+        await anki_mcp.run_async()
+
+
+def main():
+    asyncio.run(setup(run_server=True))
+
+
+if __name__ == "__main__":
+    main()

iflow_mcp_ujisati_anki_mcp-0.1.0/src/anki_mcp/card_service.py

@@ -0,0 +1,116 @@
+from typing import Annotated, Any, Dict, List, Optional
+
+from fastmcp import FastMCP
+from pydantic import Field
+
+from .common import anki_call
+
+card_mcp = FastMCP(name="AnkiCardService")
+
+
+@card_mcp.tool(
+    name="findCards",
+    description="Returns an array of card IDs for a given Anki search query.",
+)
+async def find_cards_tool(
+    query: Annotated[
+        str, Field(description="Anki search query (e.g., 'deck:current is:new').")
+    ],
+) -> List[int]:
+    return await anki_call("findCards", query=query)
+
+
+@card_mcp.tool(
+    name="cardsInfo",
+    description="Returns a list of objects containing information for each card ID provided.",
+)
+async def get_cards_info_tool(
+    cards: Annotated[List[int], Field(description="A list of card IDs.")],
+) -> List[Dict[str, Any]]:
+    return await anki_call("cardsInfo", cards=cards)
+
+
+@card_mcp.tool(
+    name="cardsToNotes",
+    description="Returns an unordered array of note IDs for the given card IDs.",
+)
+async def convert_cards_to_notes_tool(
+    cards: Annotated[List[int], Field(description="A list of card IDs.")],
+) -> List[int]:
+    return await anki_call("cardsToNotes", cards=cards)
+
+
+@card_mcp.tool(
+    name="areSuspended",
+    description="Returns an array indicating whether each given card is suspended. Each item is boolean or null if the card doesn't exist.",
+)
+async def check_cards_suspended_tool(
+    cards: Annotated[List[int], Field(description="A list of card IDs.")],
+) -> List[Optional[bool]]:
+    return await anki_call("areSuspended", cards=cards)
+
+
+@card_mcp.tool(
+    name="cardsModTime",
+    description="Returns modification time for each card ID provided. Result is a list of objects with 'cardId' and 'modTime' (timestamp).",
+)
+async def get_cards_modification_time_tool(
+    cards: Annotated[List[int], Field(description="A list of card IDs.")],
+) -> List[Dict[str, Any]]:                                                  
+    return await anki_call("cardsModTime", cards=cards)
+
+
+@card_mcp.tool(
+    name="suspended",
+    description="Checks if a single card is suspended by its ID. Returns true if suspended, false otherwise.",
+)
+async def check_card_suspended_tool(
+    card: Annotated[int, Field(description="The ID of the card.")],
+) -> bool:
+    return await anki_call("suspended", card=card)
+
+
+@card_mcp.tool(
+    name="suspend", description="Suspends the specified cards. Returns true on success."
+)
+async def suspend_cards_tool(
+    cards: Annotated[List[int], Field(description="A list of card IDs to suspend.")],
+) -> bool:
+    return await anki_call("suspend", cards=cards)
+
+
+@card_mcp.tool(
+    name="unsuspend",
+    description="Unsuspends the specified cards. Returns true on success.",
+)
+async def unsuspend_cards_tool(
+    cards: Annotated[List[int], Field(description="A list of card IDs to unsuspend.")],
+) -> bool:
+    return await anki_call("unsuspend", cards=cards)
+
+
+@card_mcp.tool(
+    name="setSpecificValueOfCard",
+    description="Sets specific values of a single card. Use with caution. Returns list of booleans indicating success for each key.",
+)
+async def set_specific_card_value_tool(
+    card: Annotated[int, Field(description="The ID of the card to modify.")],
+    keys: Annotated[
+        List[str],
+        Field(
+            description="List of card property keys to change (e.g., 'flags', 'odue')."
+        ),
+    ],
+    newValues: Annotated[
+        List[Any],                                                             
+        Field(description="List of new values corresponding to the keys."),
+    ],
+    warning_check: Annotated[
+        Optional[bool],
+        Field(description="Set to True for potentially risky operations."),
+    ] = None,
+) -> List[bool]:
+    params: Dict[str, Any] = {"card": card, "keys": keys, "newValues": newValues}
+    if warning_check is not None:
+        params["warning_check"] = warning_check
+    return await anki_call("setSpecificValueOfCard", **params)