Document Search Server

A local MCP server that provides read-only access to documents (Word, PDF, Excel, CSV, Visio, PNG, JPG, PowerPoint, Text, Markdown, EPUB) via the Model Context Protocol (MCP).

Features

• Read-only access: Enforced at the code level.
• Recursive scanning: Scans all subdirectories of configured directories.
• File type validation: Uses magic numbers to validate file types.
• Metadata extraction: Extracts metadata from all supported file types.
• Logging: Logs all actions to a file (configurable).
• Timeout for file operations: Configurable timeout (default: 180 seconds) to prevent hanging on large or corrupt files.
• Full MCP compliance: Supports initialize, resources/list, resources/read, and tools/call methods.
• YAML configuration: Supports both CLI arguments and YAML configuration files.
• Extensive file type support: PDF, Word, Excel, CSV, Visio, Images, PowerPoint, Text, Markdown, EPUB.

Installation

1. Clone the repository:

   git clone https://github.com/bpweatherill/Document-Search-MCP-server.git
   cd Document-Search-MCP-server
   

2. Install dependencies:

   pip install -r requirements.txt
   

   For full file type support, install all optional dependencies:

   pip install PyPDF2 python-docx openpyxl Pillow textract xlrd PyYAML pdfplumber pypandoc python-pptx ebooklib
   

Usage

Start the Server

# Default: Scans ~/Documents
python -m src.main

# With custom directories and settings
python -m src.main --dir "C:\Users\Me\Documents" --dir "C:\Users\Me\Desktop" --max-file-size 50000000 --log-file "C:\logs\mcp.log" --log-level DEBUG --file-operation-timeout 180

# With a custom YAML config file
python -m src.main --config-file /path/to/custom_config.yaml

YAML Configuration

The server supports YAML configuration files in addition to CLI arguments. CLI arguments take precedence over YAML config.

Configuration file locations (checked in order):

1. mcp_server_config.yaml in the current directory
2. ~/.mcp_server/config.yaml in the user's home directory
3. /etc/mcp_server/config.yaml for system-wide config
4. Custom path specified with --config-file

Example YAML configuration:

# List of directories to scan (recursive)
allowed_dirs:
  - "~/Documents"
  - "/path/to/other/directory"

# Maximum file size in bytes (100MB default)
max_file_size: 104857600

# Path to the log file
log_file: "~/.mcp_server/log.txt"

# Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
log_level: "INFO"

# Timeout for file operations in seconds
file_operation_timeout: 180

# Additional file extensions to allow
allowed_extensions:
  - ".txt"
  - ".md"
  - ".pptx"
  - ".ppt"
  - ".epub"

MCP Client Interaction

Send JSON-RPC requests over stdio. The server supports the following MCP methods:

1. Initialize

{
  "id": 1,
  "method": "initialize",
  "params": {}
}

Response:

{
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "resources": {
        "list": {"description": "List available document resources"},
        "read": {"description": "Read a document resource"}
      }
    },
    "serverInfo": {
      "name": "Document-Search-MCP-Server",
      "version": "1.0.0"
    }
  }
}

2. List Resources

{
  "id": 2,
  "method": "resources/list",
  "params": {}
}

3. Read Resource

{
  "id": 3,
  "method": "resources/read",
  "params": {
    "uri": "file:///path/to/document.pdf"
  }
}

4. Call Tools

List Files

{
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "list_files",
    "arguments": {}
  }
}

Read File

{
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "/path/to/file.pdf"
    }
  }
}

Get Metadata

{
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "get_metadata",
    "arguments": {
      "path": "/path/to/file.pdf"
    }
  }
}

5. Ping (Health Check)

{
  "id": 7,
  "method": "ping",
  "params": {}
}

Configuration

Argument	Default	Description
--dir	~/Documents	Directories to scan (recursive). Can be specified multiple times.
--max-file-size	100MB	Skip files larger than this.
--log-file	~/.mcp_server/log.txt	Path to the log file.
--log-level	INFO	Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
--file-operation-timeout	180 (seconds)	Timeout for file operations.
--config-file	None	Path to a custom YAML configuration file.
--allowed-extensions	None	Additional file extensions to allow (e.g., --allowed-extensions .txt .md).

Security

• Read-only: All file operations are read-only.
• Path validation: Prevents directory traversal attacks.
• File type validation: Ensures files match their extensions.
• Race condition protection: Files are re-validated before each read operation.
• Timeout protection: File operations will not hang indefinitely.

MCP Compliance

This server fully implements the following MCP methods:

• initialize: Returns server capabilities and info.
• resources/list: Lists all available document resources.
• resources/read: Reads and returns the content of a resource.
• tools/call: Executes a tool (list_files, read_file, get_metadata).
• ping: Health check endpoint.

Testing

Run unit tests:

python -m unittest discover tests

Dependencies

Required

• PyPDF2: For PDF text extraction.
• python-docx: For Word document text extraction (.docx).
• openpyxl: For Excel file parsing (.xlsx).
• Pillow: For image metadata extraction (PNG, JPG, JPEG).
• PyYAML: For YAML configuration file support.

Optional (for extended file type support)

• pdfplumber: Better PDF text extraction (fallback to PyPDF2 if not available).
• textract: For binary Word document text extraction (.doc).
• xlrd: For binary Excel file parsing (.xls).
• pypandoc: For Markdown to HTML/plain text conversion.
• python-pptx: For PowerPoint file text extraction.
• ebooklib: For EPUB file text extraction.
• visio-python: For Visio file metadata extraction.

Supported File Types

File Type	Extension	MIME Type	Notes
PDF	.pdf	application/pdf	Uses pdfplumber (better) or PyPDF2
Word	.docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document	Uses python-docx
Word	.doc	application/msword	Uses textract (fallback to raw bytes)
Excel	.xlsx	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	Uses openpyxl
Excel	.xls	application/vnd.ms-excel	Uses xlrd (fallback to raw bytes)
CSV	.csv	text/csv	Uses Python's csv module
Visio	.vsdx, .vsd	application/vnd.ms-visio.viewer, application/vnd.visio	Uses visio-python (fallback to raw bytes)
Image	.png, .jpg, .jpeg	image/png, image/jpeg	Uses Pillow for metadata
PowerPoint	.pptx, .ppt	application/vnd.openxmlformats-officedocument.presentationml.presentation, application/vnd.ms-powerpoint	Uses python-pptx (fallback to raw bytes)
Text	.txt	text/plain	Read as plain text
Markdown	.md	text/markdown	Uses pypandoc or read as plain text
EPUB	.epub	application/epub+zip	Uses ebooklib (fallback to raw bytes)

Configuration File Example

Create a file named config.yaml (or use the provided example.yaml):

# Directories to scan
allowed_dirs:
  - "~/Documents"
  - "/path/to/other/directory"

# Maximum file size in bytes
max_file_size: 104857600

# Log file path
log_file: "~/.mcp_server/log.txt"

# Logging level
log_level: "INFO"

# File operation timeout in seconds
file_operation_timeout: 180

# Additional file extensions
allowed_extensions:
  - ".txt"
  - ".md"
  - ".pptx"
  - ".ppt"
  - ".epub"

Then start the server with:

python -m src.main

Or specify a custom config file:

python -m src.main --config-file /path/to/custom_config.yaml