avr-docs-mcp

공식

이 MCP 서버는 Agent Voice Response Wiki.JS 인스턴스에서 페이지를 검색하고 나열하기 위해 Wiki.JS와의 통합을 제공합니다.

GitHub

Avr Docs MCP(으)로 무엇을 할 수 있나요?

키워드로 위키 페이지 검색 — search_wiki_pages를 사용하여 쿼리와 일치하는 페이지를 찾으며, 선택적 페이지 매김 제어 기능이 있습니다.
모든 위키 페이지 나열 — list_wiki_pages를 통해 Wiki.JS 인스턴스에서 사용 가능한 페이지의 페이지 매김 목록을 검색합니다.
특정 페이지 가져오기 — get_wiki_page를 사용하여 숫자 ID 또는 경로 문자열로 단일 페이지의 전체 내용을 가져옵니다.
Wiki.JS 연결 테스트 — 서버가 Wiki.JS 인스턴스에 도달하고 인증할 수 있는지 확인합니다.

문서

AVR Docs MCP 서버 (Wiki.JS 통합)

이 MCP(Model Context Protocol) 서버는 Wiki.JS 인스턴스에서 페이지를 검색하고 목록을 조회할 수 있도록 Wiki.JS와의 통합을 제공합니다.

기능

Wiki.JS 페이지 검색: 키워드나 주제를 사용하여 페이지 검색
Wiki.JS 페이지 목록: 사용 가능한 모든 페이지의 페이지네이션 목록 조회
특정 페이지 가져오기: ID로 특정 페이지 조회
연결 테스트: Wiki.JS 인스턴스 연결 테스트
다중 전송 모드: stdio 및 HTTP 스트림 모드 지원
Docker 지원: 헬스 체크가 포함된 바로 사용 가능한 Docker 이미지

설정

사전 요구 사항

실행 중인 Wiki.JS 인스턴스
페이지 읽기에 적절한 권한이 있는 API 키

환경 변수

환경 변수는 두 가지 방법으로 설정할 수 있습니다:

옵션 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"

설치

의존성 설치:

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 스트림 모드

서버는 HTTP 모드로도 실행할 수 있으며, MCP 통신을 위해 Server-Sent Events(SSE)를 포함한 REST API를 제공합니다.

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

HTTP 모드로 실행 시 서버는 다음을 제공합니다:

헬스 체크: GET /health - 서버 상태 반환
MCP 엔드포인트: POST /mcp - JSON-RPC 2.0을 사용하는 MCP 통신 엔드포인트

HTTP 모드 테스트

curl 또는 Postman을 사용하여 HTTP 모드를 테스트할 수 있습니다:

# 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 또는 경로로 특정 페이지를 가져옵니다.

매개변수:

pageId (필수): 조회할 페이지의 ID(숫자) 또는 경로(문자열). 예: ID의 경우 '3', 경로의 경우 'deepgram'

Wiki.JS API 구성

이 MCP 서버는 Wiki.JS GraphQL API(/graphql 엔드포인트)를 사용합니다. Wiki.JS 인스턴스에서 API 접근이 활성화되어 있고 API 키에 다음 권한이 있는지 확인하세요:

page:read - 페이지 콘텐츠 읽기
page:list - 페이지 목록 조회
search:read - 페이지 검색

서버는 모든 작업에 대해 GraphQL 쿼리와 응답을 자동으로 처리합니다. 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 파일을 참조하세요.