# Academic Paper Explorer MCP Server (BUPT SE Practice - Lab 2)

本项目是北京邮电大学软件工程实践课程实验 2（Bring Your Own Agent）的产物。项目基于 **Vibe Coding** 理念，采用 **TypeScript + Node.js** 技术栈，构建一个基于 MCP (Model Context Protocol) 协议的严谨学术论文分析 Agent。

## 🎯 核心功能体系
不同于普通的聊天 AI，本项目要求 Agent **绝对严谨**，禁止任何形式的幻觉与凭空捏造。Agent 必须完全基于用户指定的本地 PDF 论文集，提供以下四大核心交付物：

1. 🗺️ **领域地图 (Domain Map - 可编辑)**：梳理该论文集所涉及的宏观学术领域、主要流派及技术演进路线（以 Mermaid 文本格式输出，用户可自由二次编辑）。
2. 🧠 **思维导图 (Mindmap - 可编辑)**：针对单篇或多篇论文的核心架构、实验方法、技术路线进行微观拆解（以 Mermaid Mindmap 文本格式输出，用户可自由二次编辑）。
3. 🔍 **目前研究空缺 (Research Gaps)**：严谨对比文献，找出当前研究中尚未解决、被忽略或存在局限性的“Gap”。
4. 🚀 **可入手研究方向 (Future Directions)**：基于研究空缺，为用户提供具有落地可行性的具体研究切入点。

## 🔒 严谨性红线 (Zero-Hallucination Policy)
* **绝对不允许胡编乱造**：任何产出（无论是观点还是图表节点）必须在输入的 PDF 论文中找到明确的文本支撑。
* **溯源要求**：在分析“研究空缺”和“研究方向”时，Agent 必须显式注明引用的论文文件名或章节。如果文件夹内的资料不足以推导出某一结论，Agent 必须直接回答“根据现有文献无法推导”，严禁主观猜测。

## 🛠️ 技术栈
* **语言与环境**：Node.js + TypeScript (`tsx` 执行环境)
* **核心协议**：Model Context Protocol (MCP) SDK
* **PDF 解析依赖**：`pdf-parse` (用于严谨提取 PDF 纯文本)
* **工具交互接口**：Claude Code CLI / VS Code Terminal

---

## 📅 项目开发进展阶段 (Project Phases)

本项目遵循敏捷开发与 Vibe Coding 流程，共分为以下三个推进阶段：

### 阶段 1：基础架构与 PDF 解析核心 (Phase 1: Foundation & PDF Parsing)
* **目标**：搭建 MCP 服务端骨架，实现本地任意指定目录的 PDF 文本严谨提取。
* **核心任务**：
  * 初始化 TypeScript 与 MCP SDK 基础环境。
  * 实现 `set_paper_directory` 工具，验证本地路径有效性。
  * 集成 `pdf-parse`，编写 PDF 文本提取逻辑，确保双栏学术排版文字提取不丢失。
* **阶段交付物**：可通过 MCP 基础协议控制台或 Claude 成功读取并打印本地 PDF 文本。

### 阶段 2：学术分析引擎与可编辑图表生成 (Phase 2: Academic Analysis & Chart Export)
* **目标**：赋予 Agent 严谨的学术分析能力，并能将结构化数据转化为可编辑的 Mermaid 图表。
* **核心任务**：
  * 设计严谨的 Prompt 模版，约束 Claude 在分析领域地图、思维导图、Research Gaps 时必须带有关联依据。
  * 实现 `export_editable_chart` 工具，将生成的 Mermaid 源码持久化写入本地 `.md` 文件。
* **阶段交付物**：本地生成包含规范 Mermaid 代码的 Markdown 文件，可在 VS Code 中完美预览并自由修改节点。

### 阶段 3：系统联调、红线测试与实验交付 (Phase 3: Integration, Safety Testing & Delivery)
* **目标**：进行完整的 Agent 闭环测试，确保零幻觉，并完成代码托管与实验报告撰写。
* **核心任务**：
  * 在 Claude Code 中完整挂载此 MCP 服务，输入测试论文集进行端到端联调。
  * **红线压力测试**：输入无关或模糊概念，测试 Agent 是否会触发“无法推导”的熔断机制，确保严谨性。
  * 录制运行日志，截取 3-4 张核心推理链截图。
  * 整理代码并实时 push 至 GitHub 仓库；撰写实验报告与技术反思。

---

## 🔧 Agent 核心工具接口定义 (Tools API)

### 1. `set_paper_directory`
* **功能**：允许用户动态指定或切换本地包含 PDF 论文的文件夹路径。
* **参数**：`directoryPath` (string)

### 2. `parse_and_analyze_papers`
* **功能**：扫描并读取当前目录下所有 PDF 的文本，执行零幻觉学术剖析。
* **参数**：`analysisType` ("domain_map" | "mindmap" | "gaps" | "directions")

### 3. `export_editable_chart`
* **功能**：将生成的领域地图或思维导图，以标准 Mermaid 语法的 `.md` 文件持久化保存到本地。
* **参数**：`fileName` (string), `mermaidCode` (string)


---

## 🛠️ 本地部署与使用指南 (Getting Started)

未来用户如果需要运行本 MCP 服务器，请遵循以下步骤：

### 1. 环境准备
确保本地已安装 [Node.js (v18+)](https://nodejs.org/)。

### 2. 克隆项目并安装依赖
```bash
git clone [https://github.com/你的GitHub用户名/paper-analyzer-mcp.git](https://github.com/你的GitHub用户名/paper-analyzer-mcp.git)
cd paper-analyzer-mcp
npm install
```
### 3. 创建数据目录与放置论文
本服务器在运行时需要读取本地的论文文件。请在项目根目录下手动创建一个名为 `test-papers` 的文件夹，并将你需要分析的 PDF 论文放入其中：
```bash
mkdir test-papers
# 随后请将你的论文 PDF 文件拖入该 test-papers 文件夹中