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

ปัญหาการติดตั้งส่วนใหญ่แบ่งได้เป็นสี่กลุ่ม: คีย์ API ไปไม่ถึงเซิร์ฟเวอร์ บริดจ์ @maguyva/mcp ไม่ยอมเริ่มทำงาน หารีโพซิทอรีไม่เจอ หรือไคลเอนต์เชื่อมต่อไม่ได้เลย ไล่ดูส่วนที่ตรงกับอาการของคุณ

ทุกคำขอจะยืนยันตัวตนด้วยคีย์ API ของคุณ ซึ่งส่งไปเป็นเฮดเดอร์ Authorization: Bearer หรือเป็นเฮดเดอร์ X-API-Key หากไคลเอนต์ตั้งค่าเฮดเดอร์แรกไม่ได้ ถ้าการเรียกเครื่องมือถูกปฏิเสธ:

• ตรวจสอบว่าคีย์ของคุณขึ้นต้นด้วยพรีฟิกซ์ mgv_
• ตรวจสอบว่าคุณเปลี่ยนตัวยึดตำแหน่ง mgv_xxxx ในตัวอย่างการกำหนดค่าเป็นคีย์จริงจาก app.maguyva.ai แล้ว
• ถ้าการกำหนดค่าของคุณอ่านคีย์จาก MAGUYVA_API_KEY ให้ยืนยันว่าตัวแปรนี้ถูกตั้งค่าไว้ในสภาพแวดล้อมที่ไคลเอนต์ของคุณเปิดขึ้นมาจริง ๆ ค่า export ของ shell ที่ใส่ไว้ใน ~/.zshrc หรือ ~/.bashrc จะมีผลก็ต่อเมื่อโหลด shell ใหม่ — และแอป GUI บางตัวก็อาจไม่รับค่าเหล่านี้เลย ถ้าไม่แน่ใจ ให้เขียนคีย์ลงในการกำหนดค่าโดยตรง: ในเฮดเดอร์ Authorization ของการกำหนดค่ารีโมตแบบเนทีฟ (Bearer ตามด้วยคีย์ของคุณ) หรือในบล็อก env ของการกำหนดค่าที่ใช้บริดจ์ @maguyva/mcp
• ตรวจสอบว่าคีย์ยังไม่หมดอายุหรือถูกเพิกถอน

หากไคลเอนต์ใช้ตัวเชื่อม @maguyva/mcp ระบบจะเริ่มกระบวนการในเครื่องที่เชื่อมต่อกับเซิร์ฟเวอร์ระยะไกลของ Maguyva:

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

ถ้าเซิร์ฟเวอร์ไม่เคยขึ้นในไคลเอนต์ของคุณเลย หรือขึ้นมาแล้วตัดการเชื่อมต่อทันที:

• ตรวจสอบว่า npx ใช้งานได้ใน PATH ของคุณ — บริดจ์ต้องการ Node.js ที่ติดตั้งใช้งานได้ รัน npx -y @maguyva/mcp --help ในเทอร์มินัลเพื่อยืนยันว่ามันเริ่มทำงานได้
• ตรวจสอบไวยากรณ์ของการกำหนดค่า MCP ในไคลเอนต์ของคุณ — ไฟล์ JSON ที่ผิดรูปแบบจะล้มเหลวแบบเงียบ ๆ ในบางไคลเอนต์
• ไคลเอนต์หลายตัวไม่ต้องใช้บริดจ์เลยด้วยซ้ำ Claude Code ใช้ปลั๊กอิน Maguyva (/plugin install maguyva@maguyva) ส่วน Cursor, VS Code, Devin Desktop และ Zed เชื่อมต่อกับเซิร์ฟเวอร์รีโมตแบบเนทีฟด้วยเฮดเดอร์ Bearer (Zed ผ่าน context_servers) บริดจ์มีไว้สำหรับไคลเอนต์ที่ส่งเฮดเดอร์นั้นจากการกำหนดค่าของตัวเองไม่ได้ เช่น Claude Desktop ซึ่ง claude_desktop_config.json เริ่มได้เฉพาะเซิร์ฟเวอร์ในเครื่อง ตัวเชื่อมแบบกำหนดเองของ Claude Desktop ส่งเฮดเดอร์คำขอ authorization ได้ แต่เฮดเดอร์คำขอยังเป็นเบต้าสำหรับองค์กรจำนวนจำกัด

• ตรวจสอบว่ารีโพซิทอรีเชื่อมต่อและจัดทำดัชนีใน app.maguyva.ai
• ตรวจสอบรูปแบบ: "owner/repo" กำหนดเป้าหมายแบรนช์เริ่มต้น "owner/repo:branch" กำหนดเป้าหมายแบรนช์เฉพาะ (เช่น "owner/repository:develop")
• ตรวจสอบให้แน่ใจว่าบัญชีของคุณมีสิทธิ์เข้าถึงรีโพซิทอรี
• ใช้ repository_context(action="info", repository="...") เพื่อตรวจสอบวิธีจับคู่รีโพซิทอรี โดยไม่ต้องระบุพารามิเตอร์ repository เฉพาะเมื่อไคลเอนต์ MCP กำหนดค่าเริ่มต้นสำหรับคำขอนั้น หรือเมื่อคีย์เข้าถึงได้เพียงรีโพซิทอรีเดียว

• ทดสอบการเชื่อมต่อไปยัง https://maguyva.tools/mcp จากเครื่องของคุณ — พร็อกซีและไฟร์วอลล์ขององค์กรมักเป็นตัวการ
• ตรวจสอบว่า API token ของคุณยังใช้ได้และไม่หมดอายุ
• ตรวจสอบการกำหนดค่าของไคลเอนต์อีกครั้งเทียบกับ คู่มือการติดตั้ง สำหรับไคลเอนต์ของคุณ — ตำแหน่งไฟล์การกำหนดค่าและรูปแบบต่างกันไปในแต่ละไคลเอนต์

หลังจากเปลี่ยนแปลงอะไรก็ตาม ให้ถามเอเจนต์ของคุณว่า "ฉันเชื่อมต่อรีโพซิทอรีไหนไว้บ้าง?" — วิธีนี้จะยืนยันการเชื่อมต่อแบบครบวงจร จากนั้นลองถามคำถามจริงเกี่ยวกับรีโพของคุณ คุณควรจะเห็นคำตอบพร้อมพาธไฟล์และเลขบรรทัดจากรีโพซิทอรีที่เชื่อมต่ออยู่