MCP de Base de Conocimientos

Servicio MCP de base de conocimientos inter-proyectos, que admite búsqueda de tres capas (coincidencia de texto / TF-IDF / vectores semánticos) y proporciona una interfaz web para la gestión.

Características

8 herramientas MCP — kb_write / kb_read / kb_search / kb_search_semantic / kb_list / kb_delete / kb_update / kb_outline
Arquitectura de búsqueda de tres capas — P0 coincidencia de texto + P1 TF-IDF + P2 vectores semánticos multilingües, con clasificación de fusión ponderada
Búsqueda semántica multilingüe — Basada en paraphrase-multilingual-MiniLM-L12-v2, admite búsqueda interlingüe en más de 50 idiomas
Modo de transmisión dual — Stdio (cliente MCP local) + HTTP (StreamableHTTP / SSE / REST API)
Interfaz Web — Vite 6 + React 18 + Zustand + Tailwind + Ant Design

Inicio rápido

Inicio con un clic mediante npx (recomendado)

Sin necesidad de clonar el repositorio, ejecute directamente:

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

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

Instalación global (opcional)

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

Construcción desde el código fuente

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

Al usar la búsqueda semántica por primera vez, es necesario descargar previamente el modelo de embedding:

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

Si no se descarga el modelo, la búsqueda semántica (P2) no estará disponible, pero la coincidencia de texto (P0) y TF-IDF (P1) seguirán funcionando normalmente.

Configuración de OpenCode

Modo Stdio (recomendado para uso local)

Edite ~/.config/opencode/opencode.json y añada lo siguiente en mcp.servers:

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

No es necesario iniciar manualmente, OpenCode gestionará automáticamente el ciclo de vida del proceso.

Modo StreamableHTTP (servidor remoto)

Primero inicie el servicio:

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

Configuración:

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

Modo SSE (cliente de versión antigua)

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

Interfaz Web

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

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

Acceda a http://localhost:5180, las solicitudes de API se redirigen automáticamente a :19877.

Herramientas MCP

Herramienta	Descripción
`kb_write`	Guarda documentos de conocimiento, admite metadatos como etiquetas, palabras clave, proyectos de origen, etc.
`kb_read`	Lee el contenido del documento, truncado automáticamente si supera las 50 líneas
`kb_search`	Búsqueda multidimensional de texto + palabras clave + etiquetas
`kb_search_semantic`	Búsqueda de vectores semánticos, admite búsqueda interlingüe
`kb_list`	Explora la lista de documentos, filtrando por etiquetas o proyectos
`kb_delete`	Elimina documentos y actualiza el índice de forma sincronizada
`kb_update`	Actualiza el cuerpo, título, etiquetas y palabras clave del documento
`kb_outline`	Obtiene el esquema de documentos de un proyecto específico

Parámetros de 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

Los siguientes endpoints solo están disponibles en modo HTTP.

Método	Ruta	Descripción
GET	`/health`	Comprobación de estado
GET	`/api/docs`	Lista todos los documentos
GET	`/api/doc/:id`	Lee un documento específico
POST	`/api/search`	Búsqueda integral (fusión de tres capas)
POST	`/api/search/semantic`	Búsqueda semántica
GET	`/api/outline?project=...`	Obtiene el esquema del proyecto

Arquitectura de búsqueda

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

Nivel	Algoritmo	Características	Escenario
P0	Coincidencia de subcadenas + ponderación de campos	Preciso, rápido	Palabras clave conocidas
P1	TF-IDF + similitud de coseno	Segmentación de bigramas en chino, campos ponderados	Coincidencia difusa
P2	multilingual-MiniLM + similitud de coseno	Coincidencia semántica interlingüe en más de 50 idiomas	Consultas en lenguaje natural

kb_search utiliza P0, kb_search_semantic utiliza P2, y HTTP /api/search utiliza la fusión de tres capas.

Estructura de almacenamiento

Todos los datos se almacenan en ~/.knowledge/ (se puede personalizar mediante la variable de entorno KB_DIR):

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

Ejemplo de archivo de documento individual:

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

Pruebas

bun test

Variables de entorno

Variable	Valor predeterminado	Descripción
`KB_DIR`	`~/.knowledge`	Directorio de almacenamiento de la base de conocimientos
`PORT`	`19877`	Puerto del modo HTTP (también disponible mediante el parámetro `--port`)

Licencia

MIT

Knowledge Base MCP