mcp-wiki-helper-tools

用于查询存储在 Git 仓库中的 Wiki 的 MCP 服务器。

它会同步 Wiki、索引 Markdown 文件，并提供工具在 Codex 或 VS Code 中列出、搜索和阅读文档。

功能

Related MCP server: knowledge-mcp

工作原理

1. MCP 克隆或更新 Wiki 的 Git 仓库。

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. 打开 设置。

2. 进入 MCP 服务器。

3. 点击 + 添加服务器。

4. 选择 URL/HTTP 类型。

5. 使用名称 wiki-helper。

6. 仅填写 URL：

http://IP_DO_SERVIDOR:3000/mcp

示例：

http://192.168.3.233:3000/mcp

将以下字段完全留空：

• Bearer token 环境变量

• Headers

• 来自环境变量的 Headers

不要在认证字段中填写 none。

然后：

1. 保存服务器。

2. 启用 wiki-helper 旁边的开关。

3. 在 Codex 中打开新对话。

4. 发送：

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

如果 Codex 提示环境变量 none 不存在：

1. 打开 设置 > MCP 服务器 > wiki-helper。

2. 点击 卸载。

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

同时检查 WIKI_REPOSITORY_URL 中配置的 Git 仓库访问权限。

安全

• 仅在受控的本地网络中使用此无认证模式。

• 不要将 3000 端口直接暴露到互联网。

• 如需外部访问，请使用 HTTPS、认证和反向代理。

• 切勿在 .env 中版本化密钥或凭据。