University Rules RAG MCP Agent

A Python project for learning RAG, Reranker, persistent indexing, DeepSeek API, and MCP from scratch. It uses the 中山大学 Undergraduate Academic Status Management Regulations as its knowledge base, retrieves relevant clauses, and generates answers with sources; the same retrieval capability can also be exposed as an MCP Tool for Agents to call.

This project is for technical learning. For real academic status matters, please refer to the university's latest official regulations and the academic affairs department's replies.

Features

• Split the local regulation text by "Article X".

• BGE Embedding semantic retrieval.

• Hybrid Search combining keyword + semantics.

• BGE Reranker reranks candidate clauses.

• Store document vectors and clause metadata locally to avoid duplicate Document Embedding generation.

• Use DeepSeek to generate source-cited answers based on the final clauses.

• Expose the search_university_rules(question) MCP Tool.

Related MCP server: byrdocs-search-mcp

Architecture

用户问题
  ↓
持久化向量索引
  ↓
Hybrid Search：Top 10 候选条款
  ↓
Reranker：Top 3 最相关条款
  ├─→ DeepSeek：生成带来源的自然语言回答
  └─→ MCP Tool：将条款 JSON 返回给 Agent

Project Structure

knowledge_base/                 # 学习用管理规定文本
rag_search.py                   # 基础关键词检索
semantic_search.py              # Embedding 语义检索
hybrid_search.py                # 混合检索
rerank_search.py                # Reranker 精排
index_store.py                  # 本地索引读写和有效性判断
final_rag_chat.py               # 完整 RAG + DeepSeek 问答
university_rules_mcp_server.py  # RAG MCP Server
test_*.py                       # 单元测试

Installation

Python 3.10 or later is recommended:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

On the first run of Embedding or Reranker, the models are downloaded to the local Hugging Face cache; subsequent runs reuse the cache directly.

Running

Basic search:

python rag_search.py

Full RAG Q&A version:

$env:DEEPSEEK_API_KEY="你的 DeepSeek API Key"
python final_rag_chat.py

The flow of final_rag_chat.py:

本地索引 → Hybrid Top 10 → Reranker Top 3 → DeepSeek 回答

Here, index/ is automatically generated on the first run and stores document vectors and metadata; this directory is Git-ignored because it can be rebuilt from the knowledge base.

MCP Server

Start the Server:

python university_rules_mcp_server.py

Verify with MCP Inspector:

npx @modelcontextprotocol/inspector python university_rules_mcp_server.py

Core search tool:

search_university_rules(question)

The tool does not call DeepSeek; instead, it returns 3 sources after RAG retrieval and Reranker reranking, for the MCP Client or Agent to continue using.

Testing

python -m unittest discover -p "test_*.py" -v

Data and Security

• The regulations in knowledge_base/ are kept as learning material for this project.

• Do not write API Keys into code, README, or .env and then commit; .env is Git-ignored.

• index/ is locally generated data and is Git-ignored.