Metadata-Version: 2.4
Name: lxd-knowledge-test-mcp
Version: 0.1.0
Summary: Personal knowledge base RAG MCP server — index local markdown/txt files, search via vector similarity
Author: liuxiaodong
License-Expression: MIT
Keywords: rag,mcp,knowledge-base,vector-search,claude-code
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.8.0
Requires-Dist: sentence-transformers>=3.0.0
Requires-Dist: lancedb>=0.17.0
Requires-Dist: markdown-it-py>=3.0.0
Requires-Dist: pyarrow>=17.0.0
Dynamic: license-file

# knowledge-mcp

把私有笔记变成可检索的向量库，每次和 AI 助手对话时自动补全上下文。

## 快速开始

```bash
# 1. 安装
pip install knowledge-mcp

# 2. 创建知识库目录
mkdir my-knowledge-base && cd my-knowledge-base
mkdir data  # 放入你的 .md / .txt 文件

# 3. 配置 MCP 客户端（见下方"注册到 AI 助手"）

# 4. 索引文件（在 AI 助手中）
# knowledge_index data/

# 5. 提问即可自动检索
```

## 注册到 AI 助手

在项目根目录创建 `.mcp.json`：

```json
{
  "mcpServers": {
    "knowledge-base": {
      "command": "python",
      "args": ["-m", "knowledge_mcp"],
      "cwd": "."
    }
  }
}
```

**支持的 AI 客户端**：Claude Code、Cursor、以及所有支持 MCP 协议的工具。

Claude Code 用户可在 `settings.json` 中设置 `"enabledMcpjsonServers": ["knowledge-base"]` 跳过每次的确认弹窗。

## 工作原理

```
用户提问 → AI 客户端判定需检索 → 调用 knowledge_search
         → 查询向量化（BGE-small-zh-v1.5）
         → LanceDB 向量相似度搜索
         → 返回 top-5 相关文本片段
         → AI 客户端组装 prompt + 检索结果 → 生成回答
```

## 提供的 MCP 工具

| 工具 | 功能 |
|------|------|
| `knowledge_search` | 搜索知识库，返回相关文本片段及元数据 |
| `knowledge_index` | 索引文件或目录（支持 .md / .txt，SHA256 增量检测） |
| `knowledge_list` | 列出已索引的文档及统计 |
| `knowledge_remove` | 按源文件移除索引 |
| `knowledge_stats` | 全局索引统计 |

## 配置

通过环境变量覆盖默认值：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `KNOWLEDGE_MCP_DATA_DIR` | `data` | 知识库文件目录 |
| `KNOWLEDGE_MCP_DB_PATH` | `db` | 向量库存储目录 |

## 技术选型

| 环节 | 选型 | 理由 |
|------|------|------|
| Embedding | BGE-small-zh-v1.5 | 本地运行，512维，中英文良好 |
| 向量库 | LanceDB | 嵌入式零部署，支持元数据过滤、增量 CRUD |
| MD 解析 | markdown-it-py | token stream 正确处理嵌套标题和代码块 |
| 分块 | 标题感知 + 代码块原子化 | 按 h2/h3 切分，代码块绝不切割 |
| 集成框架 | FastMCP | MCP 官方 Python SDK，stdio 传输 |

## 开发

```bash
git clone <repo-url>
cd personal-knowledge-base
pip install -e .
# 将 .mcp.dev.json 的内容覆盖到 .mcp.json（或直接用全局 ~/.mcp.json 配绝对路径）
```
