# TiDB RAG MCP Server

一个用于读取 TiDB 数据库中 RAG 知识库的 MCP (Model Context Protocol) 服务器。

## 功能特性

- 📚 **知识库浏览** - 列出和查看知识条目
- 🔍 **关键词搜索** - 在知识库中搜索内容
- 🎯 **向量搜索** - 支持 TiDB 向量相似度搜索（开发中）
- 🔄 **双模式支持** - Mock 数据模式和 TiDB 数据库模式

## 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
# Mock 模式 (无需数据库)
USE_MOCK=true

# TiDB 数据库配置 (USE_MOCK=false 时需要)
TIDB_HOST=localhost
TIDB_PORT=4000
TIDB_USER=root
TIDB_PASSWORD=your_password
TIDB_DATABASE=knowledge_db
```

### 3. 构建和运行

```bash
# 构建
npm run build

# 运行
npm start
```

## MCP 工具

### tidb_list_knowledge

列出知识库条目，支持分页和分类过滤。

**参数:**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| limit | number | 否 | 20 | 返回数量 (1-100) |
| offset | number | 否 | 0 | 跳过数量 |
| category | string | 否 | - | 按分类过滤 |
| response_format | string | 否 | markdown | 输出格式: markdown/json |

**示例:**

```json
{ "limit": 10, "category": "技术文档" }
```

### tidb_get_knowledge

获取单条知识详情。

**参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | string | 是 | 知识条目 ID |
| response_format | string | 否 | 输出格式: markdown/json |

**示例:**

```json
{ "id": "kb-001" }
```

### tidb_search_knowledge

在知识库中搜索。

**参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| query | string | 是 | 搜索关键词 |
| limit | number | 否 | 返回数量 |
| offset | number | 否 | 跳过数量 |
| category | string | 否 | 按分类过滤 |
| response_format | string | 否 | 输出格式 |

**示例:**

```json
{ "query": "MCP 协议" }
```

### tidb_vector_search

向量相似度搜索（开发中）。

**参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| embedding | number[] | 是 | 查询向量 |
| top_k | number | 否 | 返回数量 |
| threshold | number | 否 | 相似度阈值 |

## Claude Desktop 配置

在 Claude Desktop 配置文件中添加：

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "tidb-rag": {
      "command": "node",
      "args": ["E:\\code\\mcp_test\\readKnowledgeMcp\\dist\\index.js"],
      "env": {
        "USE_MOCK": "true"
      }
    }
  }
}
```

### 使用 TiDB 数据库

```json
{
  "mcpServers": {
    "tidb-rag": {
      "command": "node",
      "args": ["E:\\code\\mcp_test\\readKnowledgeMcp\\dist\\index.js"],
      "env": {
        "USE_MOCK": "false",
        "TIDB_HOST": "your-tidb-host",
        "TIDB_PORT": "4000",
        "TIDB_USER": "root",
        "TIDB_PASSWORD": "your-password",
        "TIDB_DATABASE": "knowledge_db"
      }
    }
  }
}
```

## 数据库表结构

当使用 TiDB 数据库时，需要以下表结构：

```sql
CREATE TABLE knowledge_base (
  id VARCHAR(36) PRIMARY KEY,
  title VARCHAR(255) NOT NULL,
  content TEXT NOT NULL,
  category VARCHAR(100),
  embedding VECTOR(1536),  -- 向量嵌入 (可选)
  metadata JSON,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- 向量索引 (可选，用于向量搜索)
CREATE VECTOR INDEX idx_embedding ON knowledge_base(embedding);
```

## Mock 数据

Mock 模式包含以下示例知识：

1. MCP 协议简介
2. TiDB 向量搜索指南
3. RAG 最佳实践
4. TypeScript 类型系统进阶
5. 知识库系统架构设计

## 开发

```bash
# 开发模式 (热重载)
npm run dev

# 构建
npm run build

# 清理构建
npm run clean
```

## 使用 MCP Inspector 测试

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## 项目结构

```
tidb-rag-mcp-server/
├── src/
│   ├── index.ts           # MCP Server 入口
│   ├── types.ts           # 类型定义
│   ├── constants.ts       # 常量配置
│   ├── schemas/           # Zod 验证 schemas
│   │   └── index.ts
│   ├── services/          # 数据库和 Mock 服务
│   │   ├── database.ts
│   │   └── mock-data.ts
│   ├── tools/             # MCP 工具实现
│   │   ├── index.ts
│   │   ├── knowledge.ts
│   │   └── search.ts
│   └── utils/             # 工具函数
│       └── format.ts
├── dist/                  # 编译输出
├── package.json
├── tsconfig.json
└── .env.example
```

## 文档

- [TiDB 知识库接入指南](./docs/TIDB_INTEGRATION_GUIDE.md) - 从 Mock 模式切换到真实 TiDB 数据库的完整指南

## License

MIT