TiDB RAG MCP Server

TiDB RAG MCP Server

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

功能特性

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

快速开始

1. 安装依赖

npm install

2. 配置环境变量

cp .env.example .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. 构建和运行

# 构建
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 |

示例:

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

tidb_get_knowledge

获取单条知识详情。

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

示例:

{ "id": "kb-001" }

tidb_search_knowledge

在知识库中搜索。

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

示例:

{ "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

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

使用 TiDB 数据库

{
  "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 数据库时，需要以下表结构：

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. 知识库系统架构设计

开发

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

# 构建
npm run build

# 清理构建
npm run clean

使用 MCP Inspector 测试

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 知识库接入指南 - 从 Mock 模式切换到真实 TiDB 数据库的完整指南

License

MIT