mcp-wiki-helper-tools

MCP-сервер для просмотра Wiki, хранящейся в Git-репозитории.

Он синхронизирует Wiki, индексирует Markdown-файлы и предоставляет инструменты для перечисления, поиска и чтения документов в Codex или VS Code.

Возможности

Related MCP server: knowledge-mcp

Как это работает

1. MCP клонирует или обновляет Git-репозиторий Wiki.

2. Находит все файлы .md.

3. Создаёт индекс в памяти.

4. Предоставляет инструменты через HTTP-маршрут /mcp.

5. Периодически обновляет Wiki.

Папка, указанная в WIKI_LOCAL_PATH, обновляется с помощью git reset --hard. Не вносите в неё ручные изменения, так как они будут отброшены.

1. Настройка сервера

На машине, где будет работать MCP, перейдите в папку проекта:

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

Установите зависимости:

npm install

Создайте файл .env:

cp .env.example .env

Заполните .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

Для упрощения первого теста в локальной сети не настраивайте MCP_API_KEY.

2. Запуск сервера

Скомпилируйте:

npm run build

Запустите:

npm run start:http

Держите этот терминал открытым. Ожидаемое сообщение:

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

Узнайте IP-адрес машины:

hostname -I

При необходимости откройте порт в локальной сети:

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

3. Проверка подключения

На другой машине выполните:

curl http://IP_DO_SERVIDOR:3000/health

Пример:

curl http://192.168.3.233:3000/health

Ожидаемый ответ:

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

Поле documents должно быть больше нуля.

4. Подключение к Codex

В Codex:

1. Откройте Settings.

2. Перейдите в MCP servers.

3. Нажмите + Add server.

4. Выберите тип URL/HTTP.

5. Используйте имя wiki-helper.

6. Заполните только URL:

http://IP_DO_SERVIDOR:3000/mcp

Пример:

http://192.168.3.233:3000/mcp

Оставьте эти поля полностью пустыми:

• Bearer token env var

• Headers

• Headers from environment variables

Не пишите none в полях аутентификации.

Затем:

1. Сохраните сервер.

2. Включите переключатель рядом с wiki-helper.

3. Откройте новый разговор в Codex.

4. Отправьте:

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

Если Codex сообщает, что переменная окружения none не существует:

1. Откройте Settings > MCP servers > wiki-helper.

2. Нажмите Uninstall.

3. Добавьте снова, заполнив только URL.

4. Оставьте все поля аутентификации пустыми.

5. Подключение в VS Code/Copilot

В VS Code:

1. Нажмите Ctrl+Shift+P.

2. Выполните MCP: Open User Configuration.

3. Поместите в файл mcp.json:

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

Затем выполните MCP: List Servers, выберите wiki-helper и выберите Start Server.

6. Примеры использования

Проверить сервер:

Use a ferramenta Server do MCP wiki-helper.

Перечислить документы:

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

Поиск по имени:

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

Поиск внутри Wiki:

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

Прочитать документ:

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

Частые проблемы

Ошибка ECONNREFUSED ...:80

В URL отсутствует порт или маршрут. Всегда используйте:

http://IP_DO_SERVIDOR:3000/mcp

Открылся маршрут /authorize

Клиент попытался использовать OAuth. Этот MCP не поддерживает OAuth. Удалите аутентификацию и оставьте поля Bearer и Headers пустыми.

MCP не подключается

Проверьте на серверной машине:

npm run start:http
ss -lntp | grep 3000

Проверьте снова на клиентской машине:

curl http://IP_DO_SERVIDOR:3000/health

Wiki не возвращает документы

Проверьте, содержит ли настроенная папка Markdown-файлы:

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

Также проверьте доступ к Git-репозиторию, указанному в WIKI_REPOSITORY_URL.

Безопасность

• Используйте этот режим без аутентификации только в контролируемой локальной сети.

• Не открывайте порт 3000 напрямую в интернет.

• Для внешнего доступа используйте HTTPS, аутентификацию и обратный прокси.

• Никогда не сохраняйте ключи или учётные данные в .env в системе контроля версий.