anki-mcp

Instructions

Implementation Reference

• src/anki_mcp/media_service.py:35-79 (handler)

  The main handler function `store_media_file_tool` that implements the `media_storeMediaFile` tool logic. It validates that exactly one source (data, path, or url) is provided, constructs parameters, and delegates to AnkiConnect's `storeMediaFile` via `anki_call`.

  @media_mcp.tool(
      name="storeMediaFile",
      description="Stores a media file in Anki's media folder. Provide one of 'data' (base64), 'path', or 'url'. Returns the stored filename or false on error.",
  )
  async def store_media_file_tool(
      filename: Annotated[
          str, Field(description="The desired filename in Anki's media collection.")
      ],
      data: Annotated[
          Optional[str], Field(description="Base64-encoded file content.")
      ] = None,
      path: Annotated[
          Optional[str], Field(description="Absolute local path to the file.")
      ] = None,
      url: Annotated[
          Optional[str], Field(description="URL to download the file from.")
      ] = None,
      deleteExisting: Annotated[                                                            
          Optional[bool],
          Field(
              description="Whether to delete an existing file with the same name. Default is true."
          ),
      ] = True,
  ) -> Any:                                            
      params: Dict[str, Any] = {"filename": filename}
      source_count = sum(1 for src in (data, path, url) if src is not None)
      if source_count != 1:
          raise ValueError(
              "Exactly one of 'data', 'path', or 'url' must be provided for storeMediaFile."
          )
  
      if data:
          params["data"] = data
      elif path:
          params["path"] = path
      elif url:
          params["url"] = url
  
      if (
          deleteExisting is not None
      ):                                                                
          params["deleteExisting"] = deleteExisting
  
      return await anki_call("storeMediaFile", **params)

• src/anki_mcp/__init__.py:27-27 (registration)

  Registers the `media_mcp` FastMCP instance (containing the `storeMediaFile` tool) into the main `anki_mcp` server under the 'media' namespace, resulting in the tool name `media_storeMediaFile`.

  await anki_mcp.import_server("media", media_mcp)

• src/anki_mcp/common.py:8-23 (helper)

  Shared helper `anki_call` that performs HTTP POST requests to AnkiConnect API (localhost:8765), used by the handler to invoke the underlying `storeMediaFile` action.

  async def anki_call(action: str, **params: Any) -> Any:
      async with httpx.AsyncClient() as client:
          payload = {"action": action, "version": 6, "params": params}
          result = await client.post(ANKICONNECT_URL, json=payload)
          result.raise_for_status()                                      
          result_json = result.json()
          error = result_json.get("error")
          if error:
              raise Exception(f"AnkiConnect error for action '{action}': {error}")
          response = result_json.get("result")
                                                               
                                                                                                       
                                                                                          
          if "result" in result_json:
              return response
          return result_json                                                                        

• src/anki_mcp/media_service.py:40-58 (schema)

  Pydantic schema definitions for the tool parameters using Annotated and Field for input validation and descriptions.

      filename: Annotated[
          str, Field(description="The desired filename in Anki's media collection.")
      ],
      data: Annotated[
          Optional[str], Field(description="Base64-encoded file content.")
      ] = None,
      path: Annotated[
          Optional[str], Field(description="Absolute local path to the file.")
      ] = None,
      url: Annotated[
          Optional[str], Field(description="URL to download the file from.")
      ] = None,
      deleteExisting: Annotated[                                                            
          Optional[bool],
          Field(
              description="Whether to delete an existing file with the same name. Default is true."
          ),
      ] = True,
  ) -> Any: