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

Ferramenta	O que faz
Server	Verifica se o MCP está funcionando.
list_documents	Lista os documentos da Wiki.
search_documents	Pesquisa pelo nome ou caminho do documento.
search_content	Pesquisa dentro do conteúdo dos documentos.
read_document	Lê um documento Markdown completo.

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.