Knowlin MCP

KnowlinMCP

具有混合语义搜索的按项目知识数据库，作为MCP服务器公开。捕获见解，索引文档和会话记录，通过密集+稀疏+重新排序搜索进行检索。

                          KnowlinMCP
  +-----------+     +-------------------+     +-----------+
  | Claude    |     |   MCP Server      |     | .knowledge-db/
  | Gemini    ||   (stdio)         ||   entries.jsonl
  | Codex     |     |  knowlin_search   |     |   embeddings.npy
  | Cursor    |     |  knowlin_get      |     |   sessions/
  | VS Code   |     |  knowlin_capture  |     |   docs/
  +-----------+     |  knowlin_stats    |     +-----------+
                    |  knowlin_ingest   |
                    +-------------------+
                            |
  +-------------------------+-------------------------+
  |                         |                         |
  v                         v                         v
  Dense Search          Sparse Search           Cross-encoder
  (BGE-small 384d)      (SPLADE++ sparse)        Reranker
  |                         |                         |
  +------------+------------+                         |
               |                                      |
               v                                      |
         RRF Fusion -------> Intent Weighting ------->+
         (per source)        DEBUG -> sessions
                             HOWTO -> docs
                             RECALL -> sessions

安装

需要 Python 3.9+.

git clone https://github.com/calinfaja/KnowlinMCP.git && cd KnowlinMCP
./install.sh              # creates .venv, installs deps + MCP support
./install.sh --with-pdf   # also install PDF ingestion

或手动：

pip install -e ".[mcp]"

快速启动（30秒）

# Activate the venv (or add .venv/bin to your PATH)
source .venv/bin/activate

# 1. Initialize in your project
cd /your/project
knowlin init                    # creates .knowledge-db/ + .mcp.json

# 2. Index your docs
knowlin ingest all              # indexes docs/ and Claude sessions
                                # First run downloads ~200MB of ML models

# 3. Search
knowlin search "authentication"

输出示例：

1. [kb:warning] JWT tokens must be validated server-side (87%, 2026-01-10)
   Client-side JWT validation is bypassable; always verify on the server.
2. [docs:finding] OAuth2 PKCE flow for single-page apps (72%, 2026-02-15)
   Use PKCE instead of implicit grant for browser-based OAuth2 flows.

就是这样。Claude Code（和其他MCP客户端）现在可以使用 knowlin_search 自动通过 .mcp.json 由...创建 init.

运作原理

三个来源，一个搜索：

搜索管道： 每个查询都按意图分类（调试？如何？回忆？），然后使用密集嵌入+稀疏关键字+每个源的RRF融合进行搜索，使用意图感知权重在源之间进行融合，并使用交叉编码器重新排序。通过TCP服务器传输约30ms。

增量摄入： SHA-256文件哈希跟踪已处理的内容。只有新的或更改的文件才会重新索引。跑 knowlin ingest all 任何时候，它都很快。

命令行界面

# Search (default: compact format, all sources)
knowlin search "query"
knowlin search "query" -s kb -s docs       # specific sources
knowlin search "query" -f detailed         # verbose output
knowlin search "query" -f json             # machine-readable
knowlin search "query" --type warning      # filter by type
knowlin search "query" --since 2026-01-01  # date filter

# Capture knowledge
knowlin capture "JWT must be validated server-side" --type warning --tags "auth,jwt"

# Ingest
knowlin ingest all              # docs + sessions (incremental)
knowlin ingest docs             # docs only
knowlin ingest sessions         # sessions only
knowlin ingest all --full       # force re-process everything

# Browse & manage
knowlin list                    # recent entries across all sources
knowlin get                 # full details of an entry
knowlin delete              # remove an entry
knowlin export                  # export entries as JSONL (pipeable)

# Admin
knowlin init                    # set up project (.knowledge-db/ + .mcp.json)
knowlin stats                   # entry counts per source
knowlin doctor --fix            # health check and auto-repair
knowlin sources --init          # create sources.yaml template
knowlin server start            # TCP server for ~30ms queries (foreground)

条目类型： finding, solution, pattern, warning, decision, discovery

环境变量：

• CLAUDE_PROJECT_DIR --覆盖项目根检测（在CI或嵌套子目录中很有用）
• KNOWLIN_DEBUG --启用stderr的调试日志记录

源配置

无需配置，KnowlinMCP会自动发现 docs/, doc/, INFOS/ 目录和Claude会话来自 ~/.claude/projects/.

要进行显式控制，请编辑 .knowledge-db/sources.yaml （由创建 knowlin init):

docs:
  paths:
    - docs/                       # relative to project root
    - ~/Desktop/INFOS/            # absolute path (~ expanded)
  # include: ["*.md", "*.txt", "*.pdf", "*.rst"]
  # exclude: ["drafts/**", "*.tmp"]

sessions:
  auto_discover: true             # scan ~/.claude/projects/

MCP 服务器

knowlin init 写 .mcp.json 克劳德代码。对于其他客户：

Gemini CLI, Codex, Cursor, VS Code

双子星命令行工具 (~/.gemini/settings.json):

{ "mcpServers": { "knowlin-mcp": { "command": "knowlin-mcp" } } }

Codex 命令行界面 (~/.codex/config.toml):

[mcp_servers.knowlin-mcp]
command = "knowlin-mcp"

光标 (.cursor/mcp.json):

{ "mcpServers": { "knowlin-mcp": { "command": "knowlin-mcp" } } }

VS Code (.vscode/mcp.json):

{ "servers": { "knowlin-mcp": { "type": "stdio", "command": "knowlin-mcp" } } }

5个暴露的工具： knowlin_search, knowlin_get, knowlin_capture, knowlin_stats, knowlin_ingest.

Python API

from knowlin_mcp import KnowledgeDB, MultiSourceSearch

db = KnowledgeDB("/path/to/project")
results = db.search("query", limit=5)

ms = MultiSourceSearch("/path/to/project")
results = ms.search("how to configure auth", sources=["kb", "docs"])

存储

.knowledge-db/
  sources.yaml              # source config (optional)
  entries.jsonl              # curated KB (source of truth)
  embeddings.npy             # dense vectors (384-dim)
  sparse_index.json          # SPLADE++ sparse vectors
  sessions/                  # ingested session transcripts
    entries.jsonl, embeddings.npy, session-registry.json
  docs/                      # ingested documentation chunks
    entries.jsonl, embeddings.npy, doc-registry.json

发展

git clone https://github.com/calinfaja/KnowlinMCP.git && cd KnowlinMCP
./install.sh
.venv/bin/pytest tests/ -v           # unit tests
.venv/bin/ruff check src/ tests/     # lint
.venv/bin/black src/ tests/          # format

许可证

麻省理工学院