로컬 MCP 서버로, 에이전트가 오프라인 ZIM 아카이브 로컬 지식 코퍼스(Wikipedia, 의료(MDWiki), 개발자 문서(DevDocs), Stack Exchange)를 하나의 통일된 인터페이스로 깔끔하고 효율적으로 접근할 수 있게 합니다. 인터넷도, 임베딩도, 벡터 데이터베이스도 필요 없습니다. libzim 전문(full-text) 검색과 서버 내부의 결정적(deterministic) 콘텐츠 정제만 사용합니다.
공개 MCP 인터페이스는 정확히 두 개의 도구입니다.
search(query, limit?)
fetch(ref, sections?)구성된 코퍼스는 **운영자(operator)**가 신경 쓸 일이지 에이전트가 신경 쓸 일이 아닙니다. 에이전트가 할 수 있는 일은 오직 다음과 같습니다:
discover → search()
select → fetch()Corpus |
| 문서 | 섹션 모델 |
Wikipedia, MDWiki |
| 문서 | 제목 트리(h2+), 리드 문단 id |
DevDocs (C, CMake, Python) |
| 문서 페이지 | 제목 트리; 페이지 내 목차(TOC)와 네비 크롬(nav chrome) 제거 |
Stack Exchange |
| 질문 + 답변 | 합성 섹션: |
모든 코퍼스 식별, 라우팅, ZIM 접근, HTML 해석, 정제, 순위화, 리다이렉트 처리, 정규화는 서버의 책임입니다. 에이전트가 HTML을 파싱하거나, 리다이렉트를 해석하거나, 참조를 만들거나 파싱하거나, libzim, ZIM 네임스페이스, 코퍼스 저장 방식 내부에 대해 알 필요가 전혀 없습니다.
Related MCP server: mcpzim
search() 결과에는 불투명한 ref(예: corpus://Wikipedia/Bell_test)가 담겨 있으며 fetch()가 그것을 소비합니다. 에이전트는 참조를 만들거나, 파싱하거나, 수정해서는 안 되며, 참조에서 코퍼스를 추측해서도 안 됩니다:
search() produces ref fetch() consumes refLocal agent
│ MCP / Streamable HTTP → http://127.0.0.1:8000/mcp
▼
┌──────────────────────────────────────────────┐
│ Corpus MCP Server │
│ search() fetch() │
│ ├─ CorpusManager (routing, cache, │
│ │ bounded-concurrency fan-out) │
│ ├─ federated ranking (RRF + lexical title │
│ │ reranking + diversity) │
│ ├─ adapters: mediawiki / devdocs / │
│ │ stackexchange │
│ ├─ HTML cleaner → Markdown, section trees │
│ └─ GlobalRef codec (opaque refs) │
└─────────────┬────────────────────────────────┘
▼
per-library ZIM service (only libzim touchpoint,
one search lock per archive)
▼
corpus/ (read-only volume, N .zim archives)
corpus.toml (manifest: name, adapter, path)MCP 계층은 libzim 관련 개념을 노출하지 않습니다: 네임스페이스, 클러스터 ID, 원시 항목, MIME 타입 또는 원시 HTML은 없습니다.
Docker + Docker Compose
ZIM 아카이브(아래 참조)
로컬에서 테스트 스위트를 실행하려면: Python 3.12 및 uv(또는 pip)
서버는 아카이브를 직접 다운로드하지 않습니다 — 코퍼스 확보는 의도적으로 애플리케이션 시작과 분리되어 있습니다. 기본 배치는 다음과 같습니다:
corpus/
wikipedia/wikipedia_en_all_nopic_*.zim
medical/mdwiki_en_all_maxi_*.zim
devdocs/devdocs_en_cpp_*.zim
devdocs/devdocs_en_cmake_*.zim
devdocs/devdocs_en_python_*.zim
stackexchange/stackoverflow.com_en_all_*.zim
stackexchange/security.stackexchange.com_en_all_*.zim
stackexchange/softwareengineering.stackexchange.com_en_all_*.zim
corpus.tomlcorpus.toml은 각 라이브러리, 해당 어댑터, 그리고 경로(코퍼스 루트 기준)를 지정합니다:
version = 1
[[library]]
name = "Wikipedia"
path = "wikipedia/wikipedia_en_all_nopic_2026-06.zim"
adapter = "mediawiki"
[[library]]
name = "CMake-Docs"
path = "devdocs/devdocs_en_cmake_2026-08.zim"
adapter = "devdocs"검증 규칙: 이름은 고유해야 하고, 어댑터는 알려진 것이어야 하며, 경로는 코퍼스 루트 내부에 있어야 합니다. 서ver를 시작하기 전에 코퍼스를 검증하세요:
make validate-corpus # opens every archive, reports metadata
make corpus-list # list configured librariesmake start # build + start (docker compose, detached)
make logs # tail logs
make ps # container status
make stop # stop (keep containers)
make down # stop + remove
make restart
make build그다음 MCP 엔드포인트는 http://127.0.0.1:8000/mcp(Streamable HTTP)에서 사용할 수 있습니다. 호스트 포트는 기본적으로 루프백에만 바인딩되며, 컨테이너는 내부적으로 0.0.0.0:8000에서 수신합니다.
구성된 ZIM 중 하나라도 열 수 없으면 서버는 시작에 실패하며, 문제의 라이브러리 이름을 알려줍니다. 부분적으로만 동작하는 모드는 없습니다.
search(query: str, limit?: int)구성된 모든 라이브러리의 전체 텍스트 인덱스를 검색하되(동시성 제한, 아카이브당 워크 1개), 순위가 매겨진 결과를 Reciprocal Rank Fusion으로 융합하고, 동률인 교차 코퍼스 후보는 제목 어휘 포함도를 기준으로 다시 정렬하며, 결정적 다양성 처리(pass)를 거쳐 깔끔한 결과를 반환합니다. limit 기본값은 5이며, 서버는 상한(SEARCH_MAX_LIMIT, 기본 10)을 강제합니다.
{
"results": [
{
"ref": "corpus://Wikipedia/Bell_test",
"library": "Wikipedia",
"kind": "article",
"title": "Bell test",
"snapshot": "2026-06",
"snippet": "To close the detection loophole, an apparatus with a high detection efficiency is needed.",
"relevant_sections": [
{ "id": "Notable_experiments", "title": "Notable experiments" },
{ "id": "Loopholes", "title": "Loopholes" }
]
}
]
}ref — 불투명한 전역 식별자; fetch()에 그대로 넘겨주세요.
library / kind / snapshot — 출처 정보: 어떤 아카이브, 어떤 종류의 문서, 그리고 (아카이브 메타데이터에서 파생한) 코퍼스 스냅샷인지를 나타냅니다.
relevant_sections — 0–3개의 결정적 어휘 힌트(명확히 일치하는 섹션이 없으면 비어 있음). 섹션 ID는 서버가 산출하며, 에이전트가 이를 재구성해서는 안 됩니다.
하나의 라이브러리가 실패해도 검색 결과는 저하될 뿐(다른 라이브러리는 계속 응답함) 중단되지는 않습니다.
fetch(ref: str, sections?: list[str])정제된 문서를 구조화된 Markdown으로 반환합니다.
sections 미지정: 문서 전체(MAX_FETCH_CHARS 제한, 섹션 경계에서 잘리면 truncated: true).
sections 지정: 해당 섹션만 반환(하위 트리 포함). 섹션 ID는 search()힌트 또는 available_sections에서 가져옵니다. 리드/소개 섹션의 id는 ""입니다. 스레드의 경우 섹션은 question, accepted-answer, answer-<id>이며, 이들의 metadata에는 점수, 채택 여부, 태그가 담깁니다.
{
"ref": "corpus://Wikipedia/Bell_test",
"library": "Wikipedia",
"kind": "article",
"title": "Bell test",
"snapshot": "2026-06",
"sections": [
{ "id": "Loopholes", "title": "Loopholes", "content": "## Loopholes\n\n..." }
],
"available_sections": [
{ "id": "", "title": "Bell test" },
{ "id": "Background", "title": "Background" },
{ "id": "Loopholes", "title": "Loopholes" }
],
"truncated": false
}오류는 간결하고 바로 조치할 수 있도록 제공됩니다:
{ "error": "invalid_ref", "message": "invalid reference: ..." }
{ "error": "not_found", "message": "Document not found in Wikipedia: Foo_bar" }
{
"error": "section_not_found",
"missing_sections": ["Experiments"],
"available_sections": [ { "id": "Loopholes", "title": "Loopholes" }, "..." ]
}search("Bell experiment loopholes")
↓
fetch("corpus://Wikipedia/Bell_test", ["Notable_experiments", "Loopholes"])환경 변수(컨테이너 기본값 표시):
Variable | Default | 의미 대략 |
|
| 컨테이너 내부의 코퍼스 루트(필수) |
|
| 컨테이너 내부의 매니페스트 경로 (필수) |
|
| 컨테이너 내부 수신(listen) 주소 |
|
| 컨테이너 내부 수신 포트 |
|
|
|
|
|
|
|
| 가져온(fetch) 콘텐츠 출력 예산 |
|
| 팬아웃 시 동시에 실행되는 아카이브 검색 |
|
| 다양성 패스: 각 라이브러리에서 연속으로 반환할 최대 건수 |
|
| 검색 쿼리 텍스트 로그 여부(개인정보) |
|
| 시작 시 libzim 전체 체크섬 검증 실행(코퍼스전체를 읽음, 옵트인이라 대형 아카이브에서 큼)임) |
호스트 측 compose 변수: CORPUS_ROOT(기본 ./corpus)와 CORPUS_CONFIG(기본 ./corpus.toml).
서버는 잘못된 구성이면 즉시(fail fast) 실패합니다.
make test # unit + integration + MCP surface tests (needs .venv)
make lint
make format로컬 테스트 실행을 위한 설정:
uv venv .venv --python 3.12
uv pip install -e . --python .venv/bin/python
uv pip install --python .venv/bin/python pytest pytest-asyncio ruff
make test테스트는 libzim의 writer를 이용해 코퍼스 패밀리당 하나씩 작은 자체 ZIM fixture를 만듭니다. 별도의 코퍼스는 필요 없습니다. MCP 표면 회귀 테스트는 서버가 도구 search와 fetch 정확히 두 가지만 노출하고, 다른 프롬프트나 리소스가 없을 확인합니다.
설계상 로컬 서비스입니다: 호스트 바인딩은 기본적으로 루프백 전용, 코퍼스 볼륨은 읽기 전용, 컨테이너는 비루트 사용자로 실행되며, 권한 모드(privileged mode)가 없고, Docker 소켓도 없고, 임의 파일 시스템 접근도, URL 가져오기도, 셸 실행도 허용하지 않습니다. 두 도구 모두 파일 시스템 경로, URL, 명령어, 실행 가능한 콘텐츠를 허용하지 않습니다 — ref는 단지 불투명한 코퍼스 식별자일 뿐입니다.
This server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Shared, peer-validated knowledge archive for AI agents — search, contribute, and validate via MCP
Agentic search over your Dewey document collections from any MCP-compatible client.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/MagoDelBlocco/mcp-wiki'
If you have feedback or need assistance with the MCP directory API, please join our Discord server