# Documents MCP Server
### Advanced Model Context Protocol Document Management System

[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-43853D?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)
[![Notion](https://img.shields.io/badge/Notion-000000?style=for-the-badge&logo=notion&logoColor=white)](https://www.notion.so/)
[![Cloudflare Workers](https://img.shields.io/badge/Cloudflare_Workers-F38020?style=for-the-badge&logo=cloudflare&logoColor=white)](https://workers.cloudflare.com/)

---

## Table of Contents

- [Problem Statement](#-problem-statement)
- [Solution Overview](#-solution-overview)
- [Use Case Scenarios](#-use-case-scenarios)
- [System Architecture](#-system-architecture)
- [Design Process](#-design-process)
- [Implementation](#-implementation)
- [Features](#-features)
- [Installation](#-installation)
- [Configuration](#-configuration)
- [Usage](#-usage)
- [API Reference](#-api-reference)
- [Development](#-development)
- [Testing](#-testing)
- [Deployment](#-deployment)
- [Contributing](#-contributing)
- [License](#-license)

---

## Problem Statement

### The Challenge

Modern knowledge workers face significant inefficiencies in document management:

- **Fragmented Ecosystems**: Documents scattered across local storage, cloud platforms, and collaborative tools
- **Limited AI Integration**: Existing document systems don't provide seamless AI agent access
- **Manual Sync Overhead**: Constant manual synchronization between local work and cloud storage
- **Context Loss**: AI assistants can't access local documents for contextual assistance
- **Version Control Issues**: Difficulty tracking changes across multiple platforms

### Market Gap

Traditional document management solutions fall short in the emerging AI-first workflow era:

- **No Protocol Standardization**: Lack of standardized protocols for AI-document interaction
- **Platform Lock-in**: Vendor-specific solutions that don't interoperate
- **Limited Real-time Capabilities**: Insufficient support for real-time AI collaboration
- **Security Concerns**: Inadequate access control for sensitive local documents

---

## Solution Overview

**Documents MCP** is a production-ready Model Context Protocol server that bridges local document management with cloud synchronization, specifically designed for AI agent integration.

### Core Value Proposition

**Unified Interface**: Single protocol for AI agents to access both local and cloud documents  
**Real-time Sync**: Bidirectional synchronization with conflict resolution  
**Enterprise Security**: Path validation, access control, and audit trails  
**Protocol Compliance**: Full MCP specification implementation  
**Rich Metadata**: Comprehensive file information and sync status tracking  

---

## Use Case Scenarios

### Scenario 1: AI-Powered Content Creation
**Actor**: Content Creator  
**Goal**: Leverage AI assistance while maintaining local document control

**Workflow**:
1. Writer maintains drafts locally for version control
2. AI agent (Claude Desktop) accesses documents via MCP protocol
3. Real-time suggestions and edits are synchronized to Notion
4. Team collaboration occurs through cloud interface
5. Final versions sync back to local storage

**Benefits**: 
- Maintains local control while enabling cloud collaboration
- AI assistant has full context of writing projects
- Seamless version tracking across platforms

### Scenario 2: Technical Documentation Management
**Actor**: Software Development Team  
**Goal**: Maintain synchronized technical documentation across environments

**Workflow**:
1. Developers write documentation locally alongside code
2. MCP server automatically syncs to shared Notion workspace
3. AI agents help maintain consistency and completeness
4. Non-technical stakeholders access via Notion interface
5. Changes propagate bidirectionally with conflict resolution

**Benefits**:
- Documentation stays current with codebase
- Reduces documentation maintenance overhead
- Enables AI-assisted technical writing

### Scenario 3: Research Data Organization
**Actor**: Academic Researcher  
**Goal**: Organize and analyze research documents with AI assistance

**Workflow**:
1. Research files stored locally for security and offline access
2. AI agent helps categorize and analyze document content
3. Structured metadata synced to Notion for team visibility
4. Search and discovery enhanced through AI understanding
5. Publication-ready documents maintained locally

**Benefits**:
- Sensitive research data remains local
- AI-enhanced document analysis and organization
- Team collaboration without compromising data security

---

## System Architecture

### High-Level Architecture

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Agents     │    │  Documents MCP   │    │  Cloud Storage  │
│  (Claude, etc.) │◄──►│     Server       │◄──►│   (Notion)      │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │ Local File System│
                       └──────────────────┘
```

### Component Architecture

```
Documents MCP Server
├── MCP Protocol Layer
│   ├── JSON-RPC Handler
│   ├── Tool Registration
│   └── Request/Response Processing
├── Document Management
│   ├── File System Operations
│   ├── Metadata Extraction
│   ├── Search & Indexing
│   └── Security & Validation
├── Sync Engine
│   ├── Notion API Integration
│   ├── Conflict Resolution
│   ├── Status Tracking
│   └── Bidirectional Sync
└── Configuration & Utilities
    ├── Environment Management
    ├── Error Handling
    └── Logging & Monitoring
```

---

## Design Process

### Phase 1: Requirements Analysis

**Stakeholder Research**:
- AI application developers needing document access
- Knowledge workers seeking AI-enhanced workflows
- Development teams requiring synchronized documentation

**Technical Requirements**:
- MCP protocol compliance for AI agent compatibility
- Secure local file system access with path validation
- Cloud synchronization with conflict resolution
- Rich metadata and search capabilities

### Phase 2: Protocol Selection

**Decision: Model Context Protocol (MCP)**
- **Rationale**: Emerging standard for AI-system integration
- **Benefits**: Future-proofing, standardization, ecosystem compatibility
- **Trade-offs**: Early adoption risks, limited tooling

**Alternative Considered**: REST API
- **Rejected**: Less suitable for AI agent integration patterns

### Phase 3: Architecture Design

**Modular Architecture Principles**:
- **Separation of Concerns**: Distinct layers for protocol, documents, and sync
- **Extensibility**: Plugin architecture for additional cloud providers
- **Testability**: Isolated components for unit testing
- **Security**: Defense-in-depth with multiple validation layers

### Phase 4: Technology Stack Selection

**Core Technologies**:
- **TypeScript**: Type safety, developer experience, ecosystem maturity
- **Node.js**: JavaScript ecosystem, npm packages, deployment flexibility
- **Notion API**: Rich collaboration features, extensive API capabilities

**Development Tools**:
- **tsx**: TypeScript execution for development and testing
- **dotenv**: Environment configuration management
- **MCP SDK**: Official protocol implementation libraries

---

## Implementation

### Development Stages

#### Stage 1: Core MCP Protocol Implementation
**Objective**: Establish basic MCP server functionality

**Implementation**:
- JSON-RPC request/response handling
- Tool registration and discovery
- Basic document operations (list, read, write)
- Protocol compliance testing

**Challenges Addressed**:
- MCP specification interpretation
- TypeScript type definitions for protocol
- Request validation and error handling

#### Stage 2: Enhanced Document Operations
**Objective**: Add production-ready file management capabilities

**Implementation**:
- Rich metadata extraction (size, dates, file types)
- Path security and validation
- File type detection and filtering
- Search functionality (name and content)
- Directory operations and traversal

**Security Measures**:
- Path traversal attack prevention
- File size limits and validation
- Type checking and sanitization

#### Stage 3: Cloud Synchronization
**Objective**: Implement bidirectional Notion sync with conflict resolution

**Implementation**:
- Notion API integration and authentication
- Database schema design and management
- Sync status tracking and monitoring
- Conflict detection and resolution algorithms
- Error handling and retry logic

**Synchronization Logic**:
- Compare local vs. cloud modification timestamps
- Detect and flag conflicts for user resolution
- Maintain sync history and audit trails

### Code Quality and Testing

**TypeScript Implementation**:
- Strict type checking enabled
- Comprehensive interface definitions
- Generic types for reusability
- Proper error type handling

**Testing Strategy**:
- Manual JSON-RPC protocol testing
- Integration testing with Notion API
- File system operation validation
- Error condition testing

---

## Features

### Core Document Operations
- **List Documents**: Recursive directory scanning with metadata
- **Read Documents**: Content extraction with encoding detection
- **Write Documents**: Atomic operations with backup support
- **Search Documents**: Full-text search across name and content

### Synchronization Capabilities
- **Notion Integration**: Bidirectional sync with rich metadata
- **Conflict Resolution**: Intelligent handling of concurrent changes
- **Sync Status**: Real-time monitoring of synchronization state
- **Timestamp Tracking**: Modification time comparison and validation

### Security & Performance
- **Path Validation**: Prevention of directory traversal attacks
- **File Size Limits**: Protection against resource exhaustion
- **Type Detection**: Safe handling of different file formats
- **Efficient Operations**: Optimized for large document collections

### Developer Experience
- **Environment Configuration**: Flexible setup via environment variables
- **Rich Error Messages**: Comprehensive error reporting and debugging
- **TypeScript Support**: Full type safety and IntelliSense
- **Protocol Compliance**: Adherence to MCP specifications

---

## Installation

### Prerequisites

- Node.js 18+ 
- npm or yarn package manager
- TypeScript 5.0+
- Active Notion account (for cloud sync features)

### Quick Start

```bash
# Clone the repository
git clone https://github.com/corneyc/documents-mcp.git
cd documents-mcp

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your configuration

# Build the project
npm run build

# Start the MCP server
npm run mcp
```

### Docker Installation

```bash
# Build Docker image
docker build -t documents-mcp .

# Run container
docker run -v $(pwd)/documents:/app/documents \
  -e NOTION_TOKEN=your_token \
  -e NOTION_DATABASE_ID=your_db_id \
  documents-mcp
```

---

## Configuration

### Environment Variables

Create a `.env` file in the project root:

```env
# Notion Integration (Required for sync features)
NOTION_TOKEN=secret_your_notion_integration_token
NOTION_DATABASE_ID=your_database_uuid

# Document Storage (Optional)
DOCUMENTS_ROOT=/path/to/documents

# Server Configuration (Optional)
LOG_LEVEL=info
MAX_FILE_SIZE=10485760  # 10MB default
```

### Notion Setup

1. **Create Integration**:
   - Visit https://www.notion.so/my-integrations
   - Create new integration named "Documents MCP Sync"
   - Copy the integration token

2. **Create Database**:
   - Create new database in Notion
   - Add required properties:
     - Title (title type)
     - Local Path (text type)
     - File Size (number type)
     - Last Modified (date type)
     - Status (select type)

3. **Share Database**:
   - Click Share on your database
   - Add your integration
   - Copy database ID from URL

---

## Usage

### Claude Desktop Integration

Configure Claude Desktop to use your MCP server:

```json
// ~/.claude-desktop/claude_desktop_config.json
{
  "mcpServers": {
    "documents-mcp": {
      "command": "/opt/homebrew/bin/npm",
      "args": ["run", "mcp"],
      "cwd": "/path/to/documents-mcp"
    }
  }
}
```

### Manual Testing

Test server functionality with JSON-RPC calls:

```bash
# List documents
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "list_documents", "arguments": {}}}' | npm run mcp

# Read document
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "read_document", "arguments": {"key": "example.md"}}}' | npm run mcp

# Sync to Notion
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "sync_to_notion", "arguments": {"path": "example.md"}}}' | npm run mcp
```

---

## API Reference

### MCP Tools

#### `list_documents`
Lists all documents with metadata filtering options.

**Parameters**:
- `includeDirectories` (boolean): Include directories in results
- `textFilesOnly` (boolean): Filter to text files only  
- `maxSize` (number): Maximum file size in bytes

**Response**: Array of file metadata objects

#### `read_document`
Reads document content with metadata.

**Parameters**:
- `key` (string): Document path to read

**Response**: Document content and metadata

#### `write_document` 
Writes content to document with options.

**Parameters**:
- `key` (string): Document path to write
- `content` (string): Content to write
- `createBackup` (boolean): Create backup before overwrite
- `overwrite` (boolean): Allow overwriting existing files

**Response**: Write operation result and metadata

#### `sync_to_notion`
Synchronizes local document to Notion.

**Parameters**:
- `path` (string): Local document path to sync

**Response**: Sync operation result and Notion page ID

#### `get_sync_status`
Retrieves sync status for all documents.

**Parameters**: None

**Response**: Array of sync status objects

#### `search_documents`
Searches documents by name or content.

**Parameters**:
- `query` (string): Search query
- `searchContent` (boolean): Search file content
- `caseSensitive` (boolean): Case-sensitive search
- `filePattern` (string): File name regex pattern

**Response**: Array of matching documents

---

## Development

### Project Structure

```
documents-mcp/
├── src/
│   ├── mcp-server.ts              # Main MCP server implementation
│   ├── utils/
│   │   ├── local-documents-enhanced.ts  # Enhanced file operations
│   │   ├── local-documents.ts          # Basic file operations
│   │   └── notion-sync.ts             # Notion integration
│   └── types.ts                       # TypeScript definitions
├── documents/                         # Default document storage
├── tests/                            # Test files
├── package.json                      # Node.js configuration
├── tsconfig.json                     # TypeScript configuration
├── wrangler.toml                     # Cloudflare Workers config
└── README.md                         # Project documentation
```

### Development Commands

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Run MCP server
npm run mcp

# Run tests
npm test

# Type checking
npm run type-check

# Build for production
npm run build
```

### Adding New Features

1. **Implement Tool Logic**: Add function to appropriate utility module
2. **Register Tool**: Add tool definition to MCP server
3. **Add Handler**: Implement tool handler in CallToolRequestSchema
4. **Update Types**: Add TypeScript interfaces
5. **Test Integration**: Verify with JSON-RPC calls

---

## Testing

### Manual Testing

The project includes comprehensive manual testing procedures:

```bash
# Test basic protocol functionality
./scripts/test-protocol.sh

# Test document operations
./scripts/test-documents.sh

# Test Notion integration
./scripts/test-notion.sh

# Test error handling
./scripts/test-errors.sh
```

### Integration Testing

Test with actual AI agents:

1. Configure Claude Desktop with MCP server
2. Test document listing and reading
3. Verify Notion synchronization
4. Test error handling and recovery

### Performance Testing

```bash
# Test with large document collections
./scripts/test-performance.sh

# Monitor memory usage
npm run monitor

# Benchmark sync operations
npm run benchmark
```

---

## Deployment

### Local Development

```bash
# Start server locally
npm run mcp

# Run in development mode with auto-restart
npm run dev
```

### Production Deployment

#### Docker Deployment

```dockerfile
FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY src/ ./src/
COPY tsconfig.json ./

RUN npm run build

EXPOSE 3000
CMD ["npm", "run", "mcp"]
```

#### Cloudflare Workers

Deploy the companion web API to Cloudflare Workers:

```bash
# Deploy to Cloudflare
npm run deploy

# Deploy to specific environment
npm run deploy:staging
```

### Environment Setup

Production environment configuration:

```env
NODE_ENV=production
NOTION_TOKEN=secret_production_token
NOTION_DATABASE_ID=production_database_id
DOCUMENTS_ROOT=/app/documents
LOG_LEVEL=info
```

---

## Performance Considerations

### Optimization Strategies

- **Lazy Loading**: Documents loaded only when accessed
- **Caching**: In-memory caching of frequently accessed files
- **Batch Operations**: Efficient bulk synchronization
- **Connection Pooling**: Optimized Notion API connections

### Scaling Recommendations

- **Horizontal Scaling**: Multiple MCP server instances
- **Load Balancing**: Distribute document operations
- **Database Sharding**: Separate Notion databases by team/project
- **CDN Integration**: Cache static document content

---

## Contributing

### Development Process

1. **Fork Repository**: Create personal fork of the project
2. **Feature Branch**: Create branch for new feature or fix
3. **Implementation**: Develop with comprehensive testing
4. **Documentation**: Update documentation for changes
5. **Pull Request**: Submit PR with detailed description

### Code Standards

- **TypeScript**: Strict mode enabled with comprehensive typing
- **ESLint**: Code quality and consistency enforcement
- **Prettier**: Automated code formatting
- **Conventional Commits**: Standardized commit messages

### Testing Requirements

- **Unit Tests**: All utility functions must have unit tests
- **Integration Tests**: MCP protocol compliance testing
- **Documentation**: All public APIs must be documented

---

## License

MIT License - see [LICENSE](LICENSE) file for details.

---

## Acknowledgments

- **Anthropic**: MCP protocol specification and SDK
- **Notion**: Comprehensive API and developer documentation
- **TypeScript Team**: Excellent tooling and type system
- **Node.js Community**: Rich ecosystem and package availability

---

## Support

- **Issues**: [GitHub Issues](https://github.com/corneyc/documents-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/corneyc/documents-mcp/discussions)
- **Documentation**: [Project Wiki](https://github.com/corneyc/documents-mcp/wiki)

---

## Roadmap

### Short Term (Q1 2025)
- [ ] Google Drive integration
- [ ] Enhanced search with full-text indexing
- [ ] Automated testing suite
- [ ] Performance monitoring dashboard

### Medium Term (Q2 2025)
- [ ] Multi-cloud sync support
- [ ] Real-time collaboration features
- [ ] Advanced conflict resolution UI
- [ ] Plugin architecture for extensions

### Long Term (Q3-Q4 2025)
- [ ] Enterprise authentication integration
- [ ] Advanced analytics and reporting
- [ ] Mobile app companion
- [ ] AI-powered document insights

---

*Built with love for the AI-powered future of document management*