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)