┌─────────────────────────────────────────────────────────────┐
│                     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  │
   └─────────────────────────────────────┘

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

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

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

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

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

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

python -m backend.mcp_server.server

curl -X POST "http://localhost:8000/api/upload" \
  -F "file=@/path/to/document.pdf"

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

curl "http://localhost:8000/api/tools"

curl "http://localhost:8000/api/conversations/{id}/trace"

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

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

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

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

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

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