ko-qmdBLOCK
Local hybrid search for Korean Markdown notes & Obsidian vaults (BM25 + Hangul bigram + Qwen3 + rerank, MCP/CLI/SDK) · 한국어 마크다운 로컬 검색
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://www.npmjs.com/package/ko-qmd) [](LICENSE)
한국어 · English
ko-qmd 는 한국어 마크다운 노트(Obsidian 볼트·위키·회의록·문서 폴더)를 키워드와 자연어로 찾는 로컬 검색 엔진이다. BM25 전문 검색, 벡터 검색, LLM 리랭크를 섞어 쓰고, 조사·어미가 붙은 한국어 질의도 어간으로 찾는다. 모든 모델이 node-llama-cpp 로 내 컴퓨터에서 돌아 노트가 밖으로 나가지 않는다(GGUF, 네트워크 호출 없음). AI 에이전트(Claude Code·Claude Desktop 등)는 CLI·MCP 서버·REST·TypeScript SDK 로 쓴다. tobi/qmd(MIT)의 한국어 배포판이다.
- 패키지:
ko-qmd(npm). 실행 파일과 MCP 서버 이름은 업스트림과 같은qmd - 버전:
-ko.N(예:2.8.3-ko.5) - 영어 레퍼런스(전체 CLI 옵션·MCP 툴 파라미터·SDK API·점수 계산): docs/REFERENCE.md
- 변경 이력: CHANGELOG.md · 자주 묻는 질문: FAQ
flowchart LR Q[질의] --> H[한글 처리조사·어미 제거 · 외래어 다리] H --> FTS[BM25FTS5 + 음절 bigram] Q --> VS[벡터 검색Qwen3-Embedding] FTS --> RRF[RRF 융합] VS --> RRF RRF --> RR[리랭크Qwen3-Reranker] RR --> OUT[결과]
업스트림과 다른 점
한국어 키워드 검색 (lex)
- 조사·어미 제거 — 따옴표 없는 한글 단어는 어간도 매칭한다. 끝 조사 하나(
검색을→검색), 두 조사 연쇄(청킹에서의→청킹),
동사·명사화 어미(토큰화하는 → 토큰화, 검색하기 → 검색), 한/된 어미(필요한 → 필요), 하↔해 축약(더하 ↔ 더해). 따옴표 구문·한자·가나는 그대로 둔다.
- 외래어 다리 — 기술 용어의 한글 표기(
서치·웹·코어·마이그레이션등 약 90개 내장 표)는 영문 표기도 함께 찾는다.
하이브리드 서치가 hybrid-search 노트를, 리액트 웹 코어가 react-web-core를 찾는다. 질의 쪽만 바뀌므로 재색인은 필요 없다.
- 문자 체계가 섞인 토큰 분리 —
SKILL.md계약의핵심은skillANDmdAND계약의핵심으로 나눈다. - 긴 질의 완화 — 세 단어 이상 질의가 AND 로 한 건도 안 맞으면 같은 단어를 OR 로 다시 찾는다. 자연어 문장 질의가 0건이 되지 않는다.
- 음절 bigram 색인 — 한글 구간의 음절 bigram 을 FTS 필드에 덧붙인다. 붙여 쓴 복합어 안의 단어도 걸린다.
기존 인덱스는 처음 열 때 FTS 를 한 번 다시 만든다.
- 부정 절 제거 — "X 말고 Y" 꼴 질의는 Y 만 찾는다(
말고·빼고·제외하고·제외한).
기본 모델과 청킹
2baa3143e456OBSERVED · 2026-10-11Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add ko-qmd --env HF_TOKEN=${HF_TOKEN} --env QMD_RERANK_MAX_DOC_TOKENS=${QMD_RERANK_MAX_DOC_TOKENS} -- npx -y [email protected]{
"mcpServers": {
"ko-qmd": {
"command": "npx",
"args": [
"-y",
"[email protected]"
],
"env": {
"HF_TOKEN": "${HF_TOKEN}",
"QMD_RERANK_MAX_DOC_TOKENS": "${QMD_RERANK_MAX_DOC_TOKENS}"
}
}
}
}Exposed tools (5)
5 read · 0 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
get | read | |
grep | read | |
multi_get | read | |
query | read | |
status | read |
Trust audit
BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | FAIL |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (2 observation(s))
- Network
- declared (9 observation(s))
- Shell
- declared (6 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (14)
if (!new Function("r", `return (${process.argv[3]})`)(r)) { console.error(`dogfood: ${process.argv[1]} failed check ${process.argv[3]}: ${process.argv[2].slice(0, 200)}`); process.exit(1); }exec(sql: string): void;
URL="${DOGFOOD_URL:-http://127.0.0.1:8181}"const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "../../package.json");
import { tryAcquireEmbedLock } from "../../src/cli/embed-lock.ts";import { createStore } from "../../src/store.ts";expect(resolve("/base/a/b", "../../c")).toBe("/base/c");expect(resolve("C:/base/a/b", "../../c")).toBe("C:/base/c");curl -s http://127.0.0.1:8181/query -H 'Content-Type: application/json' -d '{curl -s http://127.0.0.1:8181/query -H 'Content-Type: application/json' -d '{- 머신 배선 env: `DOGFOOD_LABEL`(launchd 라벨, 기본 `io.github.ko-qmd.daemon`) · `DOGFOOD_URL`(기본 `http://127.0.0.1:8181`) ·
DOGFOOD_URL: "http://127.0.0.1:9",
better-sqlite3
### Does it need internet access or an API key?
Gates applied: no_behavioural_pass.
2baa3143e456full audit observations/trust-audit/mcp-server/tak-bro__ko-qmd.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-11 | 2baa3143e456 | BLOCK | D | 69 | first audit |
Questions
What is the ko-qmd MCP server?
Local hybrid search for Korean Markdown notes & Obsidian vaults (BM25 + Hangul bigram + Qwen3 + rerank, MCP/CLI/SDK) · 한국어 마크다운 로컬 검색
What tools does ko-qmd expose?
5 in total: 5 read-only, 0 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is ko-qmd safe to connect to an agent?
No — not without reading the findings first. The audit graded it D (69/100) and found 2 critical or high issues in the source. Each one is listed on this page with the file and line it is on.
What credentials does ko-qmd need?
It reads HF_TOKEN and QMD_RERANK_MAX_DOC_TOKENS from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does ko-qmd run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as ko-qmd at 2.8.3-ko.7.
How current is this page?
The grade is for one exact copy of the source (2baa3143e456), read on 2026-10-11. The repository is watched and re-audited when it changes.