Anki MCP

ทางการ

เซิร์ฟเวอร์ MCP ที่ช่วยให้ผู้ช่วย AI สามารถโต้ตอบกับ Anki ซึ่งเป็นแอปพลิเคชันบัตรคำศัพท์แบบเว้นระยะซ้ำได้

GitHub
539

คุณทำอะไรได้บ้างด้วย Anki MCP?

  • Review due cards — ขอให้ผู้ช่วยดึงการ์ดที่ถึงกำหนดจากเด็คที่ระบุและทดสอบคุณผ่าน get_due_cards และ present_card
  • Rate card performance — ให้ผู้ช่วยบันทึกคุณภาพคำตอบของคุณ (Again, Hard, Good, Easy) เพื่อจัดตารางทบทวนใหม่ผ่าน rate_card
  • Create custom flashcards — สั่งให้ผู้ช่วยสร้างประเภทโน้ตใหม่พร้อมฟิลด์ที่กำหนดเองและการจัดรูปแบบ RTL โดยใช้ createModel และ updateModelStyling จากนั้นเพิ่มโน้ตเป็นชุดด้วย addNotes
  • Manage note content — ค้นหาโน้ตด้วยไวยากรณ์คำสั่ง Anki (deck:, tag:, is:due) ผ่าน findNotes จากนั้นอัปเดตฟิลด์ด้วย updateNoteFields
  • Import media into cards — ขอให้ผู้ช่วยอัปโหลดรูปภาพจากเส้นทางในเครื่องหรือ URL ด้วย storeMediaFile และแทรกลงในฟิลด์ของโน้ตที่เลือกโดยใช้ guiSelectedNotes และ updateNoteFields
  • Organize decks and cards — สร้างเด็คแบบซ้อนกัน (Parent::Child) ด้วย createDeck ย้ายการ์ดระหว่างเด็คด้วย changeDeck หรือระงับการ์ดด้วย suspend เพื่อข้ามการ์ดเหล่านั้นระหว่างการทบทวน

เอกสาร

เซิร์ฟเวอร์ Anki MCP

Tests npm version

Anki + MCP Integration

ผสานรวม Anki เข้ากับผู้ช่วย AI ผ่าน Model Context Protocol

[!IMPORTANT] แนะนำให้ใช้ ส่วนเสริม AnkiMCP สำหรับการติดตั้งส่วนใหญ่

ส่วนเสริม (GitHub) เรียกใช้เซิร์ฟเวอร์ MCP ภายใน Anki โดยตรง ไม่ต้องติดตั้ง Node.js ไม่ต้องกำหนดค่า AnkiConnect และไม่ต้องเปิดกระบวนการแยกต่างหาก: ติดตั้งด้วยโค้ด 124672614, รีสตาร์ท Anki, และเซิร์ฟเวอร์จะพร้อมใช้งานทุกครั้งที่เปิด Anki รองรับการเข้าถึงผ่าน HTTP ในเครื่องและการเข้าถึงระยะไกลผ่านอุโมงค์ในตัว

พื้นที่เก็บข้อมูลนี้เป็นตัวเลือกที่เหมาะสมเมื่อคุณต้องการเฉพาะ:

  • การขนส่ง STDIO — Claude Desktop, Claude Code, Cursor, หรือไคลเอนต์ใดก็ตามที่เรียกใช้เซิร์ฟเวอร์เป็นกระบวนการย่อย
  • ชุด MCPB — การติดตั้ง .mcpb แบบคลิกเดียวสำหรับ Claude Desktop

สำหรับ HTTP, อุโมงค์, หรือไคลเอนต์บนเว็บ (claude.ai, ChatGPT), ส่วนเสริมเป็นเส้นทางที่ง่ายกว่าและรองรับได้ดีกว่า

พื้นที่เก็บข้อมูลนี้ไม่ได้ถูกยกเลิกการใช้งาน มันยังคงได้รับการดูแลและเผยแพร่ควบคู่ไปกับส่วนเสริมในฐานะส่วนหนึ่งของโครงการ ankimcp.ai เดียวกัน

เซิร์ฟเวอร์ Model Context Protocol (MCP) ที่ช่วยให้ผู้ช่วย AI สามารถโต้ตอบกับ Anki ซึ่งเป็นแอปพลิเคชันแฟลชการ์ดแบบเว้นระยะ

เปลี่ยนประสบการณ์ Anki ของคุณด้วยการโต้ตอบด้วยภาษาธรรมชาติ — เหมือนมีครูสอนพิเศษส่วนตัว ผู้ช่วย AI ไม่เพียงแต่นำเสนอคำถามและคำตอบ แต่ยังสามารถอธิบายแนวคิด ทำให้กระบวนการเรียนรู้มีส่วนร่วมและเป็นธรรมชาติมากขึ้น ให้บริบท และปรับให้เข้ากับสไตล์การเรียนรู้ของคุณ มันสามารถสร้างและแก้ไขโน้ตได้ทันที เปลี่ยนช่วงเวลาการเรียนของคุณให้เป็นการสนทนาที่มีชีวิตชีวา ฟีเจอร์เพิ่มเติมกำลังจะมาเร็วๆ นี้!

ตัวอย่างและบทช่วยสอน

สำหรับคำแนะนำที่ครอบคลุม ตัวอย่างจริง และบทช่วยสอนทีละขั้นตอนเกี่ยวกับการใช้เซิร์ฟเวอร์ MCP นี้กับ Claude Desktop โปรดเยี่ยมชม:

ankimcp.ai — เอกสารประกอบที่สมบูรณ์พร้อมตัวอย่างเชิงปฏิบัติและกรณีการใช้งาน

ดู docs/ สำหรับเอกสารประกอบเพิ่มเติม รวมถึง คู่มือการตั้งค่าผู้ตรวจทาน และสำรับ Anki ตัวอย่าง

ตัวอย่างกรณีการใช้งาน

พรอมต์สามตัวอย่างที่แสดงโฟลว์เครื่องมือที่เซิร์ฟเวอร์นี้เปิดใช้งาน:

  1. "ช่วยฉันทบทวนสำรับภาษาสเปนหน่อย" — ผู้ช่วยเสนอให้ซิงค์กับ AnkiWeb (sync), ดึงการ์ดที่ถึงกำหนด (get_due_cards พร้อมตัวกรองสำรับ), นำเสนอการ์ดแต่ละใบ (present_card), และบันทึกการให้คะแนนของคุณ (rate_card). บทสนทนาการเรียนที่เป็นธรรมชาติพร้อมคำอธิบายที่ปรับให้เหมาะกับคุณ

  2. "สร้างการ์ดคำศัพท์ภาษาอาหรับ 10 ใบพร้อมสไตล์ RTL" — ผู้ช่วยแสดงรายการประเภทโน้ต (modelNames), สร้างโมเดล RTL ที่กำหนดเองหากจำเป็น (createModel + updateModelStyling สำหรับ CSS จากขวาไปซ้าย), จากนั้นสร้างการ์ดเป็นชุด (addNotes)

  3. "นำเข้ารูปภาพนี้จากโฟลเดอร์ดาวน์โหลดของฉันไปที่ด้านหน้าของโน้ตที่เลือก" — ผู้ช่วยอัปโหลดไฟล์ในเครื่อง (storeMediaFile พร้อมเส้นทางไฟล์), อ่านโน้ตที่เลือกอยู่ในปัจจุบันจากเบราว์เซอร์ (guiSelectedNotes + notesInfo), และอัปเดตฟิลด์ด้านหน้าด้วยแท็ก <img> (updateNoteFields)

เครื่องมือที่มีให้

เซิร์ฟเวอร์เปิดเผย เครื่องมือ MCP 53 รายการ — เครื่องมือจำเป็น 42 รายการสำหรับการดำเนินการ Anki ในชีวิตประจำวัน และเครื่องมือ GUI 11 รายการที่ขับเคลื่อนอินเทอร์เฟซเดสก์ท็อป Anki สำหรับเวิร์กโฟลว์การแก้ไข/สร้างโน้ต

เครื่องมือจำเป็น

ทบทวนและศึกษา

  • sync - ซิงค์กับ AnkiWeb เพื่อดึงข้อมูลล่าสุดและส่งการเปลี่ยนแปลง
  • get_due_cards - รับการ์ดที่ถึงกำหนดทบทวน กรองตามสำรับได้ (ละเว้นคำตอบเว้นแต่ include_answer: true, ค่าเริ่มต้น false)
  • get_cards - รับการ์ดพร้อมการกรองที่ยืดหยุ่นตามสถานะ (ถึงกำหนด, ใหม่, กำลังเรียนรู้, ระงับ, ฝัง) และสำรับ (ละเว้นคำตอบเว้นแต่ include_answer: true, ค่าเริ่มต้น false)
  • present_card - แสดงการ์ดสำหรับทบทวนพร้อมด้านคำถาม/ด้านหน้า
  • rate_card - ให้คะแนนประสิทธิภาพการ์ด (อีกครั้ง, ยาก, ดี, ง่าย) และกำหนดเวลาการทบทวนครั้งถัดไป
  • forgetCards - รีเซ็ตการ์ดเป็นใหม่ ยกเลิกกำหนดเวลาโดยไม่บันทึกการทบทวน
  • setDueDate - กำหนดเวลาการ์ดใหม่ให้ถึงกำหนดใน N วัน ("0", "3-7", "1!") โดยไม่บันทึกการทบทวน
  • areSuspended - ตรวจสอบสถานะการระงับสำหรับการ์ดหนึ่งใบหรือมากกว่าโดยไม่เปลี่ยนแปลงอะไร
  • suspend - ระงับการ์ดเพื่อให้ข้ามระหว่างการทบทวนจนกว่าจะยกเลิกการระงับ
  • unsuspend - ยกเลิกการระงับการ์ดเพื่อให้กลับสู่การทบทวนปกติ

หมายเหตุ: forgetCards และ setDueDate เปลี่ยนกำหนดเวลา โดยไม่ บันทึกการทบทวน ซึ่งเป็นสิ่งที่แยกออกจาก rate_card. ใช้เมื่อกำหนดเวลาของการ์ดผิดมากกว่าเมื่อตอบ: การให้คะแนนการ์ด Again เพื่อฝังลึกลงไปจะบันทึกความผิดพลาดจริงและลดปัจจัยความง่ายลง ทำให้กำหนดเวลาในอนาคตและสถิติของคุณคลาดเคลื่อนอย่างถาวร forgetCards ล้างช่วงเวลาและเริ่มการ์ดใหม่; setDueDate เก็บประวัติการ์ดไว้และเพียงเลื่อนการทบทวนครั้งถัดไป

หมายเหตุ: เนื้อหาการ์ด front/back ถูกเรนเดอร์ต่อการ์ดจากเทมเพลตของตัวเอง (ตามที่ Anki แสดง) ดังนั้นการ์ดแบบกลับด้านและการ์ด cloze จะแสดงทิศทางที่ถูกต้อง ข้อความคงที่ที่เพิ่มโดยเทมเพลตการ์ดของคุณจะปรากฏในผลลัพธ์ด้วย

การจัดการสำรับ

  • listDecks - แสดงรายการสำรับทั้งหมด เลือกได้พร้อมสถิติคิวการศึกษาต่อสำรับ
  • deckStats - รับสถิติที่ครอบคลุมสำหรับสำรับเดียว (คิวการศึกษา, นับสถานะการ์ดจริง, การกระจายความง่าย/ช่วงเวลา)
  • createDeck - สร้างสำรับว่างใหม่ (รองรับ Parent::Child, สูงสุด 2 ระดับ)
  • changeDeck - ย้ายการ์ดไปยังสำรับอื่น (สร้างหากไม่มี)

หมายเหตุ: สถิติสำรับมีสองรูปแบบ บล็อก counts (และทุกอย่างที่ listDecks รายงาน) สะท้อนเบราว์เซอร์สำรับของ Anki: การ์ดที่ถึงกำหนดวันนี้ จำกัดด้วยขีดจำกัดรายวันของใหม่/ทบทวน ของแต่ละสำรับ ไม่รวมการ์ดที่ระงับและฝัง — ดังนั้น review ไม่ใช่ "การ์ดที่โตเต็มที่" และกลุ่ม other เป็นเพียงเศษที่เหลือทางคณิตศาสตร์ (ส่วนใหญ่เป็นการ์ดทบทวนที่ยังไม่ถึงกำหนดวันนี้บวกการ์ดใหม่ที่เกินขีดจำกัดรายวัน) สำหรับยอดรวมตามสถานะจริง ใช้บล็อก states บน deckStats / collection_stats ซึ่งนับ new, learning, review, suspended และ buried ผ่านการค้นหา Anki โดยไม่สนใจวันที่ครบกำหนดและขีดจำกัดรายวัน

การจัดการโน้ต

  • addNote - สร้างโน้ตเดียวพร้อมฟิลด์และแท็กที่ระบุ
  • addNotes - สร้างเป็นชุดสูงสุด 100 โน้ตที่ใช้สำรับและโมเดลร่วมกัน (รองรับความสำเร็จบางส่วน)
  • findNotes - ค้นหาโน้ตโดยใช้ไวยากรณ์การค้นหา Anki (deck:, tag:, is:due, ฯลฯ)
  • notesInfo - รับข้อมูลโดยละเอียดเกี่ยวกับโน้ต (ฟิลด์, แท็ก, ประเภทโน้ต, ID การ์ด; CSS มาจาก modelStyling)
  • updateNoteFields - อัปเดตฟิลด์โน้ตที่มีอยู่ (รองรับ CSS, รองรับเนื้อหา HTML)
  • deleteNotes - ลบโน้ตและการ์ดที่เกี่ยวข้องทั้งหมด (ทำลายล้าง ต้องยืนยัน)

การจัดการแท็ก

  • getTags - รับแท็กทั้งหมดในคอลเลกชัน (ใช้รายการแรกเพื่อหลีกเลี่ยงการซ้ำ)
  • addTags - เพิ่มแท็กที่คั่นด้วยช่องว่างให้กับโน้ตที่ระบุ
  • removeTags - ลบแท็กที่คั่นด้วยช่องว่างจากโน้ตที่ระบุ
  • replaceTags - เปลี่ยนชื่อแท็กในโน้ตที่ระบุ
  • clearUnusedTags - ลบแท็กกำพร้าที่ไม่มีโน้ตใดใช้ (ทำลายล้าง)

การจัดการสื่อ

  • getMediaFilesNames - แสดงรายการไฟล์สื่อใน collection.media, กรองตามรูปแบบได้
  • retrieveMediaFile - ดาวน์โหลดไฟล์สื่อเป็นเนื้อหา base64
  • storeMediaFile - อัปโหลดสื่อจากข้อมูล base64, เส้นทางไฟล์สัมบูรณ์, หรือ URL
  • deleteMediaFile - ลบไฟล์สื่อจาก collection.media (ทำลายล้าง)

💡 แนวทางปฏิบัติที่ดีที่สุดสำหรับรูปภาพ:

  • ✅ ใช้เส้นทางไฟล์ (เช่น /Users/you/image.png) - รวดเร็วและมีประสิทธิภาพ
  • ✅ ใช้ URL (เช่น https://example.com/image.jpg) - ดาวน์โหลดโดยตรง
  • ❌ หลีกเลี่ยง base64 - ช้ามากและสิ้นเปลืองโทเค็น

เพียงบอก Claude ว่ารูปภาพอยู่ที่ไหน มันจะจัดการอัปโหลดโดยอัตโนมัติด้วยวิธีที่มีประสิทธิภาพที่สุด

การจัดการโมเดล/เทมเพลต

  • modelNames - แสดงรายการประเภทโน้ต/โมเดลทั้งหมดที่มี
  • modelFieldNames - รับชื่อฟิลด์สำหรับประเภทโน้ตเฉพาะ
  • modelStyling - รับข้อมูลสไตล์ CSS สำหรับประเภทโน้ต
  • modelTemplates - รับเทมเพลตการ์ด (HTML ด้านหน้าและด้านหลัง) สำหรับประเภทโน้ต
  • createModel - สร้างประเภทโน้ตใหม่พร้อมฟิลด์, เทมเพลตการ์ด, และ CSS ที่กำหนดเอง (เช่น โมเดล RTL)
  • updateModelStyling - อัปเดตสไตล์ CSS สำหรับประเภทโน้ตที่มีอยู่ (ใช้กับทุกการ์ด)
  • updateModelTemplates - อัปเดตเทมเพลตการ์ด (HTML ด้านหน้าและด้านหลัง) สำหรับประเภทโน้ตที่มีอยู่ (ใช้กับทุกการ์ด)
  • addModelField - เพิ่มฟิลด์ใหม่ให้กับประเภทโน้ตที่มีอยู่ (ต่อท้ายหรือแทรกที่ตำแหน่งเฉพาะ)
  • removeModelField - ลบฟิลด์จากประเภทโน้ตที่มีอยู่ (ลบเนื้อหาจากโน้ตทั้งหมด; ต้องยืนยันอย่างชัดเจน)
  • renameModelField - เปลี่ยนชื่อฟิลด์ในประเภทโน้ตที่มีอยู่ (Anki เขียนอ้างอิงชื่อเก่าในเทมเพลตการ์ดใหม่)
  • repositionModelField - เปลี่ยนตำแหน่งของฟิลด์ภายในประเภทโน้ตที่มีอยู่

สถิติ

  • collection_stats - สถิติรวมทุกสำรับพร้อมการแยกย่อยต่อสำรับและการนับสถานะการ์ดทั้งคอลเลกชัน
  • review_stats - การวิเคราะห์ประวัติการทบทวน (รูปแบบเวลา, ตัวชี้วัดการคงอยู่, ช่วงการศึกษาต่อเนื่อง)

เครื่องมือ GUI

เครื่องมือที่ขับเคลื่อนอินเทอร์เฟซเดสก์ท็อป Anki มีไว้สำหรับเวิร์กโฟลว์การแก้ไข/สร้างโน้ตและการจัดการสำรับ ไม่ใช่ สำหรับช่วงการทบทวน

  • guiBrowse - เปิดเบราว์เซอร์การ์ดและค้นหาการ์ด
  • guiSelectCard - เลือกการ์ดเฉพาะในเบราว์เซอร์การ์ด
  • guiSelectedNotes - รับ ID ของโน้ตที่เลือกอยู่ในปัจจุบันในเบราว์เซอร์การ์ด
  • guiAddCards - เปิดกล่องโต้ตอบเพิ่มการ์ดพร้อมรายละเอียดโน้ตที่ตั้งไว้
  • guiEditNote - เปิดตัวแก้ไขโน้ตสำหรับโน้ตเฉพาะ
  • guiDeckOverview - เปิดกล่องโต้ตอบภาพรวมสำรับสำหรับสำรับเฉพาะ
  • guiDeckBrowser - เปิดกล่องโต้ตอบเบราว์เซอร์สำรับ
  • guiCurrentCard - รับข้อมูลเกี่ยวกับการ์ดปัจจุบันในโหมดทบทวน (รวมคำตอบ; เกิดข้อผิดพลาดนอกโหมดทบทวน)
  • guiShowQuestion - แสดงด้านคำถามของการ์ดปัจจุบัน
  • guiShowAnswer - แสดงด้านคำตอบของการ์ดปัจจุบัน
  • guiUndo - เลิกทำการกระทำล่าสุดใน Anki

ข้อกำหนดเบื้องต้น

  • Anki พร้อมติดตั้งปลั๊กอิน AnkiConnect
  • Node.js 22.12.0+

การติดตั้ง

มีหลายวิธีในการติดตั้งเซิร์ฟเวอร์ลงบนเครื่องของคุณ เมื่อติดตั้งแล้ว ไปที่ การเชื่อมต่อไคลเอนต์ AI เพื่อเชื่อมต่อกับผู้ช่วย AI ของคุณ — ในเครื่องหรือระยะไกล

npm (global หรือ npx)

วิธีติดตั้งเซิร์ฟเวอร์แบบทั่วไป เหมาะสำหรับไคลเอนต์ MCP ใดก็ตามที่เรียกใช้โดยตรง

ติดตั้งแบบ global สำหรับไคลเอนต์ที่รันคำสั่ง ankimcp:

npm install -g @ankimcp/anki-mcp-server

หรือรันตามความต้องการโดยไม่ต้องติดตั้ง:

npx @ankimcp/anki-mcp-server

ชุด MCPB (แนะนำสำหรับ Claude Desktop)

วิธีที่ง่ายที่สุดในการติดตั้งเซิร์ฟเวอร์ MCP นี้สำหรับ Claude Desktop:

  1. ดาวน์โหลดชุด .mcpb ล่าสุดจากหน้า Releases
  2. ใน Claude Desktop, ติดตั้งส่วนขยาย:
    • วิธีที่ 1: ไปที่ การตั้งค่า → ส่วนขยาย, จากนั้นลากและวางไฟล์ .mcpb
    • วิธีที่ 2: ไปที่ การตั้งค่า → นักพัฒนา → ส่วนขยาย → ติดตั้งส่วนขยาย, จากนั้นเลือกไฟล์ .mcpb
  3. กำหนดค่า URL AnkiConnect หากจำเป็น (ค่าเริ่มต้นคือ http://localhost:8765)
  4. รีสตาร์ท Claude Desktop

แค่นั้นเอง! ชุดรวมทุกสิ่งที่จำเป็นในการรันเซิร์ฟเวอร์ในเครื่อง

สำหรับผู้ตรวจสอบ MCP Directory ของ Anthropic: คำแนะนำแบบ zero-to-integration พร้อมสำรับตัวอย่างที่เติมข้อมูลไว้แล้วอยู่ใน docs/reviewer-setup.md

ติดตั้งจากซอร์ส (สำหรับการพัฒนา)

สำหรับการพัฒนาหรือการใช้งานขั้นสูง (การรันชุดทดสอบต้องใช้ Node.js 24.9+ — สคริปต์ npm test โหลดแพ็กเกจ NestJS 12 ที่เป็น ESM-only ผ่าน require(esm) ซึ่ง Jest รองรับเฉพาะที่นั่นเท่านั้น; ข้อกำหนดรันไทม์สำหรับ การใช้งาน เซิร์ฟเวอร์ยังคงเป็น 22.12.0+):

npm install
npm run build

การเชื่อมต่อ AI Client

มีสองวิธีที่ผู้ช่วย AI จะเข้าถึงเซิร์ฟเวอร์นี้ ขึ้นอยู่กับว่าผู้ช่วยนั้นรันอยู่ที่ใด:

  • Local — เซิร์ฟเวอร์รันบนเครื่องเดียวกับ AI client (Claude Desktop, Cursor, Cline, Zed หรือเซสชันเบราว์เซอร์ในเครื่อง) ใช้ STDIO สำหรับ MCP client แบบเดสก์ท็อป และ HTTP สำหรับเครื่องมือบนเว็บในเครื่อง
  • Remote — AI ที่โฮสต์หรืออยู่ระยะไกล (เช่น ChatGPT หรือ Claude.ai ในคลาวด์) จำเป็นต้องเข้าถึง Anki ที่รันบนเครื่องของคุณ ใช้ Tunnel ที่จัดการไว้ (✅ แนะนำ — มีการยืนยันตัวตน) หรือทางเลือกที่ไม่มีการยืนยันตัวตนที่เบากว่า คือ ngrok

Local

เซิร์ฟเวอร์รันบนคอมพิวเตอร์เครื่องเดียวกับ AI client ของคุณและสื่อสารกับ AnkiConnect บน localhost

STDIO (การรวมระบบในเครื่องหลัก)

STDIO เป็น transport มาตรฐานสำหรับ MCP client แบบเดสก์ท็อปในเครื่อง — Claude Desktop, Cursor IDE, Cline, Zed Editor, opencode และอื่นๆ client จะเปิดเซิร์ฟเวอร์เป็นซับโพรเซสและสื่อสารผ่าน standard input/output

Client ที่รองรับ:

  • Claude Desktop
  • Cursor IDE - โปรแกรมแก้ไขโค้ดที่ขับเคลื่อนด้วย AI
  • Cline - ส่วนขยาย VS Code สำหรับความช่วยเหลือด้วย AI
  • Zed Editor - โปรแกรมแก้ไขโค้ดที่ทันสมัยและรวดเร็ว
  • opencode - เอเจนต์เขียนโค้ดด้วย AI ในเทอร์มินัล
  • MCP client อื่นๆ ที่รองรับ transport แบบ STDIO

สำหรับ Claude Desktop บันเดิล MCPB เป็นวิธีที่ง่ายที่สุด สำหรับ client อื่นๆ ให้กำหนดค่าแพ็กเกจ npm ด้วยแฟล็ก --stdio

การกำหนดค่า - เลือกหนึ่งวิธี:

วิธีที่ 1: ใช้ npx (แนะนำ - ไม่ต้องติดตั้ง)

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

วิธีที่ 2: ใช้การติดตั้งแบบ global

ขั้นแรก ติดตั้งแบบ global:

npm install -g @ankimcp/anki-mcp-server

จากนั้นกำหนดค่า:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "ankimcp",
      "args": ["--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

opencode ใช้รูปแบบของตัวเอง — เซิร์ฟเวอร์อยู่ภายใต้ mcp, คำสั่งเป็นอาร์เรย์เดียว และตัวแปรสภาพแวดล้อมอยู่ภายใต้ environment:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "anki-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "enabled": true,
      "environment": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

ตำแหน่งไฟล์กำหนดค่า:

  • Cursor IDE: ~/.cursor/mcp.json (macOS/Linux) หรือ %USERPROFILE%\.cursor\mcp.json (Windows)
  • Cline: เข้าถึงได้ผ่าน UI การตั้งค่าใน VS Code
  • Zed Editor: ติดตั้งเป็นส่วนขยาย MCP ผ่านตลาดส่วนขยาย
  • opencode: opencode.json ในโฟลเดอร์โปรเจกต์ของคุณ หรือ ~/.config/opencode/opencode.json แบบ global

สำหรับคุณสมบัติเฉพาะ client และการแก้ไขปัญหา โปรดดูเอกสารของ MCP client ของคุณ ดูเพิ่มเติม เชื่อมต่อกับ Claude Desktop สำหรับการกำหนดค่าที่ชี้ไปยัง dist/main-stdio.js ที่สร้างไว้แล้วโดยตรง

HTTP (เครื่องมือบนเว็บในเครื่อง)

โหมด HTTP รันเซิร์ฟเวอร์เป็นเว็บเซิร์ฟเวอร์ในเครื่องที่พูดโปรโตคอล MCP Streamable HTTP เป็น transport ที่เครื่องมือ AI บนเว็บใช้เมื่อชี้ไปที่เครื่องของคุณ และยังเป็นสิ่งที่ตัวเลือก Remote เปิดเผยสู่โลกภายนอก โดยตัวมันเอง โหมด HTTP จะผูกกับ localhost เท่านั้น

ผูกเกินกว่า localhost? หากคุณส่ง --host 0.0.0.0 (หรือรันหลัง reverse proxy/โดเมนสาธารณะ) เซิร์ฟเวอร์จะยอมรับเฉพาะส่วนหัว Host แบบ loopback โดยค่าเริ่มต้นเพื่อป้องกัน DNS-rebinding — ตั้งค่า ALLOWED_HOSTS เป็นชื่อโฮสต์ที่ client ใช้ ดู การกำหนดค่าโหมด HTTP

การตั้งค่า - เลือกหนึ่งวิธี:

วิธีที่ 1: ใช้ npx (แนะนำ - ไม่ต้องติดตั้ง)

# Quick start
npx @ankimcp/anki-mcp-server

# With custom options
npx @ankimcp/anki-mcp-server --port 8080 --host 0.0.0.0
npx @ankimcp/anki-mcp-server --anki-connect http://localhost:8765

วิธีที่ 2: ใช้การติดตั้งแบบ global

# Install once
npm install -g @ankimcp/anki-mcp-server

# Run the server
ankimcp

# With custom options
ankimcp --port 8080 --host 0.0.0.0
ankimcp --anki-connect http://localhost:8765

วิธีที่ 3: ติดตั้งจากซอร์ส (สำหรับการพัฒนา)

npm install
npm run build
npm run start:prod:http

เพื่อให้เซิร์ฟเวอร์ HTTP ในเครื่องเข้าถึงได้โดย AI ที่โฮสต์ในคลาวด์ ให้ใช้ตัวเลือก Remote ด้านล่าง

Remote

AI ที่โฮสต์หรืออยู่ระยะไกล (เช่น ChatGPT หรือ Claude.ai ที่รันในคลาวด์) ไม่สามารถเข้าถึง localhost ได้โดยตรง ตัวเลือกเหล่านี้จะเปิดเผย Anki ในเครื่อง ของคุณสู่อินเทอร์เน็ต เพื่อให้ผู้ช่วยระยะไกลสามารถสื่อสารกับมันได้

Tunnel (✅ แนะนำ)

เส้นทางระยะไกลที่แนะนำ — มีการยืนยันตัวตนและปลอดภัย ต่างจากพอร์ตสาธารณะดิบ โหมด tunnel กำหนดให้คุณต้องเข้าสู่ระบบ (OAuth 2.0 device flow) ดังนั้น endpoint จะไม่เปิดให้ใครก็ตามที่เดา URL ได้

โหมด Tunnel ให้ผู้ช่วย AI บนเว็บเข้าถึง Anki ในเครื่อง ของคุณได้โดยไม่ต้องรัน tunnel ของคุณเอง เซิร์ฟเวอร์เชื่อมต่อออกไปยังบริการ tunnel ที่จัดการโดย AnkiMCP (wss://tunnel.ankimcp.ai) ผ่าน WebSocket และได้รับ URL สาธารณะ การยืนยันตัวตนถูกสร้างไว้แล้ว — ไม่ต้องมีบัญชี ngrok หรือโพรเซส tunnel แยก และคุณเข้าสู่ระบบเพียงครั้งเดียว

เข้าสู่ระบบ (OAuth device flow):

โหมด Tunnel ใช้ OAuth 2.0 Device Authorization Grant การเข้าสู่ระบบจะเปิดเบราว์เซอร์ของคุณไปยังหน้าให้อนุมัติโดยอัตโนมัติ โดยมีโค้ดฝังอยู่ใน URL แล้ว — ไม่ต้องพิมพ์อะไร แค่กดอนุมัติ (หากเบราว์เซอร์เปิดไม่ได้ เทอร์มินัลจะพิมพ์ URL สำหรับยืนยันและโค้ดให้ป้อนด้วยตนเองเป็นทางเลือกสำรอง) เมื่อสำเร็จ ข้อมูลประจำตัวจะถูกบันทึกไปยัง ~/.ankimcp/credentials.json (สิทธิ์ไฟล์ 0600)

# Pre-authenticate (optional — --tunnel will trigger this automatically if needed)
ankimcp --login
npx @ankimcp/anki-mcp-server --login

# Clear saved credentials
ankimcp --logout

เริ่ม tunnel:

# Connect to the managed tunnel service (wss://tunnel.ankimcp.ai)
ankimcp --tunnel
npx @ankimcp/anki-mcp-server --tunnel

# Override the tunnel server URL (must be ws:// or wss://) — e.g. for self-hosting
ankimcp --tunnel wss://my-tunnel.example.com

หากไม่มีข้อมูลประจำตัว --tunnel จะเริ่มขั้นตอนการเข้าสู่ระบบโดยอัตโนมัติก่อน แล้วจึงดำเนินการต่อกับ tunnel การเข้าสู่ระบบอัตโนมัตินี้ต้องใช้เทอร์มินัลแบบโต้ตอบ — เมื่อ stdout ไม่ใช่ TTY (systemd, headless Docker, CI) เซิร์ฟเวอร์จะล้มเหลวอย่างรวดเร็วและขอให้คุณรัน ankimcp --login ก่อน เมื่อเชื่อมต่อแล้ว URL tunnel สาธารณะจะถูกพิมพ์; กด Ctrl+C เพื่อตัดการเชื่อมต่อ แชร์ URL นั้นกับผู้ช่วย AI ของคุณ

ตัวแปรสภาพแวดล้อมโหมด Tunnel:

ตัวแปรคำอธิบายค่าเริ่มต้น
TUNNEL_SERVER_URLURL WebSocket ของเซิร์ฟเวอร์ tunnel (ค่าแฟล็ก --tunnel/--login จะแทนที่ค่านี้)wss://tunnel.ankimcp.ai
TUNNEL_AUTH_CLIENT_IDOAuth client ID สำหรับ device flow ขั้นสูง — จำเป็นเมื่อชี้ไปที่บริการ tunnel/auth ที่โฮสต์เองเท่านั้น(ในตัว)

endpoint การยืนยันตัวตนของ device flow (/auth/device, /auth/token) มาจาก TUNNEL_SERVER_URL ดังนั้นการชี้ --tunnel (หรือ TUNNEL_SERVER_URL) ไปที่โฮสต์อื่นจะย้ายการยืนยันตัวตนไปที่โฮสต์นั้นด้วย

วิธีการทำงาน: โหมด Tunnel รัน MCP server ในโพรเซสเดียวกันเบื้องหลัง transport ในหน่วยความจำ (TunnelTransport) transport นั้นเป็นเจ้าของ MCP server และเปลี่ยนเนื้อหาคำขอที่ส่งต่อแต่ละรายการเป็นการตอบสนอง และ TunnelClient เชื่อมต่อไปยังบริการ tunnel ระยะไกลผ่าน WebSocket — ส่งต่อคำขอ MCP เข้าและคำตอบออก AnkiConnect ยังคงเข้าถึงได้เฉพาะบนเครื่องของคุณเท่านั้น

การแก้ไขโปรโตคอล: เนื่องจาก tunnel เชื่อมต่อ MCP server ในโพรเซสเดียวกัน โหมด tunnel จึงให้บริการเฉพาะโปรโตคอล MCP รุ่นปี 2025 ในขณะที่โหมด STDIO และ HTTP ให้บริการทั้งรุ่นปี 2025 และรุ่นใหม่กว่า 2026-07-28 ทุกเครื่องมือทำงานเหมือนกันไม่ว่าจะด้วยวิธีใด — แต่ client ที่พูดเฉพาะรุ่น 2026-07-28 จะถูกปฏิเสธผ่าน tunnel ด้วยข้อผิดพลาดเวอร์ชันโปรโตคอล; รันโหมด STDIO หรือ HTTP สำหรับ client นั้น

ngrok (ทางเลือกที่ไม่มีการยืนยันตัวตน)

หากคุณต้องการเปิดเผย โหมด HTTP ในเครื่อง สู่สาธารณะโดยไม่มีบัญชีบน tunnel ที่จัดการไว้ แฟล็ก --ngrok ในตัวจะเปิดซับโพรเซส ngrok (src/services/ngrok.service.ts) และพิมพ์ URL สาธารณะในแบนเนอร์เริ่มต้น:

# One-time ngrok setup, then:
ankimcp --ngrok

เส้นทางนี้ไม่มีการยืนยันตัวตน — ใครก็ตามที่มี URL สามารถเข้าถึง Anki ของคุณได้ ดังนั้นจึงปลอดภัยน้อยกว่า Tunnel เลือกใช้ Tunnel เว้นแต่คุณมีเหตุผลเฉพาะที่จะจัดการ endpoint ngrok ของคุณเอง (ต้องติดตั้ง ngrok แบบ global และมี authtoken)

แฟล็ก --ngrok เปิด ngrok ด้วย --host-header=rewrite ดังนั้น ngrok จะเขียน Host ต้นทางใหม่เป็น localhost ก่อนส่งต่อ ซึ่งทำให้คำขออยู่ในรายการอนุญาต Host แบบ loopback (ดู การป้องกัน DNS-rebinding) โดยไม่ต้องเพิ่มโดเมน *.ngrok สาธารณะลงใน ALLOWED_HOSTS หากคุณรัน ngrok ด้วยตนเอง ให้ใช้แฟล็กเดียวกัน — ngrok http --host-header=rewrite 3000 — มิฉะนั้น ngrok จะส่งต่อชื่อโฮสต์ ngrok สาธารณะเป็น Host และเซิร์ฟเวอร์จะปฏิเสธด้วย 403

ตัวเลือก CLI (ทุกโหมด)

ankimcp [options]

Options:
  --stdio                        Run in STDIO mode (for MCP clients)
  --tunnel [url]                 Connect via the managed tunnel (authenticated)
  --login                        Authenticate for tunnel mode (OAuth device flow)
  --logout                       Clear saved tunnel credentials
  -p, --port <number>            Port to listen on (HTTP mode; default: 3000, or PORT env var)
  -h, --host <address>           Host to bind to (HTTP mode; default: 127.0.0.1, or HOST env var)
  -a, --anki-connect <url>       AnkiConnect URL (default: http://localhost:8765, or ANKI_CONNECT_URL env var)
  --ngrok                        Start ngrok tunnel (requires global ngrok installation)
  --read-only                    Run in read-only mode (blocks content changes and rescheduling; rating, suspend and sync still work)
  --help                         Show help message

Usage with npx (no installation needed):
  npx @ankimcp/anki-mcp-server                        # HTTP mode
  npx @ankimcp/anki-mcp-server --port 8080            # Custom port
  npx @ankimcp/anki-mcp-server --stdio                # STDIO mode
  npx @ankimcp/anki-mcp-server --tunnel               # Managed tunnel mode
  npx @ankimcp/anki-mcp-server --ngrok                # HTTP mode with ngrok tunnel
  npx @ankimcp/anki-mcp-server --read-only            # Read-only mode

Usage with global installation:
  npm install -g @ankimcp/anki-mcp-server             # Install once
  ankimcp                                             # HTTP mode
  ankimcp --port 8080                                 # Custom port
  ankimcp --stdio                                     # STDIO mode
  ankimcp --tunnel                                    # Managed tunnel mode
  ankimcp --ngrok                                     # HTTP mode with ngrok tunnel
  ankimcp --read-only                                 # Read-only mode

โหมดอ่านอย่างเดียว (ทุกโหมด)

แฟล็ก --read-only (หรือ READ_ONLY=true) บล็อกการเปลี่ยนแปลงเนื้อหาบันทึก, เด็ค, แท็ก, สื่อ และประเภทบันทึก รวมถึงการจัดตารางการ์ดด้วยตนเอง เมื่อเปิดใช้งาน:

  • การดำเนินการอ่านทั้งหมดทำงานตามปกติ (การเรียกดูเด็ค, การดูการ์ด, การค้นหาบันทึก)
  • การเปลี่ยนแปลงเหล่านี้ยังคงอนุญาต: การให้คะแนนการ์ดระหว่างการทบทวน (rate_card), การระงับ/ยกเลิกการระงับการ์ด (suspend, unsuspend), การซิงค์กับ AnkiWeb (sync) และเครื่องมือ GUI ที่นำทางหน้าต่างของ Anki (guiBrowse, guiDeckOverview, …)
  • การแก้ไขเนื้อหาถูกบล็อก (addNote, deleteNotes, createDeck, updateNoteFields, ฯลฯ); createDeck สำหรับเด็คที่มีอยู่แล้วยังคงสำเร็จ เนื่องจากไม่มีการเขียนอะไร
  • การจัดตารางด้วยตนเองถูกบล็อก: forgetCards (รีเซ็ตเป็นใหม่) และ setDueDate
  • guiUndo ถูกบล็อก เนื่องจากการเลิกทำสามารถย้อนการเปลี่ยนแปลงในคอลเลกชันได้
  • guiAddCards และ guiEditNote ถูกบล็อก เนื่องจากบันทึกที่เพิ่มหรือบันทึกในกล่องโต้ตอบที่เปิดขึ้นจะถูกเขียนลงในคอลเลกชัน
  • มีประโยชน์สำหรับการสำรวจข้อมูล Anki โดยไม่มีการเปลี่ยนแปลงเนื้อหาโดยไม่ตั้งใจ
# HTTP mode with read-only
ankimcp --read-only

# STDIO mode with read-only
ankimcp --stdio --read-only

# Can combine with other flags
ankimcp --ngrok --read-only

คุณยังสามารถเปิดใช้งานโหมดอ่านอย่างเดียวผ่านตัวแปรสภาพแวดล้อม:

READ_ONLY=true ankimcp

หรือในการกำหนดค่า MCP client:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio", "--read-only"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

เชื่อมต่อกับ Claude Desktop (โหมด Local)

คุณสามารถกำหนดค่าเซิร์ฟเวอร์ใน Claude Desktop ได้โดย:

  • ไปที่: Settings → Developer → Edit Config
  • หรือแก้ไขไฟล์กำหนดค่าด้วยตนเอง

การกำหนดค่า

เพิ่มสิ่งต่อไปนี้ในการกำหนดค่า Claude Desktop ของคุณ:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "node",
      "args": ["/path/to/anki-mcp-server/dist/main-stdio.js"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

แทนที่ /path/to/anki-mcp-server ด้วยเส้นทางโปรเจกต์จริงของคุณ

ตำแหน่งไฟล์กำหนดค่า

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

สำหรับรายละเอียดเพิ่มเติม ดู เอกสาร MCP อย่างเป็นทางการ

ตัวแปรสภาพแวดล้อม (ไม่บังคับ)

ตัวแปรคำอธิบายค่าเริ่มต้น
ANKI_CONNECT_URLURL AnkiConnecthttp://localhost:8765
ANKI_CONNECT_API_VERSIONเวอร์ชัน API6
ANKI_CONNECT_API_KEYคีย์ API หากกำหนดค่าใน AnkiConnect-
ANKI_CONNECT_TIMEOUTหมดเวลาคำขอในหน่วย ms5000
READ_ONLYเปิดใช้งานโหมดอ่านอย่างเดียว (true หรือ 1)false
PORTโหมด HTTP: พอร์ตที่ฟัง (แฟล็ก --port มีลำดับความสำคัญกว่า)3000
HOSTโหมด HTTP: ที่อยู่ที่ผูก (แฟล็ก --host มีลำดับความสำคัญกว่า)127.0.0.1
ALLOWED_HOSTSโหมด HTTP: ค่าส่วนหัว Host เพิ่มเติมที่ยอมรับนอกเหนือจาก loopback (ชื่อโฮสต์คั่นด้วยเครื่องหมายจุลภาค) จำเป็นเมื่อผูกกับที่อยู่ LAN/สาธารณะหรือรันหลัง reverse proxy ดู การกำหนดค่าโหมด HTTPloopback เท่านั้น
ALLOWED_ORIGINSโหมด HTTP: รายการอนุญาตรูปแบบ Origin/Referer ของเบราว์เซอร์คั่นด้วยเครื่องหมายจุลภาค (รองรับ wildcards เช่น https://*.ngrok.io)http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*
TUNNEL_SERVER_URLURL WebSocket ของเซิร์ฟเวอร์ tunnel (เฉพาะโหมด tunnel)wss://tunnel.ankimcp.ai
MEDIA_ALLOWED_TYPESประเภท MIME เพิ่มเติมที่อนุญาตสำหรับการนำเข้าเส้นทางไฟล์ (คั่นด้วยเครื่องหมายจุลภาค เช่น application/pdf)-
MEDIA_IMPORT_DIRจำกัดการนำเข้าเส้นทางไฟล์ไว้ที่ไดเรกทอรีนี้-
MEDIA_ALLOWED_HOSTSอนุญาตโฮสต์เครือข่ายส่วนตัวเฉพาะสำหรับการนำเข้า URL (คั่นด้วยเครื่องหมายจุลภาค เช่น 192.168.1.50,my-nas)-

ตัวอย่างการใช้งาน

การค้นหาและอัปเดตบันทึก

# Search for notes in a specific deck
findNotes(query: "deck:Spanish")

# Get detailed information about notes
notesInfo(notes: [1234567890, 1234567891])

# Update a note's fields (HTML content supported)
updateNoteFields(note: {
  id: 1234567890,
  fields: {
    "Front": "<b>¿Cómo estás?</b>",
    "Back": "How are you?"
  }
})

# Delete notes (requires confirmation)
deleteNotes(notes: [1234567890], confirmDeletion: true)

ตัวอย่างไวยากรณ์คำค้นหา Anki

เครื่องมือ findNotes รองรับไวยากรณ์คำค้นหาอันทรงพลังของ Anki:

  • "deck:DeckName" - บันทึกทั้งหมดในเด็คที่ระบุ
  • "tag:important" - บันทึกที่มีแท็ก "สำคัญ"
  • "is:due" - การ์ดที่ถึงกำหนดทบทวน
  • "is:new" - การ์ดใหม่ที่ยังไม่ได้ศึกษา
  • "added:7" - บันทึกที่เพิ่มใน 7 วันที่ผ่านมา
  • "front:hello" - บันทึกที่มีคำว่า "สวัสดี" ในช่องด้านหน้า
  • "flag:1" - บันทึกที่มีธงสีแดง
  • "prop:due<=2" - การ์ดที่ถึงกำหนดภายใน 2 วัน
  • "deck:Spanish tag:verb" - บันทึกเด็คภาษาสเปนที่มีแท็กคำกริยา (AND)
  • "deck:Spanish OR deck:French" - บันทึกจากเด็คใดเด็คหนึ่ง

หมายเหตุสำคัญ

การจัดการ CSS และ HTML

  • เครื่องมือ notesInfo คืนชื่อประเภทบันทึกของแต่ละบันทึก; ตัว CSS เองมาจาก modelStyling
  • เครื่องมือ updateNoteFields รองรับเนื้อหา HTML ในช่องและรักษารูปแบบ CSS
  • แต่ละโมเดลบันทึกมี CSS ของตัวเอง - ใช้ modelStyling เพื่อรับ CSS เฉพาะโมเดล

คำเตือนการอัปเดต

⚠️ สำคัญ: เมื่อใช้ updateNoteFields, อย่าดูบันทึกในเบราว์เซอร์ของ Anki ขณะอัปเดต มิฉะนั้นช่องจะไม่อัปเดตอย่างถูกต้อง ปิดเบราว์เซอร์หรือสลับไปยังบันทึกอื่นก่อนอัปเดต ดู ปัญหาที่ทราบ สำหรับรายละเอียดเพิ่มเติม

ความปลอดภัยในการลบ

เครื่องมือ deleteNotes ต้องมีการยืนยันอย่างชัดเจน (confirmDeletion: true) เพื่อป้องกันการลบโดยไม่ตั้งใจ การลบบันทึกจะลบการ์ดที่เกี่ยวข้องทั้งหมดอย่างถาวร

ความปลอดภัย

การตรวจสอบเส้นทางไฟล์สื่อและ URL

เครื่องมือสื่อ (storeMediaFile, retrieveMediaFile, deleteMediaFile) และช่องเสียง/รูปภาพ updateNoteFields รวมการตรวจสอบความปลอดภัยเพื่อป้องกันการใช้งานในทางที่ผิดผ่านการฉีดพรอมต์:

  • การนำเข้าเส้นทางไฟล์ จำกัดเฉพาะประเภทไฟล์สื่อเท่านั้น (รูปภาพ, เสียง, วิดีโอ) ไฟล์ที่ไม่ใช่สื่อ (เช่น คีย์ SSH, ข้อมูลรับรอง, ไฟล์กำหนดค่าเชลล์) จะถูกปฏิเสธตามประเภท MIME กำหนดค่า MEDIA_ALLOWED_TYPES เพื่ออนุญาตประเภทไฟล์เพิ่มเติม หรือ MEDIA_IMPORT_DIR เพื่อจำกัดการนำเข้าไปยังไดเรกทอรีที่ระบุ
  • การนำเข้า URL ถูกตรวจสอบการโจมตี SSRF คำขอไปยังเครือข่ายส่วนตัว (10.x, 172.16.x, 192.168.x), loopback (127.x), link-local (169.254.x) และโปรโตคอลที่ไม่ใช่ HTTP(S) จะถูกบล็อก กำหนดค่า MEDIA_ALLOWED_HOSTS เพื่ออนุญาตโฮสต์เครือข่ายส่วนตัวที่ระบุ
  • ชื่อไฟล์ ถูกทำความสะอาดเพื่อป้องกัน path traversal (เช่น ลำดับ ../../ จะถูกลบออก)

การป้องกันเหล่านี้ใช้กับ storeMediaFile, retrieveMediaFile, deleteMediaFile และช่องเสียง/รูปภาพ updateNoteFields

ช่องโหว่ path traversal รายงานโดย Hideaki Takahashi

การป้องกัน DNS-Rebinding (การขนส่ง HTTP)

เมื่อรันในโหมด HTTP เซิร์ฟเวอร์ตรวจสอบส่วนหัว Host ในทุกคำขอ โดยค่าเริ่มต้นยอมรับเฉพาะโฮสต์ loopback (localhost, 127.0.0.1, ::1) โดยไม่คำนึงถึงพอร์ต Host เป็นส่วนหัวที่เบราว์เซอร์ห้าม ดังนั้นหน้าเว็บที่เป็นอันตรายจึงไม่สามารถปลอมแปลงได้ — ซึ่งปิดเส้นทาง DNS-rebinding ที่หน้าที่ย้อนกลับมาถึงเซิร์ฟเวอร์ท้องถิ่นด้วย Host ที่ปลอมแปลงและไม่มี Origin และเข้าถึงเครื่องมือ MCP Host ที่ไม่อนุญาตจะถูกปฏิเสธด้วย 403

หากคุณผูกกับ 0.0.0.0, รันหลัง reverse proxy หรือเปิดเผยโดเมน tunnel สาธารณะ ให้ตั้งค่า ALLOWED_HOSTS (ชื่อโฮสต์คั่นด้วยเครื่องหมายจุลภาค) เพื่ออนุญาตโฮสต์เหล่านั้น เมื่อใช้ tunnel กับ ngrok เซิร์ฟเวอร์ใช้ --host-header=rewrite ดังนั้น upstream ยังคงเห็น Host loopback ดู การกำหนดค่าโหมด HTTP สำหรับรายการตัวเลือกทั้งหมด

ช่องโหว่ DNS-rebinding รายงานโดย avishaigo-commits และ yotampe-pluto

นโยบายความเป็นส่วนตัว

เซิร์ฟเวอร์ MCP นี้รันบนเครื่องของคุณและไม่เก็บข้อมูล telemetry, analytics หรือข้อมูลการใช้งานใดๆ

นโยบายฉบับเต็ม: https://ankimcp.ai/privacy/

  • การเก็บข้อมูล: เซิร์ฟเวอร์ไม่เก็บอะไรเลย มันทำหน้าที่เป็นตัวกลางระหว่างผู้ช่วย AI ของคุณและปลั๊กอิน AnkiConnect ในเครื่องของคุณ
  • การใช้งาน / การจัดเก็บ: ไม่มีการจัดเก็บฝั่งเซิร์ฟเวอร์ ข้อมูลแฟลชการ์ดทั้งหมดอยู่ใน Anki บนอุปกรณ์ของคุณเอง
  • การแบ่งปันกับบุคคลที่สาม: ไม่มี เซิร์ฟเวอร์สื่อสารกับ URL AnkiConnect ที่คุณกำหนดค่าเท่านั้น (ค่าเริ่มต้น: localhost) หากคุณเปิดใช้งานการซิงค์ AnkiWeb ในตัวของ Anki สิ่งนั้นเกิดขึ้นระหว่าง Anki ของคุณกับ AnkiWeb โดยตรง — อยู่นอกขอบเขตของเซิร์ฟเวอร์นี้
  • การเก็บรักษา: ไม่เกี่ยวข้อง — ไม่มีการเก็บข้อมูลฝั่งเซิร์ฟเวอร์
  • ติดต่อ: support@ankimcp.ai

ปัญหาที่ทราบ

สำหรับรายการปัญหาที่ทราบและข้อจำกัดอย่างครอบคลุม โปรดเยี่ยมชมเอกสารของเรา:

เอกสารปัญหาที่ทราบ

ข้อจำกัดที่สำคัญ

การอัปเดตบันทึกล้มเหลวเมื่อดูในเบราว์เซอร์

⚠️ สำคัญ: เมื่ออัปเดตบันทึกโดยใช้ updateNoteFields, การอัปเดตจะล้มเหลวอย่างเงียบๆ หากบันทึกกำลังถูกดูในหน้าต่างเบราว์เซอร์ของ Anki นี่เป็นข้อจำกัดของ AnkiConnect ต้นทาง

วิธีแก้ไข: ปิดเบราว์เซอร์หรือนำทางไปยังบันทึกอื่นก่อนอัปเดตเสมอ

สำหรับรายละเอียดเพิ่มเติมและปัญหาที่ทราบอื่นๆ ดู เอกสารฉบับเต็ม

การแก้ไขปัญหา

ข้อผิดพลาด ERR_REQUIRE_ESM

หากคุณเห็นข้อผิดพลาดเช่น:

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

หมายความว่าเวอร์ชัน Node.js ของคุณไม่ได้รับการสนับสนุน เซิร์ฟเวอร์ต้องการ Node.js 22.12.0+

หมายเหตุ: รันไทม์ขั้นต่ำที่รองรับคือ Node.js 22.12.0 Node.js 20 (Iron) ถึงจุดสิ้นสุดอายุการใช้งานเมื่อ 2026-04-30 และไม่ได้รับการสนับสนุนอีกต่อไป

ตรวจสอบเวอร์ชันของคุณ:

node --version

วิธีแก้ไข: อัปเดต Node.js เป็นเวอร์ชัน 22.12.0+ คุณสามารถดาวน์โหลดได้จาก nodejs.org หรือใช้ตัวจัดการเวอร์ชันเช่น nvm

การพัฒนา

โหมดการขนส่ง

เซิร์ฟเวอร์นี้รองรับโหมดการขนส่ง MCP สามแบบผ่าน จุดเข้าใช้งานแยกต่างหาก:

โหมด STDIO (ค่าเริ่มต้น)

  • สำหรับไคลเอนต์ MCP ในเครื่องเช่น Claude Desktop
  • ใช้มาตรฐาน input/output สำหรับการสื่อสาร
  • จุดเข้าใช้งาน: dist/main-stdio.js
  • รัน: npm run start:prod:stdio หรือ node dist/main-stdio.js
  • บันเดิล MCPB: ใช้โหมด STDIO

โหมด HTTP (Streamable HTTP)

  • สำหรับไคลเอนต์ MCP ระยะไกลและการรวมระบบบนเว็บ
  • ใช้โปรโตคอล MCP Streamable HTTP
  • จุดเข้าใช้งาน: dist/main-http.js
  • รัน: npm run start:prod:http หรือ node dist/main-http.js
  • พอร์ตเริ่มต้น: 3000 (กำหนดค่าได้ผ่านตัวแปรสภาพแวดล้อม PORT)
  • โฮสต์เริ่มต้น: 127.0.0.1 (กำหนดค่าได้ผ่านตัวแปรสภาพแวดล้อม HOST)
  • จุดสิ้นสุด MCP: http://127.0.0.1:3000/ (เส้นทางราก)

โหมด Tunnel (Managed WebSocket Tunnel)

  • สำหรับผู้ช่วย AI บนเว็บผ่านบริการ tunnel AnkiMCP ที่จัดการ พร้อมการตรวจสอบสิทธิ์ในตัว
  • เซิร์ฟเวอร์ MCP รันในกระบวนการหลังการขนส่งในหน่วยความจำ; TunnelTransport เป็นเจ้าของเซิร์ฟเวอร์ MCP และ TunnelClient เชื่อมต่อกับบริการ tunnel ผ่าน WebSocket
  • โปรโตคอล: ให้บริการเฉพาะ MCP revision ปี 2025 (STDIO และ HTTP ให้บริการ 2026-07-28 ด้วย)
  • จุดเข้าใช้งาน: dist/main-tunnel.js
  • รัน: node dist/main-tunnel.js --tunnel (หรือ ankimcp --tunnel)
  • การตรวจสอบสิทธิ์: ankimcp --login / ankimcp --logout; ข้อมูลรับรองเก็บที่ ~/.ankimcp/credentials.json (0600)
  • Dev: npm run start:dev:tunnel (โหมด watch, รัน --tunnel --debug)

การสร้าง

npm run build  # Builds once, creates dist/ with all three entry points

main-stdio.js, main-http.js และ main-tunnel.js ทั้งหมดถูกสร้างในไดเรกทอรี dist/ เดียวกัน เลือกว่าจะรันอันไหนตามความต้องการของคุณ

การกำหนดค่าโหมด HTTP

ตัวแปรสภาพแวดล้อม:

  • PORT - พอร์ตเซิร์ฟเวอร์ HTTP (ค่าเริ่มต้น: 3000)
  • HOST - ที่อยู่ผูก (ค่าเริ่มต้น: 127.0.0.1 สำหรับ localhost เท่านั้น)
  • ALLOWED_HOSTS - ค่าของส่วนหัว Host เพิ่มเติมที่ยอมรับนอกเหนือจากชุด loopback ในตัว (localhost, 127.0.0.1, ::1) คั่นด้วยเครื่องหมายจุลภาค เฉพาะชื่อโฮสต์และไม่คำนึงถึงพอร์ต ค่าเริ่มต้น: loopback เท่านั้น
  • ALLOWED_ORIGINS - รายการอนุญาตรูปแบบ Origin/Referer ของเบราว์เซอร์ คั่นด้วยเครื่องหมายจุลภาค; รองรับ wildcards (เช่น https://*.ngrok.io) ค่าเริ่มต้น: http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*
  • LOG_LEVEL - ระดับการบันทึก (ค่าเริ่มต้น: info)

ความปลอดภัย:

  • การตรวจสอบส่วนหัว Host (การป้องกัน DNS-rebinding) — ทุกคำขอ HTTP ต้องมีส่วนหัว Host ที่ตรงกับรายการอนุญาต โดยค่าเริ่มต้นยอมรับเฉพาะโฮสต์ loopback (localhost, 127.0.0.1, ::1) โดยไม่คำนึงถึงพอร์ต Host เป็นส่วนหัวที่เบราว์เซอร์ห้าม ดังนั้นหน้าเว็บที่เป็นอันตรายจึงไม่สามารถปลอมแปลงได้ — ซึ่งปิดเส้นทาง DNS-rebinding ที่หน้าที่ย้อนกลับมาถึงเซิร์ฟเวอร์ด้วย Host ที่ปลอมแปลงและไม่มี Origin Host ที่ไม่อนุญาตจะถูกปฏิเสธด้วย 403
  • การตรวจสอบส่วนหัว Origin — คำขอจากเบราว์เซอร์ที่มี Origin/Referer ที่มีอยู่แต่ไม่อนุญาตจะถูกปฏิเสธ คำขอที่ ไม่มี Origin (curl, Postman, ไคลเอนต์ MCP-over-HTTP) จะได้รับอนุญาต; การตรวจสอบ Host คือการป้องกันการ rebinding
  • ผูกกับ localhost (127.0.0.1) โดยค่าเริ่มต้น
  • ไม่มีการตรวจสอบสิทธิ์ในเวอร์ชันปัจจุบัน (วางแผนรองรับ OAuth)

การเปิดเผยโหมด HTTP นอกเหนือจาก localhost — หากคุณผูกกับที่อยู่ LAN/สาธารณะหรือวางเซิร์ฟเวอร์หลัง reverse proxy หรือโดเมนสาธารณะ คุณ ต้อง ตั้งค่า ALLOWED_HOSTS เป็นชื่อโฮสต์ที่ไคลเอนต์จะใช้ มิฉะนั้นทุกคำขอที่ไม่ใช่ loopback จะถูกปฏิเสธด้วย 403:

# Bind to all interfaces and accept the machine's LAN name + a public domain
ALLOWED_HOSTS=my-nas.local,anki.example.com PORT=8080 HOST=0.0.0.0 node dist/main-http.js

เมื่อคุณผูกกับ 0.0.0.0/:: โดยไม่มี ALLOWED_HOSTS, เซิร์ฟเวอร์บันทึกคำเตือนการเริ่มต้นว่าเฉพาะส่วนหัว Host loopback จะถูกยอมรับ

Docker / reverse proxy / โดเมนสาธารณะ: กฎเดียวกันนี้ใช้ ใน Docker คำขอโดยปกติมาถึงด้วยชื่อโฮสต์ที่เผยแพร่ของคอนเทนเนอร์หรือ Host ของ proxy ดังนั้นตั้งค่า ALLOWED_HOSTS ตามนั้น reverse proxy (nginx, Caddy, Traefik) ควรส่งต่อ Host เดิมและมีชื่อโฮสต์นั้นอยู่ใน ALLOWED_HOSTS หรือเขียน Host upstream ใหม่เป็น localhost การรวม --ngrok ในตัวจัดการสิ่งนี้โดยอัตโนมัติ (ดูด้านล่าง)

ตัวอย่าง: โหมดการรัน

# Development - STDIO mode (watch mode with auto-rebuild)
npm run start:dev:stdio

# Development - HTTP mode (watch mode with auto-rebuild)
npm run start:dev:http

# Production - STDIO mode
npm run start:prod:stdio
# or
node dist/main-stdio.js

# Production - HTTP mode
npm run start:prod:http
# or
PORT=8080 HOST=0.0.0.0 node dist/main-http.js

การสร้างบันเดิล MCPB

เพื่อสร้างบันเดิล MCPB ที่แจกจ่ายได้:

npm run mcpb:bundle

คำสั่งนี้จะ:

  1. ซิงค์เวอร์ชันจาก package.json ไปยัง manifest.json
  2. ลบไฟล์ .mcpb เก่า
  3. สร้างโปรเจกต์ TypeScript
  4. แพ็คเกจ dist/ และ node_modules/ ลงในไฟล์ .mcpb
  5. รัน mcpb clean เพื่อลบ devDependencies (ปรับขนาดบันเดิลจาก ~47MB เป็น ~10MB)

ไฟล์ผลลัพธ์จะถูกตั้งชื่อ anki-mcp-server-X.X.X.mcpb และสามารถแจกจ่ายสำหรับการติดตั้งคลิกเดียว

สิ่งที่รวมในบันเดิล

บันเดิล MCPB รวม:

  • JavaScript ที่คอมไพล์แล้ว (ไดเรกทอรี dist/ - รวมจุดเข้าใช้งานทั้งสาม)
  • เฉพาะ dependencies สำหรับการผลิต (node_modules/ - devDependencies ถูกลบโดย mcpb clean)
  • ข้อมูลเมตาของแพ็คเกจ (package.json)
  • การกำหนดค่า Manifest (manifest.json - กำหนดค่าให้ใช้ main-stdio.js)
  • ไอคอน (icon.png)

ไฟล์ต้นฉบับ การทดสอบ และการกำหนดค่าการพัฒนาจะถูกแยกออกโดยอัตโนมัติผ่าน .mcpbignore

การบันทึกใน Claude Desktop

เมื่อรันเป็นส่วนขยาย MCPB ใน Claude Desktop บันทึกจะถูกเขียนไปที่:

ตำแหน่งบันทึก: ~/Library/Logs/Claude/ (macOS)

บันทึกถูกแบ่งออกเป็นหลายไฟล์:

  • main.log - บันทึกแอปพลิเคชันทั่วไปของ Claude Desktop
  • mcp-server-Anki MCP Server.log - ข้อความโปรโตคอล MCP สำหรับส่วนขยายนี้
  • mcp.log - บันทึก MCP รวมจากเซิร์ฟเวอร์ทั้งหมด

หมายเหตุ: ผลลัพธ์ของ logger pino (ข้อความ INFO, ERROR, WARN จากโค้ดเซิร์ฟเวอร์) ไปที่ stderr และปรากฏในไฟล์บันทึกเฉพาะ MCP Claude Desktop กำหนดว่าไฟล์บันทึกใดได้รับข้อความใด แต่โดยทั่วไป:

  • การเริ่มต้นแอปพลิเคชันและการสื่อสารโปรโตคอล MCP → บันทึกเฉพาะ MCP
  • การบันทึกภายในเซิร์ฟเวอร์ (pino) → ทั้งบันทึกเฉพาะ MCP และบางครั้ง main.log

เพื่อดูบันทึกแบบเรียลไทม์:

tail -f ~/Library/Logs/Claude/mcp-server-Anki\ MCP\ Server.log

การดีบักเซิร์ฟเวอร์ MCP

คุณสามารถดีบักเซิร์ฟเวอร์ MCP โดยใช้ MCP Inspector และแนบดีบักเกอร์จาก IDE ของคุณ (WebStorm, VS Code ฯลฯ)

หมายเหตุสำหรับโหมด HTTP: เมื่อทดสอบโหมด HTTP (Streamable HTTP) กับ MCP Inspector ให้ใช้ "Connection Type: Via Proxy" เพื่อหลีกเลี่ยงข้อผิดพลาด CORS

ขั้นตอนที่ 1: กำหนดค่าเซิร์ฟเวอร์ดีบักใน MCP Inspector

mcp-inspector-config.json มีการกำหนดค่าเซิร์ฟเวอร์ดีบักอยู่แล้ว:

{
  "mcpServers": {
    "stdio-server-debug": {
      "type": "stdio",
      "command": "node",
      "args": ["--inspect-brk=9229", "dist/main-stdio.js"],
      "env": {
        "MCP_SERVER_NAME": "anki-mcp-stdio-debug",
        "MCP_SERVER_VERSION": "1.0.0",
        "LOG_LEVEL": "debug"
      },
      "note": "Anki MCP server with debugging enabled on port 9229"
    }
  }
}

ขั้นตอนที่ 2: เริ่ม Debug Server

รัน MCP Inspector พร้อมกับ debug server:

npm run inspector:debug

การดำเนินการนี้จะเริ่ม server โดยเปิดใช้งาน Node.js debugging บนพอร์ต 9229 และหยุดการทำงานชั่วคราวที่บรรทัดแรก

ขั้นตอนที่ 3: แนบ Debugger จาก IDE ของคุณ

WebStorm
  1. ไปที่ Run → Edit Configurations
  2. เพิ่มการกำหนดค่า Attach to Node.js/Chrome ใหม่
  3. ตั้งค่าพอร์ตเป็น 9229
  4. คลิก Debug เพื่อแนบ
VS Code
  1. เปิดแผง Debug (Ctrl+Shift+D / Cmd+Shift+D)
  2. เลือกการกำหนดค่า Debug MCP Server (Attach)
  3. กด F5 เพื่อแนบ

ขั้นตอนที่ 4: ตั้ง Breakpoints และ Debug

เมื่อแนบแล้ว คุณสามารถ:

  • ตั้ง breakpoints ในไฟล์ซอร์ส TypeScript ของคุณ
  • เรียกดูการทำงานของโค้ดทีละขั้นตอน
  • ตรวจสอบตัวแปรและ call stack
  • ใช้คอนโซล debug สำหรับการประเมินนิพจน์

Debugger จะทำงานร่วมกับ source maps ทำให้คุณสามารถ debug โค้ด TypeScript ต้นฉบับแทนที่จะเป็น JavaScript ที่คอมไพล์แล้ว

การ Debug กับ Claude Desktop

คุณยังสามารถ debug MCP server ในขณะที่มันทำงานภายใน Claude Desktop ได้โดยการเปิดใช้งาน Node.js debugger และแนบ IDE ของคุณ

ขั้นตอนที่ 1: กำหนดค่า Claude Desktop สำหรับการ Debug

อัปเดตการกำหนดค่า Claude Desktop ของคุณเพื่อเปิดใช้งานการ debug:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "anki-mcp": {
      "command": "node",
      "args": [
        "--inspect=9229",
        "<path_to_project>/anki-mcp-server/dist/main-stdio.js"
      ],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

การเปลี่ยนแปลงที่สำคัญ: เพิ่ม --inspect=9229 ก่อนพาธไปยัง dist/main-stdio.js

ตัวเลือก Debug:

  • --inspect=9229 - เริ่ม debugger ทันที ไม่บล็อก (แนะนำ)
  • --inspect-brk=9229 - หยุดการทำงานจนกว่า debugger จะแนบ (สำหรับการแก้ไขปัญหาเริ่มต้น)

ขั้นตอนที่ 2: รีสตาร์ท Claude Desktop

หลังจากบันทึกการกำหนดค่าแล้ว ให้รีสตาร์ท Claude Desktop MCP server จะทำงานโดยเปิดใช้งานการ debug บนพอร์ต 9229

ขั้นตอนที่ 3: แนบ Debugger จาก IDE ของคุณ

WebStorm
  1. ไปที่ Run → Edit Configurations
  2. คลิกปุ่ม + และเลือก Attach to Node.js/Chrome
  3. กำหนดค่า:
    • Name: Attach to Anki MCP (Claude Desktop)
    • Host: localhost
    • Port: 9229
    • Attach to: Node.js < 8 หรือ Chrome or Node.js > 6.3 (ขึ้นอยู่กับเวอร์ชัน WebStorm)
  4. คลิก OK
  5. คลิก Debug (Shift+F9) เพื่อแนบ
VS Code
  1. เพิ่มใน .vscode/launch.json:
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Anki MCP (Claude Desktop)",
      "port": 9229,
      "skipFiles": ["<node_internals>/**"],
      "sourceMaps": true,
      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
    }
  ]
}
  1. เปิดแผง Debug (Ctrl+Shift+D / Cmd+Shift+D)
  2. เลือก Attach to Anki MCP (Claude Desktop)
  3. กด F5 เพื่อแนบ

ขั้นตอนที่ 4: Debug แบบเรียลไทม์

เมื่อแนบแล้ว คุณสามารถ:

  • ตั้ง breakpoints ในไฟล์ซอร์ส TypeScript ของคุณ (เช่น src/mcp/primitives/essential/tools/create-model.tool.ts)
  • ใช้ Claude Desktop ตามปกติ - breakpoints จะหยุดเมื่อมีการเรียกใช้เครื่องมือ
  • เรียกดูการทำงานของโค้ดทีละขั้นตอน
  • ตรวจสอบตัวแปรและ call stack
  • ใช้คอนโซล debug

ตัวอย่าง: ตั้ง breakpoint ใน create-model.tool.ts ที่บรรทัด 119 จากนั้นถาม Claude ให้สร้างโมเดลใหม่ Debugger จะหยุดที่ breakpoint ของคุณ!

หมายเหตุ: Debugger จะยังคงแนบอยู่ตราบเท่าที่ Claude Desktop ยังทำงานอยู่ คุณสามารถถอด/แนบใหม่ได้ตลอดเวลาโดยไม่ต้องรีสตาร์ท Claude Desktop

คำสั่ง Build

npm run build              # Build the project (compile TypeScript to JavaScript)
npm run start:dev:stdio    # STDIO mode with watch (auto-rebuild)
npm run start:dev:http     # HTTP mode with watch (auto-rebuild)
npm run type-check         # Run TypeScript type checking
npm run lint               # Run ESLint
npm run mcpb:bundle        # Sync version, clean, build, and create MCPB bundle

การทดสอบแพ็คเกจ npm (ในเครื่อง)

ทดสอบแพ็คเกจ npm ในเครื่องก่อนเผยแพร่:

# 1. Create local package
npm run pack:local         # Builds and creates @ankimcp/anki-mcp-server-*.tgz

# 2. Install globally from local package
npm run install:local      # Installs from ./@ankimcp/anki-mcp-server-*.tgz

# 3. Test the command
ankimcp                    # Runs HTTP server on port 3000

# 4. Uninstall when done testing
npm run uninstall:local    # Removes global installation

วิธีการทำงาน:

  • npm pack สร้างไฟล์ .tgz ที่เหมือนกับสิ่งที่ npm publish จะสร้าง
  • การติดตั้งจาก .tgz จำลองสิ่งที่ผู้ใช้ได้รับจาก npm install -g ankimcp
  • วิธีนี้ช่วยให้คุณทดสอบประสบการณ์ผู้ใช้ทั้งหมดก่อนเผยแพร่ไปยัง npm

คำสั่งการทดสอบ

npm test              # Run all tests
npm run test:unit     # Run unit tests only
npm run test:tools    # Run tool-specific tests
npm run test:workflows # Run workflow integration tests
npm run test:e2e      # Run end-to-end tests
npm run test:cov      # Run tests with coverage report
npm run test:watch    # Run tests in watch mode
npm run test:debug    # Run tests with debugger
npm run test:ci       # Run tests for CI (silent, with coverage)

ความครอบคลุมการทดสอบ

โปรเจกต์นี้รักษาเกณฑ์ความครอบคลุมขั้นต่ำ 70% สำหรับ:

  • Branches
  • Functions
  • Lines
  • Statements

รายงานความครอบคลุมจะถูกสร้างในไดเรกทอรี coverage/

การกำหนดเวอร์ชัน

โปรเจกต์นี้ปฏิบัติตาม Semantic Versioning ด้วยแนวทางการพัฒนาแบบ pre-1.0:

  • 0.x.x - เวอร์ชัน Beta/Development (ระยะปัจจุบัน)

    • 0.1.x - การแก้ไขข้อบกพร่องและแพตช์
    • 0.2.0+ - ฟีเจอร์ใหม่หรือการปรับปรุงเล็กน้อย
    • การเปลี่ยนแปลงที่ทำลายความเข้ากันได้ สามารถทำได้ในเวอร์ชัน 0.x

  • 1.0.0 - เวอร์ชันเสถียรแรก

    • จะเผยแพร่เมื่อ API มีความเสถียรและผ่านการทดสอบ
    • การเปลี่ยนแปลงที่ทำลายความเข้ากันได้จะต้องเพิ่มเวอร์ชันหลัก (2.0.0, ฯลฯ)

สถานะปัจจุบัน: 0.27.0 - การพัฒนา beta ที่ใช้งานอยู่ ฟีเจอร์ล่าสุดรวมถึงการวิเคราะห์การทบทวนทั้งคอลเลกชัน (review_stats ตอนนี้รวมข้อมูลทุกสำรับเมื่อละเว้น deck), การจัดการฟิลด์โมเดล (addModelField, removeModelField, renameModelField, repositionModelField), การสร้างโน้ตแบบกลุ่ม (addNotes), การทำอุโมงค์ ngrok แบบบูรณาการ (แฟล็ก --ngrok), การจัดการไฟล์สื่อ, การจัดการโมเดล/เทมเพลต และสถิติสำรับที่ครอบคลุม API อาจเปลี่ยนแปลงตามความคิดเห็นและการทดสอบ

วิวัฒนาการสเปก MCPB

โปรเจกต์นี้กำหนดเป้าหมายสเปกบันเดิล MCPB ของ Anthropic ซึ่งยังคงพัฒนา เราติดตามสเปกที่ https://github.com/modelcontextprotocol/mcpb และอาจแนะนำการเปลี่ยนแปลงที่ทำลายความเข้ากันได้เพื่อให้สอดคล้อง การเปลี่ยนแปลงที่ทำลายความเข้ากันได้ได้รับอนุญาตภายใต้รูปแบบเวอร์ชัน 0.x.x

โปรเจกต์ที่คล้ายกัน

หากคุณกำลังสำรวจการบูรณาการ Anki MCP นี่คือโปรเจกต์อื่น ๆ ในพื้นที่นี้:

scorzeth/anki-mcp-server

  • สถานะ: ดูเหมือนจะถูกทิ้งร้าง (ไม่มีการอัปเดตล่าสุด)
  • การนำ Anki MCP integration ไปใช้ในช่วงแรก

nailuoGG/anki-mcp-server

  • แนวทาง: การนำไปใช้แบบน้ำหนักเบา ไฟล์เดียว
  • สถาปัตยกรรม: โครงสร้างโค้ดแบบ Procedural โดยมีเครื่องมือทั้งหมดในไฟล์เดียว
  • เหมาะสำหรับ: กรณีการใช้งานง่าย ๆ การพึ่งพาน้อยที่สุด

เหตุผลที่โปรเจกต์นี้แตกต่าง:

  • สถาปัตยกรรมระดับองค์กร: สร้างบน NestJS พร้อม dependency injection
  • การออกแบบแบบโมดูลาร์: เครื่องมือแต่ละตัวเป็นคลาสแยกที่มีการแยกความรับผิดชอบที่ชัดเจน
  • การบำรุงรักษา: ง่ายต่อการขยายด้วยฟีเจอร์ใหม่โดยไม่ต้องแก้ไขโค้ดที่มีอยู่
  • การทดสอบ: ชุดทดสอบที่ครอบคลุมพร้อมข้อกำหนดความครอบคลุม 70%
  • ความปลอดภัยของประเภท: TypeScript ที่เข้มงวดพร้อมการตรวจสอบ Zod
  • การจัดการข้อผิดพลาด: การจัดการข้อผิดพลาดที่แข็งแกร่งพร้อมข้อเสนอแนะที่เป็นประโยชน์ต่อผู้ใช้
  • พร้อมสำหรับการผลิต: การบันทึกที่เหมาะสม การรายงานความคืบหน้า และการสนับสนุนบันเดิล MCPB
  • ความสามารถในการปรับขนาด: สามารถเติบโตจากเครื่องมือพื้นฐานไปจนถึงเวิร์กโฟลว์ที่ซับซ้อนได้อย่างง่ายดาย

กรณีการใช้งาน: หากคุณต้องการพื้นฐานที่แข็งแกร่งสำหรับการสร้างการบูรณาการ Anki ขั้นสูงหรือวางแผนที่จะขยายฟังก์ชันการทำงานอย่างมีนัยสำคัญ แนวทางสถาปัตยกรรมของโปรเจกต์นี้ทำให้ง่ายต่อการบำรุงรักษาและปรับขนาดเมื่อเวลาผ่านไป

ลิงก์ที่มีประโยชน์

ใบอนุญาตและการระบุแหล่งที่มา

โปรเจกต์นี้ได้รับอนุญาตภายใต้ MIT License — ดู LICENSE สำหรับข้อความเต็ม

ลิขสิทธิ์ © 2026 Anatoly Tarnavsky

การระบุแหล่งที่มาของบุคคลที่สาม

  • Anki® เป็นเครื่องหมายการค้าจดทะเบียนของ Ankitects Pty Ltd โปรเจกต์นี้เป็นเครื่องมือบุคคลที่สามที่ไม่เป็นทางการและไม่เกี่ยวข้องกับ รับรองโดย หรือสนับสนุนโดย Ankitects Pty Ltd โลโก้ Anki ใช้ภายใต้ใบอนุญาตทางเลือกสำหรับการอ้างอิง Anki พร้อมลิงก์ไปยัง https://apps.ankiweb.net สำหรับแอปพลิเคชัน Anki อย่างเป็นทางการ โปรดเยี่ยมชม https://apps.ankiweb.net

  • Model Context Protocol (MCP) เป็นมาตรฐานเปิดโดย Anthropic โลโก้ MCP มาจาก ที่เก็บเอกสาร MCP อย่างเป็นทางการ และใช้ภายใต้ MIT License สำหรับข้อมูลเพิ่มเติมเกี่ยวกับ MCP โปรดเยี่ยมชม https://modelcontextprotocol.io

  • นี่เป็นโปรเจกต์อิสระที่เชื่อมโยงเทคโนโลยี Anki และ MCP เครื่องหมายการค้า เครื่องหมายบริการ ชื่อทางการค้า ชื่อผลิตภัณฑ์ และโลโก้ทั้งหมดเป็นทรัพย์สินของเจ้าของตามลำดับ