avr-docs-mcp Server

resmi

Bu MCP (Model Context Protocol) sunucusu, Agent Voice Response Wiki.JS örneğinden sayfaları aramak ve listelemek için Wiki.JS ile entegrasyon sağlar.

GitHub

Dokümantasyon

Wiki.JS Entegrasyonlu AVR Docs MCP Sunucusu

Bu MCP (Model Context Protocol) sunucusu, Wiki.JS örneğinizden sayfaları aramak ve listelemek için Wiki.JS ile entegrasyon sağlar.

Özellikler

Wiki.JS Sayfalarında Arama: Anahtar kelimeler veya konular kullanarak sayfaları arayın
Wiki.JS Sayfalarını Listeleme: Mevcut tüm sayfaların sayfalı bir listesini alın
Belirli Sayfayı Getirme: ID'sine göre belirli bir sayfayı alın
Bağlantı Testi: Wiki.JS örneğinize olan bağlantıyı test edin
Çoklu Aktarım Modları: Hem stdio hem de HTTP akış modları için destek
Docker Desteği: Sağlık kontrolleriyle kullanıma hazır Docker imajı

Kurulum

Ön Koşullar

Çalışan bir Wiki.JS örneği
Sayfaları okumak için uygun izinlere sahip bir API anahtarı

Ortam Değişkenleri

Ortam değişkenlerini iki şekilde ayarlayabilirsiniz:

Seçenek 1: .env dosyası kullanma (Önerilir)

Örnek ortam dosyasını kopyalayın:

cp .env.example .env

.env dosyasını gerçek değerlerinizle düzenleyin:

# 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

Seçenek 2: Sistem ortam değişkenlerini kullanma

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"

Kurulum

Bağımlılıkları yükleyin:

npm install

Projeyi derleyin:

npm run build

Bağlantıyı test edin (isteğe bağlı):

npm test

Sunucuyu çalıştırın:

npm start

Geliştirme için:

npm run dev

Çalışma Modları

Sunucu iki çalışma modunu destekler:

Stdio Modu (Varsayılan)

Sunucu varsayılan olarak stdio modunda çalışır ve standart giriş/çıkış üzerinden iletişim kurar. Bu, geleneksel MCP modudur.

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

HTTP Akış Modu

Sunucu HTTP modunda da çalışabilir ve MCP iletişimi için Sunucu Tarafından Gönderilen Olaylar (SSE) ile bir REST API sağlar.

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

HTTP modunda çalışırken sunucu şunları sağlar:

Sağlık Kontrolü: GET /health - Sunucu durumunu döndürür
MCP Uç Noktası: POST /mcp - JSON-RPC 2.0 kullanan MCP iletişim uç noktası

HTTP Modunu Test Etme

HTTP modunu curl veya Postman kullanarak test edebilirsiniz:

# 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
      }
    }
  }'

Veya yerleşik test istemcisini kullanın:

npm run test:http

Docker Kullanımı

Docker İmajını Kullanma

# 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

Mevcut Araçlar

1. search_wiki_pages

Anahtar kelimeler kullanarak Wiki.JS'te sayfaları arayın.

Parametreler:

query (zorunlu): Arama sorgusu
page (isteğe bağlı): Sayfalama için sayfa numarası (varsayılan: 1)
limit (isteğe bağlı): Sayfa başına sonuç sayısı (varsayılan: 10, maks: 50)

2. list_wiki_pages

Wiki.JS'teki tüm mevcut sayfaları listeleyin.

Parametreler:

page (isteğe bağlı): Sayfalama için sayfa numarası (varsayılan: 1)
limit (isteğe bağlı): Sayfa başına sonuç sayısı (varsayılan: 20, maks: 50)

3. get_wiki_page

ID'sine veya yoluna göre belirli bir sayfayı alın.

Parametreler:

pageId (zorunlu): Alınacak sayfanın ID'si (sayısal) veya yolu (dize). Örnekler: ID için '3', yol için 'deepgram'

Wiki.JS API Yapılandırması

Bu MCP sunucusu, Wiki.JS GraphQL API'sini (/graphql uç noktası) kullanır. Wiki.JS örneğinizde API erişiminin etkin olduğundan ve API anahtarınızın aşağıdaki izinlere sahip olduğundan emin olun:

page:read - Sayfa içeriğini okumak için
page:list - Sayfaları listelemek için
search:read - Sayfaları aramak için

Sunucu, tüm işlemler için GraphQL sorgularını ve yanıtlarını otomatik olarak işler. Wiki.JS GraphQL API'sinin bazı sınırlamaları olduğunu unutmayın:

Arama ve listeleme işlemleri yerel sayfalamayı desteklemez, bu nedenle sayfalama istemci tarafında simüle edilir
Arama sonuçları tam sayfa içeriğini içermez
Listeleme sonuçları tam sayfa içeriğini içermez (tam içerik için get_wiki_page kullanın)
Etiketler, virgülle ayrılmış dizeler değil, dize dizileri olarak döndürülür

Günlük Kaydı

Sunucu, yapılandırılabilir günlük seviyeleriyle kapsamlı günlük kaydı içerir:

debug - Ayrıntılı hata ayıklama bilgisi
info - Genel bilgi (varsayılan)
warn - Yalnızca uyarı mesajları
error - Yalnızca hata mesajları

Günlük ayrıntı düzeyini kontrol etmek için LOG_LEVEL ortam değişkenini ayarlayın.

Hata Yönetimi

Sunucu, aşağıdakiler için kapsamlı hata yönetimi içerir:

Eksik ortam değişkenleri
Ağ bağlantısı sorunları
API kimlik doğrulama hataları
Geçersiz sayfa ID'leri
Hız sınırlaması

Geliştirme

Anlık yeniden yükleme ile geliştirme modunda çalıştırmak için:

npm run watch

Derleme

Üretim için derlemek için:

npm run build

Derlenmiş JavaScript, dist/ dizininde olacaktır.

Destek ve Topluluk

GitHub: https://github.com/agentvoiceresponse - Sorunları bildirin, kod katkısında bulunun.
Discord: https://discord.gg/DFTU69Hg74 - Topluluk tartışmasına katılın.
Docker Hub: https://hub.docker.com/u/agentvoiceresponse - Docker imajlarını bulun.
Wiki: https://wiki.agentvoiceresponse.com/en/home - Proje dokümantasyonu ve kılavuzlar.

AVR'yi Destekleyin

AVR ücretsiz ve açık kaynaklıdır. Herhangi bir destek tamamen gönüllüdür ve kişisel bir takdir göstergesi olarak düşünülmüştür. Bağışlar özelliklere, hizmetlere veya özel avantajlara erişim sağlamaz ve proje, bağışlardan bağımsız olarak tamamen kullanılabilir durumda kalır.

Lisans

MIT Lisansı - ayrıntılar için LICENSE dosyasına bakın.