mcp-document-server CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP Document Server - A Python FastAPI-based Model Context Protocol (MCP) server that provides Claude AI with secure, read-only access to local documents. Supports both network (SSE/HTTP) and local (STDIO) transports.

Commands

Docker (Recommended)

docker-compose up -d              # Start server
docker-compose down               # Stop server
docker-compose logs -f            # View logs
docker-compose up -d --build      # Rebuild and start

Direct Python

python -m venv venv
venv\Scripts\activate             # Windows
source venv/bin/activate          # Linux/Mac
pip install -r requirements.txt
python server.py                  # Run server

Testing

curl http://localhost:8000/health # Health check
python test_server.py             # Run test client

Architecture

Claude AI
    │
    ├── STDIO (local) ──┐
    │                   │
    └── SSE/HTTP ───────┴──→ MCP Document Server (FastMCP + FastAPI)
                                    │
                                    ├── list_documents()   - List files with metadata
                                    ├── read_document()    - Read with format parsing
                                    ├── search_documents() - Full-text search
                                    └── documents://list   - Resource endpoint
                                    │
                                    ↓
                            Documents Directory (read-only)

Core Components

server.py - Main implementation:

• is_safe_path() - Path traversal protection (validates all paths stay within DOCUMENTS_PATH)
• get_file_info() - File metadata extraction
• list_documents() / read_document() / search_documents() - MCP tools
• main() - Entry point with transport selection (SSE vs STDIO)

test_server.py - Async test client that validates all MCP tools via Docker exec