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. /mcp HTTP 경로를 통해 도구를 제공합니다.

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 필드는 0보다 커야 합니다.

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

또한 WIKI_REPOSITORY_URL에 구성된 Git 저장소에 대한 액세스를 확인하세요.

보안

• 인증 없이 이 모드를 사용하는 것은 통제된 로컬 네트워크에서만 하세요.

• 포트 3000을 인터넷에 직접 노출하지 마세요.

• 외부 액세스에는 HTTPS, 인증 및 리버스 프록시를 사용하세요.

• .env에 키나 자격 증명을 버전 관리하지 마세요.