AnkiMCP Server Addon
- 项目简介
- 该仓库实现了一个在 Anki 内部运行的 MCP 服务器插件。它通过一个本地 HTTP 传输为 MCP 客户端（如 Claude Desktop 等）提供上下文服务，核心职责包括：托管和管理资源 (Resources)、注册和执行工具 (Tools)、定义并渲染 Prompt 模板 (Prompts)，以及在客户端与服务器之间通过 JSON-RPC 形式进行请求与响应。
- 服务器在后台线程运行 MCP 服务并通过一个跨线程桥接 QueueBridge 将请求传递给 Anki 的主线程执行操作，确保对 mw.col 的访问只能在 Qt 主线程完成，从而实现安全的集成。
- 主要功能点
- 本地 MCP 服务器与传输：提供本地 HTTP 传输 (streamable HTTP) 供 MCP 客户端访问，端口默认 3141，监听 127.0.0.1。
- 资源、工具、提示注册与渲染：通过装饰器（@Resource、@Tool、@Prompt）进行注册，并在服务器启动时将这些资源/工具/prompts 注册到 MCP 服务端，实现统一暴露给客户端的能力。
- 跨线程调用与主线程桥接：Background 线程的 MCP 服务通过 QueueBridge 将工具请求发送到主线程，主线程通过 RequestProcessor 轮询队列并执行 Anki 操作，随后将结果返回给背景线程。
- 主线程安全访问：所有涉及 Anki 集合的操作都在 Qt 主线程执行，借助注册的处理器（handler_registry）完成分发。
- 延迟首次加载依赖：首次运行时会下载 pydantic_core（必要的二进制依赖），并在下载完成后将其加入到 Python 路径，以便继续运行。
- 兼容性与扩展：提供了完善的工具、资源、提示的注册框架，支持 GUI 相关操作、Deck/Note/Model 的创建与查询、以及丰富的资源文档（schema、stats 等）以支持强化的 AI 辅助能力。
- 安装与使用步骤
- 安装方式
- 通过 AnkiWeb 获取插件（按 README 指引输入购买码并重启 Anki），或从 Releases 下载并在 Anki 中安装。
- 插件在首次运行时会自动从网络下载必要的 pydantic_core 二进制依赖包，完成后即可正常工作。
- 启动与运行
- 打开 Anki，插件会在后台启动 MCP 服务器并通过本地 HTTP 服务对外暴露端点，默认地址为 http://127.0.0.1:3141/。
- 服务器启动后，可以通过 MCP 客户端连接并调用资源、工具与 prompts，获取上下文、执行外部功能、渲染模板等。
- 使用要点
- 通过 Claude Desktop 等 MCP 客户端将服务器地址配置为本地地址，即可向服务器发起请求以读取资源、调用工具、获取提示模板等。
- 客户端的具体请求与参数遵循 MCP 协议的 JSON-RPC 传输规则，服务器端会将请求投递到相应的主线程操作并返回结果。
- 安装方式
- 服务器配置（给 MCP 客户端使用的配置示例，格式为 JSON，字段含义如下；请按实际环境填写，客户端客户端仅需读取 server 信息与连接参数）
{
"server_name": "AnkiMCP Server",
"command": "Anki Addon 启动时自动启动本地 MCP 服务器",
"args": {
"http_host": "127.0.0.1",
"http_port": 3141,
"mode": "http",
"cors_origins": [],
"cors_expose_headers": ["mcp-session-id", "mcp-protocol-version"],
"auto_connect_on_startup": true
}
}
说明：
- server_name：服务器名称，标识该 MCP 服务器的实例。
- command：启动命令在本实现中为 Anki 插件自动启动的本地 MCP 服务器的动作描述，客户端无需手动执行该命令。
- args：服务器运行参数，主要包括主机、端口、传输模式、跨域等设置。MCP 客户端需要读取这些信息以建立与服务器的连接。
- 基本使用方法
- MCP 客户端连接
- 将服务器地址设为 http://127.0.0.1:3141/，并按 MCP 客户端的规范将请求发送给服务器。
- 使用资源、工具、提示
- 通过 MCP 客户端的工具列表查看服务器暴露的工具名称，如 list_decks、addNote、get_due_cards 等，并按需要调用。
- 通过资源列表读取系统信息、查询语法、今日统计、集合统计等静态或动态资源，以获取 AI 需要的上下文信息。
- 使用 Prompts 获取可用的提示模板，结合对话场景进行上下文准备。
- 运行与调试
- 服务器在 Anki 启动时自动启动，若遇到依赖下载失败或端口占用等问题，请检查网络连接和端口占用情况，必要时可在设置中调整端口。
- MCP 客户端连接