kb-mcp-lite 0.2.1__tar.gz

kb_mcp_lite-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kb-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kb_mcp_lite-0.2.1/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: kb-mcp-lite
+Version: 0.2.1
+Summary: Lightweight agent-native knowledge base. SQLite + FTS5 + vec0 + MCP server.
+Author: HelloTomBruce (Zhang Bei)
+License: MIT
+Project-URL: Homepage, https://github.com/HelloTomBruce/kb-mcp-lite
+Project-URL: Source, https://github.com/HelloTomBruce/kb-mcp-lite
+Project-URL: Issues, https://github.com/HelloTomBruce/kb-mcp-lite/issues
+Project-URL: Changelog, https://github.com/HelloTomBruce/kb-mcp-lite/releases
+Keywords: knowledge-base,mcp,agent,sqlite,fts5,vector-search,semantic-search,lightweight
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: pydantic>=2.5
+Requires-Dist: mcp>=1.0
+Requires-Dist: python-frontmatter>=1.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: vec
+Requires-Dist: sqlite-vec>=0.1.0; extra == "vec"
+Requires-Dist: pysqlite3>=0.5; extra == "vec"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# kb-mcp
+
+**An agent-native knowledge base.**
+
+`pip install kb-mcp` — give any LLM agent a structured, queryable, local-first second brain.
+
+[![PyPI version](https://img.shields.io/badge/pypi-v0.2.0-blue)](https://pypi.org/project/kb-mcp/)
+[![Python](https://img.shields.io/badge/python-≥3.10-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io/)
+[![Status: alpha](https://img.shields.io/badge/status-alpha-orange)](#status)
+
+</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
+
+```bash
+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](./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):
+
+```json
+{
+  "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
+
+```bash
+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](./docs/requirements.md) ·
+Architecture: [docs/architecture.md](./docs/architecture.md) ·
+CLI reference: [docs/cli-reference.md](./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 |
+
+See [docs/requirements.md](./docs/requirements.md) § 4 for v0.1 scope decisions
+and out-of-scope list.
+
+---
+
+## Status
+
+**alpha.** API and storage format may change before v0.2.0. Pin minor versions
+(`kb-mcp>=0.1,<0.2`) in production.
+
+---
+
+## Contributing
+
+Issues and PRs welcome. See
+[CONTRIBUTING.md](./CONTRIBUTING.md) (TODO before v0.1.0 release).
+
+By participating, you agree to abide by the
+[Code of Conduct](./CODE_OF_CONDUCT.md) (TODO before v0.1.0 release).
+
+---
+
+## License
+
+[MIT](./LICENSE) — do what you want, just keep the copyright notice.

kb_mcp_lite-0.2.1/README.md

@@ -0,0 +1,166 @@
+<div align="center">
+
+# kb-mcp
+
+**An agent-native knowledge base.**
+
+`pip install kb-mcp` — give any LLM agent a structured, queryable, local-first second brain.
+
+[![PyPI version](https://img.shields.io/badge/pypi-v0.2.0-blue)](https://pypi.org/project/kb-mcp/)
+[![Python](https://img.shields.io/badge/python-≥3.10-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io/)
+[![Status: alpha](https://img.shields.io/badge/status-alpha-orange)](#status)
+
+</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
+
+```bash
+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](./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):
+
+```json
+{
+  "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
+
+```bash
+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](./docs/requirements.md) ·
+Architecture: [docs/architecture.md](./docs/architecture.md) ·
+CLI reference: [docs/cli-reference.md](./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 |
+
+See [docs/requirements.md](./docs/requirements.md) § 4 for v0.1 scope decisions
+and out-of-scope list.
+
+---
+
+## Status
+
+**alpha.** API and storage format may change before v0.2.0. Pin minor versions
+(`kb-mcp>=0.1,<0.2`) in production.
+
+---
+
+## Contributing
+
+Issues and PRs welcome. See
+[CONTRIBUTING.md](./CONTRIBUTING.md) (TODO before v0.1.0 release).
+
+By participating, you agree to abide by the
+[Code of Conduct](./CODE_OF_CONDUCT.md) (TODO before v0.1.0 release).
+
+---
+
+## License
+
+[MIT](./LICENSE) — do what you want, just keep the copyright notice.

kb_mcp_lite-0.2.1/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kb-mcp-lite"
+version = "0.2.1"
+description = "Lightweight agent-native knowledge base. SQLite + FTS5 + vec0 + MCP server."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "HelloTomBruce (Zhang Bei)" }]
+keywords = [
+  "knowledge-base",
+  "mcp",
+  "agent",
+  "sqlite",
+  "fts5",
+  "vector-search",
+  "semantic-search",
+  "lightweight",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "click>=8.1",
+  "pydantic>=2.5",
+  "mcp>=1.0",
+  "python-frontmatter>=1.0",
+  "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+# vec: install for semantic search (vec0 + pysqlite3). pysqlite3
+# ships precompiled wheels for Linux x86_64/arm64 and macOS x86_64
+# /arm64; it provides a SQLite build with extension support (which
+# the stdlib ``sqlite3`` lacks on Python 3.12+). Without this extra
+# the package still works — semantic search is silently disabled.
+vec = [
+  "sqlite-vec>=0.1.0",
+  "pysqlite3>=0.5",
+]
+dev = [
+  "pytest>=8",
+  "pytest-cov",
+  "ruff",
+  "mypy",
+]
+
+[project.scripts]
+kb = "kb_mcp_lite.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/HelloTomBruce/kb-mcp-lite"
+Source = "https://github.com/HelloTomBruce/kb-mcp-lite"
+Issues = "https://github.com/HelloTomBruce/kb-mcp-lite/issues"
+Changelog = "https://github.com/HelloTomBruce/kb-mcp-lite/releases"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.mypy]
+python_version = "3.10"
+strict_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+
+[tool.setuptools.package-data]
+"kb_mcp_lite" = ["migrations/*.sql"]  # SQLite DDL files loaded at runtime

kb_mcp_lite-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kb_mcp_lite-0.2.1/src/kb_mcp_lite/__init__.py

@@ -0,0 +1,60 @@
+"""kb-mcp-lite: lightweight agent-native knowledge base.
+
+A local-first, schema-first, MCP-native knowledge base for LLM agents.
+See https://github.com/HelloTomBruce/kb-mcp-lite for the full spec.
+"""
+
+from kb_mcp_lite.schema import (
+    Decision,
+    Document,
+    DocumentType,
+    DoctorCheck,
+    DoctorReport,
+    DuplicateError,
+    Faq,
+    Glossary,
+    ImportReport,
+    IntegrityError,
+    KbMcpError,
+    Lesson,
+    Link,
+    NotFoundError,
+    Person,
+    Project,
+    SearchHit,
+    TypeRegistry,
+    ValidationError,
+    default_registry,
+    make_id,
+    slugify,
+)
+
+__version__ = "0.2.1"
+
+__all__ = [
+    "__version__",
+    # schema
+    "Document",
+    "DocumentType",
+    "Project",
+    "Decision",
+    "Lesson",
+    "Glossary",
+    "Person",
+    "Faq",
+    "Link",
+    "SearchHit",
+    "ImportReport",
+    "DoctorCheck",
+    "DoctorReport",
+    "TypeRegistry",
+    "default_registry",
+    "make_id",
+    "slugify",
+    # exceptions
+    "KbMcpError",
+    "NotFoundError",
+    "DuplicateError",
+    "ValidationError",
+    "IntegrityError",
+]