Afrotech Connect And Control Pdfmcpdemo

基于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. 克隆存储库

   git clone 
   cd afrotech-cac-dv

1. 安装依赖项

   # Frontend
   pnpm install

   # MCP Server
   cd server
   pip install -r requirements.txt
   cd ..

1. 配置环境变量

   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. 启动开发服务器

终端1-Next.js用户界面：

   pnpm dev

终端2-MCP服务器：

   cd server
   python main.py

1. 打开应用程序

   http://localhost:3000

📖 用法

浏览文档

1. 导航到主页以查看所有可用文档
2. 每张卡片显示标题、作者、标签和页数
3. 单击任何文档打开预览模式

查看预览

1. 预览模式显示文档摘要
2. 点击“查看更多”以加载完整文档

生成摘要

对于小文档（\50页）：

1. 点击“创建摘要”
2. 出现包含以下选项的激励对话框：

- 摘要类型： 简要/详细/全面 - 最大字数： 300-5000（滑块） - 包括引用： 是/否

1. 选择操作：

- 接受： 使用您的偏好 - 使用默认值： 跳过自定义 - 取消： 放弃操作

1. 根据偏好生成的摘要
2. 摘要与元数据一起显示

转换格式

1. 查看完整文档
2. 点击“转换为EPUB”或“转换为Markdown”
3. 转换过程开始
4. 已转换的文件已保存到 reformatted-docs/ 目录
5. 提供下载链接

🧪 测试

运行测试

# 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

🤝 贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交更改(git commit -m 'feat: add amazing feature')
4. 推送到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

承诺公约

跟随 约定式提交:

• 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 以获取详细的进度跟踪。

🐛 已知问题

技术债

1. MCP客户端根模块测试 -Vitest中fs模块模拟复杂性

- 状态：排除在测试套件之外 - 影响：低（功能正常，只是没有经过单元测试） - 未来：重构依赖注入或使用更好的模拟

1. 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