内容
<p align="center">
<img src="https://img.shields.io/badge/Go-1.22+-00ADD8?style=for-the-badge&logo=go&logoColor=white" alt="Go 版本"/>
<img src="https://img.shields.io/badge/MCP-Protocol-8B5CF6?style=for-the-badge&logo=anthropic&logoColor=white" alt="MCP 协议"/>
<img src="https://img.shields.io/badge/Google_AI-Embeddings-4285F4?style=for-the-badge&logo=google&logoColor=white" alt="Google AI"/>
<img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="许可证"/>
</p>
<h1 align="center">📚 本地知识库 MCP</h1>
<p align="center">
<strong>本地 RAG 服务器，支持自定义 PDF 文档</strong>
</p>
<p align="center">
将任意 PDF 文档集合转化为可通过 AI 查询的知识库，无需 Docker，无需外部服务器，仅需一个 Go 语言编译后的二进制文件。
</p>
---
## 🎯 这是什么？
一个 [MCP（Model Context Protocol）](https://modelcontextprotocol.io/) 服务器，允许 AI 助手（Claude、Gemini 等）通过语义搜索查询**您自己的文档集合**。
### 使用场景
- 📖 **学生**：索引您的书籍和讲义，以自然语言提问
- 👨💻 **开发者**：创建自定义的技术知识库
- 📋 **专业人士**：查询手册、内部文档和技术规范
- 🔬 **研究人员**：搜索学术论文和文献
---
## ✨ 特性
| 特性 | 描述 |
| --- | --- |
| **零依赖** | 无 Docker，无外部服务器，无 Python |
| **嵌入式向量数据库** | chromem-go 持久化存储在本地磁盘 |
| **Google AI 嵌入** | `text-embedding-004` 模型（768 维） |
| **MCP 协议** | 兼容 Claude Desktop、Antigravity 等 |
| **100% 本地** | 您的 PDF 文档永远不会离开您的计算机\* |
> \* 仅将分段文本发送到 Google API 以生成嵌入。
---
## 🏛️ 架构
```
┌─────────────────────┐ JSON-RPC (stdio) ┌──────────────────────────────────────────┐
│ │◄──────────────────────────►│ │
│ Claude Desktop │ │ 本地知识库 MCP │
│ Antigravity │ │ ┌──────────────┐ ┌────────────────┐ │
│ 其他 MCP 客户端 │ │ │ chromem-go │ │ Google AI │ │
│ │ │ │ (向量数据库) │ │ (嵌入) │ │
└─────────────────────┘ │ └──────────────┘ └────────────────┘ │
└──────────────────────────────────────────┘
```
---
## 🛠️ 可用工具
服务器暴露两个工具给 MCP 客户端：
### `consultar_base_conhecimento`
知识库的语义搜索。
| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| `pergunta` | 字符串 | ✅ | 您的自然语言问题 |
**返回：** 5 个最相关的片段，包含相似度得分、来源和内容。
### `verificar_status_vectordb`
检查向量数据库的状态。
**返回：** 数据库状态、索引文档计数和内存使用情况。
---
## 🚀 安装
### erequisites
- **Go 1.22+**
- **Google AI API 密钥** — [免费获取](https://aistudio.google.com/app/apikey)
### 1. 编译
```bash
git clone https://github.com/Capman002/Local-Knowledge-Base-MCP---golang.git
cd Local-Knowledge-Base-MCP---golang
go build -o senior-architect-rag.exe .
go build -o ingest.exe ./cmd/ingest
```
### 2. 配置
创建 `.env` 文件：
```env
# 必填
GOOGLE_API_KEY=您的 API 密钥
# 可选 - 根据您的使用场景自定义
COLLECTION_NAME=我的知识库
DB_PATH=vector_db
DOCS_DIR=我的文档
EMBEDDING_MODEL=text-embedding-004
```
### 3. 添加 PDF 文档
创建 `DOCS_DIR` 配置的目录（默认为 `biblioteca_docs/`），并添加您的 PDF 文档：
```
biblioteca_docs/
├── 书籍1.pdf
├── 技术手册.pdf
├── 讲义.pdf
└── ...
```
### 4. 索引
```bash
./ingest.exe
```
### 5. 配置 MCP 客户端
在 Claude Desktop 或 Antigravity 中添加：
```json
{
"mcpServers": {
"我的知识库": {
"command": "C:/路径/到/senior-architect-rag.exe",
"args": [],
"env": {}
}
}
}
```
---
## ⚙️ 自定义
### 环境变量
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `GOOGLE_API_KEY` | _(必填)_ | Google AI API 密钥 |
| `COLLECTION_NAME` | `biblioteca_arquitetura` | 知识库名称 |
| `DB_PATH` | `vector_db` | 向量数据库存储路径 |
| `DOCS_DIR` | `biblioteca_docs` | PDF 文档目录 |
| `EMBEDDING_MODEL` | `text-embedding-004` | 嵌入模型 |
### 配置示例
**法律知识库：**
```env
COLLECTION_NAME=legislacao_brasileira
DOCS_DIR=pdfs_juridicos
```
**技术文档：**
```env
COLLECTION_NAME=docs_empresa
DOCS_DIR=manuais
```
**学术研究：**
```env
COLLECTION_NAME=papers_mestrado
DOCS_DIR=literatura
```
---
## 📝 默认配置说明
代码中的默认名称（`Senior-Architect-RAG`、`biblioteca_arquitetura`）反映了原始使用场景：一个 **软件架构文献** 的知识库（DDD、System Design、Microservices 等）。
您可以直接使用这些默认值，也可以自定义 `.env` 文件以适应任何领域。
---
## 技术细节
| 组件 | 值 |
| --- | --- |
| 分段大小 | 800 字符 |
| 分段重叠 | 150 字符 |
| 查询结果 | 前 5 个 |
| 嵌入维度 | 768 |
| 通信方式 | MCP via stdio |
---
## 📁 项目结构
```
├── main.go # MCP 服务器
├── cmd/ingest/main.go # PDF 索引器
├── biblioteca_docs/ # PDF 文档（git-ignored）
├── vector_db/ # 向量数据库（git-ignored）
├── .env # 配置文件（git-ignored）
└── .env.example # 配置文件模板
```
---
## 🐛 问题解决
| 问题 | 解决方案 |
| --- | --- |
| "GOOGLE_API_KEY 未定义" | 创建 `.env` 文件并添加您的 API 密钥 |
| "未找到 PDF 文档" | 检查 `DOCS_DIR` 目录 |
| "文档计数为零" | 执行 `ingest.exe` |
| "PDF 文本提取错误" | PDF 可能是扫描图像（使用 OCR） |
---
## 🤝 贡献
欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
---
## 📄 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
---
## 🔗 依赖
- [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go) — MCP 库
- [philippgille/chromem-go](https://github.com/philippgille/chromem-go) — 嵌入式向量数据库
- [ledongthuc/pdf](https://github.com/ledongthuc/pdf) — PDF 解析器
- [joho/godotenv](https://github.com/joho/godotenv) — `.env` 文件加载
