avr-docs-mcp

ทางการ

เซิร์ฟเวอร์ MCP (Model Context Protocol) นี้ให้การทำงานร่วมกับ Wiki.JS สำหรับการค้นหาและแสดงรายการหน้าจากอินสแตนซ์ Wiki.JS ของ Agent Voice Response

GitHub

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

ค้นหาหน้าวิกิด้วยคำสำคัญ — ค้นหาหน้าที่ตรงกับคำค้นหาโดยใช้ search_wiki_pages พร้อมตัวเลือกควบคุมการแบ่งหน้า
แสดงรายการหน้าวิกิทั้งหมด — ดึงรายการหน้าที่มีอยู่แบบแบ่งหน้าจากอินสแตนซ์ Wiki.JS ผ่าน list_wiki_pages
ดึงข้อมูลหน้าเฉพาะ — ดึงเนื้อหาเต็มของหน้าเดียวโดยใช้รหัสตัวเลขหรือสตริงเส้นทางด้วย get_wiki_page
ทดสอบการเชื่อมต่อ Wiki.JS — ตรวจสอบว่าเซิร์ฟเวอร์สามารถเข้าถึงและยืนยันตัวตนกับอินสแตนซ์ Wiki.JS ของคุณได้

เอกสาร

AVR Docs MCP Server พร้อมการผสานรวม Wiki.JS

MCP (Model Context Protocol) server นี้ให้การผสานรวมกับ Wiki.JS สำหรับการค้นหาและแสดงรายการหน้าจากอินสแตนซ์ Wiki.JS ของคุณ

คุณสมบัติ

ค้นหาหน้า Wiki.JS: ค้นหาหน้าโดยใช้คำสำคัญหรือหัวข้อ
แสดงรายการหน้า Wiki.JS: รับรายการหน้าทั้งหมดที่มีแบบแบ่งหน้า
รับหน้าเฉพาะ: ดึงข้อมูลหน้าเฉพาะด้วย ID ของมัน
ทดสอบการเชื่อมต่อ: ทดสอบการเชื่อมต่อไปยังอินสแตนซ์ Wiki.JS ของคุณ
โหมดการขนส่งหลายแบบ: รองรับทั้งโหมด stdio และ HTTP stream
รองรับ Docker: อิมเมจ Docker พร้อมใช้งานพร้อมการตรวจสอบสถานะ

การตั้งค่า

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

อินสแตนซ์ Wiki.JS ที่กำลังทำงานอยู่
API key ที่มีสิทธิ์เหมาะสมสำหรับการอ่านหน้า

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

คุณสามารถตั้งค่าตัวแปรสภาพแวดล้อมได้สองวิธี:

ตัวเลือกที่ 1: ใช้ไฟล์ .env (แนะนำ)

คัดลอกไฟล์สภาพแวดล้อมตัวอย่าง:

cp .env.example .env

แก้ไขไฟล์ .env ด้วยค่าจริงของคุณ:

# Wiki.JS Configuration
WIKI_JS_BASE_URL=https://your-wiki-instance.com
WIKI_JS_API_KEY=your-api-key-here
LOG_LEVEL=info

# MCP Server Configuration
MCP_MODE=stdio
PORT=3000

ตัวเลือกที่ 2: ใช้ตัวแปรสภาพแวดล้อมของระบบ

export WIKI_JS_BASE_URL="https://your-wiki-instance.com"
export WIKI_JS_API_KEY="your-api-key-here"
export LOG_LEVEL="info"
export MCP_MODE="stdio"
export PORT="3000"

การติดตั้ง

ติดตั้ง dependencies:

npm install

สร้างโปรเจกต์:

npm run build

ทดสอบการเชื่อมต่อ (ไม่บังคับ):

npm test

รันเซิร์ฟเวอร์:

npm start

สำหรับการพัฒนา:

npm run dev

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

เซิร์ฟเวอร์รองรับสองโหมดการทำงาน:

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

เซิร์ฟเวอร์ทำงานในโหมด stdio เป็นค่าเริ่มต้น สื่อสารผ่านอินพุต/เอาต์พุตมาตรฐาน นี่คือโหมด MCP แบบดั้งเดิม

npm start
# or
npm run start:http  # for HTTP mode
# or
MCP_MODE=stdio npm start

โหมด HTTP Stream

เซิร์ฟเวอร์ยังสามารถทำงานในโหมด HTTP โดยให้ REST API พร้อม Server-Sent Events (SSE) สำหรับการสื่อสาร MCP

npm run start:http
# or
MCP_MODE=http npm start

เมื่อทำงานในโหมด HTTP เซิร์ฟเวอร์จะให้บริการ:

การตรวจสอบสถานะ: GET /health - ส่งคืนสถานะเซิร์ฟเวอร์
จุดปลาย MCP: POST /mcp - จุดปลายการสื่อสาร MCP โดยใช้ JSON-RPC 2.0

การทดสอบโหมด HTTP

คุณสามารถทดสอบโหมด HTTP โดยใช้ curl หรือ Postman:

# Health check
curl http://localhost:3000/health

# Initialize MCP session
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "curl-client",
        "version": "1.0.0"
      }
    }
  }'

# List available tools (use session ID from initialize response)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

# Call a tool (use session ID from initialize response)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_wiki_pages",
      "arguments": {
        "query": "deepgram",
        "page": 1,
        "limit": 10
      }
    }
  }'

หรือใช้ไคลเอนต์ทดสอบในตัว:

npm run test:http

การใช้งาน Docker

การใช้อิมเมจ Docker

# Run in stdio mode (default)
docker run -d \
  --name avr-docs-mcp \
  -e WIKI_JS_BASE_URL="https://your-wiki-instance.com" \
  -e WIKI_JS_API_KEY="your-api-key-here" \
  agentvoiceresponse/avr-docs-mcp:latest

# Run in HTTP mode
docker run -d \
  --name avr-docs-mcp \
  -p 3000:3000 \
  -e WIKI_JS_BASE_URL="https://your-wiki-instance.com" \
  -e WIKI_JS_API_KEY="your-api-key-here" \
  -e MCP_MODE="http" \
  -e PORT="3000" \
  agentvoiceresponse/avr-docs-mcp:latest

Docker Compose

version: '3.8'

services:
  avr-docs-mcp:
    image: agentvoiceresponse/avr-docs-mcp:latest
    container_name: avr-docs-mcp
    ports:
      - "3000:3000"  # Only needed for HTTP mode
    environment:
      - WIKI_JS_BASE_URL=https://your-wiki-instance.com
      - WIKI_JS_API_KEY=your-api-key-here
      - MCP_MODE=http
      - PORT=3000
      - LOG_LEVEL=info
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

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

1. search_wiki_pages

ค้นหาหน้าใน Wiki.JS โดยใช้คำสำคัญ

พารามิเตอร์:

query (จำเป็น): คำค้นหา
page (ไม่บังคับ): หมายเลขหน้าสำหรับการแบ่งหน้า (ค่าเริ่มต้น: 1)
limit (ไม่บังคับ): จำนวนผลลัพธ์ต่อหน้า (ค่าเริ่มต้น: 10, สูงสุด: 50)

2. list_wiki_pages

แสดงรายการหน้าทั้งหมดที่มีใน Wiki.JS

พารามิเตอร์:

page (ไม่บังคับ): หมายเลขหน้าสำหรับการแบ่งหน้า (ค่าเริ่มต้น: 1)
limit (ไม่บังคับ): จำนวนผลลัพธ์ต่อหน้า (ค่าเริ่มต้น: 20, สูงสุด: 50)

3. get_wiki_page

รับหน้าเฉพาะด้วย ID หรือ path ของมัน

พารามิเตอร์:

pageId (จำเป็น): ID (ตัวเลข) หรือ path (สตริง) ของหน้าที่ต้องการเรียกดู ตัวอย่าง: '3' สำหรับ ID, 'deepgram' สำหรับ path

การกำหนดค่า Wiki.JS API

MCP server นี้ใช้ Wiki.JS GraphQL API (จุดปลาย /graphql) ตรวจสอบให้แน่ใจว่าอินสแตนซ์ Wiki.JS ของคุณเปิดใช้งานการเข้าถึง API และ API key ของคุณมีสิทธิ์ดังต่อไปนี้:

page:read - เพื่ออ่านเนื้อหาหน้า
page:list - เพื่อแสดงรายการหน้า
search:read - เพื่อค้นหาหน้า

เซิร์ฟเวอร์จัดการ GraphQL queries และ responses สำหรับการดำเนินการทั้งหมดโดยอัตโนมัติ โปรดทราบว่า Wiki.JS GraphQL API มีข้อจำกัดบางประการ:

การดำเนินการค้นหาและแสดงรายการไม่รองรับการแบ่งหน้าแบบเนทีฟ ดังนั้นการแบ่งหน้าจึงถูกจำลองขึ้นทางฝั่งไคลเอนต์
ผลลัพธ์การค้นหาไม่รวมเนื้อหาหน้าแบบเต็ม
ผลลัพธ์การแสดงรายการไม่รวมเนื้อหาหน้าแบบเต็ม (ใช้ get_wiki_page สำหรับเนื้อหาแบบเต็ม)
แท็กถูกส่งคืนเป็นอาร์เรย์ของสตริง ไม่ใช่สตริงที่คั่นด้วยเครื่องหมายจุลภาค

การบันทึก

เซิร์ฟเวอร์รวมการบันทึกที่ครอบคลุมพร้อมระดับการบันทึกที่กำหนดค่าได้:

debug - ข้อมูลดีบักโดยละเอียด
info - ข้อมูลทั่วไป (ค่าเริ่มต้น)
warn - ข้อความเตือนเท่านั้น
error - ข้อความข้อผิดพลาดเท่านั้น

ตั้งค่าตัวแปรสภาพแวดล้อม LOG_LEVEL เพื่อควบคุมความละเอียดของการบันทึก

การจัดการข้อผิดพลาด

เซิร์ฟเวอร์รวมการจัดการข้อผิดพลาดที่ครอบคลุมสำหรับ:

ตัวแปรสภาพแวดล้อมที่ขาดหายไป
ปัญหาการเชื่อมต่อเครือข่าย
ความล้มเหลวในการตรวจสอบสิทธิ์ API
ID หน้าที่ไม่ถูกต้อง
การจำกัดอัตรา

การพัฒนา

เพื่อรันในโหมดการพัฒนาพร้อมการโหลดซ้ำอัตโนมัติ:

npm run watch

การสร้าง

เพื่อสร้างสำหรับการใช้งานจริง:

npm run build

JavaScript ที่คอมไพล์แล้วจะอยู่ในไดเรกทอรี dist/

การสนับสนุนและชุมชน

GitHub: https://github.com/agentvoiceresponse - รายงานปัญหา, มีส่วนร่วมโค้ด
Discord: https://discord.gg/DFTU69Hg74 - เข้าร่วมการสนทนาชุมชน
Docker Hub: https://hub.docker.com/u/agentvoiceresponse - ค้นหาอิมเมจ Docker
Wiki: https://wiki.agentvoiceresponse.com/en/home - เอกสารและคำแนะนำโปรเจกต์

สนับสนุน AVR

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

ใบอนุญาต

MIT License - ดูรายละเอียดในไฟล์ LICENSE