avr-docs-mcp

Server MCP AVR Docs dengan Integrasi Wiki.JS

Server MCP (Model Context Protocol) ini menyediakan integrasi dengan Wiki.JS untuk mencari dan menampilkan halaman dari instans Wiki.JS Anda.

Fitur

• Cari Halaman Wiki.JS: Cari halaman menggunakan kata kunci atau topik
• Daftar Halaman Wiki.JS: Dapatkan daftar halaman yang tersedia dengan paginasi
• Ambil Halaman Tertentu: Ambil halaman tertentu berdasarkan ID-nya
• Uji Koneksi: Uji koneksi ke instans Wiki.JS Anda
• Beberapa Mode Transport: Mendukung mode stdio dan HTTP stream
• Dukungan Docker: Gambar Docker siap pakai dengan health check

Penyiapan

Prasyarat

1. Instans Wiki.JS yang berjalan
2. Kunci API dengan izin yang sesuai untuk membaca halaman

Variabel Lingkungan

Anda dapat mengatur variabel lingkungan dengan dua cara:

Opsi 1: Menggunakan file .env (Direkomendasikan)

1. Salin file lingkungan contoh:

cp .env.example .env

2. Edit file .env dengan nilai Anda yang sebenarnya:

# 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

Opsi 2: Menggunakan variabel lingkungan sistem

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"

Instalasi

1. Instal dependensi:

npm install

2. Bangun proyek:

npm run build

3. Uji koneksi (opsional):

npm test

4. Jalankan server:

npm start

Untuk pengembangan:

npm run dev

Mode Berjalan

Server mendukung dua mode operasi:

Mode Stdio (Default)

Server berjalan dalam mode stdio secara default, berkomunikasi melalui input/output standar. Ini adalah mode MCP tradisional.

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

Mode HTTP Stream

Server juga dapat berjalan dalam mode HTTP, menyediakan REST API dengan Server-Sent Events (SSE) untuk komunikasi MCP.

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

Saat berjalan dalam mode HTTP, server menyediakan:

• Health Check: GET /health - Mengembalikan status server
• Endpoint MCP: POST /mcp - Endpoint komunikasi MCP menggunakan JSON-RPC 2.0

Menguji Mode HTTP

Anda dapat menguji mode HTTP menggunakan curl atau 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
      }
    }
  }'

Atau gunakan klien uji bawaan:

npm run test:http

Penggunaan Docker

Menggunakan Gambar 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

Alat yang Tersedia

1. search_wiki_pages

Cari halaman di Wiki.JS menggunakan kata kunci.

Parameter:

• query (wajib): Kueri pencarian
• page (opsional): Nomor halaman untuk paginasi (default: 1)
• limit (opsional): Jumlah hasil per halaman (default: 10, maks: 50)

2. list_wiki_pages

Daftar semua halaman yang tersedia di Wiki.JS.

Parameter:

• page (opsional): Nomor halaman untuk paginasi (default: 1)
• limit (opsional): Jumlah hasil per halaman (default: 20, maks: 50)

3. get_wiki_page

Ambil halaman tertentu berdasarkan ID atau path-nya.

Parameter:

• pageId (wajib): ID (numerik) atau path (string) halaman yang akan diambil. Contoh: '3' untuk ID, 'deepgram' untuk path

Konfigurasi API Wiki.JS

Server MCP ini menggunakan API GraphQL Wiki.JS (endpoint /graphql). Pastikan instans Wiki.JS Anda mengaktifkan akses API dan kunci API Anda memiliki izin berikut:

• page:read - Untuk membaca konten halaman
• page:list - Untuk mendaftar halaman
• search:read - Untuk mencari halaman

Server secara otomatis menangani kueri dan respons GraphQL untuk semua operasi. Perhatikan bahwa API GraphQL Wiki.JS memiliki beberapa batasan:

• Operasi pencarian dan daftar tidak mendukung paginasi asli, sehingga paginasi disimulasikan di sisi klien
• Hasil pencarian tidak menyertakan konten halaman lengkap
• Hasil daftar tidak menyertakan konten halaman lengkap (gunakan get_wiki_page untuk konten lengkap)
• Tag dikembalikan sebagai array string, bukan string yang dipisahkan koma

Pencatatan

Server menyertakan pencatatan komprehensif dengan level log yang dapat dikonfigurasi:

• debug - Informasi debug terperinci
• info - Informasi umum (default)
• warn - Hanya pesan peringatan
• error - Hanya pesan kesalahan

Atur variabel lingkungan LOG_LEVEL untuk mengontrol verbositas pencatatan.

Penanganan Kesalahan

Server menyertakan penanganan kesalahan komprehensif untuk:

• Variabel lingkungan yang hilang
• Masalah konektivitas jaringan
• Kegagalan autentikasi API
• ID halaman tidak valid
• Pembatasan laju

Pengembangan

Untuk menjalankan dalam mode pengembangan dengan hot reloading:

npm run watch

Membangun

Untuk membangun untuk produksi:

npm run build

JavaScript yang dikompilasi akan berada di direktori dist/.

Dukungan & Komunitas

• GitHub: https://github.com/agentvoiceresponse - Laporkan masalah, kontribusikan kode.
• Discord: https://discord.gg/DFTU69Hg74 - Bergabunglah dengan diskusi komunitas.
• Docker Hub: https://hub.docker.com/u/agentvoiceresponse - Temukan gambar Docker.
• Wiki: https://wiki.agentvoiceresponse.com/en/home - Dokumentasi proyek dan panduan.

Dukung AVR

AVR gratis dan sumber terbuka. Dukungan apa pun sepenuhnya sukarela dan dimaksudkan sebagai gestur apresiasi pribadi. Donasi tidak memberikan akses ke fitur, layanan, atau manfaat khusus, dan proyek tetap tersedia sepenuhnya terlepas dari donasi.

Lisensi

Lisensi MIT - lihat file LICENSE untuk detailnya.