使用说明
基于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 │
└─────────────────────────────────────┘
关键组件
-
Next.js用户界面（MCP主机）
- 前端应用程序
- 实例化MCP客户端
- 管理用户交互
-
MCP客户端
- 根： 显示重新格式化的文档目录
- 取样： 为摘要提供LLM访问权限
- 引语： 处理自适应用户提示
-
MCP服务器
- 连接到PDF提供商服务
- 公开文档操作工具
- 协调人工智能操作
-
PDF提供商服务
- 外部服务（不包括在内）
- 存储完整的PDF文档
- 提供元数据和检索API
🚀 快速开始
先决条件
- Node.js 18+
- Python 3.10+
- pnpm（推荐）或npm
- 无烟煤API键
安装
-
克隆存储库
git clone <repository-url> cd afrotech-cac-dv -
安装依赖项
# Frontend pnpm install # MCP Server cd server pip install -r requirements.txt cd .. -
配置环境变量
cp .env.example .env.local编辑
.env.local: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-Next.js用户界面：
pnpm dev终端2-MCP服务器：
cd server python main.py -
打开应用程序
http://localhost:3000
📖 用法
浏览文档
- 导航到主页以查看所有可用文档
- 每张卡片显示标题、作者、标签和页数
- 单击任何文档打开预览模式
查看预览
- 预览模式显示文档摘要
- 点击“查看更多”以加载完整文档
生成摘要
对于小文档（<50页）：
- 点击“创建摘要”
- 自动生成摘要（简短，约500字）
- 即时显示摘要
对于大型文档（>50页）：
- 点击“创建摘要”
- 出现包含以下选项的激励对话框：
- 摘要类型： 简要/详细/全面
- 最大字数： 300-5000（滑块）
- 包括引用： 是/否
- 选择操作：
- 接受： 使用您的偏好
- 使用默认值： 跳过自定义
- 取消： 放弃操作
- 根据偏好生成的摘要
- 摘要与元数据一起显示
转换格式
- 查看完整文档
- 点击“转换为EPUB”或“转换为Markdown”
- 转换过程开始
- 已转换的文件已保存到
reformatted-docs/目录 - 提供下载链接
🧪 测试
运行测试
# 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服务器：
// 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服务器的目录：
{
uri: 'file:///reformatted-docs',
name: 'reformatted-documents'
}
采样
提供LLM访问权限以生成摘要：
await client.createMessage({
messages: [{ role: 'user', content: 'Summarize...' }]
})
引出
基于文档大小的自适应提示：
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文件
🙏 致谢
📧 联系
如有疑问或支持，请在GitHub上发布问题。
内置❤️ 使用Next.js、MCP和Claude AI
