Knowledge Base MCP

Ein projektübergreifender Knowledge-Base-MCP-Server, der eine dreistufige Suche (Textabgleich / TF-IDF / semantische Vektoren) unterstützt und eine Web-UI zur Verwaltung bietet.

Funktionen

8 MCP-Tools — kb_write / kb_read / kb_search / kb_search_semantic / kb_list / kb_delete / kb_update / kb_outline
Dreistufige Sucharchitektur — P0 Textabgleich + P1 TF-IDF + P2 mehrsprachige semantische Vektoren, gewichtete Fusionssortierung
Mehrsprachige semantische Suche — Basierend auf paraphrase-multilingual-MiniLM-L12-v2, unterstützt sprachübergreifende Suche in über 50 Sprachen
Zwei Übertragungsmodi — Stdio (lokaler MCP-Client) + HTTP (StreamableHTTP / SSE / REST API)
Web UI — Vite 6 + React 18 + Zustand + Tailwind + Ant Design

Schnelleinstieg

npx One-Click-Start (empfohlen)

Kein Klonen des Repositorys erforderlich, einfach ausführen:

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

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

Globale Installation (optional)

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

Aus dem Quellcode bauen

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

Bei der ersten Verwendung der semantischen Suche muss das Embedding-Modell vorab heruntergeladen werden:

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")
'

Wenn das Modell nicht heruntergeladen wird, ist die semantische Suche (P2) nicht verfügbar, aber der Textabgleich (P0) und TF-IDF (P1) funktionieren weiterhin normal.

OpenCode-Konfiguration

Stdio-Modus (empfohlen für lokale Nutzung)

Bearbeiten Sie ~/.config/opencode/opencode.json und fügen Sie Folgendes unter mcp.servers hinzu:

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

Kein manueller Start erforderlich, OpenCode verwaltet den Prozesslebenszyklus automatisch.

StreamableHTTP-Modus (Remote-Server)

Starten Sie zuerst den Dienst:

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

Konfiguration:

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

SSE-Modus (ältere Clients)

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

Web UI

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

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

Besuchen Sie http://localhost:5180, API-Anfragen werden automatisch an :19877 weitergeleitet.

MCP-Tools

Tool	Beschreibung
`kb_write`	Speichert Wissensdokumente, unterstützt Metadaten wie Tags, Schlüsselwörter, Quellprojekte usw.
`kb_read`	Liest Dokumentinhalte, automatische Kürzung ab 50 Zeilen
`kb_search`	Mehrdimensionale Suche nach Text + Schlüsselwörtern + Tags
`kb_search_semantic`	Semantische Vektorsuche, unterstützt sprachübergreifende Suche
`kb_list`	Durchsuchen der Dokumentenliste, Filterung nach Tags oder Projekten
`kb_delete`	Löscht Dokumente, aktualisiert den Index synchron
`kb_update`	Aktualisiert Dokumenttext, Titel, Tags, Schlüsselwörter
`kb_outline`	Ruft die Dokumentgliederung für ein angegebenes Projekt ab

kb_write Parameter

{
  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

Die folgenden Endpunkte sind nur im HTTP-Modus verfügbar.

Methode	Pfad	Beschreibung
GET	`/health`	Gesundheitsprüfung
GET	`/api/docs`	Alle Dokumente auflisten
GET	`/api/doc/:id`	Bestimmtes Dokument lesen
POST	`/api/search`	Umfassende Suche (dreistufige Fusion)
POST	`/api/search/semantic`	Semantische Suche
GET	`/api/outline?project=...`	Projektgliederung abrufen

Sucharchitektur

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

Ebene	Algorithmus	Merkmale	Szenario
P0	Teilstring-Abgleich + Feldgewichtung	Präzise, schnell	Bekannte Schlüsselwörter
P1	TF-IDF + Kosinus-Ähnlichkeit	Chinesische Bigram-Segmentierung, gewichtete Felder	Fuzzy-Matching
P2	multilingual-MiniLM + Kosinus-Ähnlichkeit	Sprachübergreifender semantischer Abgleich (50+ Sprachen)	Natürlichsprachliche Abfragen

kb_search verwendet P0, kb_search_semantic verwendet P2, HTTP /api/search verwendet die dreistufige Fusion.

Speicherstruktur

Alle Daten werden unter ~/.knowledge/ gespeichert (kann über die Umgebungsvariable KB_DIR angepasst werden):

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

Beispiel für eine einzelne Dokumentdatei:

---
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 的注意事项
...

Testen

bun test

Umgebungsvariablen

Variable	Standardwert	Beschreibung
`KB_DIR`	`~/.knowledge`	Speicherverzeichnis der Wissensdatenbank
`PORT`	`19877`	Port für den HTTP-Modus (auch über `--port` Parameter verfügbar)

Lizenz

MIT

Knowledge Base MCP

Knowledge Base MCP

Funktionen

Schnelleinstieg

npx One-Click-Start (empfohlen)

Globale Installation (optional)

Aus dem Quellcode bauen

OpenCode-Konfiguration

Stdio-Modus (empfohlen für lokale Nutzung)

StreamableHTTP-Modus (Remote-Server)

SSE-Modus (ältere Clients)

Web UI

MCP-Tools

kb_write Parameter

REST API

Sucharchitektur

Speicherstruktur

Testen

Umgebungsvariablen

Lizenz

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API