Skip to content

README.md

Latest commit

 

History

History
441 lines (329 loc) · 19.9 KB

README.md

File metadata and controls

441 lines (329 loc) · 19.9 KB

การดีบักด้วย MCP Inspector

MCP Inspector เป็นเครื่องมือดีบักที่จำเป็น ที่ช่วยให้คุณทดสอบและแก้ไขปัญหาเซิร์ฟเวอร์ MCP ของคุณอย่างโต้ตอบได้โดยไม่ต้องใช้งานโฮสต์ AI แบบเต็มรูปแบบ คิดว่าเป็น "Postman สำหรับ MCP" - มันให้ส่วนติดต่อแบบภาพเพื่อส่งคำขอ ดูการตอบกลับ และเข้าใจพฤติกรรมของเซิร์ฟเวอร์คุณ

ทำไมต้องใช้ MCP Inspector?

เมื่อสร้างเซิร์ฟเวอร์ MCP คุณมักจะพบกับความท้าทายเหล่านี้:

  • "เซิร์ฟเวอร์ของฉันกำลังทำงานอยู่หรือไม่?" - Inspector แสดงสถานะการเชื่อมต่อ
  • "เครื่องมือของฉันถูกลงทะเบียนอย่างถูกต้องหรือไม่?" - Inspector แสดงรายการเครื่องมือที่มีทั้งหมด
  • "รูปแบบการตอบกลับเป็นอย่างไร?" - Inspector แสดงการตอบกลับ JSON เต็มรูปแบบ
  • "ทำไมเครื่องมือนี้ถึงไม่ทำงาน?" - Inspector แสดงข้อความข้อผิดพลาดอย่างละเอียด

สิ่งที่ต้องเตรียม

  • ติดตั้ง Node.js 18 ขึ้นไป
  • npm (มากับ Node.js)
  • เซิร์ฟเวอร์ MCP สำหรับทดสอบ (ดู Module 3.1 - First Server)

การติดตั้ง

ตัวเลือกที่ 1: รันด้วย npx (แนะนำสำหรับการทดสอบอย่างรวดเร็ว)

npx @modelcontextprotocol/inspector

ตัวเลือกที่ 2: ติดตั้งแบบ Global

npm install -g @modelcontextprotocol/inspector
mcp-inspector

ตัวเลือกที่ 3: เพิ่มในโปรเจกต์ของคุณ

cd your-mcp-server-project
npm install --save-dev @modelcontextprotocol/inspector

เพิ่มใน package.json:

{
  "scripts": {
    "inspector": "mcp-inspector"
  }
}

การเชื่อมต่อกับเซิร์ฟเวอร์ของคุณ

เซิร์ฟเวอร์ stdio (กระบวนการภายในเครื่อง)

สำหรับเซิร์ฟเวอร์ที่สื่อสารผ่าน standard input/output:

# เซิร์ฟเวอร์ Python
npx @modelcontextprotocol/inspector python -m your_server_module

# เซิร์ฟเวอร์ Node.js
npx @modelcontextprotocol/inspector node ./build/index.js

# พร้อมตัวแปรแวดล้อม
OPENAI_API_KEY=xxx npx @modelcontextprotocol/inspector python server.py

เซิร์ฟเวอร์ SSE/HTTP (เครือข่าย)

สำหรับเซิร์ฟเวอร์ที่รันเป็นบริการ HTTP:

  1. เริ่มเซิร์ฟเวอร์ก่อน:

    python server.py  # เซิร์ฟเวอร์กำลังทำงานที่ http://localhost:8080

  2. เปิด Inspector และเชื่อมต่อ:

    npx @modelcontextprotocol/inspector --sse http://localhost:8080/sse

ภาพรวมส่วนติดต่อ Inspector

เมื่อเปิด Inspector คุณจะเห็นอินเทอร์เฟซเว็บ (ปกติที่ http://localhost:5173):

┌─────────────────────────────────────────────────────────────┐
│  MCP Inspector                              [Connected ✅]   │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   🔧 Tools  │  │ 📄 Resources│  │ 💬 Prompts  │         │
│  │    (3)      │  │    (2)      │  │    (1)      │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐ │
│  │  📋 Message Log                                       │ │
│  │  ─────────────────────────────────────────────────── │ │
│  │  → initialize                                         │ │
│  │  ← initialized (server info)                          │ │
│  │  → tools/list                                         │ │
│  │  ← tools (3 tools)                                    │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

การทดสอบเครื่องมือ

การแสดงรายการเครื่องมือที่มี

  1. คลิกแท็บ Tools
  2. Inspector เรียกใช้คำสั่ง tools/list อัตโนมัติ
  3. คุณจะเห็นเครื่องมือทั้งหมดที่ลงทะเบียนพร้อม:
    • ชื่อเครื่องมือ
    • คำอธิบาย
    • สคีมาของอินพุต (พารามิเตอร์)

การเรียกใช้เครื่องมือ

  1. เลือกเครื่องมือจากรายการ
  2. กรอกพารามิเตอร์ที่จำเป็นในฟอร์ม
  3. คลิก Run Tool
  4. ดูผลลัพธ์ตอบกลับในแผงผลลัพธ์

ตัวอย่าง: การทดสอบเครื่องคิดเลข

Tool: add
Parameters:
  a: 25
  b: 17

Response:
{
  "content": [
    {
      "type": "text",
      "text": "42"
    }
  ]
}

การดีบักข้อผิดพลาดของเครื่องมือ

เมื่อเครื่องมือไม่ทำงาน Inspector จะแสดง:

Error Response:
{
  "error": {
    "code": -32602,
    "message": "Invalid params: 'b' is required"
  }
}

รหัสข้อผิดพลาดที่พบบ่อย:

รหัส ความหมาย
-32700 ข้อผิดพลาดการวิเคราะห์ (JSON ไม่ถูกต้อง)
-32600 คำขอไม่ถูกต้อง
-32601 ไม่พบเมธอด
-32602 พารามิเตอร์ไม่ถูกต้อง
-32603 ข้อผิดพลาดภายใน

การทดสอบทรัพยากร

การแสดงรายการทรัพยากร

  1. คลิกแท็บ Resources
  2. Inspector เรียก resources/list
  3. คุณจะเห็น:
    • URI ของทรัพยากร
    • ชื่อและคำอธิบาย
    • ประเภท MIME

การอ่านทรัพยากร

  1. เลือกทรัพยากร
  2. คลิก Read Resource
  3. ดูเนื้อหาที่ส่งกลับมา

ตัวอย่างผลลัพธ์:

Resource: file:///config/settings.json
Content-Type: application/json

{
  "config": {
    "debug": true,
    "maxConnections": 10
  }
}

การทดสอบ Prompt

การแสดงรายการ Prompt

  1. คลิกแท็บ Prompts
  2. Inspector เรียก prompts/list
  3. ดูเทมเพลต prompt ที่มีให้

การรับ Prompt

  1. เลือก prompt
  2. กรอกอาร์กิวเมนต์ที่จำเป็น
  3. คลิก Get Prompt
  4. ดูข้อความ prompt ที่เรนเดอร์แล้ว

การวิเคราะห์บันทึกข้อความ

บันทึกข้อความแสดงข้อความโปรโทคอล MCP ทั้งหมด:

14:32:01 → {"jsonrpc":"2.0","id":1,"method":"initialize",...}
14:32:01 ← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25",...}}
14:32:02 → {"jsonrpc":"2.0","id":2,"method":"tools/list"}
14:32:02 ← {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}
14:32:05 → {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add",...}}
14:32:05 ← {"jsonrpc":"2.0","id":3,"result":{"content":[...]}}

สิ่งที่ควรมองหา

  • คู่คำขอ/ตอบกลับ: ทุก → ควรมีคู่ ←
  • ข้อความผิดพลาด: มองหาคำว่า "error" ในการตอบกลับ
  • เวลาที่เกิดขึ้น: ช่องว่างใหญ่ ๆ อาจบ่งชี้ปัญหาด้านประสิทธิภาพ
  • เวอร์ชันโปรโตคอล: ตรวจสอบให้แน่ใจว่าเซิร์ฟเวอร์และไคลเอนต์ตรงกัน

การผสานกับ VS Code

คุณสามารถรัน Inspector ได้โดยตรงจาก VS Code:

ใช้ launch.json

เพิ่มใน .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug with MCP Inspector",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npx",
      "runtimeArgs": [
        "@modelcontextprotocol/inspector",
        "python",
        "${workspaceFolder}/server.py"
      ],
      "console": "integratedTerminal"
    },
    {
      "name": "Debug SSE Server with Inspector",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:5173",
      "preLaunchTask": "Start MCP Inspector"
    }
  ]
}

ใช้ Tasks

เพิ่มใน .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start MCP Inspector",
      "type": "shell",
      "command": "npx @modelcontextprotocol/inspector node ${workspaceFolder}/build/index.js",
      "isBackground": true,
      "problemMatcher": {
        "pattern": {
          "regexp": "^$"
        },
        "background": {
          "activeOnStart": true,
          "beginsPattern": "Inspector",
          "endsPattern": "listening"
        }
      }
    }
  ]
}

สถานการณ์ดีบักที่พบบ่อย

สถานการณ์ที่ 1: เซิร์ฟเวอร์ไม่เชื่อมต่อ

อาการ: Inspector แสดง "Disconnected" หรือค้างที่ "Connecting..."

เช็คลิสต์:

  1. ✅ คำสั่งเซิร์ฟเวอร์ถูกต้องหรือไม่?
  2. ✅ ติดตั้ง dependencies ครบถ้วนหรือไม่?
  3. ✅ เส้นทางเซิร์ฟเวอร์เป็นแบบ absolute หรือสัมพันธ์กับโฟลเดอร์ปัจจุบันหรือไม่?
  4. ✅ ตัวแปรสภาพแวดล้อมที่จำเป็นถูกตั้งค่าหรือไม่?

ขั้นตอนแก้ไขปัญหา:

# ทดสอบเซิร์ฟเวอร์ด้วยตนเองก่อน
python -c "import your_server_module; print('OK')"

# ตรวจสอบข้อผิดพลาดในการนำเข้า
python -m your_server_module 2>&1 | head -20

# ยืนยันว่าติดตั้ง MCP SDK แล้ว
pip show mcp

สถานการณ์ที่ 2: เครื่องมือไม่แสดง

อาการ: แท็บเครื่องมือแสดงรายการว่างเปล่า

สาเหตุที่เป็นไปได้:

  1. เครื่องมือไม่ได้ลงทะเบียนในขั้นตอนเริ่มต้นเซิร์ฟเวอร์
  2. เซิร์ฟเวอร์ล่มหลังจากเริ่มทำงาน
  3. ตัวจัดการ tools/list ส่งคืนอาร์เรย์ว่าง

ขั้นตอนแก้ไขปัญหา:

  1. ตรวจสอบบันทึกข้อความสำหรับการตอบกลับ tools/list
  2. เพิ่มการบันทึกในโค้ดลงทะเบียนเครื่องมือของคุณ
  3. ตรวจสอบว่ามีตัวตกแต่ง @mcp.tool() (ใน Python)

สถานการณ์ที่ 3: เครื่องมือส่งคืนข้อผิดพลาด

อาการ: การเรียกเครื่องมือส่งคืนการตอบกลับข้อผิดพลาด

วิธีดีบัก:

  1. อ่านข้อความข้อผิดพลาดอย่างละเอียด
  2. ตรวจสอบชนิดพารามิเตอร์ให้ตรงกับสคีมา
  3. เพิ่ม try/catch พร้อมข้อความข้อผิดพลาดที่ละเอียด
  4. ตรวจสอบบันทึกเซิร์ฟเวอร์สำหรับ stack trace

ตัวอย่างการจัดการข้อผิดพลาดที่ดีกว่า:

@mcp.tool()
async def my_tool(param1: str, param2: int) -> str:
    try:
        # ลอจิกของเครื่องมือนี้อยู่ที่นี่
        result = process(param1, param2)
        return str(result)
    except ValueError as e:
        raise McpError(f"Invalid parameter: {e}")
    except Exception as e:
        raise McpError(f"Tool failed: {type(e).__name__}: {e}")

สถานการณ์ที่ 4: เนื้อหาทรัพยากรว่างเปล่า

อาการ: ทรัพยากรส่งคืนแต่เนื้อหาว่างเปล่าหรือเป็น null

เช็คลิสต์:

  1. ✅ เส้นทางไฟล์หรือ URI ถูกต้องหรือไม่
  2. ✅ เซิร์ฟเวอร์มีสิทธิ์อ่านทรัพยากรหรือไม่
  3. ✅ เนื้อหาทรัพยากรถูกส่งคืนอย่างถูกต้องหรือไม่

คุณสมบัติขั้นสูงของ Inspector

เฮดเดอร์ที่กำหนดเอง (SSE)

npx @modelcontextprotocol/inspector \
  --sse http://localhost:8080/sse \
  --header "Authorization: Bearer your-token"

การบันทึกแบบละเอียด

DEBUG=mcp* npx @modelcontextprotocol/inspector python server.py

การบันทึกเซสชัน

Inspector สามารถส่งออกบันทึกข้อความเพื่อนำไปวิเคราะห์ภายหลัง:

  1. คลิก Export Log ในแผงข้อความ
  2. บันทึกไฟล์ JSON
  3. แชร์กับสมาชิกทีมเพื่อดีบัก

แนวปฏิบัติที่ดีที่สุด

  1. ทดสอบตั้งแต่เนิ่นๆ และบ่อยครั้ง - ใช้ Inspector ในระหว่างพัฒนา ไม่ใช่แค่เมื่อเกิดปัญหา
  2. เริ่มต้นง่ายๆ - ทดสอบการเชื่อมต่อพื้นฐานก่อนเรียกใช้เครื่องมือซับซ้อน
  3. ตรวจสอบสคีมา - ข้อผิดพลาดหลายอย่างมาจากชนิดพารามิเตอร์ไม่ตรงกัน
  4. อ่านข้อความข้อผิดพลาด - ข้อผิดพลาด MCP มักมีคำอธิบายที่ชัดเจน
  5. เปิด Inspector ไว้เสมอ - ช่วยจับปัญหาได้ระหว่างพัฒนา

ต่อไปทำอะไรดี

คุณได้ทำครบ Module 3: Getting Started แล้ว! เรียนรู้ต่อได้ที่:

แหล่งข้อมูลเพิ่มเติม

ข้อจำกัดความรับผิดชอบ:
เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษา AI Co-op Translator แม้ว่าเราจะพยายามให้ความถูกต้องสูงสุด โปรดทราบว่าการแปลอัตโนมัติอาจมีข้อผิดพลาดหรือความคลาดเคลื่อน เอกสารต้นฉบับในภาษาต้นทางควรถูกพิจารณาเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่สำคัญ ขอแนะนำให้ใช้บริการแปลโดยนักแปลมืออาชีพ เราจะไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความผิดที่เกิดจากการใช้การแปลนี้