avr-docs-mcp

Servidor MCP de Documentação AVR com Integração Wiki.JS

Este servidor MCP (Model Context Protocol) fornece integração com o Wiki.JS para pesquisar e listar páginas da sua instância do Wiki.JS.

Funcionalidades

• Pesquisar Páginas do Wiki.JS: Pesquise páginas usando palavras-chave ou tópicos
• Listar Páginas do Wiki.JS: Obtenha uma lista paginada de todas as páginas disponíveis
• Obter Página Específica: Recupere uma página específica pelo seu ID
• Teste de Conexão: Teste a conexão com sua instância do Wiki.JS
• Múltiplos Modos de Transporte: Suporte para modos stdio e HTTP stream
• Suporte Docker: Imagem Docker pronta para uso com verificações de saúde

Configuração

Pré-requisitos

1. Uma instância do Wiki.JS em execução
2. Uma chave de API com permissões apropriadas para leitura de páginas

Variáveis de Ambiente

Você pode definir variáveis de ambiente de duas maneiras:

Opção 1: Usando um arquivo .env (Recomendado)

1. Copie o arquivo de ambiente de exemplo:

cp .env.example .env

2. Edite o arquivo .env com seus valores reais:

# 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

Opção 2: Usando variáveis de ambiente do sistema

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"

Instalação

1. Instale as dependências:

npm install

2. Compile o projeto:

npm run build

3. Teste a conexão (opcional):

npm test

4. Execute o servidor:

npm start

Para desenvolvimento:

npm run dev

Modos de Execução

O servidor suporta dois modos de operação:

Modo Stdio (Padrão)

O servidor é executado no modo stdio por padrão, comunicando-se através de entrada/saída padrão. Este é o modo MCP tradicional.

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

Modo HTTP Stream

O servidor também pode ser executado no modo HTTP, fornecendo uma API REST com Server-Sent Events (SSE) para comunicação MCP.

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

Ao executar no modo HTTP, o servidor fornece:

• Verificação de Saúde: GET /health - Retorna o status do servidor
• Endpoint MCP: POST /mcp - Endpoint de comunicação MCP usando JSON-RPC 2.0

Testando o Modo HTTP

Você pode testar o modo HTTP usando curl ou 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
      }
    }
  }'

Ou use o cliente de teste integrado:

npm run test:http

Uso com Docker

Usando a Imagem 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

Ferramentas Disponíveis

1. search_wiki_pages

Pesquise páginas no Wiki.JS usando palavras-chave.

Parâmetros:

• query (obrigatório): A consulta de pesquisa
• page (opcional): Número da página para paginação (padrão: 1)
• limit (opcional): Número de resultados por página (padrão: 10, máx: 50)

2. list_wiki_pages

Liste todas as páginas disponíveis no Wiki.JS.

Parâmetros:

• page (opcional): Número da página para paginação (padrão: 1)
• limit (opcional): Número de resultados por página (padrão: 20, máx: 50)

3. get_wiki_page

Obtenha uma página específica pelo seu ID ou caminho.

Parâmetros:

• pageId (obrigatório): O ID (numérico) ou caminho (string) da página a ser recuperada. Exemplos: '3' para ID, 'deepgram' para caminho

Configuração da API do Wiki.JS

Este servidor MCP usa a API GraphQL do Wiki.JS (endpoint /graphql). Certifique-se de que sua instância do Wiki.JS tenha o acesso à API habilitado e que sua chave de API tenha as seguintes permissões:

• page:read - Para ler o conteúdo da página
• page:list - Para listar páginas
• search:read - Para pesquisar páginas

O servidor lida automaticamente com consultas e respostas GraphQL para todas as operações. Note que a API GraphQL do Wiki.JS tem algumas limitações:

• Operações de pesquisa e listagem não suportam paginação nativa, então a paginação é simulada no lado do cliente
• Resultados de pesquisa não incluem o conteúdo completo da página
• Resultados de listagem não incluem o conteúdo completo da página (use get_wiki_page para conteúdo completo)
• Tags são retornadas como arrays de strings, não strings separadas por vírgula

Registro de Logs

O servidor inclui registro abrangente com níveis de log configuráveis:

• debug - Informações detalhadas de depuração
• info - Informações gerais (padrão)
• warn - Apenas mensagens de aviso
• error - Apenas mensagens de erro

Defina a variável de ambiente LOG_LEVEL para controlar a verbosidade do log.

Tratamento de Erros

O servidor inclui tratamento abrangente de erros para:

• Variáveis de ambiente ausentes
• Problemas de conectividade de rede
• Falhas de autenticação da API
• IDs de página inválidos
• Limitação de taxa

Desenvolvimento

Para executar em modo de desenvolvimento com recarregamento automático:

npm run watch

Compilação

Para compilar para produção:

npm run build

O JavaScript compilado estará no diretório dist/.

Suporte e Comunidade

• GitHub: https://github.com/agentvoiceresponse - Relate problemas, contribua com código.
• Discord: https://discord.gg/DFTU69Hg74 - Participe da discussão da comunidade.
• Docker Hub: https://hub.docker.com/u/agentvoiceresponse - Encontre imagens Docker.
• Wiki: https://wiki.agentvoiceresponse.com/en/home - Documentação e guias do projeto.

Apoie o AVR

O AVR é gratuito e de código aberto. Qualquer apoio é totalmente voluntário e destinado como um gesto pessoal de agradecimento. Doações não fornecem acesso a funcionalidades, serviços ou benefícios especiais, e o projeto permanece totalmente disponível independentemente de doações.

Licença

Licença MIT - veja o arquivo LICENSE para detalhes.