Skip to main content
Glama
deenesjakoruzh
dyyz1993

Knowledge Base MCP

by dyyz1993
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Knowledge Base MCP

A cross-project knowledge base MCP server that supports three-layer search (text matching / TF-IDF / semantic vectors) and provides a Web UI for management.

Features

  • 8 MCP Tools — kb_write / kb_read / kb_search / kb_search_semantic / kb_list / kb_delete / kb_update / kb_outline

  • Three-Layer Search Architecture — P0 text matching + P1 TF-IDF + P2 multilingual semantic vectors, with weighted fusion ranking

  • Multilingual Semantic Search — Based on paraphrase-multilingual-MiniLM-L12-v2, supporting cross-lingual retrieval for 50+ languages

  • Dual Transport Modes — Stdio (local MCP client) + HTTP (StreamableHTTP / SSE / REST API)

  • Web UI — Vite 6 + React 18 + Zustand + Tailwind + Ant Design

Related MCP server: RAG MCP Server

Quick Start

npx One-Click Launch (Recommended)

No need to clone the repository, just run:

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

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

Global Installation (Optional)

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

Build from Source

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

When using semantic search for the first time, you need to download the embedding model in advance:

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

If the model is not downloaded, semantic search (P2) will be unavailable, but text matching (P0) and TF-IDF (P1) will still work normally.

OpenCode Configuration

Stdio Mode (Recommended for local use)

Edit ~/.config/opencode/opencode.json and add the following to mcp.servers:

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

No manual startup is required; OpenCode will automatically manage the process lifecycle.

StreamableHTTP Mode (Remote Server)

Start the service first:

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

Configuration:

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

SSE Mode (Legacy Client)

{
  "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

Visit http://localhost:5180, and API requests will be automatically proxied to :19877.

MCP Tools

Tool

Description

kb_write

Save knowledge documents, supporting metadata such as tags, keywords, and source projects

kb_read

Read document content, automatically truncated if over 50 lines

kb_search

Multi-dimensional search for text + keywords + tags

kb_search_semantic

Semantic vector search, supporting cross-lingual retrieval

kb_list

Browse document list, filtered by tags or projects

kb_delete

Delete documents and update indexes synchronously

kb_update

Update document body, title, tags, and keywords

kb_outline

Get the document outline for a specified project

kb_write Parameters

{
  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

The following endpoints are only available in HTTP mode.

Method

Path

Description

GET

/health

Health check

GET

/api/docs

List all documents

GET

/api/doc/:id

Read a specific document

POST

/api/search

Comprehensive search (three-layer fusion)

POST

/api/search/semantic

Semantic search

GET

/api/outline?project=...

Get project outline

Search Architecture

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

Layer

Algorithm

Features

Scenario

P0

Substring matching + field weighting

Precise, fast

Known keywords

P1

TF-IDF + cosine similarity

Chinese bigram tokenization, weighted fields

Fuzzy matching

P2

multilingual-MiniLM + cosine similarity

50+ languages cross-lingual semantic matching

Natural language queries

kb_search uses P0, kb_search_semantic uses P2, and HTTP /api/search uses three-layer fusion.

Storage Structure

All data is stored in ~/.knowledge/ (customizable via the KB_DIR environment variable):

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

Example of a single document file:

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

Testing

bun test

Environment Variables

Variable

Default Value

Description

KB_DIR

~/.knowledge

Knowledge base storage directory

PORT

19877

HTTP mode port (also available via --port parameter)

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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