MCP 服务器

kb-mcp

Provides LLM agents with a structured, queryable, local-first knowledge base with typed documents and full-text search via MCP.

README

kb-mcp

An agent-native knowledge base.

pip install kb-mcp — give any LLM agent a structured, queryable, local-first second brain.

</div>

The problem

Knowledge bases for humans (Notion, Obsidian) and for search engines (Elasticsearch, vector DBs) leave a gap: LLM agents need a knowledge layer that speaks their protocol and assumes the reader is a model, not a person.

kb-mcp fills it.

	Obsidian / Notion	Vector DBs (Chroma / LanceDB)	`kb-mcp`
Reader-optimised for	Humans	Embeddings	LLM agents
Protocol	Web UI	SDK	MCP (stdio)
Schema	Free-form	Free-form	Typed (project / decision / lesson / ...)
Default storage	Cloud / proprietary	Local files	SQLite + FTS5
Setup	Sign up	`pip install` + configure	`pip install` and go

Features

🧠 Agent-native. Every document is reachable from any MCP client (Claude Desktop, Cursor, OpenCode, Codex, …) via kb_search / kb_get / kb_add / kb_link.
📐 Schema-first. Six built-in document types (project, decision, lesson, glossary, person, faq) — extensible via Python subclassing.
🔍 Full-text search. SQLite FTS5 with BM25 ranking. Snippet-aware results returned to the agent.
🔗 Typed links. Documents reference other documents; backlinks are automatic.
📝 Markdown friendly. Round-trip import/export with frontmatter. Humans can edit, agents can read.
🪶 Zero deps by default. SQLite ships with Python. pip install kb-mcp and you're done.
🔒 Local-first. Your data lives in ~/.local/share/kb-mcp/. No cloud, no telemetry, no phone-home.

Quickstart

pip install kb-mcp
kb init
kb add --type project --title "kb-mcp" --tags kb,mcp,open-source --body "Agent-native knowledge base."
kb search "mcp server"

# Expose to any MCP client
kb serve

That's it. Five commands, zero config files.

👉 Full walkthrough: docs/quickstart.md

Document types

Type	Purpose	Example
`project`	Repo / initiative background	`kb-mcp`, `micro-app-fork`
`decision`	Architecture Decision Record (ADR)	"Use SQLite FTS5 over Elasticsearch"
`lesson`	Post-mortem / lessons learned	"Don't `last_insert_rowid()` across multi-INSERT batches"
`glossary`	Term definitions	`FTS5`, `MCP`, `ADR`
`person`	People the agent should recognise	"Zhang Bei, owner, uses Hermes"
`faq`	Frequently asked questions	"Why SQLite?"

Subclass kb_mcp.schema.Document to add your own.

MCP integration

Add to ~/.config/claude_desktop_config.json (or any MCP client):

{
  "mcpServers": {
    "kb": {
      "command": "kb",
      "args": ["serve"]
    }
  }
}

The agent then sees four tools:

kb_search(query, type?, tags?, limit?) — BM25-ranked results with snippets
kb_get(id) — full document by id (or slug)
kb_add(type, title, body, tags?, source?) — create document
kb_link(from_id, to_id, rel?) — typed edge between documents

Development

git clone https://github.com/your-org/kb-mcp
cd kb-mcp
pip install -e ".[dev]"
pytest          # unit + E2E (real SQLite temp file, no mocks)
ruff check .
mypy src/

👉 Spec: docs/requirements.md · Architecture: docs/architecture.md · CLI reference: docs/cli-reference.md

Roadmap

Version	Scope	Status
v0.1.0	CLI + MCP server + SQLite/FTS5 + 6 doc types + Markdown I/O	🚧 in progress
v0.2.0	Vector search (sqlite-vss) as opt-in, hybrid BM25 + embedding ranking	planned
v0.3.0	Multi-vault (per-project isolated KBs) + shared-vault mode	planned
v0.4.0	Web UI (read-only) + collaborative editing hints	exploring
v1.0.0	Postgres backend, multi-user auth, hosted mode	exploring