# DocAgent-MCP

面向本地文档的 **Agentic-RAG** 与 **MCP 工具化**问答系统

## 项目简介

基于 FastAPI、GLM-4-Flash、TF-IDF 构建的本地文档智能问答系统，支持多轮对话、意图识别、查询改写、工具路由和 MCP Server 封装。

## 核心功能

- 📄 **文档上传解析** - 支持 PDF 和 Word 文档
- 🔍 **中文检索** - jieba 分词 + TF-IDF 向量检索
- 🤖 **LLM 问答** - 智谱 GLM-4-Flash 生成答案
- 📚 **引用溯源** - 返回答案对应的文档来源
- 💬 **多轮对话** - 支持连续追问，上下文记忆
- 🎯 **意图识别** - 自动判断问题类型（新问题/追问/摘要/对比/计算/闲聊）
- ✏️ **查询改写** - 追问时自动将"它"等指代词改写为完整问题
- 🛠️ **工具路由** - 根据意图自动选择问答/摘要/计算工具
- 🔧 **Tool Registry** - 统一工具注册、调用和返回格式
- 🌐 **MCP Server** - 通过 Model Context Protocol 暴露本地文档能力

## 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                     HTML 前端 (index.html)                  │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTP
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                     FastAPI 后端 (端口 8000)                 │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │ Conversation │  │ Intent Router │  │   Tool Router    │   │
│  │  Manager    │  │ + Query       │  │   → Tool Registry│   │
│  └─────────────┘  │  Rewriter     │  └──────────────────┘   │
└───────────────────┴───────────────┴─────────────────────────┘
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   ┌────────────┐   ┌────────────┐   ┌────────────┐
   │Document QA │   │  Summary   │   │ Calculator │
   │   Tool     │   │   Tool     │   │    Tool    │
   └─────┬──────┘   └─────┬──────┘   └────────────┘
         │                │
         ▼                ▼
   ┌─────────────────────────────────────┐
   │        RAG Service                  │
   │  ┌──────────┐    ┌──────────────┐   │
   │  │ TF-IDF   │───▶│  Retriever   │   │
   │  │ VectorDB │    └──────────────┘   │
   │  └──────────┘           │           │
   │                         ▼           │
   │                  ┌──────────────┐   │
   │                  │  GLM-4-Flash │   │
   │                  └──────────────┘   │
   └─────────────────────────────────────┘
                           │
                           ▼
   ┌─────────────────────────────────────┐
   │     MCP Server (stdio 模式)          │
   │  list_documents / search_document   │
   │  ask_document / summarize_document  │
   └─────────────────────────────────────┘
```

## 快速开始

### 1. 克隆项目

```bash
git clone <your-repo-url>
cd docagent-mcp
```

### 2. 创建虚拟环境并安装依赖

```bash
conda create -n docagent python=3.10
conda activate docagent
pip install -r requirements.txt
```

### 3. 配置 API Key

```bash
# 方式1：环境变量
export ZHIPU_API_KEY="your-api-key"

# 方式2：直接修改 backend/config.py
ZHIPU_API_KEY = "your-api-key"
```

### 4. 启动 FastAPI 后端

```bash
python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000
```

### 5. 打开前端

直接双击打开 `frontend/index.html`，或启动 HTTP 服务器：

```bash
cd frontend
python -m http.server 8080
# 访问 http://localhost:8080
```

### 6. (可选) 启动 MCP Server

```bash
python -m backend.mcp_server.server
```

## API 接口

### 上传文档
```bash
curl -X POST "http://localhost:8000/api/upload" \
  -F "file=@/path/to/document.pdf"
```

### 问答
```bash
curl -X POST "http://localhost:8000/api/chat" \
  -H "Content-Type: application/json" \
  -d '{"question": "博士学位申请需要满足哪些条件？", "top_k": 4}'
```

### 列出工具
```bash
curl "http://localhost:8000/api/tools"
```

### 获取执行轨迹
```bash
curl "http://localhost:8000/api/conversations/{id}/trace"
```

## 意图识别示例

| 问题 | 识别意图 | 调用工具 |
|------|----------|----------|
| "博士学位申请需要满足哪些条件？" | NEW_QUESTION | document_qa |
| "它的学制是几年？" | FOLLOW_UP | document_qa (查询改写后) |
| "总结一下这篇文章" | SUMMARY | document_summary |
| "它和硕士有什么区别？" | COMPARE | document_qa |
| "1+1 等于多少？" | CALCULATION | calculator |
| "你好" | CHITCHAT | direct_answer |

## 项目结构

```
docagent-mcp/
├── backend/
│   ├── main.py                    # FastAPI 入口
│   ├── config.py                  # 配置
│   ├── agent/
│   │   ├── base_tool.py           # 工具基类
│   │   ├── tool_result.py         # 统一返回格式
│   │   ├── tool_registry.py       # 工具注册中心
│   │   ├── conversation_manager.py# 多轮对话管理
│   │   ├── intent_router.py       # 意图识别
│   │   ├── query_rewriter.py      # 查询改写
│   │   ├── tool_router.py         # 工具路由
│   │   └── tools/
│   │       ├── document_qa_tool.py
│   │       ├── document_summary_tool.py
│   │       └── calculator_tool.py
│   ├── rag/
│   │   ├── loader.py              # 文档加载
│   │   ├── splitter.py            # 文本分块
│   │   ├── vectorstore.py         # TF-IDF 向量库
│   │   ├── retriever.py           # 检索器
│   │   └── generator.py           # LLM 生成器
│   ├── api/
│   │   ├── chat.py                # 问答 API
│   │   ├── upload.py              # 上传 API
│   │   └── documents.py           # 文档 API
│   └── mcp_server/
│       ├── server.py              # MCP Server
│       ├── mcp_tools.py           # MCP 工具定义
│       ├── adapters.py            # 格式转换
│       └── README_MCP.md          # MCP 使用说明
├── frontend/
│   └── index.html                 # HTML 前端
├── data/
│   ├── uploads/                   # 上传文件 (不上传)
│   └── tfidf/                     # TF-IDF 持久化 (不上传)
├── requirements.txt
└── README.md
```

## 技术栈

- **后端框架**: FastAPI + Uvicorn
- **中文分词**: jieba
- **向量检索**: TF-IDF (numpy/sklearn)
- **LLM**: 智谱 GLM-4-Flash
- **协议**: Model Context Protocol (MCP)
- **前端**: HTML + JavaScript (无框架)

## 简历描述

```
DocAgent-MCP：面向本地文档的 Agentic-RAG 与 MCP 工具化问答系统

- 基于 FastAPI、GLM-4-Flash、jieba、TF-IDF 构建本地文档 RAG 系统，
  支持 PDF/Word 解析、中文检索、持久化存储、引用溯源和基于检索增强的问答生成。

- 设计多轮对话管理、意图识别和查询改写模块，支持新问题、追问、摘要、对比、
  计算和闲聊等 6 类意图，并根据上下文动态选择检索策略。

- 抽象 Tool Registry 工具注册中心，统一封装文档问答、文档摘要和计算器工具，
  设计 ToolResult 标准返回格式，实现工具调用轨迹可视化。

- 基于 MCP Server 将本地文档检索、问答和摘要能力暴露为标准工具接口，
  支持外部 Agent 通过统一协议调用本地知识库能力。
```

## License

MIT License