py-mcp-wiki-helper

Servidor MCP para consultar uma Wiki armazenada em um repositório Git.

Ele sincroniza a Wiki, indexa os arquivos Markdown e oferece ferramentas para listar, pesquisar e ler documentos no Codex ou no VS Code.

Funcionalidades

Related MCP server: Project RAG wiki

Como funciona

1. O MCP clona ou atualiza o repositório Git da Wiki.

2. Localiza todos os arquivos .md.

3. Cria um índice em memória.

4. Disponibiliza as ferramentas pela rota HTTP /mcp.

5. Atualiza a Wiki periodicamente.

A pasta definida em WIKI_LOCAL_PATH é atualizada com git reset --hard. Não faça alterações manuais nela, pois serão descartadas.

1. Configurar o servidor

Na máquina onde o MCP ficará rodando, entre na pasta do projeto:

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

Instale as dependências:

npm install

Crie o arquivo .env:

cp .env.example .env

Preencha o .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 o primeiro teste na rede local, não configure MCP_API_KEY.

2. Iniciar o servidor

Compile:

npm run build

Inicie:

npm run start:http

Mantenha esse terminal aberto. A mensagem esperada é:

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

Descubra o IP da máquina:

hostname -I

Se necessário, libere a porta na rede local:

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

3. Testar a conexão

Na outra máquina, execute:

curl http://IP_DO_SERVIDOR:3000/health

Exemplo:

curl http://192.168.3.233:3000/health

Resposta esperada:

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

O campo documents deve ser maior que zero.

4. Conectar no Codex

No Codex:

1. Abra Settings.

2. Entre em MCP servers.

3. Clique em + Add server.

4. Escolha o tipo URL/HTTP.

5. Use o nome wiki-helper.

6. Preencha somente a URL:

http://IP_DO_SERVIDOR:3000/mcp

Exemplo:

http://192.168.3.233:3000/mcp

Deixe estes campos completamente vazios:

• Bearer token env var

• Headers

• Headers from environment variables

Não escreva none nos campos de autenticação.

Depois:

1. Salve o servidor.

2. Ative a chave ao lado de wiki-helper.

3. Abra uma conversa nova no Codex.

4. Envie:

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

Se o Codex informar que a variável de ambiente none não existe:

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

2. Clique em Uninstall.

3. Adicione novamente preenchendo somente a URL.

4. Deixe todos os campos de autenticação vazios.

5. Conectar no VS Code/Copilot

No VS Code:

1. Pressione Ctrl+Shift+P.

2. Execute MCP: Open User Configuration.

3. Coloque no arquivo mcp.json:

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

Depois execute MCP: List Servers, selecione wiki-helper e escolha Start Server.

6. Exemplos de uso

Verificar o servidor:

Use a ferramenta Server do MCP wiki-helper.

Listar documentos:

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

Pesquisar pelo nome:

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

Pesquisar dentro da Wiki:

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

Ler um documento:

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

Problemas comuns

Erro ECONNREFUSED ...:80

A URL está sem a porta ou a rota. Use sempre:

http://IP_DO_SERVIDOR:3000/mcp

Abriu a rota /authorize

O cliente tentou usar OAuth. Este MCP não possui OAuth. Remova a autenticação e deixe os campos Bearer e Headers vazios.

O MCP não conecta

Confira na máquina servidora:

npm run start:http
ss -lntp | grep 3000

Teste novamente na máquina cliente:

curl http://IP_DO_SERVIDOR:3000/health

A Wiki não retorna documentos

Confira se a pasta configurada contém arquivos Markdown:

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

Também confira o acesso ao repositório Git configurado em WIKI_REPOSITORY_URL.

Segurança

• Use este modo sem autenticação apenas em uma rede local controlada.

• Não exponha a porta 3000 diretamente na internet.

• Para acesso externo, utilize HTTPS, autenticação e um proxy reverso.

• Nunca versione chaves ou credenciais no .env.