mcp-wiki-helper-tools

Servidor MCP para consultar una Wiki almacenada en un repositorio Git.

Sincroniza la Wiki, indexa los archivos Markdown y ofrece herramientas para listar, buscar y leer documentos en Codex o en VS Code.

Funcionalidades

Related MCP server: knowledge-mcp

Cómo funciona

1. El MCP clona o actualiza el repositorio Git de la Wiki.

2. Localiza todos los archivos .md.

3. Crea un índice en memoria.

4. Ofrece las herramientas a través de la ruta HTTP /mcp.

5. Actualiza la Wiki periódicamente.

La carpeta definida en WIKI_LOCAL_PATH se actualiza con git reset --hard. No hagas cambios manuales en ella, ya que se descartarán.

1. Configurar el servidor

En la máquina donde se ejecutará el MCP, entra en la carpeta del proyecto:

cd "/caminho/para/mcp-wiki-helper"

Instala las dependencias:

npm install

Crea el archivo .env:

cp .env.example .env

Completa el .env:

WIKI_REPOSITORY_URL=git@github.com:empresa/wiki.git
WIKI_LOCAL_PATH=./data/wiki
WIKI_BRANCH=main
WIKI_SYNC_INTERVAL_MS=1800000

MCP_HTTP_HOST=0.0.0.0
MCP_HTTP_PORT=3000
MCP_HTTP_ROUTE=/mcp

Para facilitar la primera prueba en la red local, no configures MCP_API_KEY.

2. Iniciar el servidor

Compila:

npm run build

Inicia:

npm run start:http

Mantén ese terminal abierto. El mensaje esperado es:

[MCP] HTTP ativo em http://0.0.0.0:3000/mcp

Descubre la IP de la máquina:

hostname -I

Si es necesario, libera el puerto en la red local:

sudo ufw allow from 192.168.0.0/16 to any port 3000 proto tcp

3. Probar la conexión

En la otra máquina, ejecuta:

curl http://IP_DO_SERVIDOR:3000/health

Ejemplo:

curl http://192.168.3.233:3000/health

Respuesta esperada:

{
  "status": "ok",
  "documents": 100
}

El campo documents debe ser mayor que cero.

4. Conectar en Codex

En Codex:

1. Abre Settings.

2. Entra en MCP servers.

3. Haz clic en + Add server.

4. Elige el tipo URL/HTTP.

5. Usa el nombre wiki-helper.

6. Completa solo la URL:

http://IP_DO_SERVIDOR:3000/mcp

Ejemplo:

http://192.168.3.233:3000/mcp

Deja estos campos completamente vacíos:

• Bearer token env var

• Headers

• Headers from environment variables

No escribas none en los campos de autenticación.

Después:

1. Guarda el servidor.

2. Activa la clave al lado de wiki-helper.

3. Abre una conversación nueva en Codex.

4. Envía:

Use list_documents do MCP wiki-helper e mostre os primeiros 10 documentos.

Si Codex informa que la variable de entorno none no existe:

1. Abre Settings > MCP servers > wiki-helper.

2. Haz clic en Uninstall.

3. Agrégalo de nuevo completando solo la URL.

4. Deja todos los campos de autenticación vacíos.

5. Conectar en VS Code/Copilot

En VS Code:

1. Presiona Ctrl+Shift+P.

2. Ejecuta MCP: Open User Configuration.

3. Coloca en el archivo mcp.json:

{
  "servers": {
    "wiki-helper": {
      "type": "http",
      "url": "http://IP_DO_SERVIDOR:3000/mcp"
    }
  }
}

Después ejecuta MCP: List Servers, selecciona wiki-helper y elige Start Server.

6. Ejemplos de uso

Verificar el servidor:

Use a ferramenta Server do MCP wiki-helper.

Listar documentos:

Use list_documents do wiki-helper e mostre os primeiros 10 documentos.

Buscar por nombre:

Use search_documents do wiki-helper para procurar "autenticação".

Buscar dentro de la Wiki:

Use search_content do wiki-helper para pesquisar "JWT", com limite 5.

Leer un documento:

Use read_document do wiki-helper para ler "caminho/documento.md" e faça um resumo.

Problemas comunes

Error ECONNREFUSED ...:80

La URL no tiene el puerto o la ruta. Usa siempre:

http://IP_DO_SERVIDOR:3000/mcp

Se abrió la ruta /authorize

El cliente intentó usar OAuth. Este MCP no tiene OAuth. Elimina la autenticación y deja los campos Bearer y Headers vacíos.

El MCP no conecta

Verifica en la máquina servidora:

npm run start:http
ss -lntp | grep 3000

Prueba de nuevo en la máquina cliente:

curl http://IP_DO_SERVIDOR:3000/health

La Wiki no devuelve documentos

Verifica si la carpeta configurada contiene archivos Markdown:

find ./data/wiki -type f -name '*.md' | head

También verifica el acceso al repositorio Git configurado en WIKI_REPOSITORY_URL.

Seguridad

• Usa este modo sin autenticación solo en una red local controlada.

• No expongas el puerto 3000 directamente a internet.

• Para acceso externo, utiliza HTTPS, autenticación y un proxy inverso.

• Nunca versiones claves o credenciales en el .env.