Skip to main content
Glama
deenesjakoruzh
dyyz1993

Knowledge Base MCP

by dyyz1993
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

지식 베이스 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

Related MCP server: RAG MCP Server

빠른 시작

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

This server cannot be deployed

Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • fund-mcp

    xiaobenyang-com
    A
    license
    C
    quality
    D
    maintenance
    A fund knowledge base server based on Model Context Protocol (MCP), providing query and retrieval functions of fund-related knowledge, and supporting multiple deployment modes and protocols.
    3
    2
    Apache 2.0

  • RAG MCP Server

    sglwsjxh
    A
    license
    Not graded
    quality
    C
    maintenance
    A RAG knowledge base MCP server that adds vector search and reranking capabilities to opencode, supporting multimodal embeddings, multiple knowledge bases, and local storage.
    1
    MIT

  • knowledge-mcp

    gilanggsb
    A
    license
    A
    quality
    B
    maintenance
    Vendor-neutral MCP server for knowledge retrieval across repositories, offering stable tools for searching, getting, and listing documents with hybrid lexical and optional semantic search.
    3
    MIT