afrotech-connect-and-control-pdfmcpdemo

mrhillsman-talks/afrotech-connect-and-control-pdfmcpdemo

3.2

If you are the rightful owner of afrotech-connect-and-control-pdfmcpdemo and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Model Context Protocol (MCP) server is a sophisticated backend system designed to manage and manipulate PDF documents using AI-powered features. It integrates with various components to provide document browsing, summarization, and format conversion capabilities.

Tools
2
Resources
0
Prompts
0

PDF Document Management System with MCP

A sophisticated document management platform built with Next.js, Model Context Protocol (MCP), and AI-powered features for PDF document browsing, summarization, and format conversion.

🎯 Features

  • 📚 Document List View - Browse PDF documents with rich metadata (title, authors, tags, page count)
  • 👁️ Quick Preview - Click to view document abstracts in a modal
  • 📖 Full Document Viewer - View complete PDFs with zoom and navigation controls
  • 🤖 AI-Powered Summaries - Generate brief, detailed, or comprehensive summaries using Claude AI
  • 📝 Adaptive Elicitation - Smart preference gathering for large documents (>50 pages)
  • 🔄 Format Conversion - Convert PDFs to EPUB or Markdown formats
  • 💾 Local Storage - Only metadata stored locally; full PDFs fetched on-demand
  • 🎨 Modern UI - Beautiful interface built with Tailwind CSS and shadcn/ui

🏗️ Architecture

This system implements the Model Context Protocol (MCP) architecture:

┌─────────────────────────────────────┐
│   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           │
└─────────────────────────────────────┘

Key Components

  1. Next.js UI (MCP Host)

    • Frontend application
    • Instantiates MCP client
    • Manages user interactions

  2. MCP Client

    • Roots: Exposes reformatted documents directory
    • Sampling: Provides LLM access for summaries
    • Elicitation: Handles adaptive user prompts

  3. MCP Server

    • Connects to PDF provider service
    • Exposes document manipulation tools
    • Orchestrates AI operations

  4. PDF Provider Service

    • External service (not included)
    • Stores full PDF documents
    • Provides metadata and retrieval APIs

🚀 Quick Start

Prerequisites

  • Node.js 18+
  • Python 3.10+
  • pnpm (recommended) or npm
  • Anthropic API key

Installation

  1. Clone the repository

    git clone <repository-url>
cd afrotech-cac-dv

  2. Install dependencies

    # Frontend
pnpm install

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

  3. Configure environment variables

    cp .env.example .env.local

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

  4. Start the development servers

    Terminal 1 - Next.js UI:

    pnpm dev

    Terminal 2 - MCP Server:

    cd server
python main.py

  5. Open the application

    http://localhost:3000

📖 Usage

Browsing Documents

  1. Navigate to the home page to see all available documents
  2. Each card shows title, authors, tags, and page count
  3. Click any document to open the preview modal

Viewing Previews

  1. Preview modal displays the document abstract
  2. Click "View More" to load the full document

Generating Summaries

For small documents (<50 pages):

  1. Click "Create Summary"
  2. Summary automatically generated (brief, ~500 words)
  3. Summary displayed instantly

For large documents (>50 pages):

  1. Click "Create Summary"
  2. Elicitation dialog appears with options:
    • Summary Type: Brief / Detailed / Comprehensive
    • Max Words: 300-5000 (slider)
    • Include Citations: Yes/No
  3. Choose action:
    • Accept: Use your preferences
    • Use Defaults: Skip customization
    • Cancel: Abort operation
  4. Summary generated according to preferences
  5. Summary displayed with metadata

Converting Formats

  1. View a full document
  2. Click "Convert to EPUB" or "Convert to Markdown"
  3. Conversion process starts
  4. Converted file saved to reformatted-docs/ directory
  5. Download link provided

🧪 Testing

Run Tests

# 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 Statistics

✓ Test Files: 11 passed
✓ Tests: 250 passed | 3 skipped
✓ Coverage: ~75%
✓ Duration: ~8 seconds

Test Suites

  • Unit Tests (41): MCP client modules (sampling, elicitation)
  • Component Tests (185): All UI components with React Testing Library
  • Integration Tests (14): All 6 API routes and MCP communication
  • E2E Tests (10): Complete user workflows and journeys

Mock Mode

The application includes a comprehensive mock mode for development without requiring the MCP server:

// Enabled by default in development
const client = createMCPClient(); // useMock: true

See for detailed testing documentation.

📚 Documentation

Core Documentation

  • - Complete system architecture and design
  • - API endpoints and MCP tools reference
  • - End-user instructions and workflows

Development Guides

  • - Developer setup and contributing guide
  • - Testing strategy and guidelines
  • - Production deployment guide

MCP Documentation

  • - MCP client implementation details
  • - MCP server tools and configuration
  • - Quick MCP reference

Project Planning

  • - Development roadmap
  • - Current progress (96%)
  • - Step-by-step plan for remaining 4%

🛠️ Technology Stack

Frontend

  • Framework: Next.js 15+ (App Router)
  • Language: TypeScript 5+
  • Styling: Tailwind CSS v4
  • Components: shadcn/ui (Radix UI)
  • Icons: Lucide React
  • PDF Rendering: react-pdf

Backend

  • MCP Server: Python FastMCP
  • MCP Client: TypeScript MCP SDK
  • LLM: Anthropic Claude API (Opus, Sonnet, Haiku)
  • HTTP Client: httpx (Python), fetch (TS)

Development Tools

  • Package Manager: pnpm
  • Testing: Vitest 4+ with Testing Library
  • Linting: ESLint, Ruff
  • Formatting: Prettier, Black

🎨 UI Components

Built with shadcn/ui and Lucide React icons:

  • DocumentCard - Individual document display
  • DocumentList - Grid of document cards
  • DocumentPreviewModal - Abstract viewer
  • FullDocumentViewer - Complete PDF renderer
  • SummaryGenerationPanel - Summary controls
  • FormatConversionPanel - Conversion controls
  • ElicitationDialog - Adaptive preference gathering

🔑 MCP Implementation Highlights

Roots

Exposes reformatted-docs/ directory to MCP server:

{
  uri: 'file:///reformatted-docs',
  name: 'reformatted-documents'
}

Sampling

Provides LLM access for summary generation:

await client.createMessage({
  messages: [{ role: 'user', content: 'Summarize...' }]
})

Elicitation

Adaptive prompts based on document size:

if page_count > 50:
    preferences = await client.elicitation.create(
        message="Configure summary options:",
        schema={...}
    )

🗺️ Project Structure

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

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit changes (git commit -m 'feat: add amazing feature')
  4. Push to branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Commit Convention

Follow Conventional Commits:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • test: Testing
  • refactor: Code refactoring

📊 Development Status

Overall Progress: 96% Complete (49/51 tasks)

Completed ✅

  • Project setup and architecture
  • MCP Client implementation (roots, sampling, elicitation)
  • MCP Server implementation (6 tools with FastMCP)
  • UI components (7 components with shadcn/ui)
  • Document list view with metadata
  • Preview modal with abstracts
  • Full document viewer with tabs
  • AI-powered summary generation
  • Format conversion (EPUB, Markdown)
  • Testing suite (250 tests, ~75% coverage)
  • Comprehensive documentation (10 docs, ~160KB)
  • Tailwind CSS v4 migration
  • Next.js 15+ compatibility
  • Mock mode for development
  • Error boundaries and handling
  • API routes (6 endpoints)
  • Git repository with incremental commits

In Progress / Optional ⏳

  • [~] MCP Client roots module tests (technical debt - fs mocking)
  • [~] MCP Server Python/pytest tests (optional for UI development)

📋 Want to help complete these? See for a detailed step-by-step plan (5-7 hours).

Production Ready 🚀

The application is production-ready with:

  • ✅ All core features working
  • ✅ Comprehensive testing
  • ✅ Modern tooling (Next.js 15, Tailwind v4)
  • ✅ Complete documentation
  • ✅ Error handling and recovery
  • ✅ Mock mode for development

See for detailed progress tracking.

🐛 Known Issues

Technical Debt

  1. MCP Client roots module tests - fs module mocking complexity in Vitest

    • Status: Excluded from test suite
    • Impact: Low (functionality works, just not unit tested)
    • Future: Refactor to dependency injection or use better mocking

  2. jsdom Limitations - 3 tests skipped due to browser API limitations

    • Clipboard API (2 tests in SummaryGenerationPanel)
    • scrollIntoView (1 test in ElicitationDialog)
    • Impact: None (features work in browser, just can't unit test)

Browser Compatibility

  • Modern browsers only (Chrome 90+, Firefox 88+, Safari 14+)
  • Requires JavaScript enabled
  • Recommended: Latest version of Chrome, Firefox, or Safari

📝 License

- See LICENSE file for details

🙏 Acknowledgments

📧 Contact

For questions or support, please open an issue on GitHub.

Built with ❤️ using Next.js, MCP, and Claude AI