Milvus MCP Server

ทางการ

Search, Query and interact with data in your Milvus Vector Database.

GitHub
233

เอกสาร

MCP Server สำหรับ Milvus

Model Context Protocol (MCP) เป็นโปรโตคอลแบบเปิดที่ช่วยให้สามารถผสานรวมระหว่างแอปพลิเคชัน LLM กับแหล่งข้อมูลและเครื่องมือภายนอกได้อย่างราบรื่น ไม่ว่าคุณจะกำลังสร้าง IDE ที่ขับเคลื่อนด้วย AI, ปรับปรุงอินเทอร์เฟซแชท, หรือสร้างเวิร์กโฟลว์ AI แบบกำหนดเอง MCP มอบวิธีมาตรฐานในการเชื่อมต่อ LLM กับบริบทที่จำเป็น

ที่เก็บนี้ประกอบด้วยเซิร์ฟเวอร์ MCP ที่ให้การเข้าถึงฟังก์ชันฐานข้อมูลเวกเตอร์ Milvus

MCP with Milvus

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

ก่อนใช้เซิร์ฟเวอร์ MCP นี้ ตรวจสอบให้แน่ใจว่าคุณมี:

  • Python 3.10 หรือสูงกว่า
  • อินสแตนซ์ Milvus ที่กำลังทำงานอยู่ (ภายในเครื่องหรือระยะไกล)
  • ติดตั้ง uv แล้ว (แนะนำสำหรับการรันเซิร์ฟเวอร์)

การใช้งาน

วิธีที่แนะนำในการใช้เซิร์ฟเวอร์ MCP นี้คือการรันโดยตรงด้วย uv โดยไม่ต้องติดตั้ง นี่คือวิธีการกำหนดค่าทั้ง Claude Desktop และ Cursor เพื่อใช้งานในตัวอย่างด้านล่าง

หากคุณต้องการโคลนที่เก็บ:

git clone https://github.com/zilliztech/mcp-server-milvus.git
cd mcp-server-milvus

จากนั้นคุณสามารถรันเซิร์ฟเวอร์ได้โดยตรง:

uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530

อีกทางเลือกหนึ่ง คุณสามารถเปลี่ยนไฟล์ .env ในไดเรกทอรี src/mcp_server_milvus/ เพื่อตั้งค่าตัวแปรสภาพแวดล้อมและรันเซิร์ฟเวอร์ด้วยคำสั่งต่อไปนี้:

uv run src/mcp_server_milvus/server.py

สำคัญ: ไฟล์ .env จะมีลำดับความสำคัญสูงกว่าอาร์กิวเมนต์บรรทัดคำสั่ง

โหมดการทำงาน

เซิร์ฟเวอร์รองรับโหมดการทำงานสองโหมด: stdio (ค่าเริ่มต้น) และ SSE (Server-Sent Events)

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

  • คำอธิบาย: สื่อสารกับไคลเอนต์ผ่านอินพุต/เอาต์พุตมาตรฐาน นี่คือโหมดเริ่มต้นหากไม่มีการระบุโหมด

  • การใช้งาน:

    uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530

โหมด SSE

  • คำอธิบาย: ใช้ HTTP Server-Sent Events สำหรับการสื่อสาร โหมดนี้อนุญาตให้ไคลเอนต์หลายตัวเชื่อมต่อผ่าน HTTP และเหมาะสำหรับแอปพลิเคชันบนเว็บ

  • การใช้งาน:

    uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://localhost:19530 --port 8000
    • --sse: เปิดใช้งานโหมด SSE
    • --port: ระบุพอร์ตสำหรับเซิร์ฟเวอร์ SSE (ค่าเริ่มต้น: 8000)

  • การดีบักในโหมด SSE:

    หากคุณต้องการดีบักในโหมด SSE หลังจากเริ่มบริการ SSE แล้ว ให้ป้อนคำสั่งต่อไปนี้:

    mcp dev src/mcp_server_milvus/server.py

    ผลลัพธ์จะคล้ายกับ:

    % mcp dev src/mcp_server_milvus/merged_server.py
Starting MCP inspector...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

    จากนั้นคุณสามารถเข้าถึง MCP Inspector ได้ที่ http://127.0.0.1:6274 สำหรับการทดสอบ

โหมด Streamable HTTP

  • คำอธิบาย: ใช้ HTTP พร้อมการสนับสนุนการสตรีมสำหรับการสื่อสาร นี่คือการขนส่งที่แนะนำสำหรับการปรับใช้ในระบบจริงและรองรับการทำงานทั้งแบบ stateful และ stateless

  • การใช้งาน:

    uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://localhost:19530 --port 8000
    • --streamable-http: เปิดใช้งานโหมด Streamable HTTP
    • --port: ระบุพอร์ตสำหรับเซิร์ฟเวอร์ (ค่าเริ่มต้น: 8000)
    • --stateless: แฟล็กทางเลือกสำหรับโหมด stateless (ไม่มีการคงอยู่ของเซสชัน)

  • โหมด Stateless:

    uv run src/mcp_server_milvus/server.py --streamable-http --stateless --milvus-uri http://localhost:19530 --port 8000

แอปพลิเคชันที่รองรับ

เซิร์ฟเวอร์ MCP นี้สามารถใช้กับแอปพลิเคชัน LLM ต่างๆ ที่รองรับ Model Context Protocol:

  • Claude Desktop: แอปพลิเคชันเดสก์ท็อปของ Anthropic สำหรับ Claude
  • Cursor: โปรแกรมแก้ไขโค้ดที่ขับเคลื่อนด้วย AI พร้อมการสนับสนุน MCP
  • ไคลเอนต์ MCP แบบกำหนดเอง: แอปพลิเคชันใดๆ ที่ใช้ข้อกำหนดไคลเอนต์ MCP

การใช้งานกับ Claude Desktop

การกำหนดค่าสำหรับโหมดต่างๆ

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

ทำตามขั้นตอนเหล่านี้เพื่อกำหนดค่า Claude Desktop สำหรับโหมด SSE:

  1. ติดตั้ง Claude Desktop จาก https://claude.ai/download.
  2. เปิดไฟล์การกำหนดค่า Claude Desktop ของคุณ:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  3. เพิ่มการกำหนดค่าต่อไปนี้สำหรับโหมด SSE:
{
  "mcpServers": {
    "milvus-sse": {
      "url": "http://your_sse_host:port/sse",
      "disabled": false,
      "autoApprove": []
    }
  }
}

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

{
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}
  1. รีสตาร์ท Claude Desktop เพื่อใช้การเปลี่ยนแปลง

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

สำหรับโหมด stdio ให้ทำตามขั้นตอนเหล่านี้:

  1. ติดตั้ง Claude Desktop จาก https://claude.ai/download.
  2. เปิดไฟล์การกำหนดค่า Claude Desktop ของคุณ:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  3. เพิ่มการกำหนดค่าต่อไปนี้สำหรับโหมด stdio:
{
  "mcpServers": {
    "milvus": {
      "command": "/PATH/TO/uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-milvus/src/mcp_server_milvus",
        "run",
        "server.py",
        "--milvus-uri",
        "http://localhost:19530"
      ]
    }
  }
}
  1. รีสตาร์ท Claude Desktop เพื่อใช้การเปลี่ยนแปลง

การใช้งานกับ Cursor

Cursor ยังรองรับเครื่องมือ MCP คุณสามารถผสานรวมเซิร์ฟเวอร์ Milvus MCP ของคุณกับ Cursor ได้โดยทำตามขั้นตอนเหล่านี้:

ขั้นตอนการผสานรวม

  1. เปิด Cursor Settings > MCP
  2. คลิกที่ Add new global MCP server
  3. หลังจากคลิกแล้ว ระบบจะเปลี่ยนเส้นทางคุณไปยังไฟล์ mcp.json โดยอัตโนมัติ ซึ่งจะถูกสร้างขึ้นหากยังไม่มี

การกำหนดค่าไฟล์ mcp.json

สำหรับโหมด Stdio:

เขียนทับไฟล์ mcp.json ด้วยเนื้อหาต่อไปนี้:

{
  "mcpServers": {
    "milvus": {
      "command": "/PATH/TO/uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-milvus/src/mcp_server_milvus",
        "run",
        "server.py",
        "--milvus-uri",
        "http://127.0.0.1:19530"
      ]
    }
  }
}

สำหรับโหมด SSE:

  1. เริ่มบริการโดยรันคำสั่งต่อไปนี้:

    uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://your_sse_host --port port

    หมายเหตุ: แทนที่ http://your_sse_host ด้วยที่อยู่โฮสต์ SSE จริงของคุณ และ port ด้วยหมายเลขพอร์ตเฉพาะที่คุณใช้

  2. เมื่อบริการเริ่มทำงานแล้ว ให้เขียนทับไฟล์ mcp.json ด้วยเนื้อหาต่อไปนี้:

    {
    "mcpServers": {
      "milvus-sse": {
        "url": "http://your_sse_host:port/sse",
        "disabled": false,
        "autoApprove": []
      }
    }
}

สำหรับโหมด Streamable HTTP:

  1. เริ่มบริการ:

    uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://your_host --port port

  2. อัปเดต mcp.json:

    {
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

การผสานรวมให้เสร็จสมบูรณ์

หลังจากทำตามขั้นตอนข้างต้นเสร็จแล้ว ให้รีสตาร์ท Cursor หรือโหลดหน้าต่างใหม่เพื่อให้แน่ใจว่าการกำหนดค่ามีผล

การตรวจสอบการผสานรวม

เพื่อตรวจสอบว่า Cursor ได้ผสานรวมกับเซิร์ฟเวอร์ Milvus MCP ของคุณสำเร็จแล้ว:

  1. เปิด Cursor Settings > MCP
  2. ตรวจสอบว่า "milvus", "milvus-sse" หรือ "milvus-streamable-http" ปรากฏในรายการหรือไม่ (ขึ้นอยู่กับโหมดที่คุณเลือก)
  3. ยืนยันว่ามีเครื่องมือที่เกี่ยวข้องแสดงอยู่ (เช่น milvus_list_collections, milvus_vector_search เป็นต้น)
  4. หากเซิร์ฟเวอร์เปิดใช้งานอยู่แต่แสดงข้อผิดพลาด ให้ตรวจสอบส่วนการแก้ไขปัญหาด้านล่าง

เครื่องมือที่พร้อมใช้งาน

เซิร์ฟเวอร์มีเครื่องมือดังต่อไปนี้:

การดำเนินการค้นหาและสอบถาม

  • milvus_text_search: ค้นหาเอกสารโดยใช้การค้นหาข้อความแบบเต็ม

    • พารามิเตอร์:
      • collection_name: ชื่อของคอลเลกชันที่จะค้นหา
      • query_text: ข้อความที่จะค้นหา
      • limit: จำนวนผลลัพธ์สูงสุดที่จะส่งกลับ (ค่าเริ่มต้น: 5)
      • output_fields: ฟิลด์ที่จะรวมในผลลัพธ์
      • drop_ratio: สัดส่วนของคำที่มีความถี่ต่ำที่จะละเว้น (0.0-1.0) (ค่าเริ่มต้น: 0.2)

  • milvus_vector_search: ทำการค้นหาความคล้ายคลึงของเวกเตอร์บนคอลเลกชัน

    • พารามิเตอร์:
      • collection_name: ชื่อของคอลเลกชันที่จะค้นหา
      • vector: เวกเตอร์การสอบถาม
      • vector_field: ชื่อฟิลด์สำหรับการค้นหาเวกเตอร์ (ค่าเริ่มต้น: "vector")
      • limit: จำนวนผลลัพธ์สูงสุดที่จะส่งกลับ (ค่าเริ่มต้น: 5)
      • output_fields: ฟิลด์ที่จะรวมในผลลัพธ์
      • filter_expr: นิพจน์ตัวกรอง
      • metric_type: เมตริกระยะทาง (COSINE, L2, IP) (ค่าเริ่มต้น: "COSINE")
      • radius: ขอบเขตล่างทางเลือกสำหรับการค้นหาช่วง (ค่าเริ่มต้น: None)
      • range_filter: ขอบเขตบนทางเลือกสำหรับการค้นหาช่วง (ค่าเริ่มต้น: None)

  • milvus_hybrid_search: ทำการค้นหาแบบผสมบนคอลเลกชัน

    • พารามิเตอร์:
      • collection_name: ชื่อของคอลเลกชันที่จะค้นหา
      • query_text: ข้อความสอบถามสำหรับการค้นหา
      • text_field: ชื่อฟิลด์สำหรับการค้นหาข้อความ
      • vector: เวกเตอร์ของข้อความสอบถาม
      • vector_field: ชื่อฟิลด์สำหรับการค้นหาเวกเตอร์
      • limit: จำนวนผลลัพธ์สูงสุดที่จะส่งกลับ (ค่าเริ่มต้น: 5)
      • output_fields: ฟิลด์ที่จะรวมในผลลัพธ์
      • filter_expr: นิพจน์ตัวกรอง
      • sparse_radius: ขอบเขตล่างทางเลือกสำหรับการค้นหาช่วงแบบ sparse (ค่าเริ่มต้น: None)
      • sparse_range_filter: ขอบเขตบนทางเลือกสำหรับการค้นหาช่วงแบบ sparse (ค่าเริ่มต้น: None)
      • dense_radius: ขอบเขตล่างทางเลือกสำหรับการค้นหาช่วงแบบ dense (ค่าเริ่มต้น: None)
      • dense_range_filter: ขอบเขตบนทางเลือกสำหรับการค้นหาช่วงแบบ dense (ค่าเริ่มต้น: None)

  • milvus_text_similarity_search: ทำการค้นหาความคล้ายคลึงของข้อความบนคอลเลกชัน

    หมายเหตุ: เครื่องมือนี้รองรับเฉพาะใน Milvus 2.6.0 ขึ้นไป และคุณต้องตั้งค่าฟังก์ชันการฝังที่เซิร์ฟเวอร์ Milvus ดู Embedding Function สำหรับรายละเอียดเพิ่มเติม

    • พารามิเตอร์:
      • collection_name: ชื่อของคอลเลกชันที่จะค้นหา
      • query_text: ข้อความสอบถามสำหรับการค้นหาความคล้ายคลึง
      • anns_field: ชื่อฟิลด์สำหรับการค้นหาข้อความ
      • limit: จำนวนผลลัพธ์สูงสุดที่จะส่งกลับ (ค่าเริ่มต้น: 5)
      • output_fields: ฟิลด์ที่จะรวมในผลลัพธ์
      • metric_type: เมตริกระยะทาง (COSINE, L2, IP) (ค่าเริ่มต้น: "COSINE")
      • filter_expr: นิพจน์ตัวกรองทางเลือก
      • radius: ขอบเขตล่างทางเลือกสำหรับการค้นหาช่วง (ค่าเริ่มต้น: None)
      • range_filter: ขอบเขตบนทางเลือกสำหรับการค้นหาช่วง (ค่าเริ่มต้น: None)

  • milvus_query: สอบถามคอลเลกชันโดยใช้นิพจน์ตัวกรอง

    • พารามิเตอร์:
      • collection_name: ชื่อของคอลเลกชันที่จะสอบถาม
      • filter_expr: นิพจน์ตัวกรอง (เช่น 'age > 20')
      • output_fields: ฟิลด์ที่จะรวมในผลลัพธ์
      • limit: จำนวนผลลัพธ์สูงสุดที่จะส่งกลับ (ค่าเริ่มต้น: 10)

การจัดการคอลเลกชัน

  • milvus_list_collections: แสดงรายการคอลเลกชันทั้งหมดในฐานข้อมูล

  • milvus_create_collection: สร้างคอลเลกชันใหม่ด้วยการตั้งค่าด่วนหรือสคีมาแบบกำหนดเอง

    • พารามิเตอร์:
      • collection_name: ชื่อสำหรับคอลเลกชันใหม่
      • auto_id: ว่าจะสร้าง id อัตโนมัติหรือไม่ ค่าเริ่มต้นเป็น True
      • dimension: มิติของเวกเตอร์ ค่าเริ่มต้นเป็น 768; สำหรับการตั้งค่าด่วนและจะถูกละเว้นหากระบุ field_schema
      • primary_field_name: ชื่อของฟิลด์หลัก ค่าเริ่มต้นเป็น "id"; สำหรับการตั้งค่าด่วนและจะถูกละเว้นหากระบุ field_schema
      • vector_field_name: ชื่อของฟิลด์เวกเตอร์ ค่าเริ่มต้นเป็น "vector"; สำหรับการตั้งค่าด่วนและจะถูกละเว้นหากระบุ field_schema
      • metric_type: ประเภทเมตริก ค่าเริ่มต้นเป็น "COSINE"; สำหรับการตั้งค่าด่วนและจะถูกละเว้นหากระบุ field_schema
      • field_schema: รายการสคีมาฟิลด์ แต่ละองค์ประกอบเป็นพจนานุกรมที่มีคีย์ต่อไปนี้:
        • name: ชื่อของฟิลด์
        • type: ประเภทของฟิลด์
      • index_params: รายการพารามิเตอร์ดัชนีทางเลือก แต่ละองค์ประกอบเป็นพจนานุกรมที่มีคีย์ต่อไปนี้:
        • field_name: ชื่อของฟิลด์ที่จะสร้างดัชนี
        • index_type: ประเภทดัชนี
        • **kwargs: พารามิเตอร์ดัชนีทางเลือกอื่นๆ
      • other_kwargs: อาร์กิวเมนต์คำสำคัญเพิ่มเติมสำหรับการสร้างคอลเลกชัน

  • milvus_load_collection: โหลดคอลเลกชันเข้าสู่หน่วยความจำสำหรับการค้นหาและสอบถาม

    • พารามิเตอร์:
      • collection_name: ชื่อของคอลเลกชันที่จะโหลด
      • replica_number: จำนวนเรพลิกา (ค่าเริ่มต้น: 1)

  • milvus_release_collection: ปล่อยคอลเลกชันจากหน่วยความจำ

    • พารามิเตอร์:
      • collection_name: ชื่อของคอลเลกชันที่จะปล่อย

  • milvus_get_collection_info: แสดงรายการข้อมูลโดยละเอียด เช่น สคีมา คุณสมบัติ ID คอลเลกชัน และเมทาดาทาอื่นๆ ของคอลเลกชันเฉพาะ

    • พารามิเตอร์:
      • collection_name: ชื่อของคอลเลกชันที่จะรับข้อมูลโดยละเอียด

การดำเนินการข้อมูล

  • milvus_insert_data: แทรกข้อมูลลงในคอลเลกชัน

    • พารามิเตอร์:
      • collection_name: ชื่อของคอลเลกชัน
      • data: พจนานุกรมที่แมปชื่อฟิลด์กับรายการค่า

  • milvus_delete_entities: ลบเอนทิตีออกจากคอลเลกชันตามนิพจน์ตัวกรอง

    • พารามิเตอร์:
      • collection_name: ชื่อของคอลเลกชัน
      • filter_expr: นิพจน์ตัวกรองเพื่อเลือกเอนทิตีที่จะลบ

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

  • MILVUS_URI: URI เซิร์ฟเวอร์ Milvus (สามารถตั้งค่าแทน --milvus-uri ได้)
  • MILVUS_TOKEN: โทเค็นการตรวจสอบสิทธิ์ทางเลือก
  • MILVUS_DB: ชื่อฐานข้อมูล (ค่าเริ่มต้นเป็น "default")

การพัฒนา

เพื่อรันเซิร์ฟเวอร์โดยตรง:

uv run server.py --milvus-uri http://localhost:19530

ตัวอย่าง

การใช้ Claude Desktop

ตัวอย่างที่ 1: การแสดงรายการคอลเลกชัน

What are the collections I have in my Milvus DB?

จากนั้น Claude จะใช้ MCP เพื่อตรวจสอบข้อมูลนี้บน Milvus DB ของคุณ

I'll check what collections are available in your Milvus database.

Here are the collections in your Milvus database:

1. rag_demo
2. test
3. chat_messages
4. text_collection
5. image_collection
6. customized_setup
7. streaming_rag_demo

ตัวอย่างที่ 2: การค้นหาเอกสาร

Find documents in my text_collection that mention "machine learning"

Claude จะใช้ความสามารถในการค้นหาข้อความแบบเต็มของ Milvus เพื่อค้นหาเอกสารที่เกี่ยวข้อง:

I'll search for documents about machine learning in your text_collection.

> View result from milvus-text-search from milvus (local)

Here are the documents I found that mention machine learning:
[Results will appear here based on your actual data]

การใช้ Cursor

ตัวอย่าง: การสร้างคอลเลกชัน

ใน Cursor คุณสามารถถามได้ว่า:

Create a new collection called 'articles' in Milvus with fields for title (string), content (string), and a vector field (128 dimensions)

Cursor จะใช้เซิร์ฟเวอร์ MCP เพื่อดำเนินการนี้:

I'll create a new collection called 'articles' with the specified fields.

Collection 'articles' has been created successfully with the following schema:
- title: string
- content: string
- vector: float vector[128]

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

ปัญหาทั่วไป

ข้อผิดพลาดในการเชื่อมต่อ

หากคุณเห็นข้อผิดพลาดเช่น "Failed to connect to Milvus server":

  1. ตรวจสอบว่าอินสแตนซ์ Milvus ของคุณกำลังทำงานอยู่: docker ps (หากใช้ Docker)
  2. ตรวจสอบว่า URI ในค่าคอนฟิกของคุณถูกต้อง
  3. ตรวจสอบให้แน่ใจว่าไม่มีกฎไฟร์วอลล์ที่บล็อกการเชื่อมต่อ
  4. ลองใช้ 127.0.0.1 แทน localhost ใน URI

ปัญหาการตรวจสอบสิทธิ์

หากคุณพบข้อผิดพลาดในการตรวจสอบสิทธิ์:

  1. ตรวจสอบว่า MILVUS_TOKEN ของคุณถูกต้อง
  2. ตรวจสอบว่าอินสแตนซ์ Milvus ของคุณต้องการการตรวจสอบสิทธิ์หรือไม่
  3. ตรวจสอบให้แน่ใจว่าคุณมีสิทธิ์ที่ถูกต้องสำหรับการดำเนินการที่คุณพยายามทำ

ไม่พบเครื่องมือ

หากเครื่องมือ MCP ไม่ปรากฏใน Claude Desktop หรือ Cursor:

  1. รีสตาร์ตแอปพลิเคชัน
  2. ตรวจสอบบันทึกของเซิร์ฟเวอร์เพื่อหาข้อผิดพลาด
  3. ตรวจสอบว่าเซิร์ฟเวอร์ MCP กำลังทำงานอย่างถูกต้อง
  4. กดปุ่มรีเฟรชในการตั้งค่า MCP (สำหรับ Cursor)

การขอความช่วยเหลือ

หากคุณยังคงประสบปัญหา:

  1. ตรวจสอบ GitHub Issues สำหรับปัญหาที่คล้ายกัน
  2. เข้าร่วม Milvus Community Discord เพื่อขอความช่วยเหลือ
  3. สร้าง issue ใหม่พร้อมข้อมูลโดยละเอียดเกี่ยวกับปัญหาของคุณ