지식 베이스 MCP

프로젝트 간 지식 베이스 MCP 서비스로, 3계층 검색(텍스트 매칭 / TF-IDF / 의미론적 벡터)을 지원하며 관리용 웹 UI를 제공합니다.

기능 특징

8개의 MCP 도구 — kb_write / kb_read / kb_search / kb_search_semantic / kb_list / kb_delete / kb_update / kb_outline
3계층 검색 아키텍처 — P0 텍스트 매칭 + P1 TF-IDF + P2 다국어 의미론적 벡터, 가중치 융합 정렬
다국어 의미론적 검색 — paraphrase-multilingual-MiniLM-L12-v2 기반, 50개 이상의 언어 간 교차 언어 검색 지원
이중 전송 모드 — Stdio(로컬 MCP 클라이언트) + HTTP(StreamableHTTP / SSE / REST API)
웹 UI — Vite 6 + React 18 + Zustand + Tailwind + Ant Design

빠른 시작

npx 원클릭 실행(권장)

저장소를 복제할 필요 없이 바로 실행:

# Stdio 模式
npx @dyyz1993/kb-mcp --stdio

# HTTP 模式
npx @dyyz1993/kb-mcp --http --port 19877

전역 설치(선택 사항)

npm install -g @dyyz1993/kb-mcp
kb-mcp --stdio

소스 코드에서 빌드

git clone https://github.com/dyyz1993/knowledge-base-mcp.git
cd knowledge-base-mcp
bun install

의미론적 검색을 처음 사용할 때는 임베딩 모델을 미리 다운로드해야 합니다:

bun run -e '
import { pipeline, env } from "@huggingface/transformers"
import { join } from "node:path"
import { homedir } from "node:os"
env.localModelPath = join(homedir(), ".cache/huggingface/local-models")
env.allowLocalModels = true
await pipeline("feature-extraction", "Xenova/paraphrase-multilingual-MiniLM-L12-v2", { dtype: "fp32" })
console.log("Model downloaded")
'

모델을 다운로드하지 않으면 의미론적 검색(P2)은 사용할 수 없지만, 텍스트 매칭(P0)과 TF-IDF(P1)는 정상적으로 작동합니다.

OpenCode 설정

Stdio 모드(로컬 사용 권장)

~/.config/opencode/opencode.json을 편집하여 mcp.servers에 추가합니다:

{
  "mcp": {
    "servers": {
      "knowledge-base": {
        "type": "local",
        "command": ["npx", "@dyyz1993/kb-mcp", "--stdio"]
      }
    }
  }
}

수동으로 시작할 필요 없이 OpenCode가 프로세스 수명 주기를 자동으로 관리합니다.

StreamableHTTP 모드(원격 서버)

먼저 서비스를 시작합니다:

npx @dyyz1993/kb-mcp --http --port 19877

설정:

{
  "mcp": {
    "servers": {
      "knowledge-base": {
        "type": "streamable-http",
        "url": "http://your-server:19877/mcp"
      }
    }
  }
}

SSE 모드(구버전 클라이언트)

{
  "mcp": {
    "servers": {
      "knowledge-base": {
        "type": "sse",
        "url": "http://your-server:19877/sse"
      }
    }
  }
}

웹 UI

# 先启动 HTTP 服务
npx @dyyz1993/kb-mcp --http --port 19877

# 启动 Web UI
cd web
bun install
bun run dev

http://localhost:5180에 접속하면 API 요청이 :19877로 자동 프록시됩니다.

MCP 도구

도구	설명
`kb_write`	지식 문서 저장, 태그, 키워드, 출처 프로젝트 등 메타데이터 지원
`kb_read`	문서 내용 읽기, 50줄 초과 시 자동 절단
`kb_search`	텍스트 + 키워드 + 태그 다차원 검색
`kb_search_semantic`	의미론적 벡터 검색, 교차 언어 검색 지원
`kb_list`	문서 목록 탐색, 태그 또는 프로젝트별 필터링
`kb_delete`	문서 삭제, 인덱스 동기화 업데이트
`kb_update`	문서 본문, 제목, 태그, 키워드 업데이트
`kb_outline`	지정된 프로젝트의 문서 개요 가져오기

kb_write 매개변수

{
  title: string              // 文档标题
  content: string            // 正文（Markdown）
  tags: string[]             // 标签：tutorial / document / analysis / guide / snippet / best-practice / reference / architecture / troubleshooting / decision
  keywords: string[]         // 关键词，用于检索
  intent: string             // 创建意图或使用场景
  project_description: string // 当前项目简要描述
  source_project?: string    // 来源项目路径（自动填充）
  source_worktree?: string   // 来源 worktree 路径（自动填充）
}

REST API

다음 엔드포인트는 HTTP 모드에서만 사용할 수 있습니다.

메서드	경로	설명
GET	`/health`	상태 확인
GET	`/api/docs`	모든 문서 나열
GET	`/api/doc/:id`	지정된 문서 읽기
POST	`/api/search`	통합 검색(3계층 융합)
POST	`/api/search/semantic`	의미론적 검색
GET	`/api/outline?project=...`	프로젝트 개요 가져오기

검색 아키텍처

查询 → ┌─ P0: 文本匹配（标题/关键词/意图） ──── 权重 0.2
       ├─ P1: TF-IDF（加权词频 + 余弦相似度） ── 权重 0.3
       └─ P2: 语义向量（384维 embedding + 余弦相似度） ── 权重 0.5
         ↓
       加权融合 → 排序返回 TopK

계층	알고리즘	특징	시나리오
P0	부분 문자열 매칭 + 필드 가중치	정확함, 빠름	알려진 키워드
P1	TF-IDF + 코사인 유사도	중국어 bigram 토큰화, 가중치 필드	퍼지 매칭
P2	multilingual-MiniLM + 코사인 유사도	50개 이상의 언어 간 의미론적 매칭	자연어 쿼리

kb_search는 P0을 사용하고, kb_search_semantic은 P2를 사용하며, HTTP /api/search는 3계층 융합을 사용합니다.

저장 구조

모든 데이터는 ~/.knowledge/에 저장됩니다(KB_DIR 환경 변수로 사용자 지정 가능):

~/.knowledge/
├── index.json              # 文档索引
├── vectors.json            # 语义向量缓存
├── outlines/               # 项目大纲
│   └── {project-slug}.json
├── {id}-{title-slug}.md    # 文档文件（YAML frontmatter + Markdown 正文）
└── ...

단일 문서 파일 예시:

---
id: "abc123xyz"
title: "React Hooks 最佳实践"
tags: ["best-practice"]
keywords: ["react", "hooks", "useEffect"]
intent: "React 开发中 hooks 的常见模式和陷阱"
project_description: "前端组件库项目"
source_project: "/Users/x/project-frontend"
created_at: 1746012345678
---

## 使用 useEffect 的注意事项
...

테스트

bun test

환경 변수

변수	기본값	설명
`KB_DIR`	`~/.knowledge`	지식 베이스 저장 디렉토리
`PORT`	`19877`	HTTP 모드 포트(`--port` 매개변수로도 사용 가능)

라이선스

MIT

Knowledge Base MCP