基于MCP的PDF文档管理系统
一个复杂的文档管理平台 Next.js, 模型上下文协议(MCP),以及 AI驱动的功能 用于PDF文档浏览、摘要和格式转换。
🎯 特性
- 📚 文档列表视图 -浏览具有丰富元数据(标题、作者、标签、页数)的PDF文档
- 👁️ 快速预览 -点击查看模态中的文档摘要
- 📖 完整文档查看器 -使用缩放和导航控件查看完整的PDF
- 🤖 AI驱动的摘要 -使用Claude AI生成简短、详细或全面的摘要
- 📝 适应性启发式 -大型文档(>50页)的智能偏好收集
- 🔄 格式转换 -将PDF转换为EPUB或Markdown格式
- 💾 本地存储 -仅本地存储元数据;按需获取完整PDF
- 🎨 现代用户界面 -使用Tailwind CSS和shadcn/ui构建的漂亮界面
🏗️ 建筑
该系统实现了 模型上下文协议(MCP) 架构:```
┌─────────────────────────────────────┐
│ Next.js UI (MCP Host) │
│ • Document list & viewer │
│ • User interactions │
└─────────────┬───────────────────────┘
│ instantiates
↓
┌─────────────────────────────────────┐
│ MCP Client (FastMCP) │
│ • Roots: Reformatted docs dir │
│ • Sampling: LLM API access │
│ • Elicitation: User prompts │
└─────────────┬───────────────────────┘
│ MCP Protocol
↓
┌─────────────────────────────────────┐
│ MCP Server (Python/FastMCP) │
│ • Document tools │
│ • Summary generation │
│ • Format conversion │
└─────────────┬───────────────────────┘
│ API calls
↓
┌─────────────────────────────────────┐
│ PDF Document Provider Service │
│ • Full PDF storage │
│ • Document metadata API │
└─────────────────────────────────────┘
### 关键组件
1. **Next.js用户界面(MCP主机)**
- 前端应用程序
- 实例化MCP客户端
- 管理用户交互
1. **MCP客户端**
- **根:** 显示重新格式化的文档目录
- **取样:** 为摘要提供LLM访问权限
- **引语:** 处理自适应用户提示
1. **MCP服务器**
- 连接到PDF提供商服务
- 公开文档操作工具
- 协调人工智能操作
1. **PDF提供商服务**
- 外部服务(不包括在内)
- 存储完整的PDF文档
- 提供元数据和检索API
## 🚀 快速开始
### 先决条件
- Node.js 18+
- Python 3.10+
- pnpm(推荐)或npm
- 无烟煤API键
### 安装
1. **克隆存储库**```bash
git clone
cd afrotech-cac-dv
- 安装依赖项```bash
Frontend
pnpm install
MCP Server
cd server
pip install -r requirements.txt
cd ..
1. **配置环境变量**```bash
cp .env.example .env.local
编辑 .env.local:```env
ANTHROPIC_API_KEY=sk-ant-...
PDF_PROVIDER_API_URL=https://provider.example.com
PDF_PROVIDER_API_KEY=provider_key_...
MCP_SERVER_URL=http://localhost:3001
REFORMATTED_DOCS_PATH=/path/to/reformatted-docs
1. **启动开发服务器**
终端1-Next.js用户界面:```bash
pnpm dev
终端2-MCP服务器:```bash
cd server
python main.py
1. **打开应用程序**```
http://localhost:3000
📖 用法
浏览文档
- 导航到主页以查看所有可用文档
- 每张卡片显示标题、作者、标签和页数
- 单击任何文档打开预览模式
查看预览
- 预览模式显示文档摘要
- 点击“查看更多”以加载完整文档
生成摘要
对于小文档(\<50页):
- 点击“创建摘要”
- 自动生成摘要(简短,约500字)
- 即时显示摘要
对于大型文档(>50页):
- 点击“创建摘要”
- 出现包含以下选项的激励对话框:
- 摘要类型: 简要/详细/全面
- 最大字数: 300-5000(滑块)
- 包括引用: 是/否 - 选择操作:
- 接受: 使用您的偏好
- 使用默认值: 跳过自定义
- 取消: 放弃操作 - 根据偏好生成的摘要
- 摘要与元数据一起显示
转换格式
- 查看完整文档
- 点击“转换为EPUB”或“转换为Markdown”
- 转换过程开始
- 已转换的文件已保存到
reformatted-docs/目录 - 提供下载链接
🧪 测试
运行测试```bash
All tests (unit + integration + E2E)
pnpm test
Watch mode for development
pnpm test:watch
Coverage report
pnpm test:coverage
Interactive UI mode
pnpm test:ui
### 检验统计量```
✓ Test Files: 11 passed
✓ Tests: 250 passed | 3 skipped
✓ Coverage: ~75%
✓ Duration: ~8 seconds
测试套件
- 单元测试(41): MCP客户端模块(采样、启发)
- 组件测试(185): 所有带有React测试库的UI组件
- 集成测试(14): 所有6条API路线和MCP通信
- E2E测试(10): 完成用户工作流程和旅程
模拟模式
该应用程序包括一个全面的模拟开发模式,无需MCP服务器:```typescript
// Enabled by default in development
const client = createMCPClient(); // useMock: true
看 docs/TEST.md 获取详细的测试文档。
## 📚 文档
### 核心文件
- **建筑.md** -完整的系统架构和设计
- **API_REFERENCE.md** -API端点和MCP工具参考
- **用户指南.md** -最终用户说明和工作流程
### 开发指南
- **Developpent.md** -开发人员设置和贡献指南
- **测试.md** -测试策略和指南
- **部署.md** -生产部署指南
### MCP文件
- **MCP_CLIENT.md** -MCP客户端实现细节
- **MCP_SERVER.md** -MCP服务器工具和配置
- **MCP_QUICK_REFERENCE.md** -快速MCP参考
### 项目规划
- **实施_计划.md** -发展路线图
- **IMPLEMENTATION_STATUS.md** -当前进展(96%)
- **可选\_ ASKS.md** -剩余4%的逐步计划
## 🛠️ 技术栈
### 前端
- **框架:** Next.js 15+(应用路由器)
- **语言:** TypeScript 5+
- **造型:** 顺风CSS v4
- **组件:** shadcn/ui(Radix ui)
- **图标:** Lucide反应
- **PDF渲染:** 反应pdf
### 后端
- **MCP服务器:** Python快速MCP
- **MCP客户端:** TypeScript MCP SDK
- **LLM** 人类学家克劳德·neneneba API(Opus,Sonnet,Haiku)
- **HTTP客户端:** httpx(Python),fetch(TS)
### 开发工具
- **包管理器:** pnpm
- **测试:** Vitest 4+带测试库
- **Linting:** 拉夫·ESLint
- **格式:** 更漂亮,黑色
## 🎨 UI组件
内置 **shadcn/ui** 和 **Lucide反应** 图标:
- `DocumentCard` -单个文档显示
- `DocumentList` -文档卡片网格
- `DocumentPreviewModal` -抽象查看器
- `FullDocumentViewer` -完整的PDF渲染器
- `SummaryGenerationPanel` -摘要控制
- `FormatConversionPanel` -转换控制
- `ElicitationDialog` -自适应偏好收集
## 🔑 MCP实施要点
### 根
暴露 `reformatted-docs/` MCP服务器的目录:```typescript
{
uri: 'file:///reformatted-docs',
name: 'reformatted-documents'
}
采样
提供LLM访问权限以生成摘要:```typescript
await client.createMessage({
messages: [{ role: 'user', content: 'Summarize...' }]
})
### 引出
基于文档大小的自适应提示:```python
if page_count > 50:
preferences = await client.elicitation.create(
message="Configure summary options:",
schema={...}
)
🗺️ 项目结构```
afrotech-cac-dv/
├── src/
│ ├── app/ # Next.js app router
│ ├── components/ # React components
│ │ ├── ui/ # shadcn components
│ │ ├── documents/ # Document components
│ │ └── mcp/ # MCP components
│ ├── lib/
│ │ ├── mcp-client/ # MCP client implementation
│ │ └── utils/ # Utilities
│ ├── types/ # TypeScript types
│ └── store/ # State management
├── server/ # MCP Server (Python)
│ ├── main.py
│ ├── tools/
│ ├── provider/ # PDF provider connector
│ └── tests/
├── docs/ # Documentation
├── tests/ # E2E & integration tests
├── reformatted-docs/ # Converted documents
└── public/ # Static assets
```
🤝 贡献
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交更改(
git commit -m 'feat: add amazing feature') - 推送到分支(
git push origin feature/amazing-feature) - 打开拉取请求
承诺公约
跟随 约定式提交:
feat:新功能fix:错误修复docs:文档test:测试refactor:代码重构
📊 开发状态
总体进度:96%完成(49/51项任务)
完成✅
- [x] 项目设置和架构
- [x] MCP客户端实现(根、采样、启发)
- [x] MCP服务器实现(6个FastMCP工具)
- [x] UI组件(7个带有shadcn/UI的组件)
- [x] 带有元数据的文档列表视图
- [x] 预览带有摘要的模态
- [x] 带标签的完整文档查看器
- [x] 基于人工智能的摘要生成
- [x] 格式转换(EPUB、Markdown)
- [x] 测试套件(250个测试,约75%的覆盖率)
- [x] 综合文档(10个文档,~160KB)
- [x] 顺风CSS v4迁移
- [x] Next.js 15+兼容性
- [x] 模拟开发模式
- [x] 错误边界和处理
- [x] API路由(6个端点)
- [x] 具有增量提交的Git存储库
进行中/可选⏳
- [~]MCP客户端根模块测试(技术债务-fs模拟)
- [~]MCP服务器Python/pytest测试(UI开发可选)
📋 想帮助完成这些吗? 看 docs/OPTIONAL_TASKS.md 详细的分步计划(5-7小时)。
生产就绪🚀
应用程序是 生产准备就绪 与:
- ✅ 所有核心功能均正常工作
- ✅ 全面测试
- ✅ 现代工具(Next.js 15,Tailwind v4)
- ✅ 完整文档
- ✅ 错误处理和恢复
- ✅ 模拟开发模式
看 docs/IMPLEMENTATION_STATUS.md 以获取详细的进度跟踪。
🐛 已知问题
技术债
- MCP客户端根模块测试 -Vitest中fs模块模拟复杂性
- 状态:排除在测试套件之外
- 影响:低(功能正常,只是没有经过单元测试)
- 未来:重构依赖注入或使用更好的模拟
- jsdom限制 -由于浏览器API限制,跳过了3个测试
- 剪贴板API(SummaryGenerationPanel中的2个测试)
- scrollIntoView(复苏对话框中的1个测试)
- 影响:无(功能在浏览器中工作,只是无法进行单元测试)
浏览器兼容性
- 仅限现代浏览器(Chrome 90+、Firefox 88+、Safari 14+)
- 需要启用JavaScript
- 推荐:最新版本的Chrome、Firefox或Safari
📝 许可证
MIT许可证 -有关详细信息,请参阅LICENSE文件
🙏 致谢
- 模型上下文协议 - MCP规范
- FastMCP - FastMCP库
- Anthropic -Claude AI API
- shadcn/ui -组件库
- 维塞尔 -Next.js框架
📧 联系
如有疑问或支持,请在GitHub上发布问题。
内置❤️ 使用Next.js、MCP和Claude AI
