Knowledge Base MCP

プロジェクト横断型の知識ベースMCPサービス。3層検索（テキストマッチング / TF-IDF / セマンティックベクトル）をサポートし、管理用のWeb 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）
Web 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"
      }
    }
  }
}

Web 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` パラメータも使用可能）

License

MIT

Knowledge Base MCP

Knowledge Base MCP

機能特性

クイックスタート

npx で一括起動（推奨）

グローバルインストール（オプション）

ソースからビルド

OpenCode 設定

Stdio モード（ローカル使用を推奨）

StreamableHTTP モード（リモートサーバー）

SSE モード（旧版クライアント）

Web UI

MCP ツール

kb_write パラメータ

REST API

検索アーキテクチャ

ストレージ構造

テスト

環境変数

License

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API