mcpField
A
anki-connect

anki-connect

github.com/intellectronica生産性298897 回インストール27 週間前に更新
リポジトリ

anki-connect について

anki-connectは、ローカルのAnkiConnect HTTP APIを通じてAnkiを操作するスキルです。コマンドラインで操作を実行・確認する用途向けで、変更前に確認を求めます。

主な機能

  1. 01ローカルHTTP API経由でAnkiを操作
  2. 02JSONリクエストの作成と実行
  3. 03ノートやカードの検索と内容確認
  4. 04API操作のバッチ処理
  5. 05変更前にユーザー確認を要求

活用シーン

  1. 01条件に合うノートやカードを検索
  2. 02ノート内容を確認し変更範囲を把握
  3. 03確認後にカードやノートを追加・更新
  4. 04デッキ、タグ、メディアファイルを管理

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/intellectronica/agent-skills --skill anki-connect

インストール後、Claude Code で/anki-connectを入力して読み込まれたか確認します。

詳細

AnkiConnect

概要

AnkiConnect のローカル HTTP API を通じて、Anki を確実に操作できるようにします。このスキルを使って、ユーザーのリクエストを AnkiConnect のアクションに変換し、JSON リクエストを作成して、curl/jq（または同等のツール）で実行し、安全に結果を解釈します。

前提条件と環境

  • Anki が起動していない場合は Anki を起動し、AnkiConnect サーバーが http://127.0.0.1:8765（デフォルト）で応答するまで待ちます。curl を使って準備状況を確認してください。たとえば、curl -sS http://127.0.0.1:8765 は Anki-Connect を返すはずです。

安全性と確認ポリシー（重要）

重要 — 例外なし

ノートまたはカードに対する破壊的な操作や変更操作（追加、更新、削除、再スケジュール、一時停止、一時停止解除、デッキの変更、フィールドやタグの変更）を行う前に、必ずユーザーに確認を求めてください。利用可能な場合は AskUserQuestion ツールを使用し、そうでない場合はチャットで尋ねてください。複数の API 呼び出し（例：検索＋更新＋検証）が必要な場合でも、論理上ひとまとまりの操作につき確認を求めるのは 1 回だけにしてください。意図と対象範囲ごとに確認をまとめてください（例：「クエリ X に一致する 125 件のノートを更新します」）。

以下は、デフォルトで確認が必要です。

  • ノート：addNote、addNotes、updateNoteFields、updateNoteTags、updateNote、updateNoteModel、deleteNotes、removeEmptyNotes、replaceTags、replaceTagsInAllNotes、clearUnusedTags。
  • カード：setEaseFactors、setSpecificValueOfCard、suspend、unsuspend、forgetCards、relearnCards、answerCards、setDueDate、changeDeck。
  • カードやノートに実質的な変更を加えるデッキまたはモデルの変更（デッキの削除、モデルの編集）。上記に明示されていない操作でも確認を求めてください。

API の基本事項

リクエスト形式

すべてのリクエストは、以下を含む JSON です。

  • action：アクション名を示す文字列
  • version：API バージョン（ユーザーが指定しない限り 6 を使用）
  • params：パラメーターのオブジェクト（任意）
レスポンス形式

すべてのレスポンスは、以下を含む JSON です。

  • result：戻り値
  • error：成功時は null、エラー時はエラーを説明する文字列

result を使用する前に、必ず error を確認してください。

権限
  • 信頼されていないオリジンから操作する場合は、最初に requestPermission を使用してください。任意のオリジンを受け付けるアクションはこれだけです。
  • 互換性を確認するために version を使用してください。古いバージョンでは、version が 4 以下の場合、レスポンスに error フィールドがないことがあります。

curl + jq のパターン

JSON の構築とレスポンスの解析には jq を使うことを推奨します。リクエストは明示的で構造化された形式にしてください。

最小限のリクエストテンプレート
jq -n --arg action "deckNames" --argjson version 6 '{action:$action, version:$version}' \
| curl -sS http://127.0.0.1:8765 -X POST -H 'Content-Type: application/json' -d @-
params を使用する場合
jq -n \
	--arg action "findNotes" \
	--argjson version 6 \
	--arg query "deck:French tag:verbs" \
	'{action:$action, version:$version, params:{query:$query}}' \
| curl -sS http://127.0.0.1:8765 -X POST -H 'Content-Type: application/json' -d @-
result/error の処理
curl -sS http://127.0.0.1:8765 -X POST -H 'Content-Type: application/json' -d @- \
| jq -e 'if .error then halt_error(1) else .result end'
複数のアクションをまとめて実行する

往復回数を減らし、データ変更を伴うアクションを 1 回の確認の対象としてまとめるには、multi を使用します。

jq -n --argjson version 6 --arg query "deck:French" \
	'{action:"multi", version:$version, params:{actions:[
		{action:"findNotes", params:{query:$query}},
		{action:"notesInfo", params:{notes:[]}} 
	]}}' \
| curl -sS http://127.0.0.1:8765 -X POST -H 'Content-Type: application/json' -d @-

連鎖させる場合は、空の配列を前のアクションの結果に置き換えてください。CLI で使用する場合、スクリプト言語を使わない限り、2 回に分けて呼び出します。

基本的なワークフローのガイド

1) 接続とバージョンを確認する
  • requestPermission を呼び出します（安全）。
  • version を呼び出して API レベルを確認し、リクエストでは version: 6 を使用します。
2) 対応しているアクションを確認する
  • scopes: ["actions"] を指定して apiReflect を使用し、対応しているアクションを一覧表示します。
  • この一覧を使って、ユーザーの意図をアクション名に対応付けます。
3) ユーザーのリクエストをアクションの順序に落とし込む
  • 読み取り専用操作と破壊的な操作を区別します。
  • ノートやカードに対する破壊的な操作または変更操作では、対象範囲と件数を示して、1 回だけ確認を求めます。
  • 変更の前にプレビューを行うには、findNotes／findCards と notesInfo／cardsInfo を優先して使用します。
4) 実行して検証する
  • 呼び出しを順番に実行します。
  • 各レスポンスの error を確認します。
  • 結果の概要と、返された ID を報告します。

よくあるタスクのレシピ（CLI 向け）

デッキを一覧表示する
  • アクション：deckNames
デッキを作成する
  • アクション：createDeck
  • カードまたはノートを変更するワークフローの一環としてデッキを作成する場合は、確認が必要です。
ノート／カードを検索する
  • アクション：findNotes、findCards
  • Anki の検索構文を使用します（下記の「検索構文の簡単なメモ」を参照してください）。
プレビュー用ノートデータ
  • アクション：notesInfo（ノート ID）
ノートの追加
  • アクション：addNote、addNotes
  • 確認が必要です。
  • 事前チェックには canAddNotes または canAddNotesWithErrorDetail を使用してください。
ノートのフィールドまたはタグの更新
  • アクション：updateNoteFields、updateNoteTags、または統合アクションの updateNote
  • 確認が必要です。
  • 警告：ブラウザーでノートを開いた状態にしないでください。更新が反映されない場合があります。
ノートの削除
  • アクション：deleteNotes
  • 確認が必要です。
カードの一時停止／一時停止解除
  • アクション：suspend、unsuspend
  • 確認が必要です。
カードをデッキに移動
  • アクション：changeDeck
  • 確認が必要です。
期日の設定または再スケジュール
  • アクション：setDueDate
  • 確認が必要です。
メディアのアップロード／ダウンロード
  • アクション：storeMediaFile、retrieveMediaFile、getMediaFilesNames、getMediaDirPath、deleteMediaFile
  • アップロードには base64（data）、ファイルパス（path）、または URL（url）を使用してください。
同期
  • アクション：sync

検索構文のクイックノート（findNotes／findCards 用）

  • 用語はスペースで区切ります。デフォルトでは用語は AND で結合されます。
  • or、括弧、- を使って NOT ロジックを指定します。
  • deck:Name、tag:tagname、note:ModelName、card:CardName を使用します。
  • front:... またはその他のフィールド名を使用して、フィールドで絞り込みます。
  • 正規表現には re:、単語境界検索には w:、アクセント記号を無視するには nc: を使用します。
  • カードの状態を絞り込むには、is:due、is:new、is:learn、is:review、is:suspended、is:buried を使用します。
  • 間隔や期日などのプロパティを検索するには、prop: を使用します。
  • 必要に応じて、引用符またはバックスラッシュで特殊文字をエスケープします。

アクションカタログ（対応表として使用）

カードアクション
  • getEaseFactors
  • setEaseFactors
  • setSpecificValueOfCard
  • suspend
  • unsuspend
  • suspended
  • areSuspended
  • areDue
  • getIntervals
  • findCards
  • cardsToNotes
  • cardsModTime
  • cardsInfo
  • forgetCards
  • relearnCards
  • answerCards
  • setDueDate
デッキアクション
  • deckNames
  • deckNamesAndIds
  • getDecks
  • createDeck
  • changeDeck
  • deleteDecks
  • getDeckConfig
  • saveDeckConfig
  • setDeckConfigId
  • cloneDeckConfigId
  • removeDeckConfigId
  • getDeckStats
グラフィカルアクション
  • guiBrowse
  • guiSelectCard
  • guiSelectedNotes
  • guiAddCards
  • guiEditNote
  • guiAddNoteSetData
  • guiCurrentCard
  • guiStartCardTimer
  • guiShowQuestion
  • guiShowAnswer
  • guiAnswerCard
  • guiUndo
  • guiDeckOverview
  • guiDeckBrowser
  • guiDeckReview
  • guiImportFile
  • guiExitAnki
  • guiCheckDatabase
  • guiPlayAudio
メディアアクション
  • storeMediaFile
  • retrieveMediaFile
  • getMediaFilesNames
  • getMediaDirPath
  • deleteMediaFile
その他のアクション
  • requestPermission
  • version
  • apiReflect
  • sync
  • getProfiles
  • getActiveProfile
  • loadProfile
  • multi
  • exportPackage
  • importPackage
  • reloadCollection
モデルアクション
  • modelNames
  • modelNamesAndIds
  • findModelsById
  • findModelsByName
  • modelFieldNames
  • modelFieldDescriptions
  • modelFieldFonts
  • modelFieldsOnTemplates
  • createModel
  • modelTemplates
  • modelStyling
  • updateModelTemplates
  • updateModelStyling
  • findAndReplaceInModels
  • modelTemplateRename
  • modelTemplateReposition
  • modelTemplateAdd
  • modelTemplateRemove
  • modelFieldRename
  • modelFieldReposition
  • modelFieldAdd
  • modelFieldRemove
  • modelFieldSetFont
  • modelFieldSetFontSize
  • modelFieldSetDescription
ノートアクション
  • addNote
  • addNotes
  • canAddNotes
  • canAddNotesWithErrorDetail
  • updateNoteFields
  • updateNote
  • updateNoteModel
  • updateNoteTags
  • getNoteTags
  • addTags
  • removeTags
  • getTags
  • clearUnusedTags
  • replaceTags
  • replaceTagsInAllNotes
  • findNotes
  • notesInfo
  • notesModTime
  • deleteNotes
  • removeEmptyNotes
統計アクション
  • getNumCardsReviewedToday
  • getNumCardsReviewedByDay
  • getCollectionStatsHTML
  • cardReviews
  • getReviewsOfCards
  • getLatestReviewID
  • insertReviews

注意事項と落とし穴

  • AnkiConnect が一時停止しないように、macOS では Anki を前面に表示するか、App Nap を無効にしてください。
  • ノートを更新する際は、ブラウザーエディターで表示されていないことを確認してください。表示中の場合、更新が適用されないことがあります。
  • importPackage のパスは、クライアントではなく Anki の collection.media フォルダーからの相対パスです。
  • deleteDecks でデッキと一緒にカードを削除するには、cardsToo: true が必要です。

リソース

このスキルに必要なスクリプトやアセットはありません。

コメント

Markdown 対応